Metadata-Version: 2.5
Name: idems-gitstore
Version: 0.4.0
Summary: Git as the store: branches as units of work, pull requests as results, history as the record.
Project-URL: Homepage, https://git.idems.international/IDEMSInternational/gitstore
Project-URL: Repository, https://git.idems.international/IDEMSInternational/gitstore
Project-URL: Issues, https://git.idems.international/IDEMSInternational/gitstore/issues
Author: IDEMS International
License: MIT
License-File: LICENSE
Keywords: forgejo,git,github,provenance,pull-request,worktree
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: keyring
Requires-Dist: keyring>=24; extra == 'keyring'
Description-Content-Type: text/markdown

# gitstore

**Git as the store.** A small Python library for applications that keep their state in a git
repository on a forge (GitHub, Forgejo) instead of in a backend database with its own user
accounts. A unit of work is a branch, a result is a pull request, and the history of every
decision is ordinary git history that a person can read, review and redo by hand.

> **Status: pre-alpha.** The design is in [docs/design.md](docs/design.md), and the v1 library
> is being built to it. Expect the API to change before 1.0.

## Install

```bash
pip install idems-gitstore
```

```python
import gitstore
```

The name on PyPI differs from the import name because `gitstore` on PyPI is an unrelated
project ([#40](https://git.idems.international/IDEMSInternational/gitstore/issues/40)).
Releases and their changes are in [CHANGELOG.md](CHANGELOG.md); [RELEASING.md](RELEASING.md)
says how one is made.

## Why

Several IDEMS projects arrived at the same pattern independently:

- **svc** (semantic version control for PreTeXt books) keeps documents, alignments and
  intent decompositions in project repos, lands each run as a branch and draft PR, and
  reconciles edits people make directly on the forge.
- **STACK authoring** keeps a question bank in a repo, runs each editing session on its own
  branch and worktree, and treats the open pull requests as the list of unfinished work.
- **anastom** (a review kernel for multi-agent pipelines) needs runs whose sources are pinned
  `repo@ref`s and whose outputs go back as a branch and PR.

Keeping state in git means less to host (no database of record, no user accounts: the
forge already has them) and it serves people: the state is readable in the repo, every
step is something a person could do with git or the forge's UI, and a human edit is a
commit like any other, attributed to whoever made it.

gitstore is that shared layer, so each project stops rebuilding it.

## What it will provide

| Piece | Purpose | From |
|---|---|---|
| `RepoRef(url, ref)` and parent-chain resolution | Pin exactly what a run read; resolve a variant through its parents, detecting cycles | svc |
| `GitProvider` protocol | One forge-neutral seam with a written error contract, for pull requests and issues; GitHub and Forgejo providers | svc |
| Git plumbing | Subprocess git with no-op commits, lease-only force, one rebuild-and-retry on a rejected push | svc |
| `WorkUnit` | A branch plus a worktree plus a heartbeat lease; resumable after days, safe after a crash | STACK |
| Run protocol | State commit then draft PR; result commit then ready; failure closes the PR and keeps the branch | svc |
| Provenance | A manifest entry per output and an append-only log beside each artifact, with an `ai`/`human`/`system` actor | svc + STACK |
| Guards | A PR failure is never a write to the default branch; no direct-to-main path; refuse destructive prunes | svc |
| Identity | Commits and pushes as the acting person, credentials through `GIT_ASKPASS`, never in a URL | STACK (planned there) |
| Test kit | Bare-repo fixtures and a `FakeProvider` | svc + STACK |

Domain logic stays with each application: svc's identity reconciliation, STACK's question
validation, anastom's run record.

## Licence

MIT. See [LICENSE](LICENSE).
