car-runtime 0.46.1 → 0.48.0

package/index.d.ts

@@ -59,6 +59,14 @@ export interface CoderStartOptions {
    * hypothesis, the other buys a retry.
    */
   transientRetries?: number | undefined | null;
+  /**
+   * A `coder.discuss` conversation this run was distilled from. Its agreed
+   * constraints ride into contract derivation, so a rule stated once in the
+   * discussion does not have to be restated in the intent, and the session
+   * records the provenance. An unknown id is a clear error — never a silently
+   * ungrounded run.
+   */
+  discussionId?: string | undefined | null;
 }
 
 export class CarRuntime {
@@ -143,6 +151,28 @@ export class CarRuntime {
   /** Register a tool by name. */
   registerTool(name: string): Promise<void>;
 
+  /**
+   * The tools currently registered on this runtime, as a JSON array of full
+   * `ToolSchema` objects sorted by name.
+   *
+   * Counterpart to `registerTool` / `registerToolSchema`, which had none: a
+   * caller could add tools but never ask what was actually in effect, so a
+   * governed or read-only deployment could not prove "only these tools are
+   * callable". Sorted, so two calls with no registration in between are
+   * byte-identical and can be diffed.
+   */
+  listTools(): Promise<string>;
+
+  /**
+   * Remove a tool by name. Resolves to how many were removed — `0` means
+   * nothing matched, which is not an error, so cleanup can call this
+   * unconditionally.
+   *
+   * Drops the tool from both the runtime's registry and its schema map, so
+   * the model stops seeing it and the validator stops accepting it.
+   */
+  unregisterTool(name: string): Promise<number>;
+
   /** Register CAR's built-in agent utility tools. */
   registerAgentBasics(): Promise<void>;
 
@@ -391,6 +421,26 @@ export class CarRuntime {
    * dispatches the chosen components.
    */
   planEvolutionLive(requestJson: string): Promise<string>;
+  /**
+   * `supervision.subscribe` — register this connection as a supervisor of the
+   * admission gate: `{ filter?: { tools?, sessions?, min_reversibility? } }`.
+   *
+   * Intents arrive as `supervision.intent` NOTIFICATIONS on the same socket.
+   * A caller that cannot read notifications should poll `supervisionPending`
+   * instead — subscribing without consuming them blocks every supervised
+   * proposal until it fails closed.
+   */
+  supervisionSubscribe(requestJson: string): Promise<string>;
+  /**
+   * `supervision.unsubscribe` — stop supervising: `{}`. Intents already parked
+   * run out their timeout and fail closed rather than being released, so a
+   * supervisor cannot turn a pending deny into an allow by disconnecting.
+   */
+  supervisionUnsubscribe(requestJson: string): Promise<string>;
+  /** `supervision.pending` — every intent currently parked on a verdict: `{}`. */
+  supervisionPending(requestJson: string): Promise<string>;
+  /** `supervision.decide` — `{ intent_id, decision: { kind: "allow" | "deny" | "escalate", reason? } }`. */
+  supervisionDecide(requestJson: string): Promise<string>;
   /** `sync.status` — roster, journal frontier, stable frontier, state hash (B6). */
   syncStatus(requestJson: string): Promise<string>;
   /** `sync.append` — record an op on any surface: `{ surface, payload, scope? }` (B6). */
@@ -464,6 +514,27 @@ export class CarRuntime {
    */
   enforceSkillDeploymentLive(requestJson: string): Promise<string>;
 
+  /**
+   * Read the standing permission tier granted to this connection's daemon
+   * session (`read_only` | `sandbox_edit` | `full_access`) — the tier every
+   * {@link submitProposal} on this connection is judged against
+   * (Parslee-ai/car#890).
+   */
+  permissionGetTier(): Promise<string>;
+
+  /**
+   * Set this connection's standing permission tier and return the tier as the
+   * daemon now holds it. `tier` is `read_only` | `sandbox_edit` |
+   * `full_access`.
+   *
+   * Lets a binding client govern its own session — most usefully by tightening
+   * it: dropping to `read_only` makes the runtime escalate any write this
+   * client proposes to a human instead of running it. Raising the tier is
+   * host-gated whenever the daemon runs under a host token, so an agent
+   * connection cannot self-elevate.
+   */
+  permissionSetTier(tier: string): Promise<string>;
+
   /**
    * Ingest a skill through the deployment gate on the daemon (arXiv 2602.12430
    * "Agent Skills" — the loader integration). `requestJson` carries the skill
@@ -477,6 +548,21 @@ export class CarRuntime {
    */
   ingestSkillGoverned(requestJson: string): Promise<string>;
 
+  /**
+   * Adopt an installed skill pack on the daemon through the skill-trust
+   * deployment gate (arXiv 2602.12430 "Agent Skills" — the pack-adoption
+   * call-site). `requestJson` carries `pack` (an `ApprovedSkillPack`),
+   * `requested_tier?` (default `read_only`), and either `manifest?` — the signed
+   * bundle, whose signature trust is derived against the operator's
+   * `.car/config.toml` `trusted_skill_signers` keyring — or `provenance?`
+   * (caller-assembled), plus optional `scanned?`/`vulnerabilities?`/`source?`.
+   * Governance is unconditional: a denied skill never enters the graph. Returns
+   * `{ loaded, pending, refused, requested_tier, provenance, trusted_signers }`;
+   * a pending deny is resolved via `permission.approve`/`permission.reject` by
+   * the returned `fingerprint`, then re-adopted.
+   */
+  adoptSkillPack(requestJson: string): Promise<string>;
+
   /**
    * Save a learned skill with trigger context. Returns the node
    * index.
@@ -589,6 +675,13 @@ export class CarRuntime {
    * with reasoning suppressed to produce a direct answer, or
    * `"thinking_truncated"` when even that retry was empty (car-releases#60).
    *
+   * `auth_fallback_from` is present ONLY when a candidate earlier in the
+   * fallback chain was skipped because its credential was **rejected**
+   * (not merely absent) and a later model then answered. It names that
+   * dead lane, so a caller can tell the user their sign-in lapsed instead
+   * of silently serving a different model (Parslee-ai/car#888). Absent on
+   * the common path.
+   *
    * **Note:** intent is not exposed on the tracked path until the
    * positional argument list is converted to an options object —
    * this method already takes 9 positional parameters and adding
@@ -774,8 +867,24 @@ export class CarRuntime {
   /**
    * Unified registry (local + remote). Returns JSON array of
    * `{ id, name, provider, capabilities, param_count, size_mb,
-   *   context_length, available, is_local, max_output_tokens,
-   *   public_benchmarks, cost }`. `max_output_tokens` is the registry-declared
+   *   context_length, available, is_local, weights_ready, downloads_weights,
+   *   max_output_tokens, public_benchmarks, cost }`. `available` means CAR
+   * can use the model
+   * here — for a local MLX entry with a declared `hf_repo` it is `true`
+   * before a byte is fetched, because it lazy-downloads on first use —
+   * whereas `weights_ready` means the weights are already on disk (remote
+   * models, having none to install, report `true`). Older daemons omit
+   * `weights_ready`; it defaults to `false` rather than failing.
+   * `downloads_weights` is `true` only for entries whose weights CAR fetches
+   * before use (GGUF, MLX, whisper.cpp); when it is `false` — OS-provided
+   * models such as `windows/speech-synthesis:os` and
+   * `apple/foundation:default`, server-backed local models such as
+   * `vllm-mlx/*` and Ollama, and every remote entry — there is nothing to
+   * install, so `weights_ready` is meaningless and the CLI renders
+   * `INSTALLED` as `-`. Do not substitute `is_local`: those first four are
+   * all local and all download nothing. Older daemons omit
+   * `downloads_weights`; it defaults to `false` rather than failing.
+   * `max_output_tokens` is the registry-declared
    *   per-model output ceiling (`null` when the entry omits it; callers
    *   then fall back to a fraction of `context_length`).
    * `public_benchmarks` is `[{ name, score, harness?, source_url?,
@@ -937,9 +1046,93 @@ export class CarRuntime {
    */
   coderApproveMerge(sessionId: string, approve: boolean): Promise<string>;
 
-  /** Cancel a session: stop the loop, abandon, remove the worktree. */
+  /**
+   * Cancel a session: stop the loop, abandon, remove the worktree. Returns
+   * `{state, already_terminal, message}`.
+   *
+   * An already-finished session **succeeds** rather than rejecting: `state`
+   * keeps its pre-existing name and type, `already_terminal` is `true`, and
+   * `message` names what already happened. Callers that cancel unconditionally
+   * on shutdown depend on that — rejecting would turn a quiet exit into a
+   * protocol error whenever the session raced to terminal first.
+   */
   coderCancel(sessionId: string): Promise<string>;
 
+  /**
+   * The current session list AND registration for `coder.session_changed` on
+   * this connection, atomically (registered under the same lock the list is
+   * snapshotted under, so nothing slips through the gap). Notifications are
+   * WebSocket-only, same contract as `coder.subscribe`.
+   *
+   * Each row carries the full summary: the pre-existing
+   * `{session_id, state, intent, repo, engine, iterations, updated_at, live,
+   * error}` plus `needs_you` (`"contract" | "question" | "approval" | "auth" |
+   * null`), `needs_you_label` (the daemon-owned wording, so every client says
+   * the same thing), `question_prompt`, `auth_message`, `auth_wait_secs`,
+   * `failure_kind` (`"budget_exhausted" | "auth_required" | "infrastructure" |
+   * "error"` when failed), `worktree` (only when it still exists on disk),
+   * `project`, `result_branch`, `model`, `discussion_id`, and `next_seq` (live
+   * only — the `coder.subscribe` cursor).
+   *
+   * Pass `renew: true` for the lease-renewal form: it re-registers and answers
+   * `{ was_registered }` — `false` means this connection had been shed and
+   * should take a full snapshot — and builds NO summaries, so it is cheap
+   * enough to call on a timer. The default form is unchanged.
+   */
+  coderWatch(renew?: boolean | undefined | null): Promise<string>;
+
+  /** Stop receiving `coder.session_changed` on this connection. */
+  coderUnwatch(): Promise<string>;
+
+  /**
+   * Redraft a PROPOSED outcome contract from a plain-English request (e.g.
+   * "also verify the Windows path"). Legal only in `contract_proposed`;
+   * nothing executes and the session stays at the gate either way. Unlimited
+   * rounds.
+   *
+   * Returns `{state, revised, contract, baseline, baseline_gates_nothing,
+   * message}`. **Check `revised` before trusting `contract`**: on a redraft
+   * that does not validate, the previous contract comes back byte-identical
+   * with `revised: false` and a `message` explaining why, and the daemon emits
+   * a `contract_revision_rejected` event.
+   */
+  coderReviseContract(sessionId: string, request: string): Promise<string>;
+
+  /**
+   * Open a repo-grounded, strictly **read-only** discussion — a thinking
+   * surface for working out what a change should be, before a run exists.
+   * Bound at `PermissionTier::ReadOnly` with every write/shell escalation
+   * auto-denied, so it can never touch the repo. Returns
+   * `{discussion_id, repo, repo_summary}`; a non-git path is a clear error.
+   */
+  coderDiscussStart(repo: string): Promise<string>;
+
+  /**
+   * Send one operator message. Returns `{ok, seq}` where `seq` is the first
+   * event this turn emits; the reply streams as `coder.discuss.event`
+   * (WebSocket-only, same contract as `coder.event`).
+   */
+  coderDiscussSend(discussionId: string, text: string): Promise<string>;
+
+  /**
+   * Distill the discussion into `{discussion_id, proposed_intent,
+   * constraints}`. **Starts nothing** — no worktree, no branch, no session.
+   * The caller shows `proposed_intent` (never the transcript) for the operator
+   * to edit, then passes it to `coderStart` with `discussion_id` so the agreed
+   * constraints reach contract derivation. Callable repeatedly.
+   */
+  coderDiscussPromote(discussionId: string): Promise<string>;
+
+  /** Free an in-memory discussion. Discussions do not survive a daemon restart. */
+  coderDiscussClose(discussionId: string): Promise<string>;
+
+  /**
+   * Open discussions: `{discussions: [{discussion_id, repo, created_at,
+   * turns}]}`. Also the capability probe — a daemon predating this surface
+   * answers JSON-RPC `-32601`.
+   */
+  coderDiscussList(): Promise<string>;
+
   /**
    * Managed projects + in-daemon declarative agents (the non-developer path).
    *
@@ -1436,10 +1629,25 @@ export class CarRuntime {
 /**
  * Execute a proposal through a CarRuntime with a JS tool callback.
  * The callback receives
- * `{"tool":"name","params":{...},"action_id":"<id>"}` as a JSON
- * string and must return a JSON string. `action_id` is the
+ * `{"tool":"name","params":{...},"action_id":"<id>","request_id":"<id>","timeout_ms":<ms|null>,"session_id":"<id>|null","attempt":<n>}`
+ *
+ * `attempt` is the engine's retry counter, 1-based — which retry you are
+ * serving. (Correlate a specific in-flight call by `request_id` instead.) It
+ * was hardcoded to 1 on the wire and dropped here before car#928.
+ *
+ * `session_id` is the daemon-stamped execution session (car#904) — the
+ * attribution key for which mission a callback belongs to. Null when the
+ * caller has no session. Prefer it over reconstructing attribution from
+ * `action_id`, which is client-authored and not unique across concurrent or
+ * retried attempts.
+ * as a JSON string and must return a JSON string. `action_id` is the
  * originating `Action.id` from the proposal — useful for routing
  * when the same callback closes over multiple in-flight calls.
+ * `request_id` is the daemon's callback-routing id, which a
+ * `tools.cancel` notification repeats so the host can abort the right
+ * in-flight call. `timeout_ms` is the action's declared budget in
+ * milliseconds when the action declared one (`null` otherwise); the
+ * host's tool runner may use it to bound its own work.
  *
  * `sessionId`, when provided, scopes per-action policy validation to
  * the named session opened via `CarRuntime.openSession()`. Global
@@ -1657,6 +1865,13 @@ export function registerVoiceEventHandler(
  * Promise is logged, not surfaced to the host. Process-wide setter,
  * symmetric to `registerVoiceEventHandler`; pair with
  * `unregisterChatHandler` to clear.
+ *
+ * The handler may call any runtime method and should run the turn inline.
+ * NAPI dispatches through a non-blocking `ThreadsafeFunction` and `chatEvent`
+ * is async, so this side never had the reentrancy hazard that made the same
+ * surface unusable from Python before Parslee-ai/car#905 — noted here because
+ * the two bindings' handlers now carry the same contract for the same reason,
+ * arrived at differently.
  */
 export function registerChatHandler(
   handlerFn: (paramsJson: string) => void,
@@ -1675,11 +1890,27 @@ export function unregisterChatHandler(): void;
  * this handler.
  *
  * `handlerFn(callJson)` receives
- * `{"tool":"name","params":{...},"action_id":"<id>"}` as a JSON
- * string and MUST return a Promise resolving to the tool's
+ * `{"tool":"name","params":{...},"action_id":"<id>","request_id":"<id>","timeout_ms":<ms|null>,"session_id":"<id>|null","attempt":<n>}`
+ *
+ * `attempt` is the engine's retry counter, 1-based — which retry you are
+ * serving. (Correlate a specific in-flight call by `request_id` instead.) It
+ * was hardcoded to 1 on the wire and dropped here before car#928.
+ *
+ * `session_id` is the daemon-stamped execution session (car#904) — the
+ * attribution key for which mission a callback belongs to. Null when the
+ * caller has no session. Prefer it over reconstructing attribution from
+ * `action_id`, which is client-authored and not unique across concurrent or
+ * retried attempts.
+ * as a JSON string and MUST return a Promise resolving to the tool's
  * JSON-encoded result. Throwing rejects the daemon-side action
  * with a -32000 JSON-RPC error.
  *
+ * `request_id` is the daemon's callback-routing id, repeated by the
+ * `tools.cancel` notification so the host can abort the right
+ * in-flight call. `timeout_ms` is the action's declared budget in
+ * milliseconds when the action declared one (`null` otherwise); the
+ * host's tool runner may use it to bound its own work.
+ *
  * `action_id` carries the originating `Action.id` from the
  * proposal so process-wide handlers can route concurrent
  * callbacks back to the right per-call closure. Empty string when
@@ -1942,6 +2173,30 @@ export function resumeWorkflow(pausedJson: string, inputJson: string): Promise<s
  * resumable runs after a restart. */
 export function listPausedWorkflows(runsDir: string): string;
 
+/** Bind (or clear) the memory namespace for subsequent daemon connections
+ * (car-releases#81). Returns the namespace now in effect, or `null` for the
+ * daemon's shared graph.
+ *
+ * Prefer this over setting `CAR_MEMORY_NAMESPACE` when the namespace is
+ * per-project. An env var cannot carry a per-project value: the host learns
+ * which project it is *after* the process starts, and on **bun** a JS-side
+ * `process.env` write never reaches the C `environ` this library reads — the
+ * write is silently ignored and the session falls back to the shared graph.
+ *
+ * Blank or `null` clears the override, falling back to `CAR_MEMORY_NAMESPACE`
+ * and then the shared graph.
+ *
+ * **Takes effect on the next connection.** The namespace is negotiated during
+ * `session.auth`, so an already-established connection keeps the graph it
+ * bound. Call this before your first CAR call, or disconnect afterwards to
+ * force a rebind — otherwise you keep writing to the previous project's
+ * graph. */
+export function setMemoryNamespace(namespace?: string | null): string | null;
+
+/** The memory namespace currently in effect — the explicit override if set,
+ * otherwise `CAR_MEMORY_NAMESPACE`, otherwise `null` (shared graph). */
+export function getMemoryNamespace(): string | null;
+
 /** NLP (F4): identify the dominant language of `text`. Returns
  * `{language, backend}` JSON (Apple NaturalLanguage on macOS, pure-Rust
  * fallback elsewhere). */
@@ -2145,10 +2400,25 @@ export function sendA2AMessage(rt: CarRuntime, paramsJson: string): Promise<stri
  * `{ valid, issues, simulated_state, execution_levels, conflicts,
  * evidence }`. `evidence` is the verifier's declared scope (survey
  * "Code as Agent Harness" §5.2.2): `{ checks: [{ name, ran, verifies,
- * cannot_verify, findings }], assumptions, untested_regions,
+ * cannot_verify, findings, tier }], assumptions, untested_regions,
  * residual_risks, confidence }` — so a `valid: true` verdict can be read
  * with its scope (what was checked, what was not, coverage confidence)
  * rather than as a blanket guarantee.
+ *
+ * Each issue is `{ action_id, severity, message, tier }`. `tier` is the
+ * **evidence tier** — `"decision_procedure" | "heuristic" | "sampled"` —
+ * naming which kind of check produced the finding, so you don't have to
+ * pattern-match the message to tell them apart. All of `verify`'s
+ * findings are `decision_procedure` (set membership, the STRIPS-style
+ * forward walk, write-conflict detection) except the
+ * repeated-identical-call rule, which is `heuristic`: the count is
+ * exact, "runaway loop" is a proxy, and a legitimate 3× poll trips it.
+ * The tier is orthogonal to `severity` (how bad, not how derived), and
+ * `decision_procedure` is not a proof or a soundness claim — it means
+ * the check decides the property it reports over the inputs it was
+ * given, which for the state-dependent checks is a forward model built
+ * only from *declared* effects. Each `CheckRecord` carries the same
+ * `tier` as the findings it contributed.
  */
 export function verify(
   proposalJson: string,
@@ -2652,8 +2922,13 @@ export function cascadeDecide(
  *
  * `statsJson` is aggregate counters (parsed by serde — keys are snake_case):
  * `{ total_facts, structured_facts, total_edges, total_retrievals,
- * helpful_retrievals, conflicts_resolved, outstanding_outdated, facts_created,
- * facts_superseded }` (omitted fields default to 0). Returns the report JSON:
+ * total_proactive_injections, helpful_retrievals, conflicts_resolved,
+ * outstanding_outdated, facts_created, facts_superseded }` (omitted fields
+ * default to 0). `total_retrievals` counts DELIBERATE recalls only;
+ * harness-initiated proactive injections are reported separately as
+ * `total_proactive_injections` and never feed ranking (car#816).
+ * `helpful_retrievals` is always 0 today — `record_fact_helpful` has no
+ * production caller — so read a 0 there as "not wired", not "nothing helped". Returns the report JSON:
  * `{ representation_fidelity, retrieval_precision, update_correctness,
  * long_horizon_stability, overall }` (each 0..1), `bottleneck` (one of
  * `"representation" | "retrieval" | "update_correctness" |
@@ -2742,6 +3017,16 @@ export function simulateWithPredictions(
  * `state_consistency` (changes, snapshots, rollbacks), `safety`
  * (permission escalations/denials/approvals), and `replayability` — to
  * complement task-success accuracy when comparing harness variants.
+ *
+ * The optional `task_pass_rate` field — and its two companions,
+ * `task_pass_denominator` (how many tasks that rate is over) and
+ * `tasks_unrunnable` (how many the runner could not measure) — are **always
+ * absent** from this result: end-task success is not in the event stream (the
+ * log records what ran, not whether the task was satisfied), and inventing any
+ * of the three here would hand the regression gate a fabricated number. Only a
+ * runner holding the task suite and its grading criteria can supply them —
+ * `car-bench-harness --metrics-out` does. Absent means *not measured*, never
+ * zero.
  */
 export function harnessMetrics(eventsJsonl: string): string;
 
@@ -2817,9 +3102,30 @@ export function evolutionDiagnose(
  * `HarnessMutation`; `baselineJson`/`candidateJson` are `HarnessMetrics`
  * measured before/after applying it on held-out telemetry. Returns the
  * `PromotionDecision` JSON `{ decision: "promote" | "needs_approval" |
- * "reject", reason }` — a mutation is promoted only if its target improved
- * without regressing guarded metrics; safety-affecting mutations route to
- * `needs_approval` even when they pass.
+ * "reject" | "incomparable", reason }` — a mutation is promoted only if its
+ * target improved without regressing guarded metrics; safety-affecting
+ * mutations route to `needs_approval` even when they pass.
+ *
+ * Reliability is guarded twice, because the two available measures are
+ * different quantities. `task_pass_rate` is end-task success and is checked
+ * first, but only when BOTH documents carry it (absent on either side = not
+ * measured, so the guard does not fire rather than defaulting to 0.0 or 1.0).
+ * `trajectory_efficiency.success_rate` is tool-attempt success and is always
+ * checked. A candidate that cuts tokens by abandoning hard tasks earlier holds
+ * a perfect attempt-level rate while solving fewer tasks — only the first guard
+ * sees that.
+ *
+ * Before either guard, the two pass rates must be over the SAME task set.
+ * `HarnessMetrics` carries two optional companions to `task_pass_rate`:
+ * `task_pass_denominator` (how many tasks the rate is over) and
+ * `tasks_unrunnable` (how many the runner could not measure). When both
+ * documents carry a denominator and they differ, the result is
+ * `incomparable` — no verdict, nothing applied. That is not pedantry: a
+ * harness that loses a capability also loses the ability to *measure* the
+ * tasks needing it, so those tasks leave the denominator and the surviving
+ * rate goes up. Both fields are optional and absent from documents written
+ * before they existed, in which case the check is skipped rather than
+ * failing.
  */
 export function evolutionEvaluate(
   mutationJson: string,
@@ -2849,11 +3155,76 @@ export function evolutionApply(
 // (read_only | sandbox_edit | full_access), gate it against the session's
 // granted standing tier, and record human-in-the-loop approvals as durable,
 // auditable state (a JSONL ledger keyed by a stable action fingerprint).
-
-/**
- * Classify each action in a proposal into its minimum required permission
- * tier. Returns a JSON array of `{ action_id, tool, required_tier }` where
- * `required_tier` is `"read_only" | "sandbox_edit" | "full_access"`.
+//
+// Two axes, not one. The tier answers "who may authorize this?" and says
+// nothing about whether the effect can be undone — a `git push`, a production
+// INSERT, and a charged card are all `full_access` with three different
+// rollback contracts. Every row below therefore carries a `reversibility`
+// alongside its `required_tier`.
+//
+// The matching Action IR fields (any `proposalJson` this package accepts, and
+// the full spec in docs/agent-ir-spec.md):
+//
+//   "reversibility": "reversible" | "compensable" | "irreversible"
+//       Optional. The rollback contract for this action's effects.
+//       `reversible` is undone by restoring the scope it ran in;
+//       `compensable` needs a compensating action run against it;
+//       `irreversible` cannot be undone once it reaches the world.
+//       **Defaults to "irreversible"** when omitted — deliberately, because
+//       the default decides what the runtime believes about an unclassified
+//       action and the two directions fail asymmetrically. Guessing
+//       "reversible" wrongly means silently believing a sent email can be
+//       unsent; guessing "irreversible" wrongly means over-asking for an
+//       approval on something recoverable, which is annoying, visible, and
+//       fixed locally by annotating the action.
+//
+//   "compensation": { "type": "tool", "tool": string, "parameters"?: object }
+//                 | { "type": "action_ref", "action_id": string }
+//       Optional. How to undo the action once it has run — the action-level
+//       analogue of car-workflow's saga CompensationHandler. Meaningful only
+//       with `"reversibility": "compensable"`; omitted from the serialized
+//       form when absent, so older consumers see the payload they saw before.
+//       Declaring one is a *claim*: nothing checks that the named tool is a
+//       true inverse, exactly as nothing checks `expected_effects`.
+//
+// Nothing in the runtime enforces on either field yet — they are typed,
+// classified, and audited. Do not read `"reversible"` as a promise that the
+// runtime will undo anything for you: rollback restores the state map and
+// leaves whatever a tool wrote to disk where it is. See
+// docs/proposals/shepherd-substrate-adoption.md.
+
+/**
+ * Classify each action in a proposal on both authorization-adjacent axes.
+ * Returns a JSON array of `{ action_id, tool, required_tier, reversibility,
+ * missing_compensation }`. The keys live inside a JSON string, so they stay
+ * snake_case — napi-rs camelCases function and parameter names, not payload
+ * contents.
+ *
+ * - `required_tier` — **who may authorize this**: `"read_only" |
+ *   "sandbox_edit" | "full_access"`.
+ * - `reversibility` — **can this be undone**: `"reversible" | "compensable" |
+ *   "irreversible"`. Independent of the tier and not derived from it:
+ *   `read_secret` is `full_access` and perfectly reversible (a read leaves
+ *   nothing to undo), while `send_email` and `deploy_service` are both
+ *   `full_access` and differ completely. This is the classifier's answer from
+ *   the tool name and flattened parameters — **not** an echo of the action's
+ *   declared `reversibility` field, which defaults to `"irreversible"` and so
+ *   would tell you only what you sent. It is a keyword heuristic: an
+ *   unrecognized tool comes back `"irreversible"`, deliberately.
+ * - `missing_compensation` — the action **declared** `"compensable"` and
+ *   supplied no `compensation`, the one incoherent combination the IR cannot
+ *   exclude by construction. Keyed off the declared field, so it stays `false`
+ *   for proposals that never opted into the axis.
+ *
+ * Severity ascends `"reversible" < "compensable" < "irreversible"`, so the
+ * rollback contract of a whole batch is the worst row — a plan is only as
+ * recoverable as its least recoverable step. (The daemon's `permission.classify`
+ * returns that roll-up precomputed as `declared_rollback_contract`, over the
+ * *declared* fields; this function returns a bare array with nowhere to hang
+ * it, so compute it from the column you care about.)
+ *
+ * Nothing in the runtime gates on the second axis yet — it is typed,
+ * classified, and audited, not enforced.
  */
 export function permissionClassify(proposalJson: string): string;
 
@@ -2861,10 +3232,17 @@ export function permissionClassify(proposalJson: string): string;
  * Evaluate each action against a granted standing tier, consulting the
  * durable approval ledger JSONL at `ledgerPath` when supplied. Returns a
  * JSON array of per-action decisions, each `{ decision, required, granted,
- * action_id, fingerprint, ... }` where `decision` is `"allow" |
+ * action_id, fingerprint, reversibility, ... }` where `decision` is `"allow" |
  * "needs_approval" | "deny"`. A `needs_approval` decision means autonomy is
  * suspended pending a human decision; resolve it with
  * {@link permissionRecordForFingerprint}.
+ *
+ * `reversibility` is orthogonal to `decision` and rides on **every** row, the
+ * `allow`s included: the gate's verdict says whether the action may run, not
+ * whether it could be taken back afterwards, and a caller that only learns the
+ * rollback contract of the actions it was stopped on is missing exactly the
+ * rows an incident review reads first. Same field, labels, and classifier as
+ * the `PermissionDecision` event the engine writes to its audit log.
  */
 export function permissionEvaluate(
   proposalJson: string,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.46.1",
+  "version": "0.48.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",