@odingard/guardian-sdk 0.0.0-stage → 0.2.0

package/dist-dts/contracts/resource-claims.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+/**
+ * WO-021 — Resource Claims v1 (`guardian.resource-claim.v1`).
+ *
+ * The universal resource model every action binding can be projected into:
+ * a leased connection's provider, owner, classifications, capabilities,
+ * relationships, attributes, constraints, region, assurance and version.
+ * Domain-specific binding facts (mailbox address, endpoint allowlist, tool
+ * catalog, path allowlists, delegation ceilings) keep their existing fields —
+ * `claimFromConnectionFacts` is the documented shim that derives the claim
+ * while the legacy fields stay authoritative for built-in definitions.
+ * Pack-defined actions evaluate `resource.*` facts declaratively through
+ * claim rules; nothing in this file executes pack-supplied logic.
+ */
+export declare const RESOURCE_CLAIM_FORMAT = "guardian.resource-claim.v1";
+export declare const CLAIM_MAX_ATTRIBUTES = 32;
+export declare const CLAIM_MAX_CONSTRAINTS = 32;
+export declare const CLAIM_MAX_CLASSIFICATIONS = 32;
+export declare const CLAIM_MAX_CAPABILITIES = 128;
+export declare const CLAIM_MAX_RELATIONSHIPS = 64;
+export declare const CLAIM_ATTRIBUTE_MAX_BYTES = 8192;
+export declare const CLAIM_RULES_MAX = 32;
+export declare const BINDING_RULES_MAX = 16;
+/** A bounded canonical JSON fact: no cycles, accessors or exotic prototypes. */
+export declare const ClaimFactSchema: z.ZodUnknown;
+export type ClaimFact = z.infer<typeof ClaimFactSchema>;
+export declare const ClaimPathSchema: z.ZodString;
+export type ClaimPath = z.infer<typeof ClaimPathSchema>;
+export declare const ResourceRelationshipSchema: z.ZodObject<{
+    kind: z.ZodString;
+    target: z.ZodString;
+}, z.core.$strict>;
+export type ResourceRelationship = z.infer<typeof ResourceRelationshipSchema>;
+export declare const ResourceClaimSchema: z.ZodObject<{
+    claim: z.ZodLiteral<"guardian.resource-claim.v1">;
+    type: z.ZodString;
+    id: z.ZodString;
+    provider: z.ZodString;
+    owner: z.ZodString;
+    classifications: z.ZodArray<z.ZodString>;
+    capabilities: z.ZodArray<z.ZodString>;
+    relationships: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        target: z.ZodString;
+    }, z.core.$strict>>;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    constraints: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    region: z.ZodOptional<z.ZodString>;
+    assurance: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export type ResourceClaim = z.infer<typeof ResourceClaimSchema>;
+/**
+ * Declarative rule over `resource.*` facts. Ops:
+ * - `eq` / `neq`: canonical equality / inequality of the resolved fact
+ * - `in`: the resolved scalar fact is a member of the rule's value list
+ * - `includes`: the resolved list fact contains the rule's value
+ * - `excludes`: the resolved list fact does not contain the rule's value
+ * A rule whose path resolves to `undefined` fails closed.
+ */
+export declare const ClaimRuleSchema: z.ZodObject<{
+    path: z.ZodString;
+    op: z.ZodEnum<{
+        in: "in";
+        includes: "includes";
+        eq: "eq";
+        neq: "neq";
+        excludes: "excludes";
+    }>;
+    value: z.ZodUnknown;
+}, z.core.$strict>;
+export type ClaimRule = z.infer<typeof ClaimRuleSchema>;
+/**
+ * Declarative binding rule: a material-parameter field checked against a
+ * resolved claim list (or the scalar claim fact). Ops:
+ * - `within`: the param is an endpoint inside the claim's allowlist entries
+ *   (same prefix+host semantics as the api.endpoint allowlist binding)
+ * - `memberOf`: the param string equals one of the claim list's entries
+ */
+export declare const BindingRuleSchema: z.ZodObject<{
+    field: z.ZodString;
+    claim: z.ZodString;
+    op: z.ZodEnum<{
+        within: "within";
+        memberOf: "memberOf";
+    }>;
+}, z.core.$strict>;
+export type BindingRule = z.infer<typeof BindingRuleSchema>;
+/** The connection facts the claims shim projects (mirrors the binding shape). */
+export type ConnectionClaimFacts = Readonly<{
+    provider: string;
+    connectionId?: string;
+    principalId?: string;
+    mailboxAddress?: string;
+    endpointAllowlist?: readonly string[];
+    toolServer?: Readonly<{
+        serverName: string;
+        serverVersion: string;
+        tools: readonly {
+            name: string;
+        }[];
+    }>;
+    enabledToolNames?: readonly string[];
+    calendarId?: string;
+    pathAllowlist?: readonly string[];
+    shareAllowlist?: readonly string[];
+    protectedCatalog?: readonly {
+        fieldRef: string;
+        allowUse: boolean;
+        allowView: boolean;
+    }[];
+    bondedSubAgentIds?: readonly string[];
+    delegationCeilings?: Readonly<Record<string, {
+        actionIds: readonly string[];
+    }>>;
+}>;
+/**
+ * The WO-021 migration shim: projects today's vertical binding fields into a
+ * universal Resource Claim. Built-in definitions keep reading the legacy
+ * fields; pack-defined actions read only the claim.
+ */
+export declare function claimFromConnectionFacts(connection: ConnectionClaimFacts): ResourceClaim;
+/** Resolves a `resource.*` dotted path to the claim fact (or undefined). */
+export declare function resolveClaimPath(claim: ResourceClaim, path: string): unknown;
+/**
+ * Evaluates a declarative claim policy over resolved `resource.*` facts.
+ * Deterministic and bounded: no pack-supplied code runs — rules are data.
+ */
+export declare function evaluateClaimRules(claim: ResourceClaim, rules: readonly ClaimRule[]): {
+    ok: true;
+} | {
+    ok: false;
+    reasonCode: string;
+    path: string;
+};
+/**
+ * Evaluates declarative binding rules: a material-parameter value checked
+ * against a resolved claim fact. Fails closed on a missing or mistyped fact.
+ */
+export declare function evaluateBindingRules(claim: ResourceClaim, params: Record<string, unknown>, rules: readonly BindingRule[]): {
+    ok: true;
+} | {
+    ok: false;
+    reasonCode: string;
+    field: string;
+};

