@passioncode-ai/fabric-agent-adapter 0.35.4 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.37.0 - 2026-10-19
+
+### Added
+
+- **`creating-fabric-agents` carries what the estate learned about building agents** (FAA-58, the operator's request
+  of 2026-10-19): four new references every new agent starts from.
+  - `where-agents-run.md`: this machine, a personal cloud, an organization, Enterprise; contexts (`personal`,
+    `org:<id>`) with one instance per context and no secret, spend or journal crossing; connecting a machine (nearby
+    code, headless enroll token); sharing an agent into an organization; running while the laptop is closed; selling
+    an agent (a paid agent in its developer's organization, a partner's setup).
+  - `models-and-providers.md`: lanes with a fallback of another vendor and an open-vendor model where users' content is
+    read; a dated starting choice from the OpenRouter catalog; several kinds of input and output; budgets that survive
+    reasoning; one OpenRouter key per agent and context with its ceiling, read from the environment; measuring a choice.
+  - `orchestration-and-learning.md`: workflow first; the work graph of durable jobs with intent keys, effects observed,
+    limits as pauses (DEC-0087); calling other agents within a narrower grant and budget; stops for a person; learning
+    loops (decisions with reasons, one trace per turn, failures as planted fixtures first, history replayed, learnings
+    proposed and never self-approved); the loop guard.
+  - `practices.md`: the rules production agents taught us, each with its check: judges and evals, numbers, money,
+    people in the loop, reliability, shipping.
+- The intake grill asks **Where does it run, for whom?**, **Which models?**, **Who pays?** and **How does it learn?**;
+  the knowledge intake links the four references. `test/validate.py` holds the rows, the links and each reference's
+  checklist (`KnowledgePackTests`); eval scenario `agent-for-a-personal-and-an-organization-cloud`; three trigger
+  queries.
+
+## 0.36.0 - 2026-10-19
+
+Repinned to Fabric Agent Contract `07042181bfae2a481aa0da1a5651f24c76669c48` (DEC-0084 to DEC-0088); `d8146cf` stays
+supported, so bundles issued under it stay valid. DEC-0085 and DEC-0088 (entitlements) are the platform's and the
+organization server's, not the kits'.
+
+### Added
+
+- **Jobs under limits and uncertain effects, in both interop kits** (FAA-56, contract DEC-0087, FAC-SEM-119/120): a job a
+  limit paused stays `working` with `quota-exhausted until <instant>` (`jobs.pause`); a job a limit stopped ends
+  `quota-exhausted` with `data: {retryable, resetsAt?}` (`jobs.quota_exhausted`); an effect nobody saw ends
+  `outcome-unknown` (`jobs.outcome_unknown`). Idempotency keys are kept per authenticated caller and a repeated key is
+  answered by its job (`jobs.repeat`): a limited job runs again once the limit no longer holds, an `outcome-unknown` one
+  never. Usage nobody measured is `null` only toward a caller that names `fabric-interop/0.2` (`usage_toward`). As a
+  caller: `request_meta`, `job_caller_action`, `intent_idempotency_key`. Held to the contract's `job-limits.json`.
+- **Share grants into an organization** (contract DEC-0086): new `fabric_share.py` / `fabric-share.mjs` with FAC-SEM-117
+  (a share grant id, a millisecond window, one agentRef kept against the parent revision), FAC-SEM-118 (a
+  `share-registration/1` document) and FAC-SEM-045's `grant.usage` context clause; `share-registration.schema.json`
+  vendored self-contained.
+- **The estate ceremonies** (contract DEC-0084): in both estate kits FAC-SEM-114 (what a revision drops it revokes in the
+  same revision), FAC-SEM-073 (a device key in canonical base64), FAC-SEM-076 (a key reference
+  `<kid>@sha256:<hex>`), `device_key_fingerprint`, `device_key_ref`, and `verify_estate_record(..., parent=)` runs
+  FAC-SEM-114. New `fabric_ceremonies.py` / `fabric-ceremonies.mjs`: `verify_enroll_token`, `enroll_join_input`,
+  FAC-SEM-113. Pairing and the hub's single use of a token follow in FAA-57.
+- **A partner's setup for a company** (FAA-55, the partner channel's PA-07): documented and tested as an org skill set
+  whose `requires.packages` names the agents, every package signed with the partner's key. No new format.
+
+### Changed
+
+- **FAC-SEM-034** in both profile kits compares the probes before it builds a list and names at most 64 candidates, so a
+  huge index allocates nothing (the contract's fix of this repository's report).
+- **The protocol register** in both service kits matches the contract's: `enroll-token`, `entitlement`,
+  `entitlement-key-set`, `pairing-message`, `share-registration`, `share-registration-receipt`, and `fabric-interop/0.2`.
+
 ## 0.35.4 - 2026-10-19
 
 ### Changed

