@agenticprimitives/fabric 0.0.0-alpha.1

package/dist/interactions/mandates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandates.js","sourceRoot":"","sources":["../../src/interactions/mandates.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,wDAAwD;AACxD,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,uEAAuE;AAmDvE;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAA6B,EAC7B,OAA6E,EAC7E,WAA6B,EAC7B,KAAa;IAEb,IAAI,WAAW,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC;QACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC1D,CAAC;IACD,IACE,OAAO,CAAC,WAAW,CAAC,SAAS,KAAK,SAAS;QAC3C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,EAC9D,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACvD,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;QACxD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACzD,CAAC;IACD,0EAA0E;IAC1E,wEAAwE;IACxE,IAAI,OAAO,CAAC,aAAa,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;QAC3D,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,uEAAuE;YACvE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,IACE,OAAO,CAAC,aAAa,CAAC,OAAO,KAAK,SAAS;QAC3C,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,aAAa,CAAC,OAAO,EACjD,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC;AAyBD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAA6B;IACpE,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC5F,IAAI,OAAO,CAAC,SAAS,CAAC,MAAM,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;QACnD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAChD,CAAC"}

package/dist/interactions/relationship.d.ts

@@ -0,0 +1,29 @@
+import type { CanonicalAgentId } from '@agenticprimitives/types';
+import type { Hex32 } from '../messaging/index.js';
+import type { InteractionCaseV1, InteractionTransitionEventV1 } from './types.js';
+export interface InteractionExchangeRecordV1 {
+    version: 'ap.interaction.exchange.v1';
+    interactionId: InteractionCaseV1['id'];
+    kind: InteractionCaseV1['kind'];
+    /** The relationship pair, ordered requester → responder. */
+    requester: CanonicalAgentId;
+    responder: CanonicalAgentId;
+    transition: InteractionTransitionEventV1['transition'];
+    actor: CanonicalAgentId;
+    at: string;
+    /** State AFTER the transition. */
+    resultingState: InteractionCaseV1['state'];
+    /** Hash of the resulting case snapshot — the witness's anchor. */
+    caseHash: Hex32;
+    /** Authority the exchange referenced, when any (kind + hash only). */
+    authorityKind?: string;
+    authorityHash?: Hex32;
+}
+/** Build the exchange record for a transition that was ACCEPTED (pass the
+ *  case AFTER the transition). Hashes/ids only — no subjects, no payloads. */
+export declare function buildExchangeRecord(caseAfter: InteractionCaseV1, event: InteractionTransitionEventV1): Promise<InteractionExchangeRecordV1>;
+/** Port the consumer wires over the spec 306 relationship record store. */
+export interface RelationshipExchangePort {
+    appendExchange(record: InteractionExchangeRecordV1): Promise<void>;
+}
+//# sourceMappingURL=relationship.d.ts.map

package/dist/interactions/relationship.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.d.ts","sourceRoot":"","sources":["../../src/interactions/relationship.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,4BAA4B,CAAC;IACtC,aAAa,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAChC,4DAA4D;IAC5D,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,4BAA4B,CAAC,YAAY,CAAC,CAAC;IACvD,KAAK,EAAE,gBAAgB,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,cAAc,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3C,kEAAkE;IAClE,QAAQ,EAAE,KAAK,CAAC;IAChB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;8EAC8E;AAC9E,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAAC,2BAA2B,CAAC,CAkBtC;AAED,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,cAAc,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE"}

package/dist/interactions/relationship.js

