@scopebond/hook 0.8.0 → 0.9.0

package/README.md

@@ -131,6 +131,53 @@ before-edit hook), so an out-of-policy edit there is signed and flagged, not blo
 and the message says so rather than claiming otherwise. For edits that must be stopped
 before they land, make `@scopebond/github-action` a required check on pull requests.
 
+Codex has no native file-read event: reads it makes through shell commands are derived
+from the command (`cat .env`) and checked, but a read that never goes through a shell
+is not seen. Run `capabilities` (below) for the exact per-cell picture.
+
+### What this hook can honestly claim: `capabilities`
+
+```
+npx @scopebond/hook capabilities            # the manifest, per agent host / action / phase
+npx @scopebond/hook capabilities --prove    # run the safe fixtures in temp directories
+npx @scopebond/hook capabilities --prove --save   # and record the result beside the policy
+npx @scopebond/hook capabilities --json
+```
+
+Each cell is one connector version, agent host (Claude terminal / desktop, Codex CLI /
+desktop, Cursor), action type and phase (before or after the action), in one of these
+states:
+
+| State | Meaning |
+|---|---|
+| `unsupported` | no hook for it, or it is known to escape interception (nested tool wrappers) |
+| `inactive` | the hook could cover it but that agent is not configured |
+| `configured_unverified` | configured; never proven, or proven only by a local fixture |
+| `degraded` | the current fixtures failed |
+| `verified_reporting` | a current proof from a real agent run, acknowledged by Cloud |
+
+`--prove` checks, for every supported cell, that a safe action is allowed and signed, a
+violating one is denied at the hook, every receipt verifies against the countersigning
+key, and every receipt of a tool call carries one action group. It uses temporary
+directories only and never reads or changes agent settings, policy or keys. A local
+fixture proves the adapter and policy on this machine; it cannot prove that Codex
+desktop or Cursor delivers the event, nor that Cloud received a receipt, so it never
+produces `verified_reporting`. Actions the agent only reports after they happened
+(Cursor's `afterFileEdit`) and actions the default policy only observes (fetches, MCP
+calls) are proven with a known successful fixture, labelled observation-only; no
+"denied" result is claimed for them.
+
+**Action groups.** A shell call can produce several receipts (the command, each file it
+reads or writes, every pushed ref). They now carry `action_group`, `action_group_size`
+and `action_group_seq` inside the signed intent's `params`, so they can be linked and
+counted once without guessing; the id comes from the agent's own tool-call id when it
+sends one.
+
+**Workspace roots (optional).** `rules.json` accepts `"allowed_roots": ["."]`. With it,
+a write whose physical target (symlinks and junctions followed; rename and link
+destinations included) is outside the roots, or cannot be resolved, is denied. Without
+it nothing changes. Run `rules apply` after adding it.
+
 ## Connect it to your workspace (optional)
 
 To see the receipts in your hosted Scopebond workspace, sign this computer in:
@@ -169,6 +216,169 @@ locally and retried if the workspace is unreachable. `npx @scopebond/hook flush`
 delivers anything still queued — run it on a session-end hook (and set
 `SCOPEBOND_HOOK_FLUSH_MS=0`) if you want zero per-call latency.
 