package/README.md

@@ -254,7 +254,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: `d8146cfb0a1c74fc6432284c4356bb0c864b37b5`
+- commit: `07042181bfae2a481aa0da1a5651f24c76669c48`
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.35.4",
+  "version": "0.37.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

@@ -3,7 +3,7 @@
   "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; 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.35.4",
+  "version": "0.37.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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.35.4"
+  version: "0.37.0"
   contract-version: "0.1.0"
-  contract-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
+  contract-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
 ---
 
 # 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 `d8146cfb0a1c74fc6432284c4356bb0c864b37b5`.
+- commit `07042181bfae2a481aa0da1a5651f24c76669c48`.
 
 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 = "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
+CONTRACT_COMMIT = "07042181bfae2a481aa0da1a5651f24c76669c48"
 # #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, "82e163665e156a08aa3b92e4711015582c06162c", "1636fa97262f4a26e2086572d540c2ee701e0010", "f00a7685e3861c27f7899c033fb850a145a1708f", "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b", "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "0cacd08b0e95b6abf131eae1206b60792138bc3c", "2eb91c00e852d9c31d804310d38fad91589fcbac", "8e49fbd5fbbf230e32c1969cd24ac3c22422f0a5", "a83bec6b47776af688402c18efec507143061f68", "52da526d7cc1e063d74c5b520dbc03d0ace15246", "78b2da018d2c4bd9ac1bde1dc3b7f1a110a175f5", "623bf61358c339cb10297807b3f024b5d9f1f327", "23f9fda4c05f8a3852246ee98d4f2adf74ed0875", "9091d3d6606b0c4b5591a38c3674356a01fd7f55", "df55c8c54a23251342a7ee57ba95642b7eb39e61", "2ce392291c6668598d12cd38327e24696b5ca15c")
