@decionis/agent-safe-pipeline 0.4.1 → 0.5.0

package/dist/plan/GovernedPlan.d.ts

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import type { AgentProposal } from "../intent/ExecutionIntent.js";
+import { type JsonObject } from "../intent/JsonValue.js";
+import { type PlanStepReference } from "./PlanStepReference.js";
+/**
+ * A governed plan: one change carried out as several governed operations,
+ * each proposed, decided, granted, claimed and finalized on its own.
+ *
+ * The plan is a governance object, not an orchestrator. It names the steps,
+ * which step depends on which and how (the coupling), and what stays
+ * admissible once a step has failed. Registering it with the authority
+ * authorizes no step: the authority derives each step's plan facts from its
+ * own finalization records, and policy decides each step with those facts in
+ * front of it. ADR 0008 is the design.
+ */
+export declare const GOVERNED_PLAN_VERSION = "agent-safe.plan/1";
+/** What a predecessor's outcome means for the step that depends on it. */
+export declare const PLAN_COUPLINGS: readonly ["independent", "ordered", "all_or_escalate"];
+export declare const MAX_PLAN_STEPS = 32;
+export declare const MAX_PLAN_EDGES = 64;
+export declare const PlanStepSchema: z.ZodObject<{
+    step_id: z.ZodString;
+    action: z.ZodString;
+    target: z.ZodString;
+    parameters: z.ZodOptional<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
+    compensates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const PlanEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    coupling: z.ZodEnum<{
+        independent: "independent";
+        ordered: "ordered";
+        all_or_escalate: "all_or_escalate";
+    }>;
+}, z.core.$strict>;
+/** What stays admissible once a step has FAILED. */
+export declare const PartialCommitRuleSchema: z.ZodObject<{
+    admissible: z.ZodArray<z.ZodString>;
+    otherwise: z.ZodEnum<{
+        ESCALATE: "ESCALATE";
+        BLOCK: "BLOCK";
+    }>;
+}, z.core.$strict>;
+export declare const GovernedPlanSchema: z.ZodObject<{
+    version: z.ZodLiteral<"agent-safe.plan/1">;
+    plan_id: z.ZodString;
+    tenant_id: z.ZodString;
+    steps: z.ZodArray<z.ZodObject<{
+        step_id: z.ZodString;
+        action: z.ZodString;
+        target: z.ZodString;
+        parameters: z.ZodOptional<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
+        compensates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        coupling: z.ZodEnum<{
+            independent: "independent";
+            ordered: "ordered";
+            all_or_escalate: "all_or_escalate";
+        }>;
+    }, z.core.$strict>>;
+    partial_commit: z.ZodObject<{
+        admissible: z.ZodArray<z.ZodString>;
+        otherwise: z.ZodEnum<{
+            ESCALATE: "ESCALATE";
+            BLOCK: "BLOCK";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PlanCoupling = (typeof PLAN_COUPLINGS)[number];
+export type PlanStep = z.infer<typeof PlanStepSchema>;
+export type PlanEdge = z.infer<typeof PlanEdgeSchema>;
+export type PartialCommitRule = z.infer<typeof PartialCommitRuleSchema>;
+export type GovernedPlan = z.infer<typeof GovernedPlanSchema>;
+/**
+ * The plan's digest: SHA-256 over its canonical JSON (sorted keys), the form
+ * every digest in the intent contract uses. The plan is parsed first, so two
+ * spellings of one plan that the schema accepts differ only where the plan
+ * itself differs.
+ */
+export declare function planDigest(plan: GovernedPlan): `sha256:${string}`;
+export type PlanStepMismatch = "PLAN_STEP_UNKNOWN" | "PLAN_STEP_ACTION_MISMATCH" | "PLAN_STEP_TARGET_OUT_OF_SCOPE" | "PLAN_STEP_PARAMETER_MISMATCH";
+export type PlanStepMatch = {
+    readonly ok: true;
+    readonly reference: PlanStepReference;
+} | {
+    readonly ok: false;
+    readonly code: PlanStepMismatch;
+};
+/** Whether a target is inside a step's scope: exact, or under a trailing-`*` prefix. */
+export declare function planTargetInScope(scope: string, target: string): boolean;
+/**
+ * Matches a proposal to one step of a plan and, when it fits, returns the
+ * reference the trusted executor stamps into the intent. A different action,
+ * a target outside the step's scope, or a parameter that differs from one the
+ * step pins is refused here, before anything is captured. The authority makes
+ * the same match itself; this one only fails fast.
+ */
+export declare function matchPlanStep(plan: GovernedPlan, stepId: string, proposal: AgentProposal): PlanStepMatch;
+/** The reason an action is outside a step, or null when it fits. */
+export declare function planStepMismatch(step: PlanStep, action: {
+    readonly action: string;
+    readonly target: string;
+    readonly parameters: JsonObject;
+}): Exclude<PlanStepMismatch, "PLAN_STEP_UNKNOWN"> | null;
+//# sourceMappingURL=GovernedPlan.d.ts.map

package/dist/plan/GovernedPlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GovernedPlan.d.ts","sourceRoot":"","sources":["../../src/plan/GovernedPlan.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAoB,KAAK,UAAU,EAAkB,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAkC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,0EAA0E;AAC1E,eAAO,MAAM,cAAc,wDAAyD,CAAC;AAErF,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,KAAK,CAAC;AAiBjC,eAAO,MAAM,cAAc;;;;;;kBAUhB,CAAC;AAEZ,eAAO,MAAM,cAAc;;;;;;;;kBAMhB,CAAC;AAEZ,oDAAoD;AACpD,eAAO,MAAM,uBAAuB;;;;;;kBAKzB,CAAC;AAEZ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAa3B,CAAC;AAEL,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAyD9D;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,MAAM,EAAE,CAIjE;AAED,MAAM,MAAM,gBAAgB,GACxB,mBAAmB,GACnB,2BAA2B,GAC3B,+BAA+B,GAC/B,8BAA8B,CAAC;AAEnC,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE5D,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,GACtB,aAAa,CAaf;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAC5F,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,GAAG,IAAI,CAavD"}

package/dist/plan/GovernedPlan.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { CanonicalIntentHasher } from "../intent/CanonicalIntentHasher.js";
+import { JsonObjectSchema } from "../intent/JsonValue.js";
+import { PlanIdSchema, PlanStepIdSchema } from "./PlanStepReference.js";
+/**
+ * A governed plan: one change carried out as several governed operations,
+ * each proposed, decided, granted, claimed and finalized on its own.
+ *
+ * The plan is a governance object, not an orchestrator. It names the steps,
+ * which step depends on which and how (the coupling), and what stays
+ * admissible once a step has failed. Registering it with the authority
+ * authorizes no step: the authority derives each step's plan facts from its
+ * own finalization records, and policy decides each step with those facts in
+ * front of it. ADR 0008 is the design.
+ */
+export const GOVERNED_PLAN_VERSION = "agent-safe.plan/1";
+/** What a predecessor's outcome means for the step that depends on it. */
+export const PLAN_COUPLINGS = ["independent", "ordered", "all_or_escalate"];
+export const MAX_PLAN_STEPS = 32;
+export const MAX_PLAN_EDGES = 64;
+const MAX_COMPENSATED_STEPS = 8;
+const actionName = z
+    .string()
+    .min(1)
+    .max(120)
+    .regex(/^[a-z][a-z0-9._:-]*$/);
+/** An exact target, or a prefix followed by one trailing `*`. */
+const targetScope = z
+    .string()
+    .min(1)
+    .max(500)
+    .refine((value) => !value.slice(0, -1).includes("*") && value !== "*", {
+    message: "PLAN_TARGET_SCOPE_INVALID",
+});
+export const PlanStepSchema = z
+    .object({
+    step_id: PlanStepIdSchema,
+    action: actionName,
+    target: targetScope,
+    /** Parameters the step pins: each must equal the proposal's, canonically. */
+    parameters: JsonObjectSchema.optional(),
+    /** Present only on a compensation step: the steps whose failure it may follow. */
+    compensates: z.array(PlanStepIdSchema).min(1).max(MAX_COMPENSATED_STEPS).optional(),
+})
+    .strict();
+export const PlanEdgeSchema = z
+    .object({
+    from: PlanStepIdSchema,
+    to: PlanStepIdSchema,
+    coupling: z.enum(PLAN_COUPLINGS),
+})
+    .strict();
+/** What stays admissible once a step has FAILED. */
+export const PartialCommitRuleSchema = z
+    .object({
+    admissible: z.array(PlanStepIdSchema).max(MAX_PLAN_STEPS),
+    otherwise: z.enum(["ESCALATE", "BLOCK"]),
+})
+    .strict();
+export const GovernedPlanSchema = z
+    .object({
+    version: z.literal(GOVERNED_PLAN_VERSION),
+    plan_id: PlanIdSchema,
+    tenant_id: z.string().uuid(),
+    steps: z.array(PlanStepSchema).min(1).max(MAX_PLAN_STEPS),
+    edges: z.array(PlanEdgeSchema).max(MAX_PLAN_EDGES),
+    partial_commit: PartialCommitRuleSchema,
+})
+    .strict()
+    .superRefine((plan, issues) => {
+    const problem = planStructureProblem(plan);
+    if (problem !== null)
+        issues.addIssue({ code: "custom", message: problem });
+});
+/**
+ * The first structural problem with a plan, or null. The checks are the ones
+ * a dependency graph needs to mean anything: every edge joins two known,
+ * distinct steps once; there is no cycle; and a compensation step stands
+ * outside the graph, compensating ordinary steps only.
+ */
+function planStructureProblem(plan) {
+    const steps = new Map();
+    for (const step of plan.steps) {
+        if (steps.has(step.step_id))
+            return "PLAN_STEP_DUPLICATE";
+        steps.set(step.step_id, step);
+    }
+    const isCompensation = (id) => steps.get(id)?.compensates !== undefined;
+    for (const step of plan.steps) {
+        for (const compensated of step.compensates ?? []) {
+            if (!steps.has(compensated) || isCompensation(compensated)) {
+                return "PLAN_COMPENSATION_INVALID";
+            }
+        }
+    }
+    const seen = new Set();
+    const successors = new Map();
+    for (const edge of plan.edges) {
+        if (!steps.has(edge.from) || !steps.has(edge.to))
+            return "PLAN_EDGE_UNKNOWN_STEP";
+        if (edge.from === edge.to)
+            return "PLAN_EDGE_SELF";
+        if (isCompensation(edge.from) || isCompensation(edge.to))
+            return "PLAN_COMPENSATION_INVALID";
+        const key = `${edge.from}\n${edge.to}`;
+        if (seen.has(key))
+            return "PLAN_EDGE_DUPLICATE";
+        seen.add(key);
+        successors.set(edge.from, [...(successors.get(edge.from) ?? []), edge.to]);
+    }
+    for (const id of plan.partial_commit.admissible) {
+        if (!steps.has(id) || isCompensation(id))
+            return "PLAN_PARTIAL_UNKNOWN_STEP";
+    }
+    // Kahn's algorithm: a graph with a cycle leaves steps no order can reach.
+    const indegree = new Map([...steps.keys()].map((id) => [id, 0]));
+    for (const edge of plan.edges)
+        indegree.set(edge.to, (indegree.get(edge.to) ?? 0) + 1);
+    const ready = [...indegree].filter(([, count]) => count === 0).map(([id]) => id);
+    let ordered = 0;
+    while (ready.length > 0) {
+        const id = ready.pop();
+        ordered += 1;
+        for (const next of successors.get(id) ?? []) {
+            const remaining = (indegree.get(next) ?? 0) - 1;
+            indegree.set(next, remaining);
+            if (remaining === 0)
+                ready.push(next);
+        }
+    }
+    return ordered === steps.size ? null : "PLAN_CYCLE";
+}
+/**
+ * The plan's digest: SHA-256 over its canonical JSON (sorted keys), the form
+ * every digest in the intent contract uses. The plan is parsed first, so two
+ * spellings of one plan that the schema accepts differ only where the plan
+ * itself differs.
+ */
+export function planDigest(plan) {
+    const parsed = GovernedPlanSchema.parse(plan);
+    const canonical = CanonicalIntentHasher.stringify(parsed);
+    return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+}
+/** Whether a target is inside a step's scope: exact, or under a trailing-`*` prefix. */
+export function planTargetInScope(scope, target) {
+    return scope.endsWith("*") ? target.startsWith(scope.slice(0, -1)) : target === scope;
+}
+/**
+ * Matches a proposal to one step of a plan and, when it fits, returns the
+ * reference the trusted executor stamps into the intent. A different action,
+ * a target outside the step's scope, or a parameter that differs from one the
+ * step pins is refused here, before anything is captured. The authority makes
+ * the same match itself; this one only fails fast.
+ */
+export function matchPlanStep(plan, stepId, proposal) {
+    const step = plan.steps.find((candidate) => candidate.step_id === stepId);
+    if (step === undefined)
+        return { ok: false, code: "PLAN_STEP_UNKNOWN" };
+    const mismatch = planStepMismatch(step, {
+        action: proposal.action,
+        target: proposal.target,
+        parameters: proposal.parameters,
+    });
+    if (mismatch !== null)
+        return { ok: false, code: mismatch };
+    return {
+        ok: true,
+        reference: { plan_id: plan.plan_id, plan_digest: planDigest(plan), step_id: step.step_id },
+    };
+}
+/** The reason an action is outside a step, or null when it fits. */
+export function planStepMismatch(step, action) {
+    if (action.action !== step.action)
+        return "PLAN_STEP_ACTION_MISMATCH";
+    if (!planTargetInScope(step.target, action.target))
+        return "PLAN_STEP_TARGET_OUT_OF_SCOPE";
+    for (const [name, pinned] of Object.entries(step.parameters ?? {})) {
+        const proposed = action.parameters[name];
+        if (proposed === undefined ||
+            CanonicalIntentHasher.stringify(proposed) !== CanonicalIntentHasher.stringify(pinned)) {
+            return "PLAN_STEP_PARAMETER_MISMATCH";
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=GovernedPlan.js.map

package/dist/plan/GovernedPlan.js.map

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

package/dist/plan/PlanState.d.ts

@@ -0,0 +1,94 @@
+import type { JsonObject } from "../intent/JsonValue.js";
+import { type GovernedPlan, type PlanCoupling } from "./GovernedPlan.js";
+import type { PlanStepReference } from "./PlanStepReference.js";
+/**
+ * The facts an authority derives for one step of a governed plan, from its
+ * own finalization records and nothing a caller says. This is the reference
+ * derivation: Decionis mirrors it, and the two are held to the same cases.
+ *
+ * Every fact is a function of the plan and the records, so a decision and the
+ * claim that follows it can be compared: the claim re-derives the step's view
+ * and refuses when it is not the one the decision rested on (ADR 0008).
+ */
+/** One attempt at a step, as a finalization record reads: claimed, then settled. */
+export interface PlanStepAttempt {
+    readonly step_id: string;
+    /** Null while the claim is open. */
+    readonly outcome: "COMMITTED" | "FAILED" | "INDETERMINATE" | null;
+    /** The effect evidence's status at finalization; null when none was recorded. */
+    readonly effect: "CONFIRMED" | "UNCONFIRMED" | null;
+    /** When the record last changed: the claim, or its settlement. */
+    readonly recorded_at: string;
+}
+export declare const PLAN_STEP_STATUSES: readonly ["PENDING", "IN_FLIGHT", "COMMITTED", "UNCONFIRMED", "INDETERMINATE", "FAILED"];
+export declare const PLAN_STATES: readonly ["ACTIVE", "PARTIAL", "SUSPENDED", "COMPLETE"];
+export declare const PLAN_ADMISSIBILITY: readonly ["ADMISSIBLE", "COMPENSATION", "ESCALATE", "WAITING", "INADMISSIBLE"];
+export declare const PLAN_REASON_CODES: readonly ["PLAN_UNKNOWN", "PLAN_DIGEST_MISMATCH", "STEP_UNKNOWN", "STEP_MISMATCH", "PLAN_SUSPENDED", "PLAN_COMPLETE", "STEP_ALREADY_ATTEMPTED", "NOTHING_TO_COMPENSATE", "COMPENSATION_ADMISSIBLE", "PREDECESSOR_FAILED", "PREDECESSOR_NOT_COMMITTED", "PREDECESSOR_UNCONFIRMED", "PREDECESSOR_FAILED_ESCALATE", "PLAN_PARTIAL_ADMISSIBLE", "PLAN_PARTIAL_ESCALATE", "PLAN_PARTIAL_BLOCK", "STEP_ADMISSIBLE"];
+export type PlanStepStatus = (typeof PLAN_STEP_STATUSES)[number];
+export type PlanState = (typeof PLAN_STATES)[number];
+export type PlanAdmissibility = (typeof PLAN_ADMISSIBILITY)[number];
+export type PlanReasonCode = (typeof PLAN_REASON_CODES)[number];
+/** The prefix of every plan-step signal id; reserved, so no caller can bind one. */
+export declare const PLAN_STEP_SIGNAL_PREFIX = "agent_safe.plan:";
+/** A material signal reference, in the authority's binding shape. */
+export interface PlanStepSignal {
+    readonly signal_id: string;
+    /** The digest of the step's view: what the decision rested on. */
+    readonly version: `sha256:${string}`;
+    readonly observed_at: string;
+    readonly value_digest: `sha256:${string}`;
+    readonly evidence_digest: null;
+}
+/** What policy reads under `agent_safe.plan`. */
+export interface PlanStepFacts {
+    readonly schema_version: "1.0";
+    readonly plan_id: string;
+    readonly plan_digest: string;
+    readonly step_id: string;
+    readonly state: PlanState | null;
+    readonly admissibility: PlanAdmissibility;
+    readonly reason: PlanReasonCode;
+    readonly status: PlanStepStatus | null;
+    readonly predecessors: readonly {
+        readonly step_id: string;
+        readonly coupling: PlanCoupling;
+        readonly status: PlanStepStatus;
+    }[];
+    readonly compensates: readonly {
+        readonly step_id: string;
+        readonly status: PlanStepStatus;
+    }[];
+    readonly signal: PlanStepSignal | null;
+}
+/** An action as the authority sees it, to be matched against the step it claims to be. */
+export interface PlanStepAction {
+    readonly action: string;
+    readonly target: string;
+    readonly parameters: JsonObject;
+}
+/** Each step's status, from every attempt the records hold. */
+export declare function planStepStatuses(plan: GovernedPlan, attempts: readonly PlanStepAttempt[]): ReadonlyMap<string, PlanStepStatus>;
+/**
+ * The plan's state. An unknown outcome suspends everything until it is
+ * reconciled; a failure makes the plan PARTIAL for good (it did not complete
+ * as approved, and compensating does not make it so); a plan whose every
+ * ordinary step committed is COMPLETE.
+ */
+export declare function planState(plan: GovernedPlan, statuses: ReadonlyMap<string, PlanStepStatus>): PlanState;
+/**
+ * Derives one step's facts. `plan` is the registered plan, or null when the
+ * organisation registered none under the stamped id; `action`, when given, is
+ * matched against the step. Nothing here throws on a caller's input: every
+ * way a stamp can be wrong is an `INADMISSIBLE` fact with its reason.
+ */
+export declare function derivePlanStepFacts(input: {
+    readonly reference: PlanStepReference;
+    readonly plan: GovernedPlan | null;
+    readonly attempts: readonly PlanStepAttempt[];
+    readonly action?: PlanStepAction;
+    /** When the plan was registered: the view's time when no record is newer. */
+    readonly registered_at?: string;
+}): PlanStepFacts;
+/** The signal id a step's view is bound under. */
+export declare function planStepSignalId(planId: string, stepId: string): string;
+//# sourceMappingURL=PlanState.d.ts.map

package/dist/plan/PlanState.d.ts.map

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

package/dist/plan/PlanState.js

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { CanonicalIntentHasher } from "../intent/CanonicalIntentHasher.js";
+import { planDigest, planStepMismatch, } from "./GovernedPlan.js";
+export const PLAN_STEP_STATUSES = [
+    "PENDING",
+    "IN_FLIGHT",
+    "COMMITTED",
+    "UNCONFIRMED",
+    "INDETERMINATE",
+    "FAILED",
+];
+export const PLAN_STATES = ["ACTIVE", "PARTIAL", "SUSPENDED", "COMPLETE"];
+export const PLAN_ADMISSIBILITY = [
+    "ADMISSIBLE",
+    "COMPENSATION",
+    "ESCALATE",
+    "WAITING",
+    "INADMISSIBLE",
+];
+export const PLAN_REASON_CODES = [
+    "PLAN_UNKNOWN",
+    "PLAN_DIGEST_MISMATCH",
+    "STEP_UNKNOWN",
+    "STEP_MISMATCH",
+    "PLAN_SUSPENDED",
+    "PLAN_COMPLETE",
+    "STEP_ALREADY_ATTEMPTED",
+    "NOTHING_TO_COMPENSATE",
+    "COMPENSATION_ADMISSIBLE",
+    "PREDECESSOR_FAILED",
+    "PREDECESSOR_NOT_COMMITTED",
+    "PREDECESSOR_UNCONFIRMED",
+    "PREDECESSOR_FAILED_ESCALATE",
+    "PLAN_PARTIAL_ADMISSIBLE",
+    "PLAN_PARTIAL_ESCALATE",
+    "PLAN_PARTIAL_BLOCK",
+    "STEP_ADMISSIBLE",
+];
+/** The prefix of every plan-step signal id; reserved, so no caller can bind one. */
+export const PLAN_STEP_SIGNAL_PREFIX = "agent_safe.plan:";
+/**
+ * Precedence when a step has several attempts: a commit outranks anything
+ * still open, and anything open outranks a settled failure. In v1 a failed
+ * step is not attempted again, so the order only matters for grants that
+ * raced to the same step.
+ */
+const STATUS_PRECEDENCE = [
+    "COMMITTED",
+    "UNCONFIRMED",
+    "IN_FLIGHT",
+    "INDETERMINATE",
+    "FAILED",
+    "PENDING",
+];
+function attemptStatus(attempt) {
+    if (attempt.outcome === null)
+        return "IN_FLIGHT";
+    if (attempt.outcome === "COMMITTED") {
+        return attempt.effect === "CONFIRMED" ? "COMMITTED" : "UNCONFIRMED";
+    }
+    return attempt.outcome;
+}
+/** Each step's status, from every attempt the records hold. */
+export function planStepStatuses(plan, attempts) {
+    const statuses = new Map(plan.steps.map((step) => [step.step_id, "PENDING"]));
+    for (const attempt of attempts) {
+        const current = statuses.get(attempt.step_id);
+        if (current === undefined)
+            continue;
+        const next = attemptStatus(attempt);
+        if (STATUS_PRECEDENCE.indexOf(next) < STATUS_PRECEDENCE.indexOf(current)) {
+            statuses.set(attempt.step_id, next);
+        }
+    }
+    return statuses;
+}
+/**
+ * The plan's state. An unknown outcome suspends everything until it is
+ * reconciled; a failure makes the plan PARTIAL for good (it did not complete
+ * as approved, and compensating does not make it so); a plan whose every
+ * ordinary step committed is COMPLETE.
+ */
+export function planState(plan, statuses) {
+    const all = [...statuses.values()];
+    if (all.includes("INDETERMINATE"))
+        return "SUSPENDED";
+    if (all.includes("FAILED"))
+        return "PARTIAL";
+    const ordinary = plan.steps.filter((step) => step.compensates === undefined);
+    return ordinary.every((step) => statuses.get(step.step_id) === "COMMITTED")
+        ? "COMPLETE"
+        : "ACTIVE";
+}
+function edgeResult(coupling, status) {
+    if (coupling === "independent" || status === "COMMITTED")
+        return null;
+    if (status === "FAILED") {
+        return coupling === "ordered"
+            ? { admissibility: "INADMISSIBLE", reason: "PREDECESSOR_FAILED" }
+            : { admissibility: "ESCALATE", reason: "PREDECESSOR_FAILED_ESCALATE" };
+    }
+    if (status === "UNCONFIRMED") {
+        return { admissibility: "ESCALATE", reason: "PREDECESSOR_UNCONFIRMED" };
+    }
+    return { admissibility: "WAITING", reason: "PREDECESSOR_NOT_COMMITTED" };
+}
+/** Refusals outrank waiting, and waiting outranks a person's decision. */
+const EDGE_PRECEDENCE = ["INADMISSIBLE", "WAITING", "ESCALATE"];
+function sha256(value) {
+    const canonical = CanonicalIntentHasher.stringify(value);
+    return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+}
+/**
+ * Derives one step's facts. `plan` is the registered plan, or null when the
+ * organisation registered none under the stamped id; `action`, when given, is
+ * matched against the step. Nothing here throws on a caller's input: every
+ * way a stamp can be wrong is an `INADMISSIBLE` fact with its reason.
+ */
+export function derivePlanStepFacts(input) {
+    const { reference, plan } = input;
+    const refused = (reason) => ({
+        schema_version: "1.0",
+        plan_id: reference.plan_id,
+        plan_digest: reference.plan_digest,
+        step_id: reference.step_id,
+        state: null,
+        admissibility: "INADMISSIBLE",
+        reason,
+        status: null,
+        predecessors: [],
+        compensates: [],
+        signal: null,
+    });
+    if (plan === null || plan.plan_id !== reference.plan_id)
+        return refused("PLAN_UNKNOWN");
+    if (planDigest(plan) !== reference.plan_digest)
+        return refused("PLAN_DIGEST_MISMATCH");
+    const step = plan.steps.find((candidate) => candidate.step_id === reference.step_id);
+    if (step === undefined)
+        return refused("STEP_UNKNOWN");
+    if (input.action !== undefined && planStepMismatch(step, input.action) !== null) {
+        return refused("STEP_MISMATCH");
+    }
+    const statuses = planStepStatuses(plan, input.attempts);
+    const state = planState(plan, statuses);
+    const status = statuses.get(step.step_id) ?? "PENDING";
+    const predecessors = plan.edges
+        .filter((edge) => edge.to === step.step_id)
+        .map((edge) => ({
+        step_id: edge.from,
+        coupling: edge.coupling,
+        status: statuses.get(edge.from) ?? "PENDING",
+    }))
+        .sort((left, right) => (left.step_id < right.step_id ? -1 : 1));
+    const compensates = [...(step.compensates ?? [])]
+        .sort()
+        .map((id) => ({ step_id: id, status: statuses.get(id) ?? "PENDING" }));
+    const { admissibility, reason } = stepAdmissibility(plan, step, state, status, predecessors, compensates);
+    // The view: everything this step's admissibility reads, and nothing else,
+    // so a change elsewhere in the plan that cannot change this step does not
+    // make its grant stale. Plan state is in every view.
+    const view = {
+        plan_id: plan.plan_id,
+        plan_digest: reference.plan_digest,
+        step_id: step.step_id,
+        state,
+        status,
+        predecessors: predecessors.map((entry) => ({ ...entry })),
+        compensates: compensates.map((entry) => ({ ...entry })),
+    };
+    const viewSteps = new Set([
+        step.step_id,
+        ...predecessors.map((entry) => entry.step_id),
+        ...compensates.map((entry) => entry.step_id),
+    ]);
+    // The view's time is its newest record, so it is as stable as the view: a
+    // record elsewhere in the plan cannot move it, and one that changes the
+    // plan state changes the version instead.
+    const times = input.attempts
+        .filter((attempt) => viewSteps.has(attempt.step_id))
+        .map((attempt) => attempt.recorded_at)
+        .sort();
+    const observedAt = times.at(-1) ?? input.registered_at ?? new Date(0).toISOString();
+    const digest = sha256(view);
+    return {
+        schema_version: "1.0",
+        plan_id: plan.plan_id,
+        plan_digest: reference.plan_digest,
+        step_id: step.step_id,
+        state,
+        admissibility,
+        reason,
+        status,
+        predecessors,
+        compensates,
+        signal: {
+            signal_id: planStepSignalId(plan.plan_id, step.step_id),
+            version: digest,
+            observed_at: observedAt,
+            value_digest: digest,
+            evidence_digest: null,
+        },
+    };
+}
+/** The signal id a step's view is bound under. */
+export function planStepSignalId(planId, stepId) {
+    return `${PLAN_STEP_SIGNAL_PREFIX}${planId}:${stepId}`;
+}
+function stepAdmissibility(plan, step, state, status, predecessors, compensates) {
+    if (state === "SUSPENDED")
+        return { admissibility: "INADMISSIBLE", reason: "PLAN_SUSPENDED" };
+    if (state === "COMPLETE")
+        return { admissibility: "INADMISSIBLE", reason: "PLAN_COMPLETE" };
+    if (status !== "PENDING") {
+        return { admissibility: "INADMISSIBLE", reason: "STEP_ALREADY_ATTEMPTED" };
+    }
+    if (step.compensates !== undefined) {
+        return compensates.some((entry) => entry.status === "FAILED")
+            ? { admissibility: "COMPENSATION", reason: "COMPENSATION_ADMISSIBLE" }
+            : { admissibility: "INADMISSIBLE", reason: "NOTHING_TO_COMPENSATE" };
+    }
+    const results = predecessors
+        .map((entry) => edgeResult(entry.coupling, entry.status))
+        .filter((result) => result !== null);
+    for (const admissibility of EDGE_PRECEDENCE) {
+        const found = results.find((result) => result.admissibility === admissibility);
+        if (found !== undefined)
+            return found;
+    }
+    if (state === "PARTIAL") {
+        if (plan.partial_commit.admissible.includes(step.step_id)) {
+            return { admissibility: "ADMISSIBLE", reason: "PLAN_PARTIAL_ADMISSIBLE" };
+        }
+        return plan.partial_commit.otherwise === "ESCALATE"
+            ? { admissibility: "ESCALATE", reason: "PLAN_PARTIAL_ESCALATE" }
+            : { admissibility: "INADMISSIBLE", reason: "PLAN_PARTIAL_BLOCK" };
+    }
+    return { admissibility: "ADMISSIBLE", reason: "STEP_ADMISSIBLE" };
+}
+//# sourceMappingURL=PlanState.js.map