@@ -0,0 +1,31 @@
+// Relationship-exchange seam (spec 309 W5 ← specs 306/307): every meaningful
+// interaction exchange is appended to the requester↔responder RELATIONSHIP
+// RECORD so the witness can later adjudicate ("what was asked, decided, and
+// delivered between these two agents?").
+//
+// This package cannot import the relationships/witness packages (facet
+// firewall), so it owns the record SHAPE + a builder + the append PORT; the
+// consuming app/runtime implements the port over spec 306 storage.
+import { hashInteractionCase } from './builders.js';
+/** Build the exchange record for a transition that was ACCEPTED (pass the
+ *  case AFTER the transition). Hashes/ids only — no subjects, no payloads. */
+export async function buildExchangeRecord(caseAfter, event) {
+    if (event.interactionId !== caseAfter.id) {
+        throw new Error(`event ${event.interactionId} does not belong to case ${caseAfter.id}`);
+    }
+    return {
+        version: 'ap.interaction.exchange.v1',
+        interactionId: caseAfter.id,
+        kind: caseAfter.kind,
+        requester: caseAfter.requester,
+        responder: caseAfter.responder,
+        transition: event.transition,
+        actor: event.actor,
+        at: event.at,
+        resultingState: caseAfter.state,
+        caseHash: await hashInteractionCase(caseAfter),
+        authorityKind: event.authorityRef?.kind,
+        authorityHash: event.authorityRef?.hash,
+    };
+}
+//# sourceMappingURL=relationship.js.map

package/dist/interactions/relationship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship.js","sourceRoot":"","sources":["../../src/interactions/relationship.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,2EAA2E;AAC3E,4EAA4E;AAC5E,yCAAyC;AACzC,EAAE;AACF,uEAAuE;AACvE,4EAA4E;AAC5E,mEAAmE;AAInE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAsBpD;8EAC8E;AAC9E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAA4B,EAC5B,KAAmC;IAEnC,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,SAAS,KAAK,CAAC,aAAa,4BAA4B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO;QACL,OAAO,EAAE,4BAA4B;QACrC,aAAa,EAAE,SAAS,CAAC,EAAE;QAC3B,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,cAAc,EAAE,SAAS,CAAC,KAAK;QAC/B,QAAQ,EAAE,MAAM,mBAAmB,CAAC,SAAS,CAAC;QAC9C,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,IAAI;QACvC,aAAa,EAAE,KAAK,CAAC,YAAY,EAAE,IAAI;KACxC,CAAC;AACJ,CAAC"}

package/dist/interactions/risk.d.ts

@@ -0,0 +1,39 @@
+import type { CanonicalAgentId } from '@agenticprimitives/types';
+import type { SignatureProof } from '../messaging/index.js';
+export type DataSensitivity = 'public' | 'internal' | 'confidential' | 'regulated' | 'vault-secret';
+export interface ActionRiskMetadataV1 {
+    version: 'ap.interaction.action-risk.v1';
+    action: string;
+    readOnly: boolean;
+    destructive: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+    dataSensitivity: DataSensitivity;
+    requiresHumanApproval: boolean;
+    requiresMandate: boolean;
+    requiresCredentialPresentation?: boolean;
+    policyRefs?: string[];
+    signedBy?: CanonicalAgentId;
+    signature?: SignatureProof;
+}
+export type RiskDisposition = 'auto-ok' | 'requires-approval' | 'escalate' | 'block';
+export interface RiskEvaluationOpts {
+    /** SAs whose signed risk metadata the evaluator trusts. */
+    trustedSigners: readonly CanonicalAgentId[];
+    /** Sensitivities above this level always require approval. Default 'internal'. */
+    autoOkMaxSensitivity?: DataSensitivity;
+    /** Block (instead of escalate) destructive actions from untrusted signers. */
+    blockUntrustedDestructive?: boolean;
+}
+export interface RiskEvaluation {
+    trusted: boolean;
+    disposition: RiskDisposition;
+    reason: string;
+}
+/**
+ * Pure, fail-closed disposition. Only TRUSTED metadata can yield `auto-ok`;
+ * self-declared/unsigned/unknown-signer metadata escalates (or blocks, for
+ * destructive claims when configured) — it never relaxes handling.
+ */
+export declare function evaluateActionRisk(risk: ActionRiskMetadataV1, opts: RiskEvaluationOpts): RiskEvaluation;
+//# sourceMappingURL=risk.d.ts.map

package/dist/interactions/risk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../../src/interactions/risk.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAEpG,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,+BAA+B,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,eAAe,CAAC;IACjC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,eAAe,EAAE,OAAO,CAAC;IACzB,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,mBAAmB,GAAG,UAAU,GAAG,OAAO,CAAC;AAErF,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,cAAc,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,eAAe,CAAC;IACvC,8EAA8E;IAC9E,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAcD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,oBAAoB,EAC1B,IAAI,EAAE,kBAAkB,GACvB,cAAc,CA4BhB"}

