git ents: docs: describe ents-web as the leaf layer's second occupant

commit 02c21df

docs: describe ents-web as the leaf layer's second occupant

overview.adoc’s crate-graph row and abstractions.adoc’s Layering section both predate the phase-6 kernel/package split: the former listed ents-web depending on ents-receive/ents-model/ents-anchor/ ents-query only (ents-forge and ents-kiln did not exist yet when that table was written), and the latter named only git-ents as the leaf/CLI layer’s occupant. Phase 7 actually lands ents-web depending on ents-forge and ents-kiln too (custom toolchain/comment pages), so both docs now say so — a documentation-accuracy fix, not a spec change: no requirement id is touched.

docs: add ents-forge, ents-kiln to ents-web’s overview.adoc dependency row docs: name ents-web as the CLI/leaf layer’s second occupant in abstractions.adoc, and state the one binding rule inside it (no concrete-type match in the generic rendering path) Assisted-by: Claude:claude-sonnet-4-6

Joseph D. Carpinelli · 1 month ago

tree browse at HEAD · parents: a3c2ac5 · comment on this commit

Reviews

No reviews of this commit yet — record a verdict below.

Start a review

docs/abstractions.adoc @@ -246,9 +246,13 @@ * *Package* — `ents-forge` (issues, comments, review/release/check types as they land), `ents-kiln` (toolchains). Owns types and policy: the domain entity structs, and any package-specific gate or effect definitions. A package depends on kernel crates freely, and on other packages never — `ents-forge` and `ents-kiln` do not depend on each other. -* *CLI* — `git-ents`: the composition root. -Depends on the kernel directly (for kernel-owned commands: `setup`, `members`, `account`, `effect`, `inbox`, `redact`, `hook`) and on every installed package (for `comment`, from `ents-forge`; `toolchain`, from `ents-kiln`). +* *CLI* — the leaf layer, two sibling occupants: `git-ents` and `ents-web`, the composition roots and their direct consumers. +`git-ents` depends on the kernel directly (for kernel-owned commands: `setup`, `members`, `account`, `effect`, `inbox`, `redact`, `hook`) and on every installed package (for `comment`, from `ents-forge`; `toolchain`, from `ents-kiln`). Mounts each package's subcommand grammar through one convention (`crate::package::Package`, in `git-ents`): a package owns its own figue action enum, defined in its own crate, and the CLI's top-level subcommand enum references that type directly — a compile-time pairing, not a runtime plugin registry, because the argument grammar is resolved from a `#[derive(Facet)]` shape at compile time, with nothing to register dynamically. +`ents-web` (phase 7) is a second leaf, not a third layer: it depends on kernel crates and, for v1, directly on `ents-forge` and `ents-kiln` too, hardcoding a custom page per package where one is genuinely needed (a toolchain's recipe provenance, a comment's anchor projection) — legitimate for a leaf consumer exactly as `git-ents`'s own package-specific subcommands are, not a layering violation. +The one rule that binds inside `ents-web` itself is narrower than the crate-level layering rule: its *generic* rendering path — the schema-driven list/view mechanism driven by `facet::Shape` reflection, the UI analog of the gate executor — must never match on which concrete entity type it was handed. +A generic-path need to know a concrete type is a missing generic capability to add to that mechanism, or grounds for a legitimate custom page; it is never grounds for a `match` inside the generic renderer. +`git-ents` depends on `ents-web` (for its `serve` subcommand), the one edge between the two leaves; `ents-web` never depends back on `git-ents`. The one-way rule is absolute, not just directional-on-average: a kernel crate must not depend on a package crate in any form — not a normal dependency, not a dev-dependency, not a build-dependency, not behind a feature flag. `ents-testutil` in particular must not know a package's types; a package needing test fixtures beyond the kernel's generic ones adds them inside its own crate, not by teaching `ents-testutil` its vocabulary.