docs: post-review alignment
commit
e578f56docs: post-review alignment
Aligns the spec overview abstract with the design thesis, fills the bin dependency cells in the crate graph, catches design.adoc up to the redaction (yank) design and the pass|fail|error taxonomy, adds issues as a first-class entity to abstractions and the FAQ, and fixes a README typo.
Reviews
No reviews of this commit yet — record a verdict below.
Start a review
README.adoc
@@ -40,7 +40,7 @@
=== Simplicity
This project aspires to be simple.
-All project metadata – issues, reviews, contributors, repository configurations, releases, etc. – are stored in one databasss: Git's at-rest data model.
+All project metadata – issues, reviews, contributors, repository configurations, releases, etc. – are stored in one database: Git's at-rest data model.
Of course, we will not force the usage of a data model that fundamentally cannot represent modern software projects.
If we determine the core thesis of this project is false, we will reevaluate.
As stated above, this project is experimental!
docs/abstractions.adoc
@@ -18,7 +18,7 @@
* *Authorization* — refname-keyed rules gate who may advance the ref.
* *History* — the ref's commit history is the audit trail.
-*Granularity rule:* one ref per independently-authored entity (`refs/meta/member/*`, `refs/meta/comments/*`, `refs/meta/effects/*`, `refs/meta/results/*`); one ref for repo-global state (`refs/meta/account`, `refs/meta/config`).
+*Granularity rule:* one ref per independently-authored entity (`refs/meta/member/*`, `refs/meta/issues/*`, `refs/meta/comments/*`, `refs/meta/effects/*`, `refs/meta/results/*`); one ref for repo-global state (`refs/meta/account`, `refs/meta/config`).
Entities that different actors write concurrently must not share a ref.
Writes stay conflict-free; reads aggregate refs into views.
@@ -244,7 +244,8 @@
* *Toolchains* — typed trees under `refs/meta/toolchains/*`; a resource effects declare, not a trigger.
The repo carries its own execution environment with provenance, as ~1KB hash-pinned manifests; only the sandbox touches the bytes.
They keep a subcommand only because import/activation logic is nontrivial; if that shrinks, the subcommand dies.
-* *Members, accounts, comments* — typed trees behind meta-refs (1+2), written as signed commits (4), admitted by the gate (5).
+* *Members, accounts, issues, comments* — typed trees behind meta-refs (1+2), written as signed commits (4), admitted by the gate (5).
+Issues are the plainest instance of all: assignees, labels, and states are struct fields, so multiple assignees or custom states are schema, not platform features.
* *Fanout indexes* — discovery without ref enumeration: `refs/meta/index/*` maps object oids to the entities anchored to them, rebuilt by an effect (6) and written via the worker's signed commit (4).
Clients read the index; a stale or absent index degrades to scanning ref tips, never to wrong answers.
* *Redaction* — the deliberate exception to retention: an object-level yank, scoped to content reachable only from `refs/meta/*`.
docs/design.adoc
@@ -47,6 +47,10 @@
The inbox ref is the mailing list; the adoption merge is the maintainer applying a signed patch; the trust decision is explicit, recorded, and attributed on both sides.
A rejected canonical push degrades to an inbox offer, not an error.
+Redaction is the one deliberate exception to immutability.
+A yank is an admin-signed entity under `refs/meta/redactions/*`, enforced at ingest so content addressing cannot silently refill the hole; readers see a redaction marker where the bytes were, never an error, and the oid stays in history as evidence.
+It is best-effort by nature — no design can recall bytes from clones that already fetched, which is as true of git and email as it is here, and is stated rather than implied away.
+
Workers are inside the same trust model.
An effect runner is a member with a key, scoped by refname rules, revocable as repository state — never an ambient authority.
"Official CI" is not a runtime property; it is a refname rule saying canonical results refs are writable only by designated worker keys.
@@ -61,6 +65,7 @@
Pipelines are query composition, not orchestration: staged CI is an intersection with a results set, fan-in is intersection, conditional edges are difference.
The pipeline's state is the results namespace; the work set is `trigger − results(self, any)`; exactly-once outcomes fall out of content addressing with zero state outside the repo.
Semantics are monotone and entry-only, which is what makes distributed evaluation safe with nothing but the existing CAS.
+A run's exit status is always a result — `pass` or `fail` means the effect ran; infrastructure failure is not a result but a bounded queue retry, whose exhaustion writes a terminal `error` so no obligation retries forever and no transient outage discharges one prematurely.
Execution is orthogonal to storage.
What to run is repo data; how to run it is a deployment property chosen at a composition root — so "local store, cloud executor" is a quadrant that exists without being designed: `git effect run --executor sprite` on your own account.
docs/faq.adoc
@@ -46,6 +46,16 @@
'''''
+== Issues
+
+*I want an issue tracker.*
+An issue is a typed tree on its own ref under `refs/meta/issues/*` — written, gated, synced, and audited exactly like a comment.
+
+*I want multiple assignees, custom states, or fields no forge offers.*
+Assignees, labels, and states are struct fields, and the struct is the schema; extending the issue model is a typed-tree change, not a platform request.
+
+'''''
+
== Comments and anchors
*I want to leave a comment on specific lines of code.*
docs/spec/overview.adoc
@@ -2,12 +2,14 @@
Joey Carpinelli <joseph.carpinelli@icloud.com>
[abstract]
-`git-ents` is a Git forge: a self-hosted, membership-gated Git server with a
-browser UI, a CLI, asynchronous CI checks, an issue tracker, and anchored
-code comments.
-Every piece of state — members, configuration, checks, runs, issues,
+`git-ents` is a Git forge: membership, issues, anchored code comments,
+code review, and CI-style effects, with a browser UI and a CLI.
+Every piece of state — members, configuration, effects, results, issues,
comments — lives in the repository itself as typed documents on git
-meta-refs, versioned and auditable, with no external database.
+meta-refs, versioned, signed, and auditable, with no external database.
+A hosted server is only custody of the canonical refs: a store that runs
+the same verification gate any clone can run, plus a queue that
+dispatches effects.
The spec is organized around the load-bearing abstractions (rationale in
`docs/abstractions.adoc`), each a parent section with its dependent entities
@@ -156,11 +158,13 @@
| `git-ents` (bin)
| Local composition root.
-|
+| `ents-receive`, `ents-effect`, `ents-web`, `ents-anchor`, `ents-sync`,
+`gix-receive`, `gix-ref-store`
| `git-ents-server` (bin)
| Hosted composition root.
-|
+| `ents-receive`, `ents-effect`, `ents-web`, `gix-receive`,
+`gix-ref-store`
|===
=== Boundary Rules