+### Session, health and action observations (opt-in)
+
+Beyond receipts, the hook can send a second kind of signed record, an *observation*,
+to a workspace that supports them. It is **off unless your workspace enrollment grants
+`observations:write`**, and it needs the enrollment to give an installation id (the
+enrollment's `gateway_id`, or an explicit `installation_id`) and an
+`installation_generation`; without those the hook says so in `scopebond status` and
+emits nothing. It never guesses a generation. It
+never affects a decision: sending is best effort, bounded, and runs after the decision is
+made, so an unreachable workspace, a missing route or a rate limit changes nothing about
+what is allowed or denied.
+
+Each observation is Ed25519-signed with the enrolled agent key over the domain
+`scopebond:observation/v1` plus a newline and the canonical (RFC 8785) payload, and sent
+in batches to `POST /v1/observations` as `{ version: "1.0", items: [{ payload, signature }] }`.
+A separate keyed digest binds each tool-call observation to the request the hook actually
+evaluated; the key stays on this machine and is never uploaded. Paths, commands, hosts and
+session ids never leave the machine: they are reduced to keyed opaque ids or closed enums.
+
+| Kind | Sent when | Hosts |
+|---|---|---|
+| `session` start / stop | Claude Code `SessionStart` / `SessionEnd` (stop reasons: completed, cancelled, unknown; sleep is inferred) | Claude Code |
+| `health` heartbeat | every 60 seconds while a session is explicitly active, from one short helper per session that ends with the session | Claude Code |
+| `health` queue | oldest pending receipt time and count, at most every five minutes while a backlog exists | Claude Code |
+| `tool_intent` | each evaluated action, linked to its receipt | Claude Code, Codex, Cursor (shell, file, git push, MCP) |
+| `tool_outcome` | Claude Code `PostToolUse` / `PostToolUseFailure`, echoing the intent's binding | Claude Code |
+| `capability` proof | `scopebond capabilities --prove` (marked as a fixture run, never live) | all |
+| `policy_ack` | `scopebond policy load <export.json>`, once an exported policy is loaded or refused | all |
+
+With observations on, `capabilities --prove` signs its fixtures with this machine's own keys
+(copied into the temporary directory; the originals are never changed), delivers the fixture
+receipts to the workspace first, and only then sends each proof, naming those receipts by
+`proof_digests`: the SHA-256 of `scopebond:source-receipt/v1` plus a newline plus the
+canonical full signed receipt. Only receipts of the cell's own action type are named. If the
+receipts cannot be delivered, no proof is sent. The fixture receipts are real receipts in
+the workspace's log.
+
+`scopebond policy load <export.json>` checks a policy exported from the workspace (its
+policy hash must match the policy, its scope digest must match the export, agent and
+environment, and the environment must be the one this machine is connected to) and says
+what loading would replace; `--yes` writes it atomically as `policy.json` (the old one is
+kept as `policy.previous.json`). It then acknowledges the load, or the refusal with a
+reason, echoing the export's policy hash, policy id, policy version and scope digest
+exactly. The export itself carries no signature, so get the file from your workspace.
+`scopebond rules apply` recompiles `policy.json` from `rules.json` and would replace a loaded policy.
+
+`scopebond budget load <export.json>` does the same for an action budget exported from the
+workspace: it checks the document type and version, the policy digest (over the policy
+without its acknowledgement), the scope digest, the environment, the validity window and the
+fail-closed contract, and refuses a budget an independent installation cannot enforce (one
+shared across installations). `--yes` writes it into `dispatch.json` as an acknowledged
+budget for this agent (replacing an older workspace budget, never a newer one) and queues
+the acknowledgement with the export id, budget id and version, and digests the workspace
+expects. The export names the agent key it is for (`agent_kid`): a different key than this
+machine's is refused (and acknowledged as rejected); an export whose key the workspace could not
+state (null) loads with a warning that its identity could not be bound, and an export without
+the field is refused. The budget's actor is that key. An enforced budget denies new dispatch
+once its export has expired, until you load a new one.
+
+When this machine is connected with `observations:write`, the dispatch boundary can also use
+the workspace: an approval granted there for exactly the request is found and consumed at
+dispatch with nothing to copy (the guard asks `GET /v1/monitoring/approvals/active` with the
+request hash, action type and opaque target id; the denial message still prints the request
+hash and target id to approve). Leaving `{ "cloud_approval_id": "<id>" }` in `approvals/`
+still works and is used first. Only the consume approves: a lookup that finds nothing, fails
+or finds another request approves nothing. A delegated session this machine does not know is resolved from the workspace
+(scope entries are digests of `action_type NUL target-id` or `action_type NUL *`, over the
+same opaque target id; the workspace's own `covers` answer for the action decides when it
+gives one) and cached for 15 seconds. With approvals required for an action type in
+`dispatch.json`, each typed operation also carries `approval_request_hash` (the hash the guard
+consumes with) and a `resource_id` equal to the guard's target id, so a consumed approval can be
+matched to its intent; the field is a claim and authorizes nothing. If the workspace cannot be reached and no valid local approval is
+presented, an enforced action is denied. Targets reach the workspace only as keyed opaque ids.
+Set `"cloud": false` in `dispatch.json` to keep everything local.
+
+#### Typed operations: git, GitHub and package installs
+
+A `tool_intent` carries one closed typed operation read from the request the hook is about to
+allow: the raw shell command or the MCP tool input, never a model-written summary. It replaces the
+generic shell operation for the same receipt when it can be described:
+
+| Operation | From | What it carries |
+|---|---|---|
+| `git` commit | `git commit` | repository id, current branch as a keyed ref id with a protected flag, HEAD before the commit |
+| `git` push, delete, mirror | `git push` (`--delete`, `:ref`, `--mirror`) | the same, plus `force`, the remote as a keyed id (a name and its URL give one id; credentials in a URL are dropped) and `resolution` |
+| `github_resource` pr_create, release_create | `gh pr create`, `gh release create`, the GitHub MCP `create_pull_request` | keyed repository id and the base and head commits, or the release commit, read from the local clone; `required_check_policy_version` is `unbound` unless `SCOPEBOND_REQUIRED_CHECK_POLICY_VERSION` is set |
+| `package` install, add, update | `npm`, `pnpm`, `yarn`, `pip`, `uv` with named packages | manager, the version pinned in `package.json`'s `packageManager` when it names that manager, and per package the name, an exact version only when the request pinned one, and the registry host only when the command named one |
+
+Unknown facts stay unknown. An unresolved ref or remote is `resolution: "unresolved"`;
+`integrity_status` is always `unknown` because nothing is verified before the install runs; lifecycle
+scripts are `blocked` only for `--ignore-scripts`, `unknown` for npm, pnpm and yarn otherwise, and
+`not_supported` for pip and uv. A command that installs whatever a lockfile or requirements file lists
+(`npm ci`, `pnpm install`, `pip install -r`, `uv sync`) names no packages and stays a plain shell
+operation; so does anything after a `cd` in the same command line, `git -C`, a pull request from a fork
+or another repository, and `gh pr edit` or `gh pr merge`, whose pull request is named only by number and
+has no head or base commit without a platform read-back this hook does not do (the capability manifest lists
+`github.pr_change` and `deploy.run` as unsupported). Non-registry package sources are named `url:`,
+`git:` or `local:` with credentials and queries dropped. These cells are observation-only and stay
+`configured_unverified` after `capabilities --prove` (a fixture proves the derivation on this machine, not the host);
+no proof is sent for them because they have no receipt of their own action type to name.
+
+Reference sets refer to refs, remotes and repositories by these keyed ids. `scopebond observations id ref main`,
+`observations id remote <url>`, `observations id ghrepo owner/name` and `observations id mcp <server> <tool>`
+print the id this installation gives a value; it reads the local key and sends nothing.
+
+#### Typed operations: network, Cloudflare and databases
+
+The same rules apply: the operation is read from the raw command (or a Claude Code `WebFetch` input),
+unknown facts stay unknown, and a command the reader cannot place fully stays a plain shell operation.
+
+| Operation | From | What it carries |
+|---|---|---|
+| `network` | `WebFetch` (Claude Code), `curl`, `wget`, `Invoke-WebRequest`, `Invoke-RestMethod` and their aliases | scheme, lowercase IDNA host, effective port, method, and `read` (GET, HEAD, OPTIONS), `write` (DELETE, or a POST, PUT or PATCH with no body) or `upload` (a POST, PUT or PATCH with a body or file) |
+| `cloudflare_resource` | `wrangler` (also through `npx`, `pnpm exec`, `npm exec`): `deploy`, `delete`, `pages deploy`, `pages project create/delete`, `d1 create/delete`, `r2 bucket create/delete`, `r2 bucket dev-url enable/disable`, `r2 object put/delete` | resource kind and verb, keyed account and resource ids, the `--env` as an environment class and keyed binding, and a SHA-256 of the directory a Pages deploy sends or the file an R2 put sends |
+| `database` | `wrangler d1 execute` and `d1 migrations apply`, `psql` (`-c`, `-f`), `sqlite3` | provider, verb (read, insert, update, delete, delete_all, create, alter, drop, migrate), `predicate_class` bounded, all or not_applicable, a keyed database id and a keyed digest of the statement or of the local migration set |
+
+What never leaves the machine: the URL path, query and credentials, headers and request bodies; SQL text,
+table and column names, literals and rows; recipient details; file contents. The database digest is an HMAC under
+the installation key, so another installation cannot reproduce it. The SQL classifier is deliberately
+conservative: an `UPDATE` or `DELETE` counts as bounded only when a top-level AND-ed condition is selective (an OR,
+a tautology such as `1=1`, `LIKE '%'` or `IS NOT NULL` alone counts as every row), and SQL it cannot place (dynamic
+SQL, `CALL`, `VACUUM`, a `CTE` that writes, an unbalanced quote) produces no database operation at all, because the
+closed schema has no unknown verb.
+
+Known limits, said plainly: a redirect hop is never followed or bound (`redirect_binding` is always omitted, so a
+redirected request is not qualified against the origin's approval); a request sent through a proxy,
+`--resolve`, `--connect-to`, a config file or more than one URL is not described; IPv6 literals and non-HTTP
+schemes are not described; `wrangler` has no DNS command, so `dns_record` changes are not seen; `d1 execute` records
+the environment only from `--local` or `--env`, and `environment_class` is otherwise `unknown` (the hook cannot tell which database
+is production); a `d1 migrations apply` digest covers the whole local migrations directory, not only the pending files;
+account ids come from an inline `CLOUDFLARE_ACCOUNT_ID=`, the Wrangler config or this process's environment and are
+`unbound` when none names one. The shell receipt of a command still carries the redacted command head the hook has
+always recorded (a scrubbed prefix of up to 64 characters), which can include the start of an inline SQL statement.
+
+Capability cells `network.request`, `cloudflare.resource` and `database.exec` are observation-only and stay
+`configured_unverified` without a real-host proof. `browser.action`, `communication.send` and `visibility.change`
+are registered as `unsupported` with their reasons: no host this hook supports sends an approved browser or
+communications event (a browser or mail tool arrives as a generic MCP call with no origin, verb, destination or
+attachment set), and no supported source reports a resource's visibility before and after.
+`observations id net-dest <host> <port>`, `observations id cf <kind> <name>` and `observations id database <pg|sqlite> <key>`
+print the keyed ids for writing reference sets.
+
+**Optional enforcement.** `scopebond-hook rules protect-remote-database` (off by default; `rules.json` field
+`protect_remote_database`) adds an enforce clause that denies, before the command runs, SQL against a remote
+database (a `wrangler d1` command without `--local`, or `psql` to a host other than this machine) that drops a table,
+deletes or updates every row, drops or renames inside an `ALTER`, or cannot be read. The hook cannot tell which
+database is production, so every remote database is covered; `wrangler d1 execute` with neither `--local` nor `--remote`
+is treated as remote because Wrangler's default has differed between versions. Everything else stays observation.
+
+Codex and Cursor have no tested session or after-action mapping, so those kinds are not
+sent for them. Nothing is sent from a sleeping host: a heartbeat gap is recorded as a stop
+with reason `sleep`, and an idle session releases its lease with one final heartbeat.
+
+Delivery follows the workspace's answers: only acknowledged items are removed, deferred
+items are retried with the same id and sequence, and items the workspace refuses stay in a
+local terminal-error queue shown by `scopebond observations status --refused` (an
+unsupported version or a stale generation is never retried; a rate limit, a paused plan
+(HTTP 402) and a refusal without an item id are handled as the workspace reports them). A workspace without the route
+is marked unsupported and nothing more is queued until `scopebond observations retry`.
+`scopebond observations wire` adds the Claude Code session and after-action hook entries
+(`connect` does it automatically when the enrollment grants the scope); `unwire` removes
+only those. `SCOPEBOND_OBSERVATIONS_HEARTBEAT=off` keeps everything except the heartbeat helper.
+
 ## How it works
 
 Each tool call is mapped to a normalized [Action Taxonomy](https://github.com/avouro-com/scopebond)

package/dist/budget-load.d.ts

@@ -0,0 +1,68 @@
+import { type ActionBudgetPolicy } from "@scopebond/gateway";
+import { type PolicyAckInput, type PolicyLoadError } from "./observation.js";
+export declare const BUDGET_EXPORT_TYPE = "scopebond:action-budget-export";
+export interface BudgetExportFacts {
+    exportId: string;
+    budgetId: string;
+    budgetVersion: number;
+    policyDigest: string;
+    scopeDigest: string;
+    agentId: string;
+    /** The key the workspace says this agent signs with, or null when it could not say (no enrolled key). */
+    agentKid: string | null;
+    environmentId: string;
+    validUntil: number;
+    policy: {
+        operation_set: string[];
+        authority_scope: "installation" | "shared_gateway";
+        max_dispatch: number;
+        window_seconds: number;
+        mode: "monitor" | "enforce";
+        version: number;
+    };
+}
+export type BudgetInspection = {
+    ok: true;
+    facts: BudgetExportFacts;
+}
+/** `ack` is set when the export names enough to echo in a rejection; otherwise nothing is acknowledged. */
+ | {
+    ok: false;
+    error: PolicyLoadError | "expired";
+    message: string;
+    ack?: Omit<PolicyAckInput, "error">;
+};
+/** Accept the export itself, or the workspace's `{ version, export }` answer around it. */
+export declare function unwrapBudgetExport(raw: unknown): Record<string, unknown> | null;
+/** Check an export without reading or changing anything on disk. Pure. */
+export declare function inspectBudgetExport(raw: unknown, context?: {
+    environmentId?: string;
+    now?: number;
+}): BudgetInspection;
+/** The budget policy this machine enforces for an export: the reviewed limits, acting as this installation's agent, valid until the export says. */
+export declare function localBudgetOf(facts: BudgetExportFacts, agentKid: string, acknowledgedAt: string): ActionBudgetPolicy & {
+    source_export_id: string;
+};
+export type BudgetLoadOutcome = {
+    state: "loaded";
+    facts: BudgetExportFacts;
+    replaced: string[];
+    warnings: string[];
+} | {
+    state: "would_load";
+    facts: BudgetExportFacts;
+    warnings: string[];
+} | {
+    state: "rejected";
+    error: PolicyLoadError | "expired";
+    message: string;
+    ack?: Omit<PolicyAckInput, "error">;
+};
+/** Read an export file, check it, and (with `apply`) write it into `dispatch.json` as an acknowledged budget. */
+export declare function loadBudgetExport(dir: string, file: string, options: {
+    apply: boolean;
+    agentKid: string;
+    environmentId?: string;
+    now?: number;
+}): BudgetLoadOutcome;
+//# sourceMappingURL=budget-load.d.ts.map

package/dist/budget-load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-load.d.ts","sourceRoot":"","sources":["../src/budget-load.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG3F,eAAO,MAAM,kBAAkB,mCAAmC,CAAC;AAKnE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,EAAE,CAAC;QAAC,eAAe,EAAE,cAAc,GAAG,gBAAgB,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACrL;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE;AACxC,2GAA2G;GACzG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAE5G,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAI/E;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,gBAAgB,CAyD1H;AAED,oJAAoJ;AACpJ,wBAAgB,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,kBAAkB,GAAG;IAAE,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAUnJ;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACrF;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAEpH,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAmClK"}

package/dist/budget-load.js

@@ -0,0 +1,164 @@
+// `scopebond budget load <export.json>`: load a reviewed action budget exported from a workspace,
+// as the budget this machine enforces, and say honestly what happened.
+//
+// An export is a reviewed, approved policy in a file. It is pending in the workspace until a signed
+// acknowledgement echoes exactly what the export said: its export id, the budget id and version, the
+// policy digest and the scope digest. This module checks an export and, when asked, writes it into
+// `dispatch.json` as an acknowledged budget policy; the caller then queues the `policy_ack`.
+//
+// What is checked, and what is not:
+//   - the document type and version, and the fail-closed contract it carries (an export that would
+//     permit unlimited dispatch on failure is refused);
+//   - the policy digest: SHA-256 of the canonical policy with its acknowledgement removed, which is
+//     what the workspace hashed when the budget was drafted;
+//   - the scope digest, the environment (when this machine is connected), the validity window, and
+//     that the policy is one an independent installation can enforce (a limit shared across
+//     installations needs a shared in-path gateway, which a hook is not).
+// An export carries no signature of its own: get the file from your workspace, over its own page or
+// API. Loading replaces an older workspace budget for the same agent; it never replaces a newer one.
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { budgetDigest } from "@scopebond/gateway";
+import { DISPATCH_FILE, readDispatchFile } from "@scopebond/gateway/node";
+import { digestPolicy } from "./observation.js";
+import { policyScopeDigest, MAX_EXPORT_BYTES } from "./policy-load.js";
+export const BUDGET_EXPORT_TYPE = "scopebond:action-budget-export";
+const HEX64 = /^[0-9a-f]{64}$/;
+const OPAQUE = /^[\x21-\x7e]{1,200}$/;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Accept the export itself, or the workspace's `{ version, export }` answer around it. */
+export function unwrapBudgetExport(raw) {
+    if (!isObject(raw))
+        return null;
+    if (raw.type === undefined && isObject(raw.export))
+        return raw.export;
+    return raw;
+}
+/** Check an export without reading or changing anything on disk. Pure. */
+export function inspectBudgetExport(raw, context = {}) {
+    const exp = unwrapBudgetExport(raw);
+    if (!exp || exp.type !== BUDGET_EXPORT_TYPE)
+        return { ok: false, error: "schema_invalid", message: "this is not a Scopebond action budget export" };
+    if (exp.version !== 1)
+        return { ok: false, error: "unsupported", message: `unsupported export version ${String(exp.version)}` };
+    const { export_id: exportId, budget_id: budgetId, budget_version: budgetVersion, agent_id: agentId, environment_id: environmentId, valid_until: validUntil } = exp;
+    const policy = exp.policy;
+    const agentKid = exp.agent_kid;
+    // `agent_kid` is always present in an export (a key id, or null when the workspace has no enrolled key for the agent); an export without it predates identity binding.
+    if (agentKid === undefined || (agentKid !== null && (typeof agentKid !== "string" || !OPAQUE.test(agentKid)))) {
+        return { ok: false, error: "schema_invalid", message: "the export does not say which agent key it is for (agent_kid is missing or malformed); export the budget again from the workspace" };
+    }
+    if (typeof exportId !== "string" || !OPAQUE.test(exportId) || typeof budgetId !== "string" || !OPAQUE.test(budgetId) || !Number.isInteger(budgetVersion) || budgetVersion < 1
+        || budgetVersion > 2_147_483_647 || typeof agentId !== "string" || !OPAQUE.test(agentId) || typeof environmentId !== "string" || !OPAQUE.test(environmentId)
+        || typeof validUntil !== "number" || !Number.isFinite(validUntil) || !isObject(policy) || typeof exp.policy_digest !== "string" || !HEX64.test(exp.policy_digest)
+        || typeof exp.scope_digest !== "string" || !HEX64.test(exp.scope_digest)) {
+        return { ok: false, error: "schema_invalid", message: "the export lacks a budget id, version, policy, digest or validity window, or they are malformed" };
+    }
+    // Echoed exactly as the export states them, so a rejection still names the export.
+    const echo = { exportId, policyId: budgetId, policyVersion: budgetVersion, policyDigest: exp.policy_digest, scopeDigest: exp.scope_digest };
+    const ops = policy.operation_set;
+    if (!Array.isArray(ops) || ops.length < 1 || ops.length > 100 || !ops.every((o) => typeof o === "string" && OPAQUE.test(o))
+        || (policy.authority_scope !== "installation" && policy.authority_scope !== "shared_gateway") || (policy.mode !== "monitor" && policy.mode !== "enforce")
+        || !Number.isInteger(policy.max_dispatch) || policy.max_dispatch < 1 || policy.max_dispatch > 1_000_000_000
+        || !Number.isInteger(policy.window_seconds) || policy.window_seconds < 1 || policy.window_seconds > 366 * 86_400
+        || policy.version !== budgetVersion) {
+        return { ok: false, error: "schema_invalid", message: "the export's budget policy is malformed", ack: echo };
+    }
+    if (digestPolicy({ ...policy, acknowledged: null }) !== exp.policy_digest) {
+        return { ok: false, error: "signature_invalid", message: "the policy does not match the export's policy digest; the file was changed or damaged", ack: echo };
+    }
+    if (policyScopeDigest({ export_id: exportId, agent_id: agentId, environment_id: environmentId }) !== exp.scope_digest) {
+        return { ok: false, error: "scope_mismatch", message: "the export's scope digest does not match its export, agent and environment", ack: echo };
+    }
+    if (context.environmentId !== undefined && context.environmentId !== environmentId) {
+        return { ok: false, error: "scope_mismatch", message: "this export is for a different environment than this machine is connected to", ack: echo };
+    }
+    if (policy.acknowledged === null || policy.acknowledged === undefined) {
+        return { ok: false, error: "schema_invalid", message: "the budget was not approved in the workspace (no acknowledgement); only an approved budget can be loaded", ack: echo };
+    }
+    const enforcement = isObject(exp.enforcement) ? exp.enforcement : null;
+    const failClosed = enforcement && isObject(enforcement.fail_closed) ? enforcement.fail_closed : null;
+    if (!failClosed || failClosed.unlimited_dispatch_on_failure !== false) {
+        return { ok: false, error: "unsupported", message: "the export does not state the fail-closed contract (no unlimited dispatch on failure); it is refused", ack: echo };
+    }
+    if (policy.mode === "enforce" && (policy.authority_scope !== "installation" || enforcement?.eligible !== true)) {
+        return { ok: false, error: "unsupported", message: "this budget cannot be enforced by an independent installation (a limit shared across installations needs a shared in-path gateway)", ack: echo };
+    }
+    if (validUntil <= (context.now ?? Date.now())) {
+        return { ok: false, error: "expired", message: "this export is past its validity window; export the budget again from the workspace" };
+    }
+    return {
+        ok: true,
+        facts: {
+            agentKid: agentKid, exportId, budgetId, budgetVersion: budgetVersion, policyDigest: exp.policy_digest, scopeDigest: exp.scope_digest, agentId, environmentId, validUntil,
+            policy: policy,
+        },
+    };
+}
+/** The budget policy this machine enforces for an export: the reviewed limits, acting as this installation's agent, valid until the export says. */
+export function localBudgetOf(facts, agentKid, acknowledgedAt) {
+    const policy = {
+        // The actor is the export's agent key; a null one (unverifiable identity) falls back to this installation's key, which is the only agent this machine dispatches as.
+        budget_id: facts.budgetId, actor: facts.agentKid ?? agentKid, operations: [...facts.policy.operation_set], authority_scope: facts.policy.authority_scope, max: facts.policy.max_dispatch,
+        window_seconds: facts.policy.window_seconds, mode: facts.policy.mode, version: facts.budgetVersion, expires_at: new Date(facts.validUntil).toISOString(),
+        acknowledgement: null, source_export_id: facts.exportId,
+    };
+    // Loading it is the acknowledgement: the person who ran `budget load --yes` accepts this exact policy.
+    policy.acknowledgement = { digest: budgetDigest(policy), acknowledged_at: acknowledgedAt };
+    return policy;
+}
+/** Read an export file, check it, and (with `apply`) write it into `dispatch.json` as an acknowledged budget. */
+export function loadBudgetExport(dir, file, options) {
+    let raw;
+    try {
+        if (statSync(file).size > MAX_EXPORT_BYTES)
+            return { state: "rejected", error: "schema_invalid", message: "the export file is larger than 1 MiB" };
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return { state: "rejected", error: "schema_invalid", message: `the export could not be read as JSON (${error.name})` };
+    }
+    const inspected = inspectBudgetExport(raw, { environmentId: options.environmentId, now: options.now });
+    if (!inspected.ok)
+        return { state: "rejected", error: inspected.error, message: inspected.message, ...(inspected.ack ? { ack: inspected.ack } : {}) };
+    const { facts } = inspected;
+    const ack = { exportId: facts.exportId, policyId: facts.budgetId, policyVersion: facts.budgetVersion, policyDigest: facts.policyDigest, scopeDigest: facts.scopeDigest };
+    if (!options.agentKid)
+        return { state: "rejected", error: "unsupported", message: "this machine has no agent key to act as; run init first", ack };
+    if (facts.agentKid !== null && facts.agentKid !== options.agentKid) {
+        return { state: "rejected", error: "scope_mismatch", message: `this export is for the agent key ${facts.agentKid}, but this machine's agent key is ${options.agentKid}; it was exported for a different agent or installation`, ack };
+    }
+    const warnings = facts.agentKid === null ? ["the workspace has no enrolled key for this agent, so the export could not be bound to this machine's agent identity; it is loaded for this machine's key on your say-so"] : [];
+    const current = readDispatchFile(dir) ?? {};
+    const existing = (current.budgets ?? []);
+    // Workspace budgets are per agent and versioned; a same or newer version is never replaced by an older export.
+    const workspace = existing.filter((b) => b.source_export_id !== undefined && b.actor === options.agentKid);
+    const newer = workspace.find((b) => b.budget_id !== facts.budgetId && b.version >= facts.budgetVersion);
+    if (newer)
+        return { state: "rejected", error: "unsupported", message: `a same or newer workspace budget (version ${newer.version}) is already loaded; an older export cannot replace it`, ack };
+    const same = workspace.find((b) => b.budget_id === facts.budgetId);
+    if (same && same.version > facts.budgetVersion)
+        return { state: "rejected", error: "unsupported", message: `version ${same.version} of this budget is already loaded`, ack };
+    if (!options.apply)
+        return { state: "would_load", facts, warnings };
+    mkdirSync(dir, { recursive: true });
+    const replaced = workspace.filter((b) => b.budget_id !== facts.budgetId).map((b) => b.budget_id);
+    const kept = existing.filter((b) => !workspace.includes(b));
+    const next = { ...current, budgets: [...kept, localBudgetOf(facts, options.agentKid, new Date(options.now ?? Date.now()).toISOString())] };
+    const target = join(dir, DISPATCH_FILE);
+    const temp = `${target}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temp, target);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch { /* nothing to remove */ }
+        throw error;
+    }
+    return { state: "loaded", facts, replaced, warnings };
+}
+//# sourceMappingURL=budget-load.js.map

package/dist/budget-load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-load.js","sourceRoot":"","sources":["../src/budget-load.ts"],"names":[],"mappings":"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","sourcesContent":["// `scopebond budget load <export.json>`: load a reviewed action budget exported from a workspace,\n// as the budget this machine enforces, and say honestly what happened.\n//\n// An export is a reviewed, approved policy in a file. It is pending in the workspace until a signed\n// acknowledgement echoes exactly what the export said: its export id, the budget id and version, the\n// policy digest and the scope digest. This module checks an export and, when asked, writes it into\n// `dispatch.json` as an acknowledged budget policy; the caller then queues the `policy_ack`.\n//\n// What is checked, and what is not:\n//   - the document type and version, and the fail-closed contract it carries (an export that would\n//     permit unlimited dispatch on failure is refused);\n//   - the policy digest: SHA-256 of the canonical policy with its acknowledgement removed, which is\n//     what the workspace hashed when the budget was drafted;\n//   - the scope digest, the environment (when this machine is connected), the validity window, and\n//     that the policy is one an independent installation can enforce (a limit shared across\n//     installations needs a shared in-path gateway, which a hook is not).\n// An export carries no signature of its own: get the file from your workspace, over its own page or\n// API. Loading replaces an older workspace budget for the same agent; it never replaces a newer one.\n\nimport { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { randomBytes } from \"node:crypto\";\nimport { budgetDigest, type ActionBudgetPolicy } from \"@scopebond/gateway\";\nimport { DISPATCH_FILE, readDispatchFile } from \"@scopebond/gateway/node\";\nimport { digestPolicy, type PolicyAckInput, type PolicyLoadError } from \"./observation.js\";\nimport { policyScopeDigest, MAX_EXPORT_BYTES } from \"./policy-load.js\";\n\nexport const BUDGET_EXPORT_TYPE = \"scopebond:action-budget-export\";\nconst HEX64 = /^[0-9a-f]{64}$/;\nconst OPAQUE = /^[\\x21-\\x7e]{1,200}$/;\nconst isObject = (v: unknown): v is Record<string, unknown> => typeof v === \"object\" && v !== null && !Array.isArray(v);\n\nexport interface BudgetExportFacts {\n  exportId: string;\n  budgetId: string;\n  budgetVersion: number;\n  policyDigest: string;\n  scopeDigest: string;\n  agentId: string;\n  /** The key the workspace says this agent signs with, or null when it could not say (no enrolled key). */\n  agentKid: string | null;\n  environmentId: string;\n  validUntil: number;\n  policy: { operation_set: string[]; authority_scope: \"installation\" | \"shared_gateway\"; max_dispatch: number; window_seconds: number; mode: \"monitor\" | \"enforce\"; version: number };\n}\n\nexport type BudgetInspection =\n  | { ok: true; facts: BudgetExportFacts }\n  /** `ack` is set when the export names enough to echo in a rejection; otherwise nothing is acknowledged. */\n  | { ok: false; error: PolicyLoadError | \"expired\"; message: string; ack?: Omit<PolicyAckInput, \"error\"> };\n\n/** Accept the export itself, or the workspace's `{ version, export }` answer around it. */\nexport function unwrapBudgetExport(raw: unknown): Record<string, unknown> | null {\n  if (!isObject(raw)) return null;\n  if (raw.type === undefined && isObject(raw.export)) return raw.export;\n  return raw;\n}\n\n/** Check an export without reading or changing anything on disk. Pure. */\nexport function inspectBudgetExport(raw: unknown, context: { environmentId?: string; now?: number } = {}): BudgetInspection {\n  const exp = unwrapBudgetExport(raw);\n  if (!exp || exp.type !== BUDGET_EXPORT_TYPE) return { ok: false, error: \"schema_invalid\", message: \"this is not a Scopebond action budget export\" };\n  if (exp.version !== 1) return { ok: false, error: \"unsupported\", message: `unsupported export version ${String(exp.version)}` };\n  const { export_id: exportId, budget_id: budgetId, budget_version: budgetVersion, agent_id: agentId, environment_id: environmentId, valid_until: validUntil } = exp;\n  const policy = exp.policy;\n  const agentKid = exp.agent_kid;\n  // `agent_kid` is always present in an export (a key id, or null when the workspace has no enrolled key for the agent); an export without it predates identity binding.\n  if (agentKid === undefined || (agentKid !== null && (typeof agentKid !== \"string\" || !OPAQUE.test(agentKid)))) {\n    return { ok: false, error: \"schema_invalid\", message: \"the export does not say which agent key it is for (agent_kid is missing or malformed); export the budget again from the workspace\" };\n  }\n  if (typeof exportId !== \"string\" || !OPAQUE.test(exportId) || typeof budgetId !== \"string\" || !OPAQUE.test(budgetId) || !Number.isInteger(budgetVersion) || (budgetVersion as number) < 1\n    || (budgetVersion as number) > 2_147_483_647 || typeof agentId !== \"string\" || !OPAQUE.test(agentId) || typeof environmentId !== \"string\" || !OPAQUE.test(environmentId)\n    || typeof validUntil !== \"number\" || !Number.isFinite(validUntil) || !isObject(policy) || typeof exp.policy_digest !== \"string\" || !HEX64.test(exp.policy_digest)\n    || typeof exp.scope_digest !== \"string\" || !HEX64.test(exp.scope_digest)) {\n    return { ok: false, error: \"schema_invalid\", message: \"the export lacks a budget id, version, policy, digest or validity window, or they are malformed\" };\n  }\n  // Echoed exactly as the export states them, so a rejection still names the export.\n  const echo = { exportId, policyId: budgetId, policyVersion: budgetVersion as number, policyDigest: exp.policy_digest, scopeDigest: exp.scope_digest };\n  const ops = policy.operation_set;\n  if (!Array.isArray(ops) || ops.length < 1 || ops.length > 100 || !ops.every((o) => typeof o === \"string\" && OPAQUE.test(o))\n    || (policy.authority_scope !== \"installation\" && policy.authority_scope !== \"shared_gateway\") || (policy.mode !== \"monitor\" && policy.mode !== \"enforce\")\n    || !Number.isInteger(policy.max_dispatch) || (policy.max_dispatch as number) < 1 || (policy.max_dispatch as number) > 1_000_000_000\n    || !Number.isInteger(policy.window_seconds) || (policy.window_seconds as number) < 1 || (policy.window_seconds as number) > 366 * 86_400\n    || policy.version !== budgetVersion) {\n    return { ok: false, error: \"schema_invalid\", message: \"the export's budget policy is malformed\", ack: echo };\n  }\n  if (digestPolicy({ ...policy, acknowledged: null }) !== exp.policy_digest) {\n    return { ok: false, error: \"signature_invalid\", message: \"the policy does not match the export's policy digest; the file was changed or damaged\", ack: echo };\n  }\n  if (policyScopeDigest({ export_id: exportId, agent_id: agentId, environment_id: environmentId }) !== exp.scope_digest) {\n    return { ok: false, error: \"scope_mismatch\", message: \"the export's scope digest does not match its export, agent and environment\", ack: echo };\n  }\n  if (context.environmentId !== undefined && context.environmentId !== environmentId) {\n    return { ok: false, error: \"scope_mismatch\", message: \"this export is for a different environment than this machine is connected to\", ack: echo };\n  }\n  if (policy.acknowledged === null || policy.acknowledged === undefined) {\n    return { ok: false, error: \"schema_invalid\", message: \"the budget was not approved in the workspace (no acknowledgement); only an approved budget can be loaded\", ack: echo };\n  }\n  const enforcement = isObject(exp.enforcement) ? exp.enforcement : null;\n  const failClosed = enforcement && isObject(enforcement.fail_closed) ? enforcement.fail_closed : null;\n  if (!failClosed || failClosed.unlimited_dispatch_on_failure !== false) {\n    return { ok: false, error: \"unsupported\", message: \"the export does not state the fail-closed contract (no unlimited dispatch on failure); it is refused\", ack: echo };\n  }\n  if (policy.mode === \"enforce\" && (policy.authority_scope !== \"installation\" || enforcement?.eligible !== true)) {\n    return { ok: false, error: \"unsupported\", message: \"this budget cannot be enforced by an independent installation (a limit shared across installations needs a shared in-path gateway)\", ack: echo };\n  }\n  if (validUntil <= (context.now ?? Date.now())) {\n    return { ok: false, error: \"expired\", message: \"this export is past its validity window; export the budget again from the workspace\" };\n  }\n  return {\n    ok: true,\n    facts: {\n      agentKid: agentKid as string | null, exportId, budgetId, budgetVersion: budgetVersion as number, policyDigest: exp.policy_digest, scopeDigest: exp.scope_digest, agentId, environmentId, validUntil,\n      policy: policy as unknown as BudgetExportFacts[\"policy\"],\n    },\n  };\n}\n\n/** The budget policy this machine enforces for an export: the reviewed limits, acting as this installation's agent, valid until the export says. */\nexport function localBudgetOf(facts: BudgetExportFacts, agentKid: string, acknowledgedAt: string): ActionBudgetPolicy & { source_export_id: string } {\n  const policy: ActionBudgetPolicy & { source_export_id: string } = {\n    // The actor is the export's agent key; a null one (unverifiable identity) falls back to this installation's key, which is the only agent this machine dispatches as.\n    budget_id: facts.budgetId, actor: facts.agentKid ?? agentKid, operations: [...facts.policy.operation_set], authority_scope: facts.policy.authority_scope, max: facts.policy.max_dispatch,\n    window_seconds: facts.policy.window_seconds, mode: facts.policy.mode, version: facts.budgetVersion, expires_at: new Date(facts.validUntil).toISOString(),\n    acknowledgement: null, source_export_id: facts.exportId,\n  };\n  // Loading it is the acknowledgement: the person who ran `budget load --yes` accepts this exact policy.\n  policy.acknowledgement = { digest: budgetDigest(policy), acknowledged_at: acknowledgedAt };\n  return policy;\n}\n\nexport type BudgetLoadOutcome =\n  | { state: \"loaded\"; facts: BudgetExportFacts; replaced: string[]; warnings: string[] }\n  | { state: \"would_load\"; facts: BudgetExportFacts; warnings: string[] }\n  | { state: \"rejected\"; error: PolicyLoadError | \"expired\"; message: string; ack?: Omit<PolicyAckInput, \"error\"> };\n\n/** Read an export file, check it, and (with `apply`) write it into `dispatch.json` as an acknowledged budget. */\nexport function loadBudgetExport(dir: string, file: string, options: { apply: boolean; agentKid: string; environmentId?: string; now?: number }): BudgetLoadOutcome {\n  let raw: unknown;\n  try {\n    if (statSync(file).size > MAX_EXPORT_BYTES) return { state: \"rejected\", error: \"schema_invalid\", message: \"the export file is larger than 1 MiB\" };\n    raw = JSON.parse(readFileSync(file, \"utf8\"));\n  } catch (error) {\n    return { state: \"rejected\", error: \"schema_invalid\", message: `the export could not be read as JSON (${(error as Error).name})` };\n  }\n  const inspected = inspectBudgetExport(raw, { environmentId: options.environmentId, now: options.now });\n  if (!inspected.ok) return { state: \"rejected\", error: inspected.error, message: inspected.message, ...(inspected.ack ? { ack: inspected.ack } : {}) };\n  const { facts } = inspected;\n  const ack = { exportId: facts.exportId, policyId: facts.budgetId, policyVersion: facts.budgetVersion, policyDigest: facts.policyDigest, scopeDigest: facts.scopeDigest };\n  if (!options.agentKid) return { state: \"rejected\", error: \"unsupported\", message: \"this machine has no agent key to act as; run init first\", ack };\n  if (facts.agentKid !== null && facts.agentKid !== options.agentKid) {\n    return { state: \"rejected\", error: \"scope_mismatch\", message: `this export is for the agent key ${facts.agentKid}, but this machine's agent key is ${options.agentKid}; it was exported for a different agent or installation`, ack };\n  }\n  const warnings = facts.agentKid === null ? [\"the workspace has no enrolled key for this agent, so the export could not be bound to this machine's agent identity; it is loaded for this machine's key on your say-so\"] : [];\n  const current = readDispatchFile(dir) ?? {};\n  const existing = (current.budgets ?? []) as Array<ActionBudgetPolicy & { source_export_id?: string }>;\n  // Workspace budgets are per agent and versioned; a same or newer version is never replaced by an older export.\n  const workspace = existing.filter((b) => b.source_export_id !== undefined && b.actor === options.agentKid);\n  const newer = workspace.find((b) => b.budget_id !== facts.budgetId && b.version >= facts.budgetVersion);\n  if (newer) return { state: \"rejected\", error: \"unsupported\", message: `a same or newer workspace budget (version ${newer.version}) is already loaded; an older export cannot replace it`, ack };\n  const same = workspace.find((b) => b.budget_id === facts.budgetId);\n  if (same && same.version > facts.budgetVersion) return { state: \"rejected\", error: \"unsupported\", message: `version ${same.version} of this budget is already loaded`, ack };\n  if (!options.apply) return { state: \"would_load\", facts, warnings };\n  mkdirSync(dir, { recursive: true });\n  const replaced = workspace.filter((b) => b.budget_id !== facts.budgetId).map((b) => b.budget_id);\n  const kept = existing.filter((b) => !workspace.includes(b));\n  const next = { ...current, budgets: [...kept, localBudgetOf(facts, options.agentKid, new Date(options.now ?? Date.now()).toISOString())] };\n  const target = join(dir, DISPATCH_FILE);\n  const temp = `${target}.${randomBytes(6).toString(\"hex\")}.tmp`;\n  try { writeFileSync(temp, `${JSON.stringify(next, null, 2)}\\n`, { mode: 0o600 }); renameSync(temp, target); }\n  catch (error) { try { rmSync(temp, { force: true }); } catch { /* nothing to remove */ } throw error; }\n  return { state: \"loaded\", facts, replaced, warnings };\n}\n\n"]}

package/dist/capabilities.d.ts

@@ -0,0 +1,103 @@
+import { type Vector, type VectorAgent } from "./vectors.js";
+export type CapabilityState = "unsupported" | "configured_unverified" | "verified_reporting" | "degraded" | "inactive" | "retired";
+export type HostVariant = "claude_terminal" | "claude_desktop" | "codex_cli" | "codex_desktop" | "cursor";
+export type EventPhase = "pre_action" | "after_action";
+export type Adapter = VectorAgent;
+/** The outcome of running a cell's fixtures. */
+export interface ProofRecord {
+    cell: string;
+    ran_at: string;
+    adapter_version: string;
+    test_vector_digest: string;
+    /** `fixture`: local run against temp state. `live_harness`: recorded from a real host. */
+    origin: "fixture" | "live_harness";
+    /** A benign action was allowed and produced a countersigned receipt. */
+    safe_allow: boolean;
+    /** A violating action was denied at the claimed boundary, or `not_applicable`. */
+    safe_deny: boolean | "not_applicable";
+    /** Every receipt from the fixtures verified against the countersigning key. */
+    signature: boolean;
+    /** Every receipt of one tool call carried the same action group. */
+    grouping: boolean;
+    /** Cloud acknowledgement. Never `acknowledged` from a local fixture run. */
+    cloud_ack: "not_checked" | "acknowledged" | "failed";
+    observation_only: boolean;
+    /** `source_receipt_hash` of the fixture receipts whose action type is this cell's (allow
+     *  fixtures, and deny fixtures for a before-action cell). Empty when none matched. */
+    proof_digests?: string[];
+    /** Typed-operation cells only: every fixture derived the closed operation it expects. */
+    typed_operation?: boolean;
+}
+export interface CapabilityCell {
+    key: string;
+    connector: "scopebond-hook";
+    adapter_version: string;
+    host_variant: HostVariant;
+    action_type: string;
+    event_phase: EventPhase;
+    state: CapabilityState;
+    /** Why the cell is in this state, in plain words. */
+    reason: string;
+    pre_action: boolean;
+    after_action: boolean;
+    /** Where enforcement happens: the harness's own hook, or nowhere. */
+    boundary: "harness_hook" | "none";
+    observation_only: boolean;
+    emitted_required_fields: string[];
+    supported_operations: string[];
+    /** Limits the vectors document; repeated here rather than hidden. */
+    known_gaps: string[];
+    min_runtime: {
+        node: string;
+    };
+    test_vector_digest: string | null;
+    last_proof: ProofRecord | null;
+}
+export interface Manifest {
+    connector: "scopebond-hook";
+    adapter_version: string;
+    generated_at: string;
+    cells: CapabilityCell[];
+}
+export declare const cellKey: (adapterVersion: string, host: HostVariant, actionType: string, phase: EventPhase) => string;
+/** The vectors that prove one cell: those tagged with its action type for its adapter. For
+ *  the after-action cell only the after-action vector counts. */
+export declare function vectorsForCell(adapter: Adapter, actionType: string, phase: EventPhase): Vector[];
+/** Digest of a cell's vectors (id, payload and expectation). A proof recorded against one
+ *  digest says nothing about a changed set. */
+export declare function vectorDigest(vectors: readonly Vector[]): string | null;
+export interface ManifestInput {
+    adapterVersion: string;
+    /** Which harnesses have the hook configured (any scope). */
+    configured: Record<Adapter, boolean>;
+    /** Recorded proofs by cell key. */
+    proofs?: Record<string, ProofRecord | undefined>;
+    now?: Date;
+    /** Cell keys (any version) whose adapter no longer ships, for history. */
+    retired?: string[];
+}
+/** Compute the state of one cell from what is configured and what has been proven. */
+export declare function cellState(input: {
+    supported: boolean;
+    unsupportedReason?: string;
+    configured: boolean;
+    digest: string | null;
+    adapterVersion: string;
+    proof: ProofRecord | null | undefined;
+    observationOnly: boolean;
+    retired?: boolean;
+}): {
+    state: CapabilityState;
+    reason: string;
+};
+/** The manifest for the installed hook. Pure: no filesystem, no clock beyond `now`. */
+export declare function computeManifest(input: ManifestInput): Manifest;
+/** The spec for a cell key, for the proof runner. */
+export declare function specForCell(cell: CapabilityCell): {
+    adapter: Adapter;
+    action_type: string;
+    phase: EventPhase;
+} | null;
+/** Plain-text rendering. Unsupported stays unsupported; nothing here upgrades a state. */
+export declare function renderManifest(manifest: Manifest): string;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}