package/dist/interactions/risk.js

@@ -0,0 +1,49 @@
+// ActionRiskMetadataV1 (spec 309 §6.2) — the MCP tool-annotation pattern, but
+// SIGNED and policy-checked, never self-declared. Consumed by inbox rules +
+// Home approval policy to decide auto-file / auto-approve / escalate / block.
+//
+// Trust rule (spec 309 §8.11): risk metadata is only trusted when signed by an
+// accountable SA the evaluator trusts. Untrusted metadata is advisory — the
+// disposition can only get MORE conservative, never less.
+const SENSITIVITY_ORDER = [
+    'public',
+    'internal',
+    'confidential',
+    'regulated',
+    'vault-secret',
+];
+function sensitivityAbove(s, ceiling) {
+    return SENSITIVITY_ORDER.indexOf(s) > SENSITIVITY_ORDER.indexOf(ceiling);
+}
+/**
+ * Pure, fail-closed disposition. Only TRUSTED metadata can yield `auto-ok`;
+ * self-declared/unsigned/unknown-signer metadata escalates (or blocks, for
+ * destructive claims when configured) — it never relaxes handling.
+ */
+export function evaluateActionRisk(risk, opts) {
+    const signerOk = risk.signature !== undefined &&
+        risk.signedBy !== undefined &&
+        risk.signature.signer === risk.signedBy &&
+        opts.trustedSigners.includes(risk.signedBy);
+    if (!signerOk) {
+        if (risk.destructive && (opts.blockUntrustedDestructive ?? false)) {
+            return { trusted: false, disposition: 'block', reason: 'untrusted-destructive' };
+        }
+        return { trusted: false, disposition: 'escalate', reason: 'untrusted-signer' };
+    }
+    if (risk.destructive || risk.requiresHumanApproval) {
+        return { trusted: true, disposition: 'requires-approval', reason: 'high-impact-action' };
+    }
+    if (risk.requiresMandate || risk.requiresCredentialPresentation === true) {
+        return { trusted: true, disposition: 'requires-approval', reason: 'authority-evidence-required' };
+    }
+    const ceiling = opts.autoOkMaxSensitivity ?? 'internal';
+    if (sensitivityAbove(risk.dataSensitivity, ceiling)) {
+        return { trusted: true, disposition: 'requires-approval', reason: 'sensitivity-above-ceiling' };
+    }
+    if (!risk.readOnly && !risk.idempotent) {
+        return { trusted: true, disposition: 'requires-approval', reason: 'non-idempotent-write' };
+    }
+    return { trusted: true, disposition: 'auto-ok', reason: 'within-policy' };
+}
+//# sourceMappingURL=risk.js.map

package/dist/interactions/risk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.js","sourceRoot":"","sources":["../../src/interactions/risk.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,0DAA0D;AAkC1D,MAAM,iBAAiB,GAA+B;IACpD,QAAQ;IACR,UAAU;IACV,cAAc;IACd,WAAW;IACX,cAAc;CACf,CAAC;AAEF,SAAS,gBAAgB,CAAC,CAAkB,EAAE,OAAwB;IACpE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AAC3E,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAA0B,EAC1B,IAAwB;IAExB,MAAM,QAAQ,GACZ,IAAI,CAAC,SAAS,KAAK,SAAS;QAC5B,IAAI,CAAC,QAAQ,KAAK,SAAS;QAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,QAAQ;QACvC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE9C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,yBAAyB,IAAI,KAAK,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;QACnF,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACjF,CAAC;IAED,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;QACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC3F,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,8BAA8B,KAAK,IAAI,EAAE,CAAC;QACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IACpG,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,oBAAoB,IAAI,UAAU,CAAC;IACxD,IAAI,gBAAgB,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IAClG,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC7F,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AAC5E,CAAC"}

package/dist/interactions/runs.d.ts

