anuna-research/zetl

Fork 0

docs(SPEC-044): Tier-1 design — ratify-not-fill as accessibility, predicate families, core/plugin/MCP boundary (v0.4.0) #52

Open

m3data wants to merge 1 commit from docs/spec-044-tier1-design into main

m3data commented

2026-06-11 03:30:46 +00:00

(Migrated from codeberg.org)

What

Folds the Tier-1 design into SPEC-044 (the conjunctive-layer spec), grounded by a dogfood of your SPEC-045 typed edges on the EarthianLabs corpus (2026-06-11). Each design decision is backed by something the dogfood surfaced, not theory.

The synthesis trajectory (how each decision was grounded)

Authored typed edges on a real node (relational-posture) and migrated it fully to body-inline ::. Finding: zetl edges reads only body edges — the frontmatter relations: block is invisible to the graph and SPL projection (two frontmatter-only relations vanished entirely). → §6 reconciled: body is the source of truth; render reads the body edge graph.
A stray space broke it. developed_in:: [[X]] (inserted by hand or a formatter on save) silently demoted all 6 edges to untyped, no warning. → §7.1: manual :: typing is the storage format, not the authoring model. The authoring model is ratify-not-fill, framed as the accessibility mechanism — recognising+confirming a suggested predicate is available to non-engineers; composing syntax is not. Two surfaces (syntax / GUI) over one substrate. Plus a cheap spaced-near-miss lint (extend predicate-drift) so a formatter-break is flagged, not silent.
The vocabulary clustered. 13 predicates from 2 nodes fall into five families (lineage / mapping / application / tension / support). → §7.2: the families are the suggestion-ranking + render-grouping + drift substrate (they map onto your .zetl/predicates.toml category field). Not a controlled vocabulary — crystallisation stays collision-driven (underpins vs maps_to, both → coherence-entrainment, is the first signal).
Render hook already exists. Each edge renders as .zetl-edge-predicate[data-predicate=…] — so per-type colour is a theme-CSS change, not an engine change. The CHANGELOG confirms edges_by_predicate, /_graph legend, and predicates migrate already shipped, so Tier-1 builds on them.

Two structural additions (Mat's considerations)

§7.3 — user-local vs shared-corpus settings. Presentation/authoring preference is personal; the corpus is shared. .zetl/predicates.toml is the committed team layer; personal colour/preferred-predicates/authoring-surface need a non-committed user layer (gitignored .zetl/local/ or external ~/.config/zetl/). New OQ on location + composition (user overrides corpus presentation, never semantics).
§7.4 — core / plugin / MCP boundary. Substrate + ratification loop are core and model-free; generation is an opt-in MCP (stub-drafting, predicate inference, reference-checking); presentation is a swappable plugin. A vault with no MCP and the default theme is fully usable — the agent layer only accelerates candidate supply. (Same demotion-validation posture as the criticality substrate: the model drafts freely because the human ratification gate is the validation.)

Notes

version: 0.3.0 → 0.4.0, still strawman. Adds SPEC-045 to related.
Cross-cutting design (touches your render layer, the predicates.toml schema, and the agent/MCP surface) → opened for cross-dyad review rather than landing direct.

Authoring dyad: Mat Mytka + Kairos (Claude Opus 4.8).

## What Folds the Tier-1 design into SPEC-044 (the conjunctive-layer spec), grounded by a **dogfood of your SPEC-045 typed edges on the EarthianLabs corpus** (2026-06-11). Each design decision is backed by something the dogfood surfaced, not theory. ## The synthesis trajectory (how each decision was grounded) 1. **Authored typed edges on a real node** (`relational-posture`) and migrated it fully to body-inline `::`. Finding: `zetl edges` reads **only** body edges — the frontmatter `relations:` block is invisible to the graph and SPL projection (two frontmatter-only relations vanished entirely). → **§6 reconciled**: body is the source of truth; render reads the body edge graph. 2. **A stray space broke it.** `developed_in:: [[X]]` (inserted by hand or a formatter on save) silently demoted all 6 edges to untyped, no warning. → **§7.1**: manual `::` typing is the *storage format, not the authoring model*. The authoring model is **ratify-not-fill**, framed as the **accessibility mechanism** — recognising+confirming a suggested predicate is available to non-engineers; composing syntax is not. Two surfaces (syntax / GUI) over one substrate. Plus a cheap **spaced-near-miss lint** (extend `predicate-drift`) so a formatter-break is flagged, not silent. 3. **The vocabulary clustered.** 13 predicates from 2 nodes fall into **five families** (lineage / mapping / application / tension / support). → **§7.2**: the families are the suggestion-ranking + render-grouping + drift substrate (they map onto your `.zetl/predicates.toml` `category` field). Not a controlled vocabulary — crystallisation stays **collision-driven** (`underpins` vs `maps_to`, both → `coherence-entrainment`, is the first signal). 4. **Render hook already exists.** Each edge renders as `.zetl-edge-predicate[data-predicate=…]` — so per-type colour is a theme-CSS change, not an engine change. The CHANGELOG confirms `edges_by_predicate`, `/_graph` legend, and `predicates migrate` already shipped, so Tier-1 builds on them. ## Two structural additions (Mat's considerations) - **§7.3 — user-local vs shared-corpus settings.** Presentation/authoring preference is *personal*; the corpus is *shared*. `.zetl/predicates.toml` is the committed team layer; personal colour/preferred-predicates/authoring-surface need a **non-committed user layer** (gitignored `.zetl/local/` or external `~/.config/zetl/`). New OQ on location + composition (user overrides corpus *presentation*, never *semantics*). - **§7.4 — core / plugin / MCP boundary.** Substrate + ratification loop are **core and model-free**; **generation is an opt-in MCP** (stub-drafting, predicate inference, reference-checking); **presentation is a swappable plugin**. A vault with no MCP and the default theme is fully usable — the agent layer only accelerates candidate *supply*. (Same demotion-validation posture as the criticality substrate: the model drafts freely because the human ratification gate is the validation.) ## Notes - `version: 0.3.0 → 0.4.0`, still `strawman`. Adds SPEC-045 to `related`. - Cross-cutting design (touches your render layer, the predicates.toml schema, and the agent/MCP surface) → opened for **cross-dyad review** rather than landing direct. Authoring dyad: Mat Mytka + Kairos (Claude Opus 4.8).

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/spec-044-tier1-design:docs/spec-044-tier1-design

git switch docs/spec-044-tier1-design

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff docs/spec-044-tier1-design

git switch docs/spec-044-tier1-design

git rebase main

git switch main

git merge --ff-only docs/spec-044-tier1-design

git switch docs/spec-044-tier1-design

git rebase main

git switch main

git merge --no-ff docs/spec-044-tier1-design

git switch main

git merge --squash docs/spec-044-tier1-design

git switch main

git merge --ff-only docs/spec-044-tier1-design

git switch main

git merge docs/spec-044-tier1-design

git push origin main

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

anuna-research/zetl!52

No description provided.

Rows
Columns