package/dist-dts/contracts/runtime.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/**
+ * WO-026: guardian.runtime.v1 — runtime attestation facts contract
+ * (GUA-AUTHORITY-OS-001 §24–25).
+ *
+ * Attestation facts are recorded surface evidence supplied by platforms
+ * that support them. Guardian never invents them: a field that is absent
+ * simply does not exist, and the computed level never rises on missing
+ * facts. A model/agent assertion is never evidence — only facts recorded
+ * through the injected attestation port feed the ladder.
+ *
+ * The trusted-runtime ladder is deterministic (§25):
+ *
+ *   T4 HARDWARE-BACKED — secureHardwareEvidence recorded
+ *   T3 ATTESTED        — attestation evidence from an issuer
+ *                        (attestationIssuer + attestedAt, or recorded
+ *                        cloudWorkloadEvidence)
+ *   T2 VERIFIED        — signed/verified workload or binary identity
+ *                        (workloadIdentity, binaryIdentity,
+ *                        packageIdentity, or containerIdentity recorded)
+ *   T1 IDENTIFIED      — a stable runtime identity is recorded
+ *                        (runtimeIdentity or deviceIdentity)
+ *   T0 UNKNOWN         — nothing else recorded
+ *
+ * Precedence is strongest-evidence: the highest level any recorded fact
+ * supports wins; lower facts never pull the level down.
+ */
+export declare const RUNTIME_CONTRACT_SCHEMA = "guardian.runtime.v1";
+/** Ordered trusted-runtime ladder (lowest → highest). */
+export declare const TrustedRuntimeLevelSchema: z.ZodEnum<{
+    T0_UNKNOWN: "T0_UNKNOWN";
+    T1_IDENTIFIED: "T1_IDENTIFIED";
+    T2_VERIFIED: "T2_VERIFIED";
+    T3_ATTESTED: "T3_ATTESTED";
+    T4_HARDWARE_BACKED: "T4_HARDWARE_BACKED";
+}>;
+export type TrustedRuntimeLevel = z.infer<typeof TrustedRuntimeLevelSchema>;
+export declare const TRUSTED_RUNTIME_RANK: Record<TrustedRuntimeLevel, number>;
+/** Human-readable level names for display surfaces (§27). */
+export declare const TRUSTED_RUNTIME_LABEL: Record<TrustedRuntimeLevel, string>;
+export declare function trustedRuntimeExceeds(value: TrustedRuntimeLevel, floor: TrustedRuntimeLevel): boolean;
+export declare function trustedRuntimeBelow(value: TrustedRuntimeLevel, floor: TrustedRuntimeLevel): boolean;
+/**
+ * Recorded attestation facts for an invoking runtime (§24). Every field is
+ * optional: platforms that cannot supply a fact leave it absent and the
+ * ladder lowers accordingly — facts are never fabricated.
+ */
+export declare const RuntimeAttestationFactsSchema: z.ZodObject<{
+    runtimeIdentity: z.ZodOptional<z.ZodString>;
+    deviceIdentity: z.ZodOptional<z.ZodString>;
+    workloadIdentity: z.ZodOptional<z.ZodString>;
+    binaryIdentity: z.ZodOptional<z.ZodString>;
+    packageIdentity: z.ZodOptional<z.ZodString>;
+    containerIdentity: z.ZodOptional<z.ZodString>;
+    modelIdentity: z.ZodOptional<z.ZodString>;
+    agentVersion: z.ZodOptional<z.ZodString>;
+    secureHardwareEvidence: z.ZodOptional<z.ZodString>;
+    cloudWorkloadEvidence: z.ZodOptional<z.ZodString>;
+    executionEnvironment: z.ZodOptional<z.ZodString>;
+    networkContext: z.ZodOptional<z.ZodString>;
+    region: z.ZodOptional<z.ZodString>;
+    attestedAt: z.ZodOptional<z.ZodNumber>;
+    attestationIssuer: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RuntimeAttestationFacts = z.infer<typeof RuntimeAttestationFactsSchema>;
+export interface RuntimeTrustComputation {
+    level: TrustedRuntimeLevel;
+    /** The recorded fact names the level was computed from. */
+    evidence: readonly string[];
+}
+/**
+ * Pure, deterministic level computation over recorded facts. Missing or
+ * empty facts never raise the level; an absent facts object yields T0.
+ */
+export declare function computeRuntimeTrustLevel(facts: RuntimeAttestationFacts | null | undefined): RuntimeTrustComputation;
+/**
+ * Runtime policy declared on guardian.intent.v1 (`runtime` field) —
+ * narrows, denies, or forces approval over the computed trusted-runtime
+ * level; never enlarges authority (§25, K15).
+ */
+export declare const RuntimePolicySchema: z.ZodObject<{
+    minLevel: z.ZodOptional<z.ZodEnum<{
+        T0_UNKNOWN: "T0_UNKNOWN";
+        T1_IDENTIFIED: "T1_IDENTIFIED";
+        T2_VERIFIED: "T2_VERIFIED";
+        T3_ATTESTED: "T3_ATTESTED";
+        T4_HARDWARE_BACKED: "T4_HARDWARE_BACKED";
+    }>>;
+    requireApprovalBelow: z.ZodOptional<z.ZodEnum<{
+        T0_UNKNOWN: "T0_UNKNOWN";
+        T1_IDENTIFIED: "T1_IDENTIFIED";
+        T2_VERIFIED: "T2_VERIFIED";
+        T3_ATTESTED: "T3_ATTESTED";
+        T4_HARDWARE_BACKED: "T4_HARDWARE_BACKED";
+    }>>;
+}, z.core.$strict>;
+export type RuntimePolicy = z.infer<typeof RuntimePolicySchema>;
+/**
+ * Evaluate a declared runtime policy over the computed level. Pure:
+ * reports deny | require_approval | allowed with a deterministic rule ref
+ * and never mutates authority.
+ */
+export declare function evaluateRuntimePolicy(policy: RuntimePolicy | undefined, level: TrustedRuntimeLevel): {
+    verdict: "deny";
+    ruleId: string;
+} | {
+    verdict: "require_approval";
+    ruleId: string;
+} | {
+    verdict: "allowed";
+};

package/dist-dts/contracts/safety-envelope.d.ts

@@ -0,0 +1,287 @@
+import { z } from "zod";
+/**
+ * WO-029: guardian.safety_envelope.v1 — generic physical safety envelope
+ * (GUA-AUTHORITY-OS-001 §38–40, §79, §88–89, K15).
+ *
+ * Physical actions keep the SAME kernel and gain declarative constraint
+ * facts on the canonical action envelope (§38): zone, speed, payload,
+ * force, hours, human distance. Nothing robotics-specific enters the
+ * kernel — these are generic policy facts evaluated deterministically.
+ *
+ * §39 — a generic safety-envelope structure evaluated by the pure
+ * evaluator below. A violation denies or narrows (supervision_required
+ * narrows to ASK); the evaluator never warns-and-allows and never
+ * enlarges authority.
+ *
+ * §40 — offline authority may narrow, it may never expand. When fresh
+ * authority cannot be obtained for a safety-critical physical operation,
+ * the system defaults to the previously recorded safe state; it never
+ * invents ALLOW. Edge enforcement is bounded by the freshest recorded
+ * authority: a local evaluator may only enforce a decision
+ * equal-to-or-narrower than the recorded snapshot, and a stale snapshot
+ * fails closed.
+ */
+export declare const SAFETY_ENVELOPE_CONTRACT_SCHEMA = "guardian.safety_envelope.v1";
+/**
+ * Declarative constraint facts a physical action carries on its
+ * material envelope. All values are generic numbers in whatever unit
+ * the governing envelope declares — the kernel never interprets units.
+ * Absent facts are simply not checked against the matching cap.
+ */
+export declare const PhysicalActionFactsSchema: z.ZodObject<{
+    zone: z.ZodOptional<z.ZodString>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    force: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodOptional<z.ZodNumber>;
+    atEpochMs: z.ZodOptional<z.ZodNumber>;
+    humanDistance: z.ZodOptional<z.ZodNumber>;
+    environment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    supervised: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PhysicalActionFacts = z.infer<typeof PhysicalActionFactsSchema>;
+/**
+ * A wall-clock window in minutes-of-day, e.g. 06:00–18:00 is
+ * { startMinutesOfDay: 360, endMinutesOfDay: 1080 }. An end earlier
+ * than the start wraps midnight (22:00–06:00).
+ */
+export declare const SafetyTimeWindowSchema: z.ZodObject<{
+    startMinutesOfDay: z.ZodNumber;
+    endMinutesOfDay: z.ZodNumber;
+}, z.core.$strict>;
+export type SafetyTimeWindow = z.infer<typeof SafetyTimeWindowSchema>;
+/**
+ * The generic safety-envelope structure (§39). Every field is a generic
+ * policy fact — nothing hardware- or robotics-specific. Declared on the
+ * governing intent (and persisted as a safety_envelope record); the
+ * evaluator checks the action's material facts against it.
+ */
+export declare const SafetyEnvelopeSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"guardian.safety_envelope.v1">;
+    allowedZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    forbiddenZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxSpeed: z.ZodOptional<z.ZodNumber>;
+    maxForce: z.ZodOptional<z.ZodNumber>;
+    maxPayload: z.ZodOptional<z.ZodNumber>;
+    timeWindow: z.ZodOptional<z.ZodObject<{
+        startMinutesOfDay: z.ZodNumber;
+        endMinutesOfDay: z.ZodNumber;
+    }, z.core.$strict>>;
+    proximityConstraints: z.ZodOptional<z.ZodObject<{
+        minHumanDistance: z.ZodNumber;
+    }, z.core.$strict>>;
+    environmentConditions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    supervisionRequired: z.ZodOptional<z.ZodBoolean>;
+    failSafeAction: z.ZodOptional<z.ZodString>;
+    emergencyStop: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type SafetyEnvelope = z.infer<typeof SafetyEnvelopeSchema>;
+export declare function safetyEnvelopeDigest(envelope: SafetyEnvelope): string;
+export declare const SafetyViolationSchema: z.ZodEnum<{
+    OUT_OF_ZONE: "OUT_OF_ZONE";
+    FORBIDDEN_ZONE: "FORBIDDEN_ZONE";
+    OVER_SPEED: "OVER_SPEED";
+    OVER_FORCE: "OVER_FORCE";
+    OVER_PAYLOAD: "OVER_PAYLOAD";
+    OUTSIDE_TIME_WINDOW: "OUTSIDE_TIME_WINDOW";
+    PROXIMITY_VIOLATION: "PROXIMITY_VIOLATION";
+    ENVIRONMENT_VIOLATION: "ENVIRONMENT_VIOLATION";
+    SUPERVISION_REQUIRED: "SUPERVISION_REQUIRED";
+}>;
+export type SafetyViolation = z.infer<typeof SafetyViolationSchema>;
+/** Deterministic outcome of evaluating an envelope against action facts. */
+export declare const SafetyEnvelopeOutcomeSchema: z.ZodObject<{
+    envelopeDigest: z.ZodString;
+    satisfied: z.ZodBoolean;
+    violations: z.ZodArray<z.ZodEnum<{
+        OUT_OF_ZONE: "OUT_OF_ZONE";
+        FORBIDDEN_ZONE: "FORBIDDEN_ZONE";
+        OVER_SPEED: "OVER_SPEED";
+        OVER_FORCE: "OVER_FORCE";
+        OVER_PAYLOAD: "OVER_PAYLOAD";
+        OUTSIDE_TIME_WINDOW: "OUTSIDE_TIME_WINDOW";
+        PROXIMITY_VIOLATION: "PROXIMITY_VIOLATION";
+        ENVIRONMENT_VIOLATION: "ENVIRONMENT_VIOLATION";
+        SUPERVISION_REQUIRED: "SUPERVISION_REQUIRED";
+    }>>;
+    emergencyStopped: z.ZodBoolean;
+    failSafeApplied: z.ZodBoolean;
+}, z.core.$strict>;
+export type SafetyEnvelopeOutcome = z.infer<typeof SafetyEnvelopeOutcomeSchema>;
+export type SafetyEnvelopeEvaluation = Readonly<{
+    satisfied: boolean;
+    violations: readonly SafetyViolation[];
+    /**
+     * Violations that NARROW to ASK instead of denying. Only
+     * supervision_required narrows; every other violation is a hard deny.
+     */
+    narrowsToApproval: boolean;
+}>;
+/**
+ * Pure deterministic evaluator (§39): checks a declared safety envelope
+ * against the action's material facts — inside allowed zone AND outside
+ * forbidden zone (forbidden wins even inside allowed), within max
+ * speed/force/payload, inside the time window, proximity/environment/
+ * supervision satisfied. A violation never warns-and-allows.
+ */
+export declare function evaluateSafetyEnvelope(envelope: SafetyEnvelope, facts: PhysicalActionFacts, nowEpochMs: number): SafetyEnvelopeEvaluation;
+/**
+ * The recorded emergency-stop state for one resource (§38 "always
+ * enforce"). An engaged state takes precedence over every other envelope
+ * field and is invocable independent of any pending action. Once
+ * engaged, all governed physical actions for that resource deny until
+ * explicitly cleared by authority.
+ */
+export declare const EmergencyStopStateSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    resource: z.ZodString;
+    engaged: z.ZodBoolean;
+    engagedAtEpochMs: z.ZodNullable<z.ZodNumber>;
+    engagedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    reason: z.ZodNullable<z.ZodString>;
+    clearedAtEpochMs: z.ZodNullable<z.ZodNumber>;
+    clearedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export type EmergencyStopState = z.infer<typeof EmergencyStopStateSchema>;
+export declare const EmergencyStopCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"engage">;
+    reason: z.ZodString;
+    actor: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"clear">;
+    reason: z.ZodString;
+    actor: z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export type EmergencyStopCommand = z.infer<typeof EmergencyStopCommandSchema>;
+export type EmergencyStopTransitionResult = Readonly<{
+    ok: true;
+    record: EmergencyStopState;
+}> | Readonly<{
+    ok: false;
+    reasonCode: "MALFORMED_RECORD" | "MALFORMED_COMMAND" | "STALE_VERSION" | "INVALID_TRANSITION";
+}>;
+/**
+ * Pure transition for the emergency-stop state machine (CAS-driven like
+ * the transaction evaluator). Engage is idempotent — an already-engaged
+ * stop stays engaged; only an explicit `clear` releases it.
+ */
+export declare function transitionEmergencyStop(recordInput: unknown, commandInput: unknown, nowEpochMs: number): EmergencyStopTransitionResult;
+/**
+ * The freshest recorded authority snapshot an edge evaluator is bounded
+ * by (§40): the last recorded envelope + emergency-stop state plus
+ * freshness facts. The edge may only enforce a decision
+ * equal-to-or-narrower than this snapshot — and only while it is fresh.
+ */
+export declare const EdgeAuthoritySnapshotSchema: z.ZodObject<{
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    resource: z.ZodString;
+    envelope: z.ZodNullable<z.ZodObject<{
+        schema: z.ZodLiteral<"guardian.safety_envelope.v1">;
+        allowedZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        forbiddenZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSpeed: z.ZodOptional<z.ZodNumber>;
+        maxForce: z.ZodOptional<z.ZodNumber>;
+        maxPayload: z.ZodOptional<z.ZodNumber>;
+        timeWindow: z.ZodOptional<z.ZodObject<{
+            startMinutesOfDay: z.ZodNumber;
+            endMinutesOfDay: z.ZodNumber;
+        }, z.core.$strict>>;
+        proximityConstraints: z.ZodOptional<z.ZodObject<{
+            minHumanDistance: z.ZodNumber;
+        }, z.core.$strict>>;
+        environmentConditions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supervisionRequired: z.ZodOptional<z.ZodBoolean>;
+        failSafeAction: z.ZodOptional<z.ZodString>;
+        emergencyStop: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    emergencyStop: z.ZodNullable<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        resource: z.ZodString;
+        engaged: z.ZodBoolean;
+        engagedAtEpochMs: z.ZodNullable<z.ZodNumber>;
+        engagedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+        reason: z.ZodNullable<z.ZodString>;
+        clearedAtEpochMs: z.ZodNullable<z.ZodNumber>;
+        clearedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+        version: z.ZodNumber;
+    }, z.core.$strict>>;
+    freshnessEpochMs: z.ZodNumber;
+    maxAgeMs: z.ZodNumber;
+}, z.core.$strict>;
+export type EdgeAuthoritySnapshot = z.infer<typeof EdgeAuthoritySnapshotSchema>;
+export declare const EdgeDecisionSchema: z.ZodEnum<{
+    deny: "deny";
+    allow: "allow";
+    fail_safe: "fail_safe";
+}>;
+export type EdgeDecision = z.infer<typeof EdgeDecisionSchema>;
+export type EdgeEvaluationResult = Readonly<{
+    decision: EdgeDecision;
+    violations: readonly SafetyViolation[];
+    /** True when the emergency-stop state overrode every other field. */
+    emergencyStopped: boolean;
+    /** True when the snapshot was too stale to allow anything but fail-safe. */
+    staleAuthority: boolean;
+}>;
+/**
+ * §40 — edge enforcement contract: a local evaluator may only enforce a
+ * decision equal-to-or-narrower than the freshest recorded authority,
+ * bounded by envelope freshness facts. A stale snapshot or an engaged
+ * emergency stop fails closed — the edge can never invent ALLOW.
+ */
+export declare function evaluateEdgeDecision(snapshot: EdgeAuthoritySnapshot, facts: PhysicalActionFacts, nowEpochMs: number): EdgeEvaluationResult;
+export type OfflineAuthorityResolution = Readonly<{
+    /** The envelope the offline path enforces (recorded, never invented). */
+    envelope: SafetyEnvelope | null;
+    /** True when fresh authority could not be obtained → recorded safe state. */
+    degraded: boolean;
+    /** The recorded fail-safe posture name, when declared. */
+    failSafeAction: string | null;
+}>;
+/**
+ * §40 — offline narrowing: offline authority may narrow, it may never
+ * expand. When fresh authority cannot be obtained the system defaults to
+ * the previously recorded safe state; it never invents ALLOW. A fresh
+ * envelope simply returns itself (it can still only narrow through
+ * evaluation); a missing one degrades to the recorded envelope's
+ * fail-safe posture.
+ */
+export declare function resolveOfflineAuthority(input: {
+    fresh: SafetyEnvelope | null;
+    recorded: SafetyEnvelope | null;
+}): OfflineAuthorityResolution;
+/** A recorded safety envelope for one governed resource. */
+export declare const SafetyEnvelopeRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    tenantId: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    resource: z.ZodString;
+    envelope: z.ZodObject<{
+        schema: z.ZodLiteral<"guardian.safety_envelope.v1">;
+        allowedZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        forbiddenZone: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxSpeed: z.ZodOptional<z.ZodNumber>;
+        maxForce: z.ZodOptional<z.ZodNumber>;
+        maxPayload: z.ZodOptional<z.ZodNumber>;
+        timeWindow: z.ZodOptional<z.ZodObject<{
+            startMinutesOfDay: z.ZodNumber;
+            endMinutesOfDay: z.ZodNumber;
+        }, z.core.$strict>>;
+        proximityConstraints: z.ZodOptional<z.ZodObject<{
+            minHumanDistance: z.ZodNumber;
+        }, z.core.$strict>>;
+        environmentConditions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supervisionRequired: z.ZodOptional<z.ZodBoolean>;
+        failSafeAction: z.ZodOptional<z.ZodString>;
+        emergencyStop: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    envelopeDigest: z.ZodString;
+    version: z.ZodNumber;
+    updatedBy: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "PrincipalId", "out">>;
+    createdAtEpochMs: z.ZodNumber;
+    updatedAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type SafetyEnvelopeRecord = z.infer<typeof SafetyEnvelopeRecordSchema>;

package/dist-dts/contracts/sequence.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/**
+ * WO-024: guardian.sequence.v1 — declarative sequence rules.
+ *
+ * A sequence rule is a human-authored condition declared on an intent
+ * contract: it composes the current action with recorded, earlier actions
+ * of the same principal/agent lineage (directive §14–16). Sequence rules
+ * are declarative inputs to the ONE authority kernel (§89, K15): this
+ * evaluator is pure and read-only over recorded action history — it can
+ * only report deny | require_approval | no match, and can never create,
+ * widen, or restore authority. Temporal rules combine recorded action
+ * timestamps with causal references; they never infer intent from timing
+ * alone.
+ *
+ * Six combinators wire in this build:
+ *   then                  A must be recorded strictly before the current action
+ *   plus                  A must be recorded inside the window (either order;
+ *                         recorded history is always earlier)
+ *   within_minutes        A must be recorded no more than windowMinutes earlier
+ *   using_result_of       the current action declares a causal reference
+ *                         (parentActionId, or a sourceEffectId the caller has
+ *                         resolved to the action that produced it) to A
+ *   affecting_resource_of the current action touches a resource A recorded or
+ *                         produced (resource ref or material parameter overlap)
+ *   after_protected_data  any protected_data.* action was recorded inside the
+ *                         window (rule `a` may narrow it further)
+ *
+ * A matching rule applies its declared effect: `deny` fails the request
+ * closed with the rule named on the rejection evidence;
+ * `require_approval` raises approvalRequired so the existing ASK machinery
+ * handles it. Rules are evaluated over recorded evidence only — an
+ * unrecorded, forged, or cross-tenant reference simply cannot match.
+ */
+export declare const SEQUENCE_CONTRACT_SCHEMA = "guardian.sequence.v1";
+export declare const SequenceCombinatorSchema: z.ZodEnum<{
+    then: "then";
+    plus: "plus";
+    within_minutes: "within_minutes";
+    using_result_of: "using_result_of";
+    affecting_resource_of: "affecting_resource_of";
+    after_protected_data: "after_protected_data";
+}>;
+export type SequenceCombinator = z.infer<typeof SequenceCombinatorSchema>;
+export declare const SequenceEffectSchema: z.ZodEnum<{
+    deny: "deny";
+    require_approval: "require_approval";
+}>;
+export type SequenceEffect = z.infer<typeof SequenceEffectSchema>;
+/**
+ * One side of a sequence rule. `action` accepts an exact action id or
+ * `family:<name>` (the intent-contract matching convention). Absent
+ * predicates are wildcards; at least one predicate must be declared.
+ */
+export declare const SequenceMatchSchema: z.ZodObject<{
+    action: z.ZodOptional<z.ZodString>;
+    resource: z.ZodOptional<z.ZodString>;
+    counterparty: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SequenceMatch = z.infer<typeof SequenceMatchSchema>;
+export declare const SequenceRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    a: z.ZodOptional<z.ZodObject<{
+        action: z.ZodOptional<z.ZodString>;
+        resource: z.ZodOptional<z.ZodString>;
+        counterparty: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    b: z.ZodOptional<z.ZodObject<{
+        action: z.ZodOptional<z.ZodString>;
+        resource: z.ZodOptional<z.ZodString>;
+        counterparty: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    combinator: z.ZodEnum<{
+        then: "then";
+        plus: "plus";
+        within_minutes: "within_minutes";
+        using_result_of: "using_result_of";
+        affecting_resource_of: "affecting_resource_of";
+        after_protected_data: "after_protected_data";
+    }>;
+    windowMinutes: z.ZodOptional<z.ZodNumber>;
+    effect: z.ZodEnum<{
+        deny: "deny";
+        require_approval: "require_approval";
+    }>;
+}, z.core.$strict>;
+export type SequenceRule = z.infer<typeof SequenceRuleSchema>;
+/** One matched sequence rule and the recorded actions that satisfied `a`. */
+export declare const SequenceMatchOutcomeSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    effect: z.ZodEnum<{
+        deny: "deny";
+        require_approval: "require_approval";
+    }>;
+    matchedActionRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type SequenceMatchOutcome = z.infer<typeof SequenceMatchOutcomeSchema>;
+/**
+ * The action view the evaluator reads: the current (proposed) action or one
+ * recorded earlier action. `actionFamily` is resolved by the caller's
+ * registry — an entry without a resolvable family cannot satisfy a
+ * `family:` predicate (fail closed). `resolvedSourceActionId` is the
+ * recorded action a declared sourceEffectId resolved to (evidence lookup
+ * happens in the caller, never here).
+ */
+export type SequenceActionView = Readonly<{
+    requestId?: string | undefined;
+    agentId?: string | undefined;
+    action: string;
+    actionFamily?: string | null | undefined;
+    resource?: string | undefined;
+    counterparty?: string | undefined;
+    issuedAtEpochMs: number;
+    parentActionId?: string | undefined;
+    sourceEffectId?: string | undefined;
+    resolvedSourceActionId?: string | undefined;
+    materialParameters?: Readonly<Record<string, unknown>> | undefined;
+}>;
+export type SequenceEvaluation = Readonly<{
+    /** First deny-effected matching rule, in declaration order. */
+    deny: SequenceRule | undefined;
+    /** First require_approval-effected matching rule, in declaration order. */
+    requireApproval: SequenceRule | undefined;
+    /** Every matching rule with the recorded action refs that matched `a`. */
+    matches: readonly SequenceMatchOutcome[];
+}>;
+/**
+ * Evaluate declared sequence rules over recorded action history.
+ * Pure and read-only: it can only narrow (deny / require_approval), never
+ * enlarge authority. `history` must contain only recorded actions of the
+ * same principal/agent lineage — the caller scopes the evidence port.
+ */
+export declare function evaluateSequenceRules(rules: readonly SequenceRule[], current: SequenceActionView, history: readonly SequenceActionView[], nowEpochMs: number): SequenceEvaluation;