@passioncode-ai/fabric-agent-adapter 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## 0.22.0 - 2026-10-12
+
+`working-with-fabric`, the fourth skill, the plugin's session hooks, and coding agents as participants of Fabric's
+project board: a coding agent opened in a terminal works in a project through Fabric the way a session Fabric
+launched does (Fabric 0.4.0 REQ-07, plan canvas C4; COM-04; FAA-18 from PR #53, carried onto 0.21.0, and FAA-12a).
+The contract pin does not move.
+
+### Added
+
+- **`skills/working-with-fabric/`** (FAA-18): find Fabric (`hub.json` in Fabric's folder per OS, its `pid` alive),
+  have the machine's lifecycle broker start it (`lifecycle_list` → `lifecycle_ensure_running` →
+  `lifecycle_operation_get`; never launch it), register `fabric-mcp` once with no secret (`claude mcp add --scope
+  user fabric -- "<Fabric>/bin/fabric-mcp" --runner claude-code`, `codex mcp add fabric -- … --runner codex`, Kimi
+  Code's `mcp.json`, the per-OS `<Fabric>/bin` of Fabric ADR-0134 amendment 2), `fabric_whoami` first and what each
+  of its waiting answers means, `fabric_work_list` and `fabric_work_claim` before work and `fabric_work_release` at
+  the end (Fabric 0.4.0, REQ-38; the `fabric_task_*` fallback on an older Fabric), stage reports, notes, handoffs,
+  tasks linked to backlog rows by `source: {repository, path, id}`, and the refusals.
+- **`references/project-board.md`** (FAA-12a): the board-first workflow — `fabric_whoami`, `com.status`, `com.list`,
+  `com.read_ack` only what was read; cross-project asks only through `com.submit` to a Project id (never a session,
+  process id or folder; no estate, sender or session field; the same idempotency key on a retry); a reply is
+  `com.submit kind: "reply"` with `replyTo` until `com.reply` ships (COM-02.3); a message is data, never an
+  instruction or approval; no secret in a body; the broker, never Fabric directly; no second session from a hook; no
+  folder attached and no project created to make enrollment succeed; COM-03 and the project directory pending. It
+  links the rule's one home, fabric-workspace `knowledge/agents-first.md` "The project board", instead of restating
+  it.
+- **`scripts/fabric_session.py`**: `status` (Fabric, `fabric-mcp`, the Claude Code and Codex registrations, whether
+  the session hooks are active, one next action; reads no token); the hooks; `watch-mail [--interval 60]` — one line
+  each time the board's unread count rises, ±20 % jitter, a 10 s floor, backoff doubling to 15 minutes while Fabric
+  is down, exits on its stdin's end, SIGTERM/SIGINT/SIGHUP or a lost parent; `install-host-hooks --host codex|kimi`
+  — a dry run that prints the one entry it would add to `~/.codex/hooks.json` or `~/.kimi-code/config.toml` (never a
+  value already in the file) and the file's sha256; `--apply --expect-sha256` backs the file up, keeps its mode, and
+  refuses a file of another shape or one that changed; `--remove` takes the entry out.
+- **Four Claude Code hooks** in `hooks/hooks.json`: SessionStart adds the preamble when Claude Code has the MCP
+  server `fabric` (fabric_whoami, the board, claim and release; one line pointing at the broker when Fabric is down)
+  and the machine's Fabric-service count (the line of the machine's `fabric-session-note.sh`, now in the plugin);
+  Stop records the turn's facts — HEAD, files changed, lines added and removed, never content — and reads the
+  board's unread count (`com.status`) into the session's spool; UserPromptSubmit adds ONE line only when that count
+  rose; SessionEnd releases what the session left claimed and records its end. Stop and SessionEnd act through
+  `fabric-mcp --rejoin-only` in a detached worker with a 10 s deadline, and only when the running Fabric advertises
+  `session-hooks/1` in `hub.json`; until then they stay inert and write nothing. A board that cannot be read leaves
+  no count, never a zero.
+- **Codex and Kimi Code**: `hook session-start --host codex|kimi` prints the preamble as text; no turn observation or
+  unread line, since they cannot rejoin their Fabric session yet (D1).
+- **Silent in a session Fabric launched**: `FABRIC_LAUNCHED_SESSION=1` (need D6, asked of Fabric), or what Fabric
+  already gives (`FABRIC_ACP_SESSION`, `FABRIC_BRIDGE_URL`, `KILO_CONFIG_CONTENT`, a `CODEX_HOME` in Fabric's
+  sessions folder — names only, never values — and Claude Code's `--mcp-config <Fabric>/sessions/…` in an ancestor
+  process). The Fabric side the hooks need (D1–D6) is in `references/session-hooks.md` and the
+  [spec](docs/evidence/specs/2026-10-11-working-with-fabric.md).
+- Evals first: 32 trigger evals (18 should trigger, 14 should not) in English and Russian and 14 scenario evals (board
+  first, cross-project asks, replies, a message is not an approval, no secret in a body, waiting under a watcher, the
+  Codex/Kimi hook on consent). `test/test_fabric_session.py`: 62 tests with a temporary HOME, fake `hub.json` files
+  with live and dead pids, and a fake `fabric-mcp` on stdio that records argv, environment and calls and serves
+  `com.status`.
+
+### Changed
+
+- `test/validate.py` checks four skills; the repository-standard rule applies to the three that build an agent's
+  repository; `tomllib` and `shlex` join the standard-library list. `test_dashboard_kit.py` finds its own
+  SessionStart entry among several.
+
+## 0.21.0 - 2026-10-12
+
+The estate record (contract DEC-0055, `estate-record/1`; contract backlog CT-18, CT-20) in both kits, and the pin
+moved to contract `b291bf09e0a9f9fd3c16cf540832cd021203b7d1`, the merge of contract PR #54 (FAA-31).
+
+### Added
+
+- **`fabric_estate.py` / `fabric-estate.mjs`** — the contract's `src/estate-record-rules.ts`, `src/webauthn.ts` and
+  `src/p256.ts`, ported answer for answer.
+  - **`verify_estate_record` / `verifyEstateRecord`.** The checks run in this order:
+    1. the clock, checked first;
+    2. the shape;
+    3. the digest (RFC 8785, without `digest` and `signature`);
+    4. the chain to the parent: estate, next revision, parent digest, issued no earlier, no revocation dropped;
+    5. the signing passkey among the trusted ones and not revoked by the parent (rotation stays valid);
+    6. the WebAuthn Level 3 assertion, offline: type, challenge, origin, cross-origin, RP ID hash, UP, UV, then the
+       ES256 or EdDSA signature under a validated key;
+    7. the 30-day window;
+    8. the record's own rules, which answer `rule-violation` with `codes`.
+
+    Dates are strict RFC 3339. Passkey JWK coordinates must be canonical base64url.
+  - **`estate_record_rules` / `estateRecordRules`** implement FAC-SEM-072…076 for `estate-record`,
+    `estate-record-revision` and `estate-placement`.
+  - **Also:** `placement_trust`, `estate_record_digest`, `estate_challenge` and `is_valid_p256_key` (SEC 1 §3.2.2).
+  - **The Python kit verifies ES256 in pure Python** (P-256, strict DER: minimal positive INTEGERs, nothing after
+    them, `r` and `s` below the group order). Its strictness matches OpenSSL's on a malleated, padded or trailing
+    signature; a test checks the two against each other.
+- **Trusting a delegation key (DL-14, CT-20).**
+  - `verify_delegation`, `verify_approval` and `delegation_gate` (and their Node twins) take `estate`: the current
+    verified revision, or a function that returns it.
+  - A token's `kid` is trusted only while that revision certifies it for a machine (same `kid` and key), does not
+    revoke it, and is within its window. Otherwise the token is refused with `kid-not-certified`.
+  - A record that cannot be read certifies nothing: `issuer-unavailable` with `estate-unreadable`.
+  - Without `estate`, nothing changes.
+  - `hub_key_certified` / `hubKeyCertified` answers the question on its own.
+- **Tests.**
+  - `test/fixtures/contract/estate-vectors.json` is generated by `make_estate_vectors.mjs` from the contract's own
+    functions and fixtures at the pin:
+    - 45 `verifyEstateRecord` cases, each re-answered against the contract's;
+    - 51 rule cases: the 38 semantic fixtures, the positive records, and strict-date and wrong-length edges;
+    - P-256 and passkey-key cases;
+    - the digest and challenge.
+
+    The private test keys of the contract's vectors are dropped: the kits only verify.
+  - Mutation testing: 42 planted defects, all caught.
+- **Independent review.** Nothing critical. The ES256 verifier matched OpenSSL on 3,300 signatures, and the Node
+  port matched the contract's TypeScript on 470 extra inputs.
+  - **One divergence that mattered, now fixed:** Python's `\d` matched a full-width digit in a date. A Python machine
+    would have applied a revision the contract refuses. Dates now take ASCII digits only.
+  - **`Number()` follows JavaScript.** Its whitespace, `0b`/`0o`/`0x`, and arrays are read as JavaScript reads them.
+  - **A verdict, never an exception**, for three inputs: deeply nested client data, a 400-digit revision, and a lone
+    surrogate in a pinned RP ID.
+  - **New vectors from the contract cover these:** 24 more rule cases.
+  - **The docs now require** that `estate` is a verified revision, and the highest one applied, since the rule trusts
+    the record it is given.
+
+### Changed
+
+- **The pin is `b291bf0`.** `0cacd08` stays supported. The compiled-schema checks pass for all three profiles against
+  the new pin.
+- **The settings canonical form refuses a lone surrogate in any string or key** (CT-25, DEC-0052), in both kits,
+  answering the contract's refusal vectors.
+- Docs: `references/estate-record.md` (new), `delegation.md` (*Keys the estate record certifies*), and `SKILL.md`.
+  The scenario eval `estate-record-and-certified-keys` and a trigger came first.
+
 ## 0.20.0 - 2026-10-12
 
 Runner routes in both kits: the closed probe results and the route checks FAC-SEM-028…034. These come from contract

package/README.md

@@ -8,7 +8,7 @@
 
 **Fabric Agent Adapter** makes any agent Fabric-compatible. Fabric is PassionCode.ai's
 product, the CEO AI agent: you talk to Fabric, and it chooses, binds and runs the agents that
-do the work. This adapter is how an agent becomes one Fabric can bind — three Agent Skills,
+do the work. This adapter is how an agent becomes one Fabric can bind — four Agent Skills,
 Python and Node reference kits and a live conformance probe for the
 [Fabric Agent Contract](https://github.com/passioncode-ai/fabric-agent-contract). It also works
 on its own: the skills, kits and probe need no Fabric install.
@@ -17,8 +17,33 @@ on its own: the skills, kits and probe need no Fabric install.
 [![validate](https://github.com/passioncode-ai/fabric-agent-adapter/actions/workflows/validate.yml/badge.svg)](https://github.com/passioncode-ai/fabric-agent-adapter/actions/workflows/validate.yml)
 [![license](https://img.shields.io/badge/license-AGPL--3.0%20or%20commercial-blue.svg)](LICENSE)
 
-The skills are `adapting-projects-to-fabric`, `creating-fabric-agents` and
-`building-fabric-services`.
+The skills are `adapting-projects-to-fabric`, `creating-fabric-agents`,
+`building-fabric-services` and `working-with-fabric`.
+
+`working-with-fabric` is for the other side: a coding agent (Claude Code, Codex, Kimi Code, Kilo, Hermes) opened in
+a terminal that works in a project through Fabric. It finds Fabric (`hub.json`, its `pid`), has the machine's
+lifecycle broker start it when it is down, registers `fabric-mcp` once with no secret, calls `fabric_whoami`
+first, reads the project board (`com.status`, `com.list`, `com.read_ack` only what was read) and asks other
+Projects only through `com.submit`, asks who is working on what and claims its task before it starts
+(`fabric_work_list`, `fabric_work_claim`, Fabric 0.4.0), links tasks to backlog rows instead of copying them, and
+releases at the end (`fabric_work_release`). `scripts/fabric_session.py status` prints where Fabric stands and one
+next action:
+
+```bash
+python3 plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py status
+```
+
+In Claude Code the plugin adds four session hooks: SessionStart puts that preamble into the session when the MCP
+server `fabric` is registered (one line pointing at the broker when Fabric is down), with the machine's
+Fabric-service count; Stop records each turn's facts (HEAD, files changed, lines added and removed — never content)
+and the board's unread count; UserPromptSubmit adds one line only when that count rose; SessionEnd releases what the
+session left claimed. Stop, UserPromptSubmit and SessionEnd act only when the running Fabric advertises
+`session-hooks/1`. All are silent in a session Fabric launched, never block the session, read no token and always
+exit 0. `fabric_session.py watch-mail` waits for board mail under a background watcher, and `install-host-hooks
+--host codex|kimi` adds the session-start preamble to Codex or Kimi Code (a dry run unless `--apply`). The
+[hooks reference](plugins/fabric-agent-adapter/skills/working-with-fabric/references/session-hooks.md) lists what
+they need from Fabric; the [board reference](plugins/fabric-agent-adapter/skills/working-with-fabric/references/project-board.md)
+is the board-first workflow.
 
 `building-fabric-services` makes an agent a long-lived local service with a dashboard
 that is always alive, runs as one copy, keeps its state through a reinstall and appears
@@ -40,12 +65,12 @@ box, sticky chrome at most 120 px — with seven WCAG AA themes (light and dark)
 `fabric_appearance` cookie. `scripts/dashboard_kit.py install|status` copies and checks it,
 `scripts/check_dashboard_layout.mjs` measures a rendered page in WebKit at 360, 480, 768 and 1280 px
 (Playwright; `NOT_RUN` without it), and the probe's `dashboard.declared` checks the declaration. The
-plugin's one hook (SessionStart) prints a single line in a repository whose dashboard has no kit or an
+plugin's dashboard-kit hook (SessionStart) prints a single line in a repository whose dashboard has no kit or an
 older one, and nothing anywhere else; the [kit reference](plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-kit.md)
 has the upgrade steps, taken only with the operator's go-ahead.
 
 Dashboard handoffs use the host-generated `open_link` as the primary action. The
-three skills carry the same [consumer procedure](plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-links.md)
+three builder skills carry the same [consumer procedure](plugins/fabric-agent-adapter/skills/building-fabric-services/references/dashboard-links.md)
 and a portable `scripts/check_dashboard_link.py` gate for generated renderers.
 It rejects primary HTTP when the host is available, failed-host browser fallback,
 and local links addressed to another device. A skill install alone does not filter
@@ -98,6 +123,7 @@ Generic Agent Skills clients:
 npx skills add passioncode-ai/fabric-agent-adapter --skill adapting-projects-to-fabric
 npx skills add passioncode-ai/fabric-agent-adapter --skill creating-fabric-agents
 npx skills add passioncode-ai/fabric-agent-adapter --skill building-fabric-services
+npx skills add passioncode-ai/fabric-agent-adapter --skill working-with-fabric
 ```
 
 ### Configure
@@ -178,6 +204,12 @@ Or, for an agent that does not exist yet:
 Create a new fabric-compatible agent for <capability>; its consumer is <who calls it>.
 ```
 
+Or, in a coding agent opened in a project folder:
+
+```text
+Work on backlog row FAA-18 through Fabric: check who is working here, claim it, and release it when done.
+```
+
 Or run the deterministic helper directly:
 
 ```bash
@@ -203,7 +235,7 @@ Scaffolding is non-destructive by default. It writes only the paths declared in
 The default pin for new bundles is [`fabric-contract.lock.json`](fabric-contract.lock.json):
 
 - version: `0.1.0`
-- commit: `0cacd08b0e95b6abf131eae1206b60792138bc3c`
+- commit: `b291bf09e0a9f9fd3c16cf540832cd021203b7d1`
 
 Every other mention of the default contract revision — this section, the skills' metadata, the
 skill card, `adapt_project.py` — must equal it; `python3 test/validate.py` fails a tree
@@ -230,8 +262,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.20.0. 0.19.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.20.0 is published by its `v0.20.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.21.0. 0.20.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.21.0 is published by its `v0.21.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -2,8 +2,8 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
-  "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.20.0",
+  "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
+  "version": "0.22.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "One line at session start in a repository whose Fabric dashboard has no dashboard kit or an older one (fabric-dashboard/0.1, DEC-0036). Silent everywhere else; reads only, never writes, always exits 0.",
+  "description": "Two silent-unless-relevant hook sets. The dashboard-kit notice: one line at session start in a repository whose Fabric dashboard has no kit or an older one (fabric-dashboard/0.1, DEC-0036). The Fabric session hooks (working-with-fabric, COM-04, FAA-12a): at session start the preamble when Claude Code has the MCP server `fabric` (fabric_whoami, then the project board through com.status and com.list, claim and release), and the machine's Fabric-service count; each turn's facts (HEAD, files changed, lines added and removed, never content), the board's unread count and the session's end through Fabric, only when the running Fabric advertises session-hooks/1; at each prompt one line only when the unread count rose. All silent in a session Fabric launched. Every hook reads no token, prints at most one block, always exits 0, and hands any Fabric call to a detached worker with a 10 s deadline.",
   "hooks": {
     "SessionStart": [
       {
@@ -11,6 +11,48 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/skills/working-with-fabric/scripts/fabric_session.py\" hook session-start",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/skills/working-with-fabric/scripts/fabric_session.py\" hook stop",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/skills/working-with-fabric/scripts/fabric_session.py\" hook session-end",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/skills/working-with-fabric/scripts/fabric_session.py\" hook user-prompt-submit",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,9 +5,9 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.20.0"
+  version: "0.22.0"
   contract-version: "0.1.0"
-  contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
+  contract-commit: "b291bf09e0a9f9fd3c16cf540832cd021203b7d1"
 ---
 
 # Adapting projects to Fabric
@@ -70,7 +70,7 @@ Use exactly:
 
 - contract version `0.1.0`;
 - repository `https://github.com/passioncode-ai/fabric-agent-contract`;
-- commit `0cacd08b0e95b6abf131eae1206b60792138bc3c`.
+- commit `b291bf09e0a9f9fd3c16cf540832cd021203b7d1`.
 
 This is the default for new bundles. When checking an issued legacy bundle, preserve its
 explicit supported lock and use that exact clean checkout. Never silently upgrade or

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/adapt_project.py

@@ -21,10 +21,10 @@ import fabric_secrets as _secrets  # noqa: E402 - the contract's credential dete
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "0cacd08b0e95b6abf131eae1206b60792138bc3c"
+CONTRACT_COMMIT = "b291bf09e0a9f9fd3c16cf540832cd021203b7d1"
 # #region supported-contract-revisions — docs: README.md#contract-pin
 # Only this declaration may name a legacy revision in live files.
-SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
 # #endregion supported-contract-revisions
 INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,10 +16,10 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.20.0"
+  version: "0.22.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
+  extension-commit: "b291bf09e0a9f9fd3c16cf540832cd021203b7d1"
 ---
 
 # Building Fabric services
@@ -83,7 +83,9 @@ are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 [`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs). When the callers are agents of the estate, the
 service checks each call's delegation token (DEC-0039): read [the delegation reference](references/delegation.md);
 the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
-[`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs). When Fabric chooses the service's runner and models
+[`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs). A service on the operator's machines that
+applies the estate record (DEC-0055) verifies each revision first and trusts only the keys it certifies: read
+[the estate record reference](references/estate-record.md). When Fabric chooses the service's runner and models
 (DEC-0046), or a project routes its work through an ordered list of runners (DEC-0026: the doctor's closed probe
 results, the route checks FAC-SEM-028…034), read [the profiles reference](references/profiles.md).
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/delegation.md

@@ -16,6 +16,7 @@ contract's own verifier does.
 - Approvals
 - What a refusal looks like
 - Keys and the cache
+- Keys the estate record certifies
 - What the kit does not do
 
 ## Declaring it
@@ -92,6 +93,19 @@ Python kit verifies Ed25519 itself (RFC 8032, standard library only, strict as O
 canonical points, no small-order key); it follows no redirect when it reads the key set; the Node kit uses `node:crypto` and refuses small-order keys
 itself (`isSmallOrderKey`), because Node before 26 lets OpenSSL accept a signature under one.
 
+## Keys the estate record certifies
+
+A verifier that also reads the estate's record (DEC-0055, [the estate record reference](estate-record.md)) trusts a
+`kid` only while a current revision certifies it for a machine and does not revoke it (DL-14). Pass the current
+verified revision as `estate=` / `{ estate }`, as a value or as a function returning it, to `delegation_gate`,
+`verify_delegation` or `verify_approval`.
+- An uncertified `kid` is refused `unauthenticated` (`approval-invalid` for an approval), with detail
+  `kid-not-certified`.
+- An unreadable record is refused `issuer-unavailable`, with detail `estate-unreadable`.
+- Without `estate`, nothing changes.
+- Pass only a revision `verify_estate_record` accepted, and the highest one the machine has applied. The rule trusts
+  what it is given, so an unverified or older revision would certify a key the current one revoked.
+
 ## What the kit does not do
 
 It does not mint tokens, check attenuation against a parent (the issuer's rule, DL-5), check a grant or a spend

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md

@@ -0,0 +1,90 @@
+# The estate record — what the operator's machines are, signed by their passkey (DEC-0055)
+
+Fabric Agent Contract DEC-0055, `docs/specification/estate-record.md`, schema `schemas/estate-record.schema.json`,
+rules `FAC-SEM-072…076`. One revision of one person's estate lists:
+- the passkeys that sign it;
+- the machines, with their device keys and a certificate of each machine's hub key;
+- the packages placed on each machine;
+- where each secret slot is filled from (by reference only);
+- share grants and revocations.
+
+A revision names its parent's digest and is signed by a passkey assertion (WebAuthn Level 3) over a challenge
+derived from its own digest. Python: [`scripts/fabric_estate.py`](../scripts/fabric_estate.py). Node:
+[`scripts/fabric-estate.mjs`](../scripts/fabric-estate.mjs). Both answer the contract's own vectors.
+
+## Contents
+
+- Applying a revision
+- Trusting a delegation key
+- Checking a record you produce
+- What the kit does not do
+
+## Applying a revision
+
+A machine applies a revision only when it is valid against `estate-record.schema.json` **and** the verifier accepts
+it. The verifier does not check the schema.
+
+```python
+verdict = fe.verify_estate_record(record, at=datetime.now(timezone.utc), parent=current)   # revision 2 and later
+verdict = fe.verify_estate_record(record, at=now, authorities=pinned_passkeys)             # revision 1
+if verdict["ok"]:
+    current = record          # verdict: digest, revision, signedBy, signCount
+```
+
+```js
+const verdict = verifyEstateRecord(record, { at: new Date(), parent: current });
+```
+
+It checks, in the order of the ER table:
+1. **The clock.** An unreadable one is `no-clock`, and it comes first.
+2. **The shape.**
+3. **The digest.** SHA-256 over the RFC 8785 form, without `digest` and `signature`.
+4. **The chain to the parent.** Same estate, the next revision number, the parent's digest, never issued before the
+   parent, and no revocation dropped.
+5. **The signer.** The signing passkey must be among the trusted ones and not revoked by the parent. A revision may
+   revoke its own signer: that is rotation.
+6. **The assertion.**
+   - Client data: type, challenge, origin, no cross-origin use.
+   - The RP ID hash, and the user-presence and user-verification flags.
+   - The signature: ES256 or EdDSA, under a key validated first (a valid P-256 point; an Ed25519 key of full order).
+7. **The window.** At most 30 days.
+8. **The record's own rules.** A violation is `rule-violation` with its `codes`.
+
+Dates are strict RFC 3339: a `T`, an offset, and a day that exists. `:60` and a space are refused. Passkey JWK `x`
+and `y` must be canonical base64url. The Python kit verifies ES256 in pure Python (P-256, strict DER), and the Node
+kit through `node:crypto`.
+
+## Trusting a delegation key
+
+A delegation verifier that reads the estate record trusts a token's `kid` only while a current revision certifies it
+for a machine and does not revoke it (DL-14, contract CT-20). Give the gate the current verified revision, or a
+function that returns it:
+
+```python
+gate = fd.delegation_gate(audience=..., jwks=keys, issuer=..., effects=..., estate=lambda: current)
+```
+
+- A `kid` the record does not certify is refused like an unknown key: `unauthenticated` (for an approval,
+  `approval-invalid`) with detail `kid-not-certified`. The same holds when the record names another key under that
+  kid, revokes it, or is outside its window.
+- A record that cannot be read certifies nothing: `issuer-unavailable` with detail `estate-unreadable`.
+- **What you pass in.** Pass only a revision that `verify_estate_record` accepted, and the highest revision the
+  machine has applied. The rule trusts the record it is given. A record nobody verified, or an older revision still
+  inside its window, would certify a key the current revision revoked (a rollback).
+- `hub_key_certified(record, kid, x, at)` / `hubKeyCertified(...)` answers the question on its own.
+
+## Checking a record you produce
+
+`estate_record_rules(kind, value)` / `estateRecordRules(kind, value)` are the contract's rules, finding for finding:
+- `estate-record` (FAC-SEM-072…076);
+- `estate-record-revision` `{parent, next}` (072);
+- `estate-placement` `{record, machine, package}` (074, 075).
+
+`placement_trust(record, machine, agentRef)` names the publisher keys a package verifier trusts for a placed package.
+
+## What the kit does not do
+
+- It does not sign: it holds no passkey and no private key.
+- It does not check the schema or verify packages.
+- It does not attest the authenticator (an assertion carries no attestation).
+- It does not track the signature counter: passkeys sync between devices.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -1,6 +1,6 @@
 # fabric-service/0.1 — wire reference
 
-Pinned to `fabric-agent-contract` commit `0cacd08b0e95b6abf131eae1206b60792138bc3c`
+Pinned to `fabric-agent-contract` commit `b291bf09e0a9f9fd3c16cf540832cd021203b7d1`
 (`docs/specification/service.md`, DEC-0015; the usage report DEC-0021; Windows and Linux supervision
 DEC-0032 and DEC-0033; the operator channel DEC-0034 and DEC-0035; the embedded dashboard DEC-0036;
 delegation and the operator session's lifetime DEC-0039; the meter's call window DEC-0041; session handoff DEC-0042;

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-delegation.mjs

@@ -14,6 +14,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
+import { hubKeyCertified } from './fabric-estate.mjs';
 
 export const REFUSAL_CODES = Object.freeze([
   'unauthenticated', 'token-expired', 'wrong-audience', 'scope-not-granted', 'effect-above-ceiling', 'no-grant',
@@ -252,11 +253,30 @@ function approvalShape(payload) {
  * DL-13, in its fixed order: nothing about a token is believed before its signature is. `now` is seconds since
  * the epoch. Answers {ok: true, claims, principal, caller, chain, kid} or {ok: false, code, detail}.
  */
-export function verifyDelegation(token, { audience, jwks, now, capability, effect, issuer, readOnly } = {}) {
+/**
+ * DL-14 with DEC-0055: a verifier that reads the estate record trusts a kid only while a current revision certifies it
+ * for a machine and does not revoke it. `estate` is a revision the caller verified (fabric-estate.mjs
+ * verifyEstateRecord) or a function returning the current one; undefined skips the rule. `[kind, detail]` or null.
+ */
+function estateProblem(estate, jwks, kid, now) {
+  if (estate === undefined || estate === null) return null;
+  let record;
+  try {
+    record = typeof estate === 'function' ? estate() : estate;
+  } catch {
+    return ['issuer', 'estate-unreadable']; // an unreadable record certifies nothing; it is never a pass
+  }
+  const jwk = jwks.keys.find((candidate) => isObject(candidate) && candidate.kid === kid) ?? {};
+  return hubKeyCertified(record, kid, jwk.x, now) ? null : ['token', 'kid-not-certified'];
+}
+
+export function verifyDelegation(token, { audience, jwks, now, capability, effect, issuer, readOnly, estate } = {}) {
   if (!isString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
   if (!hasKeys(jwks)) return refuse('issuer-unavailable', 'no-published-keys');
   const checked = authentic(token, jwks, DELEGATION_TYP);
   if ('problem' in checked) return refuse(checked.issuer ? 'issuer-unavailable' : 'unauthenticated', checked.problem);
+  const uncertified = estateProblem(estate, jwks, checked.kid, now);
+  if (uncertified) return refuse(uncertified[0] === 'issuer' ? 'issuer-unavailable' : 'unauthenticated', uncertified[1]);
   const shaped = delegationShape(checked.compact.payload);
   if ('problem' in shaped) return refuse('unauthenticated', shaped.problem);
   const { claims, depth } = shaped;
@@ -275,13 +295,15 @@ export function verifyDelegation(token, { audience, jwks, now, capability, effec
 }
 
 /** DL-18: approval-required carries the digest; any fault is approval-invalid; the jti is consumed last. */
-export function verifyApproval(approval, { audience, jwks, now, actionDigest: expected, issuer, jtiStore } = {}) {
+export function verifyApproval(approval, { audience, jwks, now, actionDigest: expected, issuer, jtiStore, estate } = {}) {
   if (approval === undefined || approval === null || approval === '') return refuse('approval-required', 'no-approval', { actionDigest: expected });
   if (!isObject(jtiStore) || typeof jtiStore.consume !== 'function') return refuse('unknown-state', 'no-jti-store');
   if (!isString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
   if (!hasKeys(jwks)) return refuse('issuer-unavailable', 'no-published-keys');
   const checked = authentic(approval, jwks, APPROVAL_TYP);
   if ('problem' in checked) return refuse(checked.issuer ? 'issuer-unavailable' : 'approval-invalid', checked.problem);
+  const uncertified = estateProblem(estate, jwks, checked.kid, now);
+  if (uncertified) return refuse(uncertified[0] === 'issuer' ? 'issuer-unavailable' : 'approval-invalid', uncertified[1]);
   const claims = approvalShape(checked.compact.payload);
   if (!claims) return refuse('approval-invalid', 'malformed-claims');
   if (claims.iss !== issuer) return refuse('approval-invalid', 'wrong-issuer');
@@ -447,7 +469,7 @@ export const TIERS = Object.freeze(['T0', 'T1', 'T2']);
  * relayed from off the machine). A T0 or T1 caller is never required to present a token: with none, the call passes
  * with no delegation. A present token is verified at every tier. `issuer` (auth.delegation.issuer) is required.
  */
-export function delegationGate({ audience, jwks, effects, issuer, readOnly = false, clock = () => Date.now() / 1000 }) {
+export function delegationGate({ audience, jwks, effects, issuer, readOnly = false, clock = () => Date.now() / 1000, estate }) {
   if (!isString(issuer)) throw new Error('the gate needs the issuer it trusts (auth.delegation.issuer)');
   return async (tool, headers, tier = 'T2') => {
     const effect = effects?.[tool];
@@ -458,7 +480,7 @@ export function delegationGate({ audience, jwks, effects, issuer, readOnly = fal
       return refuse('unauthenticated', 'no-token');
     }
     const keys = jwks instanceof JwksCache ? await jwks.get(kidOf(carried.token)) : jwks;
-    const verdict = verifyDelegation(carried.token, { audience, jwks: keys, now: clock(), capability: tool, effect, readOnly, issuer });
+    const verdict = verifyDelegation(carried.token, { audience, jwks: keys, now: clock(), capability: tool, effect, readOnly, issuer, estate });
     if (verdict.ok) verdict.tier = TIERS.includes(tier) ? tier : 'T2';
     return verdict;
   };