skynet-graph 1.2.0

package/README.md

@@ -0,0 +1,245 @@
+<h1 align="center">skynet-graph</h1>
+
+<p align="center">
+<b>Make a small local model work a big task the way humans always have — piece by piece.</b><br>
+The engine cuts the task into typed pieces, <i>zooms</i> the model onto one piece at a time with exactly
+the context it needs, keeps every result as a typed fact with provenance so a late correction re-derives
+for free, and steers the model's output against a certified method vocabulary. Nothing leaves the machine.
+</p>
+
+<p align="center">
+<img src="./doc/img/headImg.png">
+</p>
+
+<p align="center"><i>Active R&D · a CommonJS library to embed + an <code>sg</code> CLI · Node 18+, no build step · AGPL-3.0</i></p>
+
+<p align="center">
+<a href="https://doi.org/10.5281/zenodo.21032471"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21032471.svg" alt="DOI"></a>
+<a href="https://doi.org/10.5281/zenodo.21201877"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21201877.svg" alt="DOI"></a>
+</p>
+
+## What you get
+
+A 27B model crushed to 9.5 GB (IQ2) runs on your GPU — but quantization broke part of its judgment,
+and any big task overflows it. This engine gives that model four things, **each measured on real GPUs,
+with negative controls and deterministic re-runs**:
+
+- **Big tasks, piece by piece** — the model never sees the whole problem, only one bounded piece at a
+  time: accuracy **×2.5–3.2** on multi-step tasks, and where whole-context prompting **collapses (0/33)**,
+  the pieces hold (**10/33**).
+- **Repair for low quants** — verified method shapes steer the output: SQL **8→63 %**, finance tables
+  **7→62 %**, at **zero big-model calls** on covered queries.
+- **Task memory that reopens** — a late correction automatically un-does everything that depended on
+  it, and "done" steps **reopen themselves with the reason**. No stale state, ever.
+- **An external think mode** — benched head-to-head: the model's *native* think budget scores
+  **13/24 ≈ a coin flip** on side-judgment; the external critical mind renders **0 wrong verdicts**
+  (24/24 provable on a declared frame, an honest UNDECIDED otherwise).
+
+**See it in 30 seconds — no model, no GPU** (a deterministic replay of a real end-to-end run — the
+9.5 GB quant analyzing an annual report, erratum and crash included):
+
+```bash
+git clone https://github.com/9pings/skynet-graph && cd skynet-graph
+npm install && node examples/integrated-demo/run.js --replay      # 7 checks, bit-identical
+```
+
+Every claim on this page follows a standing rule: **a refuted claim is removed the day it falls**
+(several are listed below on purpose). The full feature map — maturity bars, numbers, limits,
+snippets — is **[doc/CAPABILITIES.md](doc/CAPABILITIES.md)**.
+
+Where it sits in your setup — two zero-integration doors into one local loop:
+
+```
+ [your agent / app / any OpenAI client]
+        │
+        ├─► OpenAI-compatible endpoint    sg serve  →  http://127.0.0.1:4747/v1
+        └─► MCP tools                     sg mcp    →  ask · hint · propose · state_recall · plan_sync · critique
+                      │
+                      ▼
+        [typed reasoning graph]    plan · admission gates · typed ledger · JTMS memory
+                      │
+                      ▼
+        [your local GGUF model]    — nothing leaves the machine
+```
+
+---
+
+## The four capabilities, measured
+
+Small local models are fine on a *surface* step; they derail when a request makes them **compose**
+several things at once. This library puts them in front of one surface at a time.
+
+**Proof degrees:** **[live]** = measured on GPU with real local models · **[measured]** = deterministic,
+replayable without a model · **[PoC]** = an accounting demonstration, not a benchmark.
+
+| Capability | What happens | Measured |
+|---|---|---|
+| **Repair low-quants** | a menu of *certified* method shapes steers a heavily-quantized model's output — it recovers most of what compression broke, at **zero big-model calls** | SQL, covered queries: low-quant 8→**63 %** (high-quant 46→92 %), N=201 · finance, traffic view: 7→**62 %** (20→78 %), N=120 · [live] |
+| **Task memory that reopens** | task state = typed facts with provenance (JTMS): a drifted premise **retracts its consequences in cascade**, and a "done" step **reopens itself with the reason** — it never rots | recomputable drift re-derives at **0 model calls**, selectively (independent facts untouched); crash-replay is bit-identical at 0 calls [live] · 100 % recall at **894 constant tokens/call** vs 50 % at 4 286 for a carry-everything baseline [PoC] |
+| **Piece-by-piece (the zoom)** | the task becomes a typed DAG; each piece is served with ONLY its bounded neighbourhood (parent goal + resolved inputs + what to produce) — the model never sees the whole | cross-domain at N=200/domain (560 tasks total): math word problems 16 %→**52 %** (×3.2), financial-table QA 20 %→**50 %** (×2.5), bootstrap CIs hold [live] · **where the lone model collapses, the pieces hold**: deep tasks 0/33 whole vs 10/33 decomposed [live] · on 20 compound "monster" tasks (~20 ops): whole-context floors at **0/20**, hierarchical 2-level split reaches 73 % of sections [live] |
+| **An external think mode** | the model proposes; the graph **refutes with the reason** and enumerates the admissible options (tested through its own gate, never guessed); the model revises — bounded, with honest refusal | one dialogue round: 17/24 → **24/24** correct at zero false admissions [live] · native think budget vs the external critical mind on side-judgment: **13/24 (≈ chance, 11 confident wrong verdicts) vs 0 wrong verdicts** — 24/24 mechanical on a declared perimeter, honest UNDECIDED otherwise [live] · disciplined argument coverage: **77 % vs 58 %** whole-context at 48 arguments [live] · anchored generation of MISSING theses: **0 fabrication** across every negative control [live] |
+
+| Feature — details per row in [doc/CAPABILITIES.md](doc/CAPABILITIES.md) | Maturity (6-rung honest scale; rung 6 = external replications, empty pre-launch) |
+|---|---|
+| [F1 — Repair low-quants](doc/CAPABILITIES.md#f1-low-quant-repair) | `█████░` 5/6 — product-integrated |
+| [F2 — The piece-by-piece zoom](doc/CAPABILITIES.md#f2-piece-by-piece-zoom-on-big-tasks) | `████░░` 4/6 — measured at scale, not turnkey yet |
+| [F3 — Task memory that reopens](doc/CAPABILITIES.md#f3-task-memory-that-reopens) | `█████░` 5/6 — product-integrated |
+| [F4 — External think mode](doc/CAPABILITIES.md#f4-external-think-mode) | `█████░` 5/6 — product-integrated |
+| [F5 — External critical mind](doc/CAPABILITIES.md#f5-external-critical-mind) | `█████░` 5/6 — product-integrated |
+| [F6 — Local `.sgc` rooms](doc/CAPABILITIES.md#f6-local-sgc-rooms) | `█████░` 5/6 — product-integrated |
+| [F7 — The versionable reasoning substrate](doc/CAPABILITIES.md#f7-the-versionable-reasoning-substrate) | `█████░` 5/6 — product-integrated |
+| [The integrated demo](doc/CAPABILITIES.md#the-integrated-demo) | `█████░` 5/6 — ships in this repo |
+
+The certified vocabulary these capabilities lean on is **fuel, not the headline**: a *forge* (`sg forge`)
+builds `.sgc` method stocks from any dataset that has an executable oracle, behind a **zero-false-admission**
+gate (held across every campaign: 0 false shapes admitted, 3 datasets, 2 forge models) — each stock ships
+with an auditable sha256 validation dossier.
+
+### Where it beats what you would reach for today
+
+Each row is a measured delta or a checked absence — details, limits and snippets per row in
+[doc/CAPABILITIES.md](doc/CAPABILITIES.md).
+
+| You would reach for | The known weakness there | Here, measured |
+|---|---|---|
+| a bigger / higher-quant model | needs VRAM you don't have | certified-stock steering on *your* hardware: SQL 8→**63 %**, finance 7→**62 %**, 0 frontier calls on the covered slice |
+| an agent scratchpad / vector memory | boxes only get ticked; similarity retrieval serves **stale** answers | premise drift → cascade retraction + reopen-with-reason: **12/12 vs 0/12** (stale) on drift, 0 model calls |
+| a decomposition framework | free-text plans, unbounded context growth | typed needs/produces + bounded per-piece context: ×2.5–3.2 at N=200, and **0/33 → 10/33** where the whole-task baseline collapses |
+| a native think mode / self-critique loop | self-critique underperforms external feedback (2024-25 literature, + our own refutation ×3) | benched head-to-head: a native think budget scores **13/24 ≈ chance** on side-judgment (11 confident wrong verdicts) — the external critical mind renders **0 wrong verdicts**: 24/24 mechanical on a declared perimeter, honest UNDECIDED otherwise; and the gate **never yields** (17/24 → **24/24** at zero false admissions) |
+| LLM-as-judge / a debate prompt | miscalibrated, gameable, no audit trail | witness-gated coverage (0 fabrication), typed ledger, and a judge that **declines by measured bound** (UNDECIDED below margin) |
+| a prompt hub / RAG index for methods | anything pasted in is trusted | `.sgc` rooms: admission-gated import (a bad bundle never lands), sha256 dossiers, local files you own |
+| a rules engine / event sourcing | fires rules or versions events — never versions *belief* | rollback / diff / fork / merge on what the system currently holds true, **rules included** — no market equivalent found |
+
+**What is honestly NOT claimed** (each of these was tested, and the page follows the results):
+- the guarantee is **at admission, not at execution** — at use time the stock *orients*; a suggestion is not
+  a correctness proof (a runtime "trusted answers" tier was tested and **refuted** — removed);
+- the win lives on the **typed, recurrent slice** of the work: free prose and genuinely novel reasoning stay
+  in the model, without guarantee — a design boundary, not a bug;
+- forge yield is a **per-domain parameter** (not model-invariant — refuted), and amortization is a property
+  of the *domain's* stereotypy;
+- the small model executes surface steps well; it is **not** the task cutter (measured limit);
+- a **verdict** (weighing which side wins) is reliable **on certified perimeters** or at wide margins;
+  on free, uncertified content the engine renders **counts + zero-false coverage + an honest UNDECIDED**,
+  not a verdict — the measured decidability bound, kept rather than papered over (graded weighting and
+  goal-criteria weighting were both tested and **refuted** for a low-quant judge).
+
+## Quick start
+
+```bash
+npm install        # no build step — pure CommonJS, Node 18+
+npm test           # 1350 tests — 0 failures, 2 known skips
+
+node bin/sg run --concepts ./concepts --builtins --seed ./seed.json
+node examples/integrated-demo/run.js --replay    # the four capabilities assembled, no GPU
+```
+
+```js
+const Graph = require('skynet-graph');
+
+// boot from folders of concept rules + providers, stabilize, read facts:
+const g = Graph.fromDirs({
+  concepts: './concepts',
+  builtins: true,                                  // wire the packaged geo + LLM providers
+  seed: { conceptMaps: [
+    { _id: 'a', Node: true, Position: { lat: 48.85, lng: 2.35 } },
+    { _id: 'b', Node: true, Position: { lat: 1.35,  lng: 103.8 } },
+    { _id: 's', Segment: true, originNode: 'a', targetNode: 'b' },
+  ]},
+  conf: { onStabilize: g => console.log(g.serialize().graph) },   // s now carries Distance { inKm: 10728 }
+});
+```
+
+The `LLM::complete` provider is backend-agnostic: inject any async `ask`, or use the bundled client
+(`LLM_API=anthropic`, default; `LLM_API=openai` for vLLM / llama.cpp / LM-Studio).
+
+### Serve it — zero-integration surfaces
+
+```bash
+# OpenAI-compatible endpoint over the local-first proxy cache: point ANY OpenAI client's baseURL at it.
+# Covered queries → served from the verified local stock at 0 frontier calls; provenance headers on every
+# completion (x-sg-*); 0 hallucination by construction on the covered slice.
+sg serve --frontier-model <path.gguf> --store ./stock.json          # → http://127.0.0.1:4747/v1
+
+# The same capabilities as MCP TOOLS for an agent host (typed refusals arrive STRUCTURED):
+claude mcp add sg -- node bin/sg mcp --frontier-model <path.gguf> --store ./stock.json
+
+# One-command typed QA, and the visual debugger:
+sg ask "your question" --concepts ./concepts --local-model <path.gguf>
+sg studio            # (or: sg serve --studio — live request lines in its trace panel)
+```
+
+Runnable, deterministic, GPU-free demos of every use-case class live in **`examples/bootstrap/`** —
+one short file per combo and per surface, each printing the guarantee it demonstrates.
+
+> **The ready-made appliance** — if you just want the endpoint + local `.sgc` stock rooms without embedding
+> the library, use **[skynet-dequantizer](https://github.com/9pings/skynet-dequantizer)**: `skynet-dequantizer serve` (OpenAI-compatible,
+> no-egress by default, proven on real sockets) · `skynet-dequantizer rooms list|import|export|freeze` (your own
+> shareable stock mini-repos — no catalog, no subscription, sha256 dossiers).
+>
+> **For AI agents reading this repo**: `CLAUDE.md` at the root is the machine-oriented map (architecture,
+> commands, gotchas); the MCP surface is one command away (`claude mcp add sg -- node bin/sg mcp …`).
+
+## Two ways to use it — and how it works
+
+The library is **one engine with two front doors**; they share the same core, and you can stop at the first.
+
+![the two uses](doc/img/two-uses.svg)
+
+**Use 1 — the substrate**: a *versionable, git-like reasoning orchestrator*, standalone, **no LLM
+required**. Model a domain in declarative concept rules (JSONC), wire deterministic providers, and let
+stabilization keep the belief state coherent as data changes: `rollbackTo(rev)` (rules included),
+`diffRevisions(a, b)`, `fork`/`merge` sub-worlds, and native cascading retraction — a falsified premise
+un-casts itself *and its consequences*, with no rollback code. A complete, tested capability on its own.
+→ **[doc/usage.md](doc/usage.md)** · **[doc/architecture.md](doc/architecture.md)** · **[doc/API.md](doc/API.md)** · schema **[doc/original-2016-doc.md](doc/original-2016-doc.md)** (FR, EN pointer inside)
+
+**Use 2 — the target system**, built on Use 1: a learned **concept-graph is a method** — a reusable
+sub-graph carried by its **typed contract, not its body**, so each step sees only a bounded
+neighbourhood. The supervisor forges methods, crystallizes the recurrent ones into reusable tools,
+composes tools into bigger tools — and **un-learns** a method when its premise drifts (the moat no
+RAG / skill-library has). Everything keys on **discrete, typed facts** — never free prose — which is
+both what makes the memoization hit and the honest ceiling: only recurrent, typed, canonicalizable
+structure amortizes; genuinely novel reasoning stays in the model.
+→ **[doc/concept-as-graph.md](doc/concept-as-graph.md)** · full model + roadmap **[doc/MODELISATION.md](doc/MODELISATION.md)**
+
+> **Heads-up.** Active R&D. Use 1 is solid and tested; Use 2 is an advancing conception with measured
+> PoCs (not a product). How best to organize concepts is still open — treat the shipped `concepts/`
+> sets as illustrative, not a recommended ontology.
+
+## Papers
+
+Two companion preprints (Nathanael Braun, 2026), open access on Zenodo, each in English and French —
+with in-repo reproducibility packages ([`artifact/paper-dll/`](artifact/paper-dll/),
+[`artifact/paper-lattice/`](artifact/paper-lattice/) — every table replays bit-for-bit without a GPU).
+
+- **“Defeasible Library Learning: Typed Methods with Runtime Contracts that Un-learn on Drift”** —
+  the system paper. DOI v1 [10.5281/zenodo.21032471](https://doi.org/10.5281/zenodo.21032471) ·
+  v2 [10.5281/zenodo.21201723](https://doi.org/10.5281/zenodo.21201723)
+- **“Sound online growth of a typed *isa* lattice from noisy LLM extraction …”** — the companion
+  admission-gate paper. DOI [10.5281/zenodo.21201877](https://doi.org/10.5281/zenodo.21201877)
+
+<details>
+<summary>BibTeX</summary>
+
+```bibtex
+@misc{braun2026dll,
+  author    = {Braun, Nathanael},
+  title     = {Defeasible Library Learning: Typed Methods with Runtime Contracts that Un-learn on Drift},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.21201723},
+  url       = {https://doi.org/10.5281/zenodo.21201723}
+}
+@misc{braun2026lattice,
+  author    = {Braun, Nathanael},
+  title     = {Sound online growth of a typed isa lattice from noisy LLM extraction, through candidate elimination made noise-tolerant by a localized-blame admission gate},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.21201877},
+  url       = {https://doi.org/10.5281/zenodo.21201877}
+}
+```
+</details>
+
+## License
+
+GNU AGPL-3.0-or-later — see [LICENSE](./LICENSE). © 2026 Nathanael Braun &lt;pp9ping@gmail.com&gt;

package/bin/sg

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2026 Nathanael Braun
+ * @author : Nathanael BRAUN <pp9ping@gmail.com>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+'use strict';
+require('../lib/sg/cli.js');

package/concepts/README.md

@@ -0,0 +1,23 @@
+# Concept sets — the shipped grammars
+
+Each sub-directory is a **concept set**: a hand-authored grammar of declarative rules (JSONC) that cast
+typed facts + child segments as the graph stabilizes. They are loaded with
+`Graph.fromDirs({ concepts: './concepts' })` or `Graph.loadConceptMap(dir)`; `conf.conceptSets` selects
+which are active. See [../doc/usage.md](../doc/usage.md) §3 (concept sets) and
+[../doc/doc.md](../doc/doc.md) (the full schema reference).
+
+> These are **examples of hand-authored grammars** — the base, standalone use of the engine (no LLM
+> required). They are *illustrative*, not a recommended ontology (concept-organization strategy is WIP).
+> The LLM-driven master-graph supervisor is layered *on top of* this substrate, not a prerequisite for it.
+
+| Set | Layer | What it shows |
+|---|---|---|
+| **`common/`** | base / illustrative | The original travel/geo grammar. `Vertice` (nodes) + `Edge` (segments) + `Edge/Distance` (great-circle via `CommonGeo::Distance`) + `Edge/Travel/*`, `Edge/Stay/*`, `Document/*`. The canonical "hand-author a deterministic grammar for a domain" example — start here. |
+| **`clinical/`** | domain grammar | **Defeasance**: `Observation → LabValue → OutOfRange` then a `Diagnosis` gated on the lab verdict → nested `Medication`; a refuted lab **retracts** the diagnosis and cascade-retracts the medication (JTMS), depositing a typed `constat` record. Shows `ensure`-driven un-casting. |
+| **`supply/`** | domain grammar | **Pavage / tiling**: `Procurement` + `Inventory` + `Transport` sub-domains under a `Fulfillment` hub; `forkPlan` derives the tiles + their separator alphabet. Shows TTL defeasance (a stale ETA re-plans). |
+| **`_substrate/`** | universal spine | The acyclic backbone (`Task`, `Claim`, `Frontier`) the **problem-solving grammar** builds on (decompose → rollup → claim, with a snapped frontier). Underpins the `examples/poc/problem-*.js` use 2 demos; usable on its own as a generic decomposition skeleton. |
+
+**Authoring invariants the loader honors** (see usage §3): a child concept's key must equal its `_id`;
+`_id` is globally unique; `_name` (the flag written on entities) defaults to the file basename; and the
+**typed-fact discipline** — `require`/`assert`/`ensure` key only on discrete typed facts (enums/ids/numbers/
+booleans), never on free-text prose. `lib/authoring/validate.js` enforces this at author time.

package/concepts/_substrate/Claim/Confidence/Trusted.json

@@ -0,0 +1,6 @@
+{
+  // Trust gate on the SNAPPED band. R2 audit: GATES on a discrete enum the LLM wrote; a
+  // low-confidence claim uncasts its dependents (defeasance via the watched ensure).
+  "require": ["Confidence"],
+  "ensure": ["$confBand == 'high'"]
+}

package/concepts/_substrate/Claim/Confidence.json

@@ -0,0 +1,10 @@
+{
+  // Graded confidence SNAPPED to a band (enum, not a raw float — gating on a raw float
+  // churns the memo every run, K1/A2). The LLM grades; the rule carries the snapped fact.
+  "require": ["Claim"],
+  "provider": ["AI::confidence"],
+  "prompt": {
+    "facts": { "confBand": { "enum": ["low", "medium", "high"] } },
+    "prose": "confRationale"
+  }
+}

package/concepts/_substrate/Claim/Freshness/Stale.json

@@ -0,0 +1,7 @@
+{
+  // Cast == "is fresh"; when the clock passes the TTL the ensure falls -> uncast -> the
+  // stale claim's dependents cascade-retract (cache-poisoning fix). Note the DOUBLE-$ on the
+  // global clock free-node (a single $clock would read the local scope, the #1 standing bug).
+  "require": ["Freshness", "producedAt"],
+  "ensure": ["$$clock:tick - $producedAt < $ttl"]
+}

package/concepts/_substrate/Claim/Freshness.json

@@ -0,0 +1,5 @@
+{
+  // Attaches a TTL to a claim (N1). R2 audit: ORIENTS (declares a freshness budget).
+  "require": ["Claim"],
+  "applyMutations": { "$_id": "_parent", "ttl": 100 }
+}

package/concepts/_substrate/Claim/Verification/Refuted.json

@@ -0,0 +1,6 @@
+{
+  // Refutation = defeasance. Exists only to CARRY the retraction: when the verdict flips
+  // to 'fail', dependents nested under the claim cascade-uncast (the Zep foil). R2-safe.
+  "require": ["Verification"],
+  "ensure": ["$claimVerdict == 'fail'"]
+}

package/concepts/_substrate/Claim/Verification.json

@@ -0,0 +1,6 @@
+{
+  // Independent verdict as a SIBLING fact (never overwrites the claim). The deterministic
+  // checker is R2-safe (a range/schema check is verification, not domain decision).
+  "require": ["Claim"],
+  "provider": ["Verify::check"]
+}

package/concepts/_substrate/Claim.json

@@ -0,0 +1,4 @@
+{
+  // An answered task asserts something verifiable. R2 audit: ORIENTS (marks "checkable").
+  "require": ["Task", "Answered"]
+}

package/concepts/_substrate/Frontier/InBeam.json

@@ -0,0 +1,6 @@
+{
+  // Beam membership by budget (the global budget free-node, double-$). Eviction (budget
+  // falls below estCost) uncasts -> the sub-tree cascade-retracts (beam-by-retraction).
+  "require": ["Frontier", "estCost"],
+  "ensure": ["$$budget:remaining > $estCost"]
+}

package/concepts/_substrate/Frontier/Stuck.json

@@ -0,0 +1,6 @@
+{
+  // No strategy left -> triggers the supervisor / self-mod (supervise.js). R2 audit:
+  // ORIENTS the supervisor; does not itself decide the repair.
+  "require": ["Frontier"],
+  "ensure": ["$strategiesExhausted"]
+}

package/concepts/_substrate/Frontier.json

@@ -0,0 +1,5 @@
+{
+  // An open node competing for budget. Cast while NOT yet answered. R2 audit: ORIENTS.
+  "require": ["Task"],
+  "assert": ["!$Answered"]
+}

package/concepts/_substrate/Intake/ToTask.json

@@ -0,0 +1,22 @@
+{
+  // Intake→Task BRIDGE (roadmap P1.a / GAP B of doc/WIP/2026-07-05-combos-design.md §11).
+  //
+  // A TYPED intake is the prose→typed front door — but on its own it is a DEAD END: the answer
+  // loop (Task → Complexity → Answer / Rollup) runs on a Task *Segment*, and nothing converts a
+  // typed Intake node into one. Without this concept the intake and the answer loop are two
+  // disconnected sub-graphs, so an appliance can only ever emit typed refusals, never answers.
+  //
+  // This closes the gap: on a FAITHFUL (typed) intake it seeds a root Task Segment carrying the
+  // question, so the loop has something to run on. Gated on the DISCRETE `IntakeStatus` (never the
+  // untracked prose): an untyped/partial intake does NOT cast, so a barrier miss stays a visible
+  // typed refusal (IntakeStatus + IntakeMissing) instead of silently seeding a task. If the typing
+  // premise later falls, JTMS un-casts this and its whole sub-tree (the seeded task + its answers).
+  //
+  // The seed TEMPLATE is the provider's job — AI::seedTask (lib/providers/reason-loop.js) reads the
+  // node's rawText and emits the origin/goal nodes + the `_task` Segment. Self-flags `ToTask`
+  // (provider-cast-marker gotcha). No answer logic here: this concept ORIENTS (a typed question is
+  // a unit of work); the decompose/answer is the AI:: loop.
+  "require": ["Intake"],
+  "ensure": ["$IntakeStatus == 'typed'"],
+  "provider": ["AI::seedTask"]
+}

package/concepts/_substrate/Intake/Typed.json

@@ -0,0 +1,10 @@
+{
+  // The downstream-gate CONTRACT, made explicit and re-usable: anything that consumes intake
+  // facts MUST gate on the discrete `IntakeStatus=='typed'`, NEVER on the (untracked) prose.
+  // A required out-of-vocabulary miss makes the intake `untyped`, so this gate does NOT cast —
+  // the boundary is gated, not crossed silently; a later premise fall (re-intake flips the
+  // status) auto-retracts this and its dependents (JTMS). No provider: a pure assert gate that
+  // self-casts when the typed projection is faithful.
+  "require": ["Intake"],
+  "ensure": ["$IntakeStatus=='typed'"]
+}

package/concepts/_substrate/Intake.json

@@ -0,0 +1,27 @@
+{
+  // C0 — the prose→typed FRONT DOOR (roadmap §3.2): the ONE place free text crosses into the
+  // typed world, and the system's declared SOUNDNESS BOUNDARY. `Intake::type` reuses the
+  // canonicalization barrier (lib/providers/canonicalize.js) and adds a discrete gate fact
+  // `IntakeStatus ∈ typed|partial|untyped`. A host wires `createIntake({ ask })`
+  // (lib/providers/intake.js) and supplies the CLOSED `facts` vocabulary for its domain.
+  //
+  // This shipped `facts` vocab is a domain-NEUTRAL template (classify an inbound message kind);
+  // a real domain specializes it via childConcepts. Fires on any object carrying inbound prose
+  // (`rawText`); a required key that comes back out-of-vocabulary makes the intake `untyped`
+  // (visible + escalated), never a silent wrong snap.
+  //
+  // The prompt MUST offer an honest out-of-enum escape ('other', deliberately NOT in the enum, so
+  // it lands OOV → `untyped`): a closed list with no escape pressures a compliant model to force-
+  // pick in-vocab — measured live (Qwen3.6-27B, 2026-07-05): without the escape an un-typeable
+  // "..." snaps to "statement" (silent wrong snap INVITED by the prompt); with it, "other" → typed
+  // refusal, while real questions still type cleanly. Same doctrine as snapToVocab's OOV-kept-raw.
+  "require": ["rawText"],
+  "provider": ["Intake::type"],
+  "prompt": {
+    "system": "Classify the inbound message kind. Reply only JSON with a 'kind' field (one of question, request, statement — or 'other' if none of them faithfully fits) and a short 'prose' restatement.",
+    "user": "${rawText}",
+    "facts": { "kind": { "enum": ["question", "request", "statement"] } },
+    "prose": "intakeNarrative"
+  },
+  "intake": { "required": ["kind"] }
+}

package/concepts/_substrate/Task/Answer.json

@@ -0,0 +1,12 @@
+{
+  // Leaf answer for an atomic task. The answer is TERMINAL prose (untracked); only the
+  // discrete `Answered` flag crosses downstream (the K1 barrier — prose never on an edge).
+  "require": ["Task", "Atomic"],
+  "provider": ["AI::answer"],
+  "prompt": {
+    "system": "Answer this atomic step directly and concisely.",
+    "user": "Step: ${label}",
+    "prose": "answer"
+  },
+  "applyMutations": { "$_id": "_parent", "Answered": true }
+}

package/concepts/_substrate/Task/Complexity/Atomic.json

@@ -0,0 +1,5 @@
+{
+  // Gate on the LLM's verdict; do not re-decide. R2 audit: GATES on a fact the LLM wrote.
+  "require": ["Complexity"],
+  "ensure": ["$complexityClass == 'atomic'"]
+}

package/concepts/_substrate/Task/Complexity/Compound/Expansion.json

@@ -0,0 +1,7 @@
+{
+  // LLM-meta: the provider SYNTHESIZES the expansion template (the AND hyper-edge of child
+  // sub-segments) and writes `expandedInto`. R2 audit: carries STRUCTURE, not the "how to
+  // split" judgment (that is the provider's).
+  "require": ["Compound"],
+  "provider": ["AI::expand"]
+}

package/concepts/_substrate/Task/Complexity/Compound.json

@@ -0,0 +1,6 @@
+{
+  // The compound branch. R2 audit: GATES on the LLM enum verdict; the split itself is the
+  // provider's job (Expansion), not a rule.
+  "require": ["Complexity"],
+  "ensure": ["$complexityClass == 'compound'"]
+}

package/concepts/_substrate/Task/Complexity.json

@@ -0,0 +1,6 @@
+{
+  // Structural classifier node. The mutually-exclusive Atomic/Compound branches nest under
+  // it and gate on the LLM's `complexityClass` enum fact (the engine's `type:"enum"` self-cast
+  // is unused — Concept.js:239 — so the discriminant is a fact, not the cast machinery).
+  "require": ["EvalComplexity"]
+}

package/concepts/_substrate/Task/EvalComplexity.json

@@ -0,0 +1,13 @@
+{
+  // The LLM JUDGES atomic-vs-compound; the rule only structures the verdict into a typed
+  // enum fact. R2 audit: the LLM decides (prompt.facts.Complexity); the rule never gates on
+  // domain judgment.
+  "require": ["Task"],
+  "provider": ["AI::evalComplexity"],
+  "prompt": {
+    "system": "Classify whether this step is atomic or needs decomposition.",
+    "user": "Step: ${label}",
+    "facts": { "complexityClass": { "enum": ["atomic", "compound"] } },
+    "prose": "complexityRationale"
+  }
+}

package/concepts/_substrate/Task/ReportUp.json

@@ -0,0 +1,6 @@
+{
+  // Orchestration: post self-id upward (race-free {__push} into the parent's answeredBy);
+  // calls no other concept. R2 audit: ORCHESTRATES (stigmergic), decides nothing.
+  "require": ["Task", "Answered", "parentSeg"],
+  "provider": ["AI::reportUp"]
+}

package/concepts/_substrate/Task/Rollup.json

@@ -0,0 +1,10 @@
+{
+  // Bounded bottom-up synthesis. GATES on a DISCRETE cardinality equality (.length on both
+  // sides — never on prose), so it fires exactly once when the last child has reported. The
+  // fold is the LLM's job; the rule carries only the bounded-cardinality trigger.
+  "require": ["Task", "Expansion"],
+  "ensure": ["$answeredBy.length == $expandedInto.length"],
+  "provider": ["AI::rollup"],
+  "prompt": { "system": "Synthesize one bounded answer from the child answers.", "prose": "answer" },
+  "applyMutations": { "$_id": "_parent", "Answered": true }
+}

package/concepts/_substrate/Task.json

@@ -0,0 +1,5 @@
+{
+  // Universal layer — the answer-loop spine root. A Segment carrying a sub-problem.
+  // R2 audit: ORIENTS (declares a unit of work); decides nothing.
+  "require": "Segment"
+}

package/concepts/clinical/Diagnosis/Medication.json

@@ -0,0 +1,6 @@
+{
+  // Nested under Diagnosis so a refuted diagnosis CASCADE-retracts it (finding #10b: a child
+  // concept un-casts when its parent falls — `require` alone would NOT defease). R2: ORIENTS.
+  "require": ["Diagnosis"],
+  "provider": ["Dx::prescribe"]
+}

package/concepts/clinical/Diagnosis.json

@@ -0,0 +1,15 @@
+{
+  // THE niche edge (the Zep foil). The LLM writes the diagnosis enum (prompt.facts.diagnosis);
+  // the rule only GATES on the lab verdict and RETRACTS when it falls (defeasance) — it never
+  // decides the diagnosis itself (R2). A refuted/corrected lab => labVerdict flips => Diagnosis
+  // uncasts => Medication (nested child) cascade-retracts => the cleaner deposits a constat.
+  "require": ["Observation", "LabValue"],
+  "ensure": ["$labVerdict == 'pass'"],
+  "provider": ["Dx::diagnose"],
+  "cleaner": ["Constat::record"],
+  "constat": { "claimKey": "diagnosis", "because": "labVerdict" },
+  "prompt": {
+    "facts": { "diagnosis": { "enum": ["t2dm", "ckd", "hyperkalemia", "anemia"] } },
+    "prose": "diagnosisRationale"
+  }
+}

package/concepts/clinical/Observation/LabValue/OutOfRange.json

@@ -0,0 +1,6 @@
+{
+  // Deterministic R2-SAFE checker: the reference bounds are DATA, not judgment — it CHECKS
+  // whether the value is out of range, it does not DECIDE a diagnosis (R11.3).
+  "require": ["LabValue"],
+  "ensure": ["$value > $refHigh || $value < $refLow"]
+}

package/concepts/clinical/Observation/LabValue.json

@@ -0,0 +1,5 @@
+{
+  // A typed lab measurement. In production an LLM::complete extracts the enum/grain facts
+  // (analyte, value, unit) via prompt.facts (the barrier); here they are seeded. R2: ORIENTS.
+  "require": ["Observation"]
+}

package/concepts/clinical/Observation.json

@@ -0,0 +1,6 @@
+{
+  // Clinical domain grammar — plugs under the universal Claim (here rooted at an encounter
+  // for a self-contained defeasance demo). A clinical observation on an encounter.
+  // R2 audit: ORIENTS (declares a verifiable observation); decides nothing.
+  "require": ["encounter"]
+}

package/concepts/common/Document/pathBasket.json

@@ -0,0 +1,6 @@
+{
+  "applyMutations" : {
+    "$_id" : "_parent",
+    "pathBasket" : []
+  }
+}

package/concepts/common/Document.json

@@ -0,0 +1,3 @@
+{
+  "require": "Record"// entryPoints for Segment primitive
+}

package/concepts/common/Edge/Distance.json

@@ -0,0 +1,13 @@
+{
+  // must wait the needed cast in originNode & targetNode
+  "require": [
+    "originNode:Position",
+    "targetNode:Position"
+  ],
+  //  "ensure" : [
+  //  ],
+  "provider": [
+    // if a distance object is requiered ask :
+    "CommonGeo::Distance"
+  ]
+}

package/concepts/common/Edge/Stay/LongStay.json

@@ -0,0 +1,8 @@
+{
+  "require": [
+    "Stay"
+  ],
+  "assert": [
+    "$TimePeriod.length > 1000*60*60*24 || $FuzzyTimePeriod.length > 1000*60*60*24"
+  ]
+}

package/concepts/common/Edge/Stay.json

@@ -0,0 +1,8 @@
+{
+//  "require": "Distance",
+  // entryPoints for the Segment primitive,
+  "assert": [
+    "!$Travel",
+    "$Undefined||$Distance&&$Distance.inKm==0"
+  ]
+}