+SUPPORTED_CONTRACT_COMMITS = (CONTRACT_COMMIT, "d8146cfb0a1c74fc6432284c4356bb0c864b37b5", "82e163665e156a08aa3b92e4711015582c06162c", "1636fa97262f4a26e2086572d540c2ee701e0010", "f00a7685e3861c27f7899c033fb850a145a1708f", "a046f57cf46ea9e3da57ff8ce6a3ed4d26d8774b", "fe55fc67cba1a9e34a736da7d148d4fe2a8fbfa0", "b291bf09e0a9f9fd3c16cf540832cd021203b7d1", "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

@@ -18,10 +18,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.35.4"
+  version: "0.37.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
-  extension-commit: "d8146cfb0a1c74fc6432284c4356bb0c864b37b5"
+  extension-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
 ---
 
 # Building Fabric services
@@ -79,7 +79,8 @@ MCP registration into a client config, the login flow or the CSRF header.
 
 When other agents or Fabric call the service over MCP, it follows `fabric-interop/0.1`:
 each manifest capability is the tool of its name, long work is a job with a stable id,
-a question for a person is an elicitation, and every call carries one trace. Read
+a question for a person is an elicitation, and every call carries one trace. A job a limit stops or pauses, and an
+effect nobody saw, have their own codes and a key per caller (DEC-0087). Read
 [the interop reference](references/interop.md) before writing an MCP tool; the helpers
 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
@@ -87,7 +88,9 @@ service checks each call's delegation token (DEC-0039): read [the delegation ref
 the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
 [`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, and runs an
-agent once per context, the person's or an organization's (DEC-0082): read
+agent once per context, the person's or an organization's (DEC-0082), and checks a share grant into an organization
+with [`scripts/fabric_share.py`](scripts/fabric_share.py) (DEC-0086); a revision's ceremonies and a headless
+machine's enroll token are in [`scripts/fabric_ceremonies.py`](scripts/fabric_ceremonies.py) (DEC-0084): 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/estate-record.md

@@ -18,6 +18,8 @@ derived from its own digest. Python: [`scripts/fabric_estate.py`](../scripts/fab
 - Applying a revision
 - Trusting a delegation key
 - Contexts: one agent for you and for an organization
+- The estate ceremonies
+- Share grants into an organization
 - Checking a record you produce
 - What the kit does not do
 
@@ -116,6 +118,49 @@ Every rule is total on hostile JSON, as the contract's are: an `instancePath` na
 non-object before it does not shift it), and a value whose own `toString` member is data is shown as its JSON. Both kits
 answer the contract's contexts fixtures and variants of them (`test/fixtures/contract/estate-vectors.json`).
 
+## The estate ceremonies
+
+Contract DEC-0084: create a network, add a machine nearby (a six-digit comparison code) or headless (an enroll token),
+remove a machine, replace a machine's key. Fabric runs the ceremonies and signs every revision with the person's
+passkey; what a service applying the record checks is in the record itself:
+
+- **What a revision drops, it revokes in the same revision (FAC-SEM-114).** A removed machine is listed as
+  `machine <id>` in `revocations`, and its hub key as `hub-key <kid>`; a replaced device key is revoked by its key
+  reference, `<kid>@sha256:<hex of its octets>` (`device_key_ref` / `deviceKeyRef`), so the new key under the same kid
+  stays usable; a hub key certified anew takes a new kid. `verify_estate_record(record, at=..., parent=previous)` runs it
+  when you pass the parent; `estate_record_rules("estate-record-revision", {"parent", "next"})` alone.
+- **A device key's octets are canonical padded base64 (FAC-SEM-073),** the one form a key reference can name
+  (`device_key_fingerprint`), and a `device-key` revocation that holds `@` is a well-formed key reference (FAC-SEM-076).
+- **A headless machine joins with an `enroll-token/1`** (`fabric_ceremonies.py`, `fabric-ceremonies.mjs`). Read the token
+  from stdin or a file only your user can read, never from argv, a URL or a log. `verify_enroll_token(token, record=,
+  genesis=, at=)` checks it against the revision you applied and revision 1's digest; sign `enroll_join_input(token)`
+  with the machine's `#sig` key and present that proof with the token. The token gives the machine no trust: only the
+  passkey-signed revision that lists it does. `enroll_token_rules("enroll-token", token)` is FAC-SEM-113.
+
+The nearby pairing (`pairing-message/1`, the comparison code, the rendezvous) and the hub's single use of a token are
+Project Observatory's node and Fabric's hub; the kits port them in a later version (FAA-57). The relay's admission and
+session checks belong to the relay; the kits do not run a relay.
+
+## Share grants into an organization
+
+Contract DEC-0086. A grant whose `context` is an organization's (`org:<orgId>`) is a share grant, and the organization
+server joins every `grant.usage` to the agent it runs through a share registration the sharer's node sends. Before you
+sign a revision that places one, run `fabric_share.py` (`fabric-share.mjs`):
+
+- `share_rules("org-share-grants", {"record": next, "parent": previous})`: FAC-SEM-117. The grant's `meta.id` is
+  `urn:fabric:share:` and 32 lower-case hex digits from a CSPRNG (`secrets.token_hex(16)`), never a name, an address or an
+  estate id; its window carries at most three fraction digits; the placements naming it run one `agentRef`; and against
+  `parent`, the latest earlier revision that placed it, that `agentRef` never changes. To move a share to another agent,
+  revoke the grant and mint a new id.
+- `share_rules("grant", grant)`: FAC-SEM-110 and 117 on one grant.
+- `share_rules("share-registration", doc)`: FAC-SEM-118 on a `share-registration/1` document you read or log.
+- `share_rules("device-attribution", {binding, batch})`: FAC-SEM-045's DEC-0086 clause, for a collector that sends
+  `grant.usage`: each carries its grant's own context, `org:` and the certificate's `org.id` as written.
+
+`share-registration.schema.json` beside the kit is the contract's schema with `shareGrantId`, `orgContextId`,
+`sha256` and `agentRef` brought in, so it validates offline. Deriving, sending, deciding and joining registrations are the
+sharer's node's and the organization server's, not this kit's.
+
 ## Checking a record you produce
 
 `estate_record_rules(kind, value)` / `estateRecordRules(kind, value)` are the contract's rules, finding for finding:

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

@@ -23,6 +23,12 @@ The interop block sits in the manifest under the capability's `extensions`:
 
 That key has one spelling (the contract's `src/extensions.ts`); copy it, never retype it.
 
+## Contents
+
+- [The kit](#the-kit)
+- [Limits and uncertain effects](#limits-and-uncertain-effects)
+- [What the probe checks](#what-the-probe-checks)
+
 ## The kit
 
 ```python
@@ -41,7 +47,8 @@ response = server.handle(json_rpc_message)          # POST /mcp body in, JSON re
   stops for a person. Fabric answers through `fabric.job.get` with `inputResponses`; the
   server calls `on_input(job_id, answers, ctx)` with the answers that matched.
 - `jobs.complete(job_id, fi.result_envelope(outcome=..., producer=..., ...))`,
-  `jobs.fail(job_id, code, message)`, `jobs.cancel(job_id)`. A terminal job never changes
+  `jobs.fail(job_id, code, message, data=None)`, `jobs.cancel(job_id)`; a limit or an unseen effect has its own calls
+  ([Limits and uncertain effects](#limits-and-uncertain-effects)). A terminal job never changes
   again. A result with unverified claims is `partial`, never `succeeded`.
 - The envelope's `trace` is authoritative for a stored result (DEC-0017): `complete` fills
   it with the span of the call that started the job and refuses one naming another span,
@@ -77,6 +84,35 @@ claude -p "Reply with the single word OK." --strict-mcp-config --mcp-config "$TM
 
 The first `system/init` event lists `mcp_servers` (`connected`) and the `mcp__<server>__*` tools.
 
+## Limits and uncertain effects
+
+Contract DEC-0087 (`FAC-SEM-119`, `FAC-SEM-120`). A limit and an effect nobody saw are not ordinary failures: a caller
+that submits again pays twice. Both kits (`fabric_interop.py`, `fabric-interop.mjs`) carry the contract's functions,
+answer for answer (`test/fixtures/contract/job-limit-vectors.json`).
+
+As a provider:
+
+- **A limit paused the job and you will resume it:** `jobs.pause(job_id, resets_at=..., text=...)` keeps it `working`
+  with `statusMessage` `quota-exhausted until <UTC instant>: <text>` and sets `pollIntervalMs` to reach the reset,
+  at most an hour. An instant with an offset, more than three fraction digits or a day that does not exist is refused.
+- **A limit stopped it and you will not resume it:** `jobs.quota_exhausted(job_id, message, retryable, resets_at=None)`
+  ends it `failed` with `quota-exhausted` and `data: {retryable, resetsAt?}`; `resetsAt` only with `retryable: True`.
+- **The effect may have happened and you cannot see whether:** `jobs.outcome_unknown(job_id, message, data)`. Its key
+  never runs again; only an observed result settles it.
+- **Keys per caller.** `jobs.create(..., caller=<authenticated caller>, idempotency_key=<key>)` keeps the key for that
+  caller only. A key that already names a job starts nothing; `jobs.repeat(caller, key, now)` answers `new`, `same`
+  (answer with that job) or `run`: a `quota-exhausted` job runs again once its reset passed or you pass
+  `limit_holds=False`, a `limit-reached` job once `approval_granted=True`, and an `outcome-unknown` job never.
+- **Usage you did not measure is `null`, never 0,** but only toward a caller whose request `_meta.protocols` names
+  `fabric-interop/0.2`: pass `request_meta` to `result_envelope` (`usage_toward`). Toward any other caller the kit
+  writes the measured lower bound, as before.
+
+As a caller: send `request_meta(traceparent)` as your `_meta` (it names `fabric-interop/0.1` and `0.2`), act on every
+`fabric.job.get` answer as `job_caller_action(answer, now)` says, and resend only under
+`intent_idempotency_key({agentId, capability, input})`, never a new key. Node names are the camelCase twins
+(`jobs.quotaExhausted(id, message, {retryable, resetsAt})`, `jobCallerAction`, `intentIdempotencyKey`). The guidance
+for an agent's own design is in `creating-fabric-agents/references/resilience-and-autonomy.md`.
+
 ## What the probe checks
 
 `check_service.py` adds these rules; they read, and never call a capability.

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

@@ -12,6 +12,7 @@ Contract DEC-0050 (format and digest), DEC-0051 (signatures), DEC-0071 and DEC-0
 - [sign](#sign)
 - [verify](#verify)
 - [A consumer agent](#a-consumer-agent)
+- [A partner's setup for a company](#a-partners-setup-for-a-company)
 - [What this version does not do](#what-this-version-does-not-do)
 
 ## What a package is
@@ -92,6 +93,18 @@ by role and tools. A role names the secret slots that configure its server (`sec
 `secrets[]`, one slot to one role. Before installing, `consumer_placement(pkg, configured)` / `consumerPlacement(pkg,
 Map)` names each role the placement does not register and each tool its server lacks.
 
+## A partner's setup for a company
+
+A partner who builds agents for a company ships them without a new format (FAA-55, the partner channel's PA-07). Each
+agent is its own `kind: agent` package. The setup is one `kind: skill-set` package at `layer: org`: the company's own
+skills (house style, procedures), with `requires.packages` naming every agent it sets up by `publisher`, `id` and a
+version `range`. The partner packs and signs every package with its own publisher key (`sign --key`); the company's
+machine pins that key and `verify` refuses a package signed by any other. One signed package serves every company: what
+differs per company (a display name, a brand, an address) is placement configuration, never a second package.
+
+Still to come, each waiting on its owner: trusting a partner's key for one organization only (contract CT-58), a
+partner's own space in a catalog and publishing to it (FAA-44, Vesta PA-03).
+
 ## What this version does not do
 
 - **ES256.** It waits for Fabric's decision D2; until then a verifier refuses it as `unknown-algorithm` (FAA-29).

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 `d8146cfb0a1c74fc6432284c4356bb0c864b37b5`
+Pinned to `fabric-agent-contract` commit `07042181bfae2a481aa0da1a5651f24c76669c48`
 (`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-ceremonies.mjs

@@ -0,0 +1,129 @@
+// The estate ceremonies' headless join (contract DEC-0084), the Node kit; the twin of fabric_ceremonies.py, answer for
+// answer (test/fixtures/contract/ceremony-vectors.json). Node built-ins only.
+// verifyEnrollToken (the hub's and the node's verifier of an enroll-token/1), enrollJoinInput (what the joining machine
+// signs with its #sig key) and enrollTokenRules (FAC-SEM-113). A token gives the machine no trust: only a passkey-signed
+// revision that lists it does. Read it from stdin or a 0600 file, never argv, a URL or a log. Every function answers and
+// never throws on malformed input. Normative source: the contract's src/enroll-token.ts and src/signing-challenges.ts.
+// #region ceremonies-kit-node, docs: plugins/fabric-agent-adapter/skills/building-fabric-services/references/estate-record.md#the-estate-ceremonies
+
+import crypto from 'node:crypto';
+import { jcs } from './fabric-delegation.mjs';
+import { CLOCK_SKEW_SECONDS, estateTime, isSigningRpId, originWithin, verifyAssertion } from './fabric-estate.mjs';
+
+export const ENROLL_TOKEN_SCHEMA = 'enroll-token/1';
+export const ENROLL_TOKEN_TYPE = 'enroll-token/1';
+export const ENROLL_JOIN_TYPE = 'enroll-join/1';
+export const ENROLL_PURPOSE = 'agent-host';
+export const MAX_ENROLL_TOKEN_SECONDS = 900;
+export const ENROLL_TOKEN_FIELDS = Object.freeze(['scope', 'genesis', 'purpose', 'ceiling', 'notBefore', 'expiresAt', 'nonce', 'uses']);
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const ESTATE_SCOPE = /^estate:[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}$/;
+const NONCE32 = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+const ASSERTION_MEMBERS = 'alg,authenticatorData,clientDataJSON,credentialId,format,sig';
+
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === 'string';
+const matches = (pattern, value) => isString(value) && pattern.test(value);
+const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
+const show = (value) => {
+  if (typeof value === 'string') return value;
+  try { return String(value); } catch { return JSON.stringify(value) ?? typeof value; }
+};
+const REGISTER = new Map([
+  [ENROLL_TOKEN_TYPE, { fields: ENROLL_TOKEN_FIELDS, check: (f) => matches(ESTATE_SCOPE, f.scope) && matches(SHA256, f.genesis) && f.purpose === ENROLL_PURPOSE
+    && (f.ceiling === null || matches(SHA256, f.ceiling)) && Number.isFinite(estateTime(f.notBefore)) && Number.isFinite(estateTime(f.expiresAt)) && matches(NONCE32, f.nonce) && f.uses === 1 }],
+  [ENROLL_JOIN_TYPE, { fields: ['digest', 'nonce'], check: (f) => matches(SHA256, f.digest) && matches(NONCE32, f.nonce) }],
+]);
+
+/** The bytes of a registered statement (DEC-0063), for enroll-token/1 and enroll-join/1; undefined otherwise. */
+export function signingStatement(type, fields) {
+  const spec = REGISTER.get(type);
+  if (!spec || !isObject(fields)) return undefined;
+  const names = Object.keys(fields);
+  if (names.length !== spec.fields.length || !spec.fields.every((name) => Object.hasOwn(fields, name)) || !spec.check(fields)) return undefined;
+  try { return Buffer.from(jcs({ ...fields, type }), 'utf8'); } catch { return undefined; }
+}
+
+function statementFields(token) {
+  if (!isObject(token) || token.schema !== ENROLL_TOKEN_SCHEMA || !isObject(token.statement) || token.statement.type !== ENROLL_TOKEN_TYPE) return undefined;
+  // The token holds exactly the schema's members: nothing unsigned rides beside the statement (DEC-0084).
+  if (Object.keys(token).sort().join() !== 'schema,signature,statement') return undefined;
+  const { type: _type, ...fields } = token.statement;
+  return signingStatement(ENROLL_TOKEN_TYPE, fields) ? fields : undefined;
+}
+
+/** The reference verifier of an enroll-token/1 under trust {record, genesis, at: Date}; the first failure answers. */
+export function verifyEnrollToken(token, trust) {
+  const at = isObject(trust) && trust.at instanceof Date ? trust.at.getTime() : Number.NaN;
+  if (!Number.isFinite(at)) return { ok: false, problem: 'no-clock' };
+  const fields = statementFields(token);
+  const record = trust.record;
+  if (!fields || !isObject(record) || !isString(record.estate)) return { ok: false, problem: 'malformed' };
+  const { signature } = token;
+  if (!isObject(signature) || Object.keys(signature).sort().join() !== ASSERTION_MEMBERS || signature.format !== 'webauthn-assertion' || !isString(signature.credentialId)) return { ok: false, problem: 'malformed' };
+  if (fields.scope !== `estate:${record.estate}` || fields.genesis !== trust.genesis) return { ok: false, problem: 'wrong-estate' };
+  const authorities = list(record.authorities);
+  if (authorities.length === 0) return { ok: false, problem: 'no-trusted-authority' };
+  if (list(record.revocations).some((entry) => entry.kind === 'authority' && entry.ref === signature.credentialId)) return { ok: false, problem: 'revoked-authority' };
+  const found = authorities.filter((entry) => entry.credentialId === signature.credentialId);
+  if (found.length > 1) return { ok: false, problem: 'duplicate-authority' };
+  const authority = found[0];
+  if (!authority) return { ok: false, problem: 'unknown-authority' };
+  const rpId = show(authority.rpId);
+  if (!isSigningRpId(rpId)) return { ok: false, problem: 'wrong-rp' };
+  const credential = {
+    credentialId: signature.credentialId, alg: show(authority.alg), publicKey: isObject(authority.publicKey) ? authority.publicKey : {}, rpId,
+    origins: Array.isArray(authority.origins) ? authority.origins.filter((origin) => isString(origin) && originWithin(origin, rpId)) : [],
+  };
+  const challenge = crypto.createHash('sha256').update(signingStatement(ENROLL_TOKEN_TYPE, fields)).digest();
+  const assertion = verifyAssertion(signature, credential, challenge);
+  if (!assertion.ok) return { ok: false, problem: assertion.problem };
+  const notBefore = estateTime(fields.notBefore);
+  const expiresAt = estateTime(fields.expiresAt);
+  if (expiresAt <= notBefore || expiresAt - notBefore > MAX_ENROLL_TOKEN_SECONDS * 1000) return { ok: false, problem: 'too-long-lived' };
+  if (at < notBefore - CLOCK_SKEW_SECONDS * 1000) return { ok: false, problem: 'not-yet-valid' };
+  if (at > expiresAt) return { ok: false, problem: 'expired' };
+  return { ok: true, nonce: fields.nonce, expiresAt: fields.expiresAt, signedBy: credential.credentialId };
+}
+
+/** The enroll-join/1 statement the joining machine signs with its #sig key; undefined without a register statement. */
+export function enrollJoinInput(token) {
+  const fields = statementFields(token);
+  const statement = fields && signingStatement(ENROLL_TOKEN_TYPE, fields);
+  if (!fields || !statement) return undefined;
+  return signingStatement(ENROLL_JOIN_TYPE, { digest: `sha256:${crypto.createHash('sha256').update(statement).digest('hex')}`, nonce: fields.nonce })?.toString('utf8');
+}
+
+function tokenFindings(value) {
+  const findings = [];
+  const flag = (instancePath, message) => findings.push({ code: 'FAC-SEM-113', instancePath, message });
+  const statement = isObject(value.statement) ? value.statement : undefined;
+  if (!statement) {
+    flag('/statement', 'an enroll token carries its signed statement');
+    return findings;
+  }
+  if (statement.type !== ENROLL_TOKEN_TYPE) flag('/statement/type', "the statement's type is enroll-token/1, the register's (DEC-0063)");
+  const extra = Object.keys(statement).filter((name) => name !== 'type' && !ENROLL_TOKEN_FIELDS.includes(name));
+  const missing = ENROLL_TOKEN_FIELDS.filter((name) => !Object.hasOwn(statement, name));
+  if (extra.length > 0 || missing.length > 0) flag('/statement', `the statement has exactly the register's fields: ${ENROLL_TOKEN_FIELDS.join(', ')}`);
+  if (statement.purpose !== ENROLL_PURPOSE) flag('/statement/purpose', "an enroll token's purpose is agent-host");
+  if (statement.uses !== 1) flag('/statement/uses', 'an enroll token is used once: uses is 1, and the hub binds its nonce on the first use');
+  const notBefore = estateTime(statement.notBefore);
+  const expiresAt = estateTime(statement.expiresAt);
+  const { type: _type, ...rest } = statement;
+  const named = extra.length === 0 && missing.length === 0 && statement.purpose === ENROLL_PURPOSE && statement.uses === 1 && Number.isFinite(notBefore) && Number.isFinite(expiresAt);
+  if (named && !signingStatement(ENROLL_TOKEN_TYPE, rest)) flag('/statement', 'scope is estate:<id>, genesis a sha256: digest, nonce 32 bytes in base64url, and ceiling null or a digest');
+  if (!Number.isFinite(notBefore) || !Number.isFinite(expiresAt)) {
+    flag(Number.isFinite(notBefore) ? '/statement/expiresAt' : '/statement/notBefore', 'notBefore and expiresAt are RFC 3339 date-times with an offset, on days that exist');
+  } else if (expiresAt <= notBefore || expiresAt - notBefore > MAX_ENROLL_TOKEN_SECONDS * 1000) {
+    flag('/statement/expiresAt', 'an enroll token is valid after notBefore and for at most 15 minutes (900 s)');
+  }
+  return findings;
+}
+
+/** FAC-SEM-113 (kind enroll-token); undefined for another kind. */
+export function enrollTokenRules(kind, value) {
+  if (kind === 'enroll-token') return tokenFindings(isObject(value) ? value : {});
+  return undefined;
+}
+// #endregion ceremonies-kit-node

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

@@ -285,7 +285,9 @@ export function verifyEstateRecord(record, trust) {
   // A revision issued a moment ahead of this clock is admitted within the skew every relay time allows (DEC-0066).
   if (at < issuedAt - CLOCK_SKEW_SECONDS * 1000) return { ok: false, problem: 'not-yet-valid' };
   if (at > validUntil) return { ok: false, problem: 'expired' };
-  const codes = [...new Set(recordFindings(record).map((finding) => finding.code))];
+  // With a parent, what the revision drops it revokes (FAC-SEM-114, DEC-0084): a removed machine, a replaced key.
+  const dropped = isObject(trust.parent) ? droppedFindings(trust.parent, record) : [];
+  const codes = [...new Set([...recordFindings(record), ...dropped].map((finding) => finding.code))];
   if (codes.length > 0) return { ok: false, problem: 'rule-violation', codes };
   return { ok: true, digest, revision: record.revision, signedBy: credential.credentialId, signCount: assertion.signCount };
 }
@@ -389,6 +391,27 @@ function revisionChain(value) {
   return findings;
 }
 
+/** Standard base64 with its padding, the one form DEC-0053 records a device key's octets in. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** DEC-0084: a key reference, a device-key kid, `@sha256:` and 64 lower-case hex digits. */
+export const KEY_REFERENCE = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}#(sig|kem)@sha256:[a-f0-9]{64}$/;
+
+/** A device key's fingerprint (DEC-0084): `sha256:` and the hex SHA-256 of its canonical base64 octets, or undefined. */
+export function deviceKeyFingerprint(key) {
+  const text = isObject(key) ? key.publicKey : undefined;
+  if (!isString(text) || text.length === 0 || !BASE64.test(text)) return undefined;
+  const raw = Buffer.from(text, 'base64');
+  if (raw.toString('base64') !== text) return undefined;
+  return `sha256:${sha256(raw).toString('hex')}`;
+}
+
+/** The `device-key` revocation reference of one key (DEC-0084): `<kid>@<fingerprint>`, or undefined. */
+export function deviceKeyRef(key) {
+  const fingerprint = deviceKeyFingerprint(key);
+  const kid = isObject(key) ? key.kid : undefined;
+  return fingerprint !== undefined && isString(kid) ? `${kid}@${fingerprint}` : undefined;
+}
+
 const validDeviceKey = (key) => {
   const raw = Buffer.from(show(key.publicKey ?? ''), 'base64');
   return key.alg === 'ed25519' ? raw.length === 32 && !smallOrder(raw) : isValidP256Key(raw);
@@ -408,7 +431,9 @@ function keys(value, flag) {
     const seen = new Set();
     deviceKeys.forEach((key, k) => {
       if (key.kid !== `${show(machine.id)}#${show(key.use)}`) flag(`${at}/deviceKeys/${k}/kid`, 'a device key is listed as <machine id>#sig or <machine id>#kem, by its role');
-      if (!validDeviceKey(key)) flag(`${at}/deviceKeys/${k}/publicKey`, 'an Ed25519 key is never of small order (DEC-0045) and a P-256 key is a valid point (SEC 1 §3.2.2)');
+      // A key with no canonical fingerprint could be read as two keys by two readers, and no key reference names it (DEC-0084).
+      if (deviceKeyFingerprint(key) === undefined) flag(`${at}/deviceKeys/${k}/publicKey`, "a device key's octets are written in canonical padded base64, the one form a key reference can name (DEC-0084)");
+      else if (!validDeviceKey(key)) flag(`${at}/deviceKeys/${k}/publicKey`, 'an Ed25519 key is never of small order (DEC-0045) and a P-256 key is a valid point (SEC 1 §3.2.2)');
       if (seen.has(key.publicKey)) flag(`${at}/deviceKeys/${k}/publicKey`, 'one key is never used for the other role');
       seen.add(key.publicKey);
     });
@@ -485,7 +510,8 @@ function grantsAndRevocations(value, flag) {
   const listed = new Map(Object.entries({
     authority: new Set(list(value.authorities).map((entry) => entry.credentialId)),
     machine: new Set(machines.map((machine) => machine.id)),
-    'device-key': new Set(machines.flatMap((machine) => list(machine.deviceKeys).map((key) => key.kid))),
+    // A kid, and each listed key's own reference (DEC-0084): revoking either while listing it is refused.
+    'device-key': new Set(machines.flatMap((machine) => list(machine.deviceKeys).flatMap((key) => [key.kid, deviceKeyRef(key)].filter((ref) => ref !== undefined)))),
     'hub-key': new Set(machines.flatMap((machine) => (isObject(machine.hubKey) ? [machine.hubKey.kid] : []))),
     'publisher-key': new Set(list(value.publisherKeys).map((key) => key.kid)),
     package: new Set(machines.flatMap((machine) => list(machine.packages).map((placement) => placement.digest))),
@@ -496,6 +522,9 @@ function grantsAndRevocations(value, flag) {
     const ref = revocation.kind === 'grant' ? grantKey(revocation.ref) : revocation.ref;
     const key = `${show(revocation.kind)} ${show(ref)}`;
     if (seen.has(key)) flag(`/revocations/${index}`, `the ${show(revocation.kind)} ${show(revocation.ref)} is revoked twice`);
+    if (revocation.kind === 'device-key' && typeof revocation.ref === 'string' && revocation.ref.includes('@') && !KEY_REFERENCE.test(revocation.ref)) {
+      flag(`/revocations/${index}/ref`, 'a device-key revocation names a kid or a key reference <kid>@sha256:<64 lower-case hex digits> (DEC-0084)');
+    }
     seen.add(key);
     if (listed.get(show(revocation.kind))?.has(ref)) flag(`/revocations/${index}/ref`, `the record still lists the ${show(revocation.kind)} it revokes: revocation outranks addition`);
   });
@@ -591,11 +620,45 @@ function installation(value) {
   return findings;
 }
 
+/**
+ * FAC-SEM-114 across two revisions (DEC-0084): what a revision drops, it revokes in the same revision. A removed machine
+ * as `machine <id>` and its hub key as `hub-key <kid>`; a replaced or dropped device key of a kept machine as `device-key`
+ * by its reference or its kid; a hub key no longer certified as it was as `hub-key <old kid>`.
+ */
+function droppedFindings(parent, next) {
+  const findings = [];
+  const flag = flagger(findings, 'FAC-SEM-114');
+  const revoked = (kind, ...refs) => list(next.revocations).some((entry) => entry.kind === kind && refs.some((ref) => ref !== undefined && entry.ref === ref));
+  const nextMachines = new Map();
+  for (const machine of list(next.machines)) if (!nextMachines.has(machine.id)) nextMachines.set(machine.id, machine);
+  indexed(parent.machines).forEach(([machine, m]) => {
+    const at = `/parent/machines/${m}`;
+    const hub = isObject(machine.hubKey) ? machine.hubKey : undefined;
+    const kept = nextMachines.get(machine.id);
+    if (!kept) {
+      if (!revoked('machine', machine.id)) flag(`${at}/id`, `machine ${show(machine.id)} is removed without its revocation: a revision that drops a machine lists machine ${show(machine.id)} in revocations`);
+      if (hub && !revoked('hub-key', hub.kid)) flag(`${at}/hubKey/kid`, `the hub key ${show(hub.kid)} of a removed machine is revoked in the same revision`);
+      return;
+    }
+    const listedRefs = new Set(list(kept.deviceKeys).map(deviceKeyRef).filter((ref) => ref !== undefined));
+    indexed(machine.deviceKeys).forEach(([key, k]) => {
+      const ref = deviceKeyRef(key);
+      if (ref === undefined || listedRefs.has(ref)) return;
+      if (!revoked('device-key', ref, key.kid)) flag(`${at}/deviceKeys/${k}`, `the device key ${show(key.kid)} is replaced or dropped without its revocation: the same revision lists device-key ${ref}`);
+    });
+    const nextHub = isObject(kept.hubKey) ? kept.hubKey : undefined;
+    if (hub && !(nextHub && nextHub.kid === hub.kid && nextHub.x === hub.x) && !revoked('hub-key', hub.kid)) {
+      flag(`${at}/hubKey/kid`, `the hub key ${show(hub.kid)} is no longer certified as it was: the same revision revokes hub-key ${show(hub.kid)}, and a re-certified hub key takes a new kid`);
+    }
+  });
+  return findings;
+}
+
 /** FAC-SEM-072…076 for an `estate-record`, an `estate-record-revision` `{parent, next}` or an `estate-placement`. */
 export function estateRecordRules(kind, value) {
   const doc = isObject(value) ? value : {};
   if (kind === 'estate-record') return recordFindings(doc);
-  if (kind === 'estate-record-revision') return revisionChain(doc);
+  if (kind === 'estate-record-revision') return [...revisionChain(doc), ...droppedFindings(isObject(doc.parent) ? doc.parent : {}, isObject(doc.next) ? doc.next : {})];
   if (kind === 'estate-placement') return installation(doc);
   return undefined;
 }