@@ -0,0 +1,26 @@
+import type { InteractionInterruptV1, InteractionResumeV1, InteractionRunEventV1, InteractionRunV1 } from './types.js';
+export type RunRejection = 'run-not-running' | 'run-not-paused' | 'wrong-run' | 'wrong-interrupt' | 'interrupt-expired' | 'unauthorized-responder' | 'duplicate-resume';
+export type RunStepResult = {
+    ok: true;
+    run: InteractionRunV1;
+    event: InteractionRunEventV1;
+} | {
+    ok: false;
+    reason: RunRejection;
+};
+export declare function startRun(runId: InteractionRunV1['runId'], interactionId: InteractionRunV1['interactionId'], at: string): {
+    run: InteractionRunV1;
+    event: InteractionRunEventV1;
+};
+/** Raise an interrupt on a running run: pauses it until a valid resume. */
+export declare function raiseInterrupt(run: InteractionRunV1, interrupt: InteractionInterruptV1, seq: number, at: string): RunStepResult;
+/**
+ * Apply a resume to a paused run. Fail-closed: wrong interrupt, expired
+ * interrupt, or a responder outside `allowedResponders` rejects; a replayed
+ * idempotency key is reported as `duplicate-resume` so callers dedupe instead
+ * of double-applying.
+ */
+export declare function applyResume(run: InteractionRunV1, interrupt: InteractionInterruptV1, resume: InteractionResumeV1, seq: number, seenIdempotencyKeys: ReadonlySet<string>): RunStepResult;
+export declare function completeRun(run: InteractionRunV1, seq: number, at: string): RunStepResult;
+export declare function failRun(run: InteractionRunV1, seq: number, at: string, reason?: string): RunStepResult;
+//# sourceMappingURL=runs.d.ts.map

package/dist/interactions/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../../src/interactions/runs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EAEnB,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,gBAAgB,GAChB,WAAW,GACX,iBAAiB,GACjB,mBAAmB,GACnB,wBAAwB,GACxB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,GACjE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC;AAYxC,wBAAgB,QAAQ,CACtB,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAChC,aAAa,EAAE,gBAAgB,CAAC,eAAe,CAAC,EAChD,EAAE,EAAE,MAAM,GACT;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAUzD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,sBAAsB,EACjC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,GACT,aAAa,CAYf;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,sBAAsB,EACjC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,MAAM,EACX,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,aAAa,CA6Bf;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAIzF;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAMtG"}

package/dist/interactions/runs.js

@@ -0,0 +1,80 @@
+// Durable interaction runs: pause on interrupt, resume on a signed answer
+// (LangGraph / OpenAI-Agents-SDK / AG-UI pattern, spec 309 §6.2).
+// A resume NEVER itself grants authority — it only un-pauses the run.
+function runEvent(run, seq, eventType, at, payload) {
+    return { version: 'ap.interaction.run-event.v1', runId: run.runId, seq, eventType, at, payload };
+}
+export function startRun(runId, interactionId, at) {
+    const run = {
+        version: 'ap.interaction.run.v1',
+        runId,
+        interactionId,
+        state: 'running',
+        startedAt: at,
+        updatedAt: at,
+    };
+    return { run, event: runEvent(run, 1, 'run-started', at) };
+}
+/** Raise an interrupt on a running run: pauses it until a valid resume. */
+export function raiseInterrupt(run, interrupt, seq, at) {
+    if (run.state !== 'running')
+        return { ok: false, reason: 'run-not-running' };
+    if (interrupt.runId !== run.runId)
+        return { ok: false, reason: 'wrong-run' };
+    const paused = {
+        ...run,
+        state: 'paused',
+        updatedAt: at,
+        pendingInterruptId: interrupt.interruptId,
+    };
+    const eventType = interrupt.raisedBy === 'human' ? 'human-interrupt-raised' : 'agent-interrupt-raised';
+    return { ok: true, run: paused, event: runEvent(paused, seq, eventType, at, interrupt) };
+}
+/**
+ * Apply a resume to a paused run. Fail-closed: wrong interrupt, expired
+ * interrupt, or a responder outside `allowedResponders` rejects; a replayed
+ * idempotency key is reported as `duplicate-resume` so callers dedupe instead
+ * of double-applying.
+ */
+export function applyResume(run, interrupt, resume, seq, seenIdempotencyKeys) {
+    if (run.state !== 'paused')
+        return { ok: false, reason: 'run-not-paused' };
+    if (interrupt.runId !== run.runId)
+        return { ok: false, reason: 'wrong-run' };
+    if (resume.interruptId !== interrupt.interruptId ||
+        run.pendingInterruptId !== interrupt.interruptId) {
+        return { ok: false, reason: 'wrong-interrupt' };
+    }
+    if (interrupt.expiresAt !== undefined && Date.parse(resume.at) >= Date.parse(interrupt.expiresAt)) {
+        return { ok: false, reason: 'interrupt-expired' };
+    }
+    if (interrupt.allowedResponders !== undefined &&
+        interrupt.allowedResponders.length > 0 &&
+        !interrupt.allowedResponders.includes(resume.responder)) {
+        return { ok: false, reason: 'unauthorized-responder' };
+    }
+    if (seenIdempotencyKeys.has(resume.idempotencyKey)) {
+        return { ok: false, reason: 'duplicate-resume' };
+    }
+    const resumed = {
+        ...run,
+        state: 'running',
+        updatedAt: resume.at,
+        pendingInterruptId: undefined,
+    };
+    return { ok: true, run: resumed, event: runEvent(resumed, seq, 'resume-submitted', resume.at, resume) };
+}
+export function completeRun(run, seq, at) {
+    if (run.state !== 'running')
+        return { ok: false, reason: 'run-not-running' };
+    const done = { ...run, state: 'completed', updatedAt: at };
+    return { ok: true, run: done, event: runEvent(done, seq, 'run-completed', at) };
+}
+export function failRun(run, seq, at, reason) {
+    if (run.state === 'completed' || run.state === 'failed') {
+        return { ok: false, reason: 'run-not-running' };
+    }
+    const failed = { ...run, state: 'failed', updatedAt: at, pendingInterruptId: undefined };
+    return { ok: true, run: failed, event: runEvent(failed, seq, 'run-failed', at, reason) };
+}
+//# sourceMappingURL=runs.js.map

package/dist/interactions/runs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../../src/interactions/runs.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,kEAAkE;AAClE,sEAAsE;AAuBtE,SAAS,QAAQ,CACf,GAAqB,EACrB,GAAW,EACX,SAAkC,EAClC,EAAU,EACV,OAAiB;IAEjB,OAAO,EAAE,OAAO,EAAE,6BAA6B,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,KAAgC,EAChC,aAAgD,EAChD,EAAU;IAEV,MAAM,GAAG,GAAqB;QAC5B,OAAO,EAAE,uBAAuB;QAChC,KAAK;QACL,aAAa;QACb,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;KACd,CAAC;IACF,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAC5B,GAAqB,EACrB,SAAiC,EACjC,GAAW,EACX,EAAU;IAEV,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC7E,IAAI,SAAS,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC7E,MAAM,MAAM,GAAqB;QAC/B,GAAG,GAAG;QACN,KAAK,EAAE,QAAQ;QACf,SAAS,EAAE,EAAE;QACb,kBAAkB,EAAE,SAAS,CAAC,WAAW;KAC1C,CAAC;IACF,MAAM,SAAS,GACb,SAAS,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,wBAAwB,CAAC;IACvF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,GAAqB,EACrB,SAAiC,EACjC,MAA2B,EAC3B,GAAW,EACX,mBAAwC;IAExC,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3E,IAAI,SAAS,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC7E,IACE,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,WAAW;QAC5C,GAAG,CAAC,kBAAkB,KAAK,SAAS,CAAC,WAAW,EAChD,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,SAAS,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QAClG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACpD,CAAC;IACD,IACE,SAAS,CAAC,iBAAiB,KAAK,SAAS;QACzC,SAAS,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;QACtC,CAAC,SAAS,CAAC,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EACvD,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,OAAO,GAAqB;QAChC,GAAG,GAAG;QACN,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,MAAM,CAAC,EAAE;QACpB,kBAAkB,EAAE,SAAS;KAC9B,CAAC;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;AAC1G,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAqB,EAAE,GAAW,EAAE,EAAU;IACxE,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC7E,MAAM,IAAI,GAAqB,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAC7E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,GAAqB,EAAE,GAAW,EAAE,EAAU,EAAE,MAAe;IACrF,IAAI,GAAG,CAAC,KAAK,KAAK,WAAW,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,MAAM,GAAqB,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC;IAC3G,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC;AAC3F,CAAC"}

package/dist/interactions/store.d.ts

@@ -0,0 +1,20 @@
+import { type TransitionResult } from './machine.js';
+import type { InteractionCaseV1, InteractionId, InteractionState, InteractionTransitionEventV1 } from './types.js';
+export interface InteractionStore {
+    /** Register a new case. Fail-closed: only `draft` cases enter; duplicate ids throw. */
+    putCase(c: InteractionCaseV1): void;
+    getCase(id: InteractionId): InteractionCaseV1 | null;
+    /**
+     * Apply a signed transition event. Idempotent: replaying an event whose
+     * `idempotencyKey` was already applied returns the current case unchanged
+     * (`ok: true`), never double-applies. Rejections do not mutate.
+     */
+    applyEvent(event: InteractionTransitionEventV1): TransitionResult;
+    listEvents(id: InteractionId): InteractionTransitionEventV1[];
+    listCases(state?: InteractionState): InteractionCaseV1[];
+    /** Deterministic clock sweep: expire every non-terminal case past its
+     *  deadline as of `nowIso`. Returns the cases it expired. */
+    processDue(nowIso: string): InteractionCaseV1[];
+}
+export declare function createInMemoryInteractionStore(): InteractionStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/interactions/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/interactions/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAA+C,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAEnH,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,OAAO,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,EAAE,aAAa,GAAG,iBAAiB,GAAG,IAAI,CAAC;IACrD;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,4BAA4B,GAAG,gBAAgB,CAAC;IAClE,UAAU,CAAC,EAAE,EAAE,aAAa,GAAG,4BAA4B,EAAE,CAAC;IAC9D,SAAS,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,iBAAiB,EAAE,CAAC;IACzD;iEAC6D;IAC7D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAAC;CACjD;AAED,wBAAgB,8BAA8B,IAAI,gBAAgB,CA6DjE"}

package/dist/interactions/store.js

@@ -0,0 +1,68 @@
+// In-memory InteractionStore: cases + transition log with idempotent replay
+// and deterministic expiry sweeps (spec 309 §6.1, §8.10).
+import { applyInteractionTransition, isTerminalState } from './machine.js';
+export function createInMemoryInteractionStore() {
+    const cases = new Map();
+    const events = new Map();
+    const appliedKeys = new Map();
+    return {
+        putCase(c) {
+            if (c.state !== 'draft') {
+                throw new Error(`case ${c.id} must enter the store in draft state, got ${c.state}`);
+            }
+            if (cases.has(c.id))
+                throw new Error(`duplicate interaction id ${c.id}`);
+            cases.set(c.id, c);
+            events.set(c.id, []);
+            appliedKeys.set(c.id, new Set());
+        },
+        getCase(id) {
+            return cases.get(id) ?? null;
+        },
+        applyEvent(event) {
+            const current = cases.get(event.interactionId);
+            if (!current)
+                return { ok: false, reason: 'wrong-case' };
+            const keys = appliedKeys.get(event.interactionId);
+            if (event.idempotencyKey !== undefined && keys.has(event.idempotencyKey)) {
+                return { ok: true, case: current };
+            }
+            const result = applyInteractionTransition(current, event);
+            if (!result.ok)
+                return result;
+            cases.set(event.interactionId, result.case);
+            events.get(event.interactionId).push(event);
+            if (event.idempotencyKey !== undefined)
+                keys.add(event.idempotencyKey);
+            return result;
+        },
+        listEvents(id) {
+            return [...(events.get(id) ?? [])];
+        },
+        listCases(state) {
+            return [...cases.values()].filter((c) => (state ? c.state === state : true));
+        },
+        processDue(nowIso) {
+            const expired = [];
+            for (const c of cases.values()) {
+                if (isTerminalState(c.state))
+                    continue;
+                if (c.expiresAt === undefined || Date.parse(nowIso) < Date.parse(c.expiresAt))
+                    continue;
+                const result = applyInteractionTransition(c, {
+                    version: 'ap.interaction.event.v1',
+                    interactionId: c.id,
+                    transition: 'expire',
+                    actor: c.responder, // role 'any' — deterministic sweep, not a user action
+                    at: nowIso,
+                });
+                if (result.ok) {
+                    cases.set(c.id, result.case);
+                    expired.push(result.case);
+                }
+            }
+            return expired;
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/interactions/store.js.map

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

package/dist/interactions/tickets.d.ts

@@ -0,0 +1,68 @@
+import type { CanonicalAgentId } from '@agenticprimitives/types';
+import type { VaultRef } from '@agenticprimitives/vault';
+import type { Hex32, SignatureProof } from '../messaging/index.js';
+import type { InteractionId } from './types.js';
+/** Ref to a presentation definition (spec 305) — by id/URI, never embedded. */
+export type PresentationDefinitionRef = string;
+export type CredentialFormat = 'jwt-vc' | 'sd-jwt-vc' | 'w3c-vc';
+export interface PermissionTicketV1 {
+    version: 'ap.interaction.permission-ticket.v1';
+    ticketId: string;
+    interactionId: InteractionId;
+    resource: string;
+    requestedActions: string[];
+    requestingAgent: CanonicalAgentId;
+    /** The person/org the requesting agent acts for, when disclosed. */
+    requestingParty?: CanonicalAgentId;
+    claimsRequired?: PresentationDefinitionRef[];
+    issuedAt: string;
+    expiresAt: string;
+    issuer: CanonicalAgentId;
+    signature?: SignatureProof;
+}
+export interface ClaimsChallengeV1 {
+    version: 'ap.interaction.claims-challenge.v1';
+    challengeId: string;
+    ticketId: string;
+    requiredClaims: PresentationDefinitionRef[];
+    acceptableCredentialFormats: CredentialFormat[];
+    expiresAt?: string;
+}
+/** The requester's answer: a selectively-disclosed presentation, by ref+hash. */
+export interface ClaimsPresentationV1 {
+    version: 'ap.interaction.claims-presentation.v1';
+    challengeId: string;
+    presenter: CanonicalAgentId;
+    format: CredentialFormat;
+    presentationHash: Hex32;
+    presentationRef?: VaultRef;
+    presentedAt: string;
+    signature?: SignatureProof;
+}
+export interface CreatePermissionTicketInput {
+    ticketId?: string;
+    interactionId: InteractionId;
+    resource: string;
+    requestedActions: string[];
+    requestingAgent: CanonicalAgentId;
+    requestingParty?: CanonicalAgentId;
+    claimsRequired?: PresentationDefinitionRef[];
+    issuedAt: string;
+    expiresAt: string;
+    issuer: CanonicalAgentId;
+}
+export declare function createPermissionTicket(input: CreatePermissionTicketInput): PermissionTicketV1;
+export declare function isTicketExpired(ticket: PermissionTicketV1, atIso: string): boolean;
+export type ChallengeAnswerReason = 'acceptable' | 'wrong-challenge' | 'format-not-acceptable' | 'challenge-expired' | 'unsigned-presentation';
+export interface ChallengeAnswerResult {
+    acceptable: boolean;
+    reason: ChallengeAnswerReason;
+}
+/**
+ * Fail-closed structural gate on a presentation BEFORE credential verification:
+ * right challenge, acceptable format, inside the window, signed by presenter.
+ * An `acceptable` result still requires the credential packages to verify the
+ * presentation itself — this never substitutes for proof verification.
+ */
+export declare function checkPresentationAnswersChallenge(challenge: ClaimsChallengeV1, presentation: ClaimsPresentationV1): ChallengeAnswerResult;
+//# sourceMappingURL=tickets.d.ts.map

package/dist/interactions/tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.d.ts","sourceRoot":"","sources":["../../src/interactions/tickets.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAE/C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,qCAAqC,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,gBAAgB,CAAC;IAClC,oEAAoE;IACpE,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,cAAc,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oCAAoC,CAAC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,yBAAyB,EAAE,CAAC;IAC5C,2BAA2B,EAAE,gBAAgB,EAAE,CAAC;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,uCAAuC,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,gBAAgB,EAAE,KAAK,CAAC;IACxB,eAAe,CAAC,EAAE,QAAQ,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,gBAAgB,CAAC;IAClC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IACnC,cAAc,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,kBAAkB,CAa7F;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAElF;AAED,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,iBAAiB,GACjB,uBAAuB,GACvB,mBAAmB,GACnB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,oBAAoB,GACjC,qBAAqB,CAiBvB"}

package/dist/interactions/tickets.js

@@ -0,0 +1,49 @@
+// PermissionTicketV1 / ClaimsChallengeV1 (spec 309 §6.2 — UMA/GNAP/OID4VC
+// pattern): "please give me access" becomes an async, policy-driven
+// negotiation. The resource side issues a ticket + a claims challenge (a
+// `privacy-credentials` presentation definition, spec 305); the requester
+// answers with a selectively-disclosed presentation; approval then issues the
+// entitlement/credential through the authority packages.
+//
+// This package owns the negotiation SHAPES + fail-closed matching only —
+// presentation verification lives with the credential packages.
+export function createPermissionTicket(input) {
+    if (Date.parse(input.expiresAt) <= Date.parse(input.issuedAt)) {
+        throw new Error(`ticket expiry ${input.expiresAt} is not after issuance ${input.issuedAt}`);
+    }
+    if (input.requestedActions.length === 0) {
+        throw new Error('a permission ticket requires at least one requested action');
+    }
+    const { ticketId, ...rest } = input;
+    return {
+        version: 'ap.interaction.permission-ticket.v1',
+        ticketId: ticketId ?? `tkt_${globalThis.crypto.randomUUID().replaceAll('-', '')}`,
+        ...rest,
+    };
+}
+export function isTicketExpired(ticket, atIso) {
+    return Date.parse(atIso) >= Date.parse(ticket.expiresAt);
+}
+/**
+ * Fail-closed structural gate on a presentation BEFORE credential verification:
+ * right challenge, acceptable format, inside the window, signed by presenter.
+ * An `acceptable` result still requires the credential packages to verify the
+ * presentation itself — this never substitutes for proof verification.
+ */
+export function checkPresentationAnswersChallenge(challenge, presentation) {
+    if (presentation.challengeId !== challenge.challengeId) {
+        return { acceptable: false, reason: 'wrong-challenge' };
+    }
+    if (challenge.expiresAt !== undefined &&
+        Date.parse(presentation.presentedAt) >= Date.parse(challenge.expiresAt)) {
+        return { acceptable: false, reason: 'challenge-expired' };
+    }
+    if (!challenge.acceptableCredentialFormats.includes(presentation.format)) {
+        return { acceptable: false, reason: 'format-not-acceptable' };
+    }
+    if (presentation.signature === undefined) {
+        return { acceptable: false, reason: 'unsigned-presentation' };
+    }
+    return { acceptable: true, reason: 'acceptable' };
+}
+//# sourceMappingURL=tickets.js.map

package/dist/interactions/tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.js","sourceRoot":"","sources":["../../src/interactions/tickets.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,oEAAoE;AACpE,yEAAyE;AACzE,0EAA0E;AAC1E,8EAA8E;AAC9E,yDAAyD;AACzD,EAAE;AACF,yEAAyE;AACzE,gEAAgE;AA8DhE,MAAM,UAAU,sBAAsB,CAAC,KAAkC;IACvE,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,CAAC,SAAS,0BAA0B,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;IACpC,OAAO;QACL,OAAO,EAAE,qCAAqC;QAC9C,QAAQ,EAAE,QAAQ,IAAI,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;QACjF,GAAG,IAAI;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAA0B,EAAE,KAAa;IACvE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3D,CAAC;AAcD;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAC/C,SAA4B,EAC5B,YAAkC;IAElC,IAAI,YAAY,CAAC,WAAW,KAAK,SAAS,CAAC,WAAW,EAAE,CAAC;QACvD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC1D,CAAC;IACD,IACE,SAAS,CAAC,SAAS,KAAK,SAAS;QACjC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,EACvE,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC5D,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,2BAA2B,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAChE,CAAC;IACD,IAAI,YAAY,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACzC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;AACpD,CAAC"}