@lssm/lib.contracts-spec 17.3.2

package/dist/agent/protocol/automation/lifecycle.d.ts

@@ -0,0 +1,362 @@
+import { z } from 'zod';
+export declare const AGENT_AUTOMATION_MATERIALIZATION_V1: 'contractspec.agent.automation-materialization.v1';
+export declare const AGENT_AUTOMATION_STATE_V1: 'contractspec.agent.automation-state.v1';
+export declare const AGENT_AUTOMATION_TRANSITION_V1: 'contractspec.agent.automation-transition.v1';
+export declare const AGENT_AUTOMATION_CLAIM_V1: 'contractspec.agent.automation-claim.v1';
+export declare const AGENT_AUTOMATION_RUN_RECEIPT_V1: 'contractspec.agent.automation-run-receipt.v1';
+export declare const AGENT_AUTOMATION_FOLLOW_UP_V1: 'contractspec.agent.automation-follow-up.v1';
+export declare const agentAutomationMaterializationV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-materialization.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    preview: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    definition: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    application: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    installation: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    installationRevision: z.ZodNumber;
+    authorityDecision: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    policyDecisions: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    canonicalConversation: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"cron">;
+        expression: z.ZodString;
+        timezone: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"once">;
+        runAt: z.ZodString;
+    }, z.core.$strict>], "kind">;
+    parameterBindings: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodObject<{
+            ref: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    deliveryChannelRef: z.ZodOptional<z.ZodString>;
+    deliveryProfile: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    initialState: z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+    }>;
+    materializedAt: z.ZodString;
+    expiresAt: z.ZodString;
+    effectAuthority: z.ZodLiteral<"none">;
+    materializationDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const agentAutomationStateV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-state.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    materialization: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    revision: z.ZodNumber;
+    status: z.ZodEnum<{
+        active: "active";
+        completed: "completed";
+        expired: "expired";
+        paused: "paused";
+        reconciliation_required: "reconciliation_required";
+        revoked: "revoked";
+    }>;
+    nextRunAt: z.ZodOptional<z.ZodString>;
+    runCount: z.ZodNumber;
+    activeClaim: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    lastRunReceipt: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    updatedAt: z.ZodString;
+    stateDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const agentAutomationTransitionV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-transition.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    automationRef: z.ZodString;
+    fromState: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    toState: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    action: z.ZodEnum<{
+        expire: "expire";
+        pause: "pause";
+        resume: "resume";
+        revoke: "revoke";
+    }>;
+    actorRef: z.ZodString;
+    authorityDecision: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    idempotencyKey: z.ZodString;
+    evidence: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            eval_result: "eval_result";
+            human_feedback: "human_feedback";
+            policy_decision: "policy_decision";
+            redaction_decision: "redaction_decision";
+            replay_bundle: "replay_bundle";
+            retrieval_context: "retrieval_context";
+            rollback_version: "rollback_version";
+            source_message: "source_message";
+            tool_receipt: "tool_receipt";
+        }>;
+        ref: z.ZodString;
+        sourcePackage: z.ZodString;
+        redactionStatus: z.ZodEnum<{
+            none: "none";
+            redacted: "redacted";
+            restricted: "restricted";
+        }>;
+        ontologyRef: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        artifactHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    transitionedAt: z.ZodString;
+    receiptDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const agentAutomationClaimV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-claim.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    automationRef: z.ZodString;
+    materialization: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    state: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    stateRevision: z.ZodNumber;
+    occurrenceRef: z.ZodString;
+    runRef: z.ZodString;
+    canonicalConversation: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    scheduledFor: z.ZodString;
+    claimedAt: z.ZodString;
+    leaseExpiresAt: z.ZodString;
+    idempotencyKey: z.ZodString;
+    authorityDecision: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    evidence: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            eval_result: "eval_result";
+            human_feedback: "human_feedback";
+            policy_decision: "policy_decision";
+            redaction_decision: "redaction_decision";
+            replay_bundle: "replay_bundle";
+            retrieval_context: "retrieval_context";
+            rollback_version: "rollback_version";
+            source_message: "source_message";
+            tool_receipt: "tool_receipt";
+        }>;
+        ref: z.ZodString;
+        sourcePackage: z.ZodString;
+        redactionStatus: z.ZodEnum<{
+            none: "none";
+            redacted: "redacted";
+            restricted: "restricted";
+        }>;
+        ontologyRef: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        artifactHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    effectAuthority: z.ZodLiteral<"none">;
+    claimDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const agentAutomationRunReceiptV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-run-receipt.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    claim: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    run: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    terminalDecision: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    outcome: z.ZodEnum<{
+        blocked: "blocked";
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        indeterminate: "indeterminate";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            eval_result: "eval_result";
+            human_feedback: "human_feedback";
+            policy_decision: "policy_decision";
+            redaction_decision: "redaction_decision";
+            replay_bundle: "replay_bundle";
+            retrieval_context: "retrieval_context";
+            rollback_version: "rollback_version";
+            source_message: "source_message";
+            tool_receipt: "tool_receipt";
+        }>;
+        ref: z.ZodString;
+        sourcePackage: z.ZodString;
+        redactionStatus: z.ZodEnum<{
+            none: "none";
+            redacted: "redacted";
+            restricted: "restricted";
+        }>;
+        ontologyRef: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        artifactHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    completedAt: z.ZodString;
+    receiptDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const agentAutomationFollowUpV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.automation-follow-up.v1">;
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    automationRef: z.ZodString;
+    runReceipt: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    canonicalConversation: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    deliveryIntent: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    policyDecision: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    notBefore: z.ZodString;
+    expiresAt: z.ZodString;
+    idempotencyKey: z.ZodString;
+    evidence: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            eval_result: "eval_result";
+            human_feedback: "human_feedback";
+            policy_decision: "policy_decision";
+            redaction_decision: "redaction_decision";
+            replay_bundle: "replay_bundle";
+            retrieval_context: "retrieval_context";
+            rollback_version: "rollback_version";
+            source_message: "source_message";
+            tool_receipt: "tool_receipt";
+        }>;
+        ref: z.ZodString;
+        sourcePackage: z.ZodString;
+        redactionStatus: z.ZodEnum<{
+            none: "none";
+            redacted: "redacted";
+            restricted: "restricted";
+        }>;
+        ontologyRef: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        artifactHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    status: z.ZodLiteral<"requested">;
+    effectAuthority: z.ZodLiteral<"none">;
+    followUpDigest: z.ZodString;
+}, z.core.$strict>;
+export type AgentAutomationMaterializationV1 = z.infer<typeof agentAutomationMaterializationV1Schema>;
+export type AgentAutomationStateV1 = z.infer<typeof agentAutomationStateV1Schema>;
+export type AgentAutomationTransitionV1 = z.infer<typeof agentAutomationTransitionV1Schema>;
+export type AgentAutomationClaimV1 = z.infer<typeof agentAutomationClaimV1Schema>;
+export type AgentAutomationRunReceiptV1 = z.infer<typeof agentAutomationRunReceiptV1Schema>;
+export type AgentAutomationFollowUpV1 = z.infer<typeof agentAutomationFollowUpV1Schema>;

package/dist/agent/protocol/automation/lifecycle.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{agentArtifactBindingV1Schema as t,agentProtocolDigestSchema as r,agentProtocolEvidencePointerSchema as c,agentProtocolRefSchema as i,agentProtocolTimestampSchema as a,agentScopeV1Schema as s}from"../common.js";import{agentAutomationParameterBindingV1Schema as m,agentAutomationTriggerV1Schema as p}from"./contracts.js";export const AGENT_AUTOMATION_MATERIALIZATION_V1="contractspec.agent.automation-materialization.v1";export const AGENT_AUTOMATION_STATE_V1="contractspec.agent.automation-state.v1";export const AGENT_AUTOMATION_TRANSITION_V1="contractspec.agent.automation-transition.v1";export const AGENT_AUTOMATION_CLAIM_V1="contractspec.agent.automation-claim.v1";export const AGENT_AUTOMATION_RUN_RECEIPT_V1="contractspec.agent.automation-run-receipt.v1";export const AGENT_AUTOMATION_FOLLOW_UP_V1="contractspec.agent.automation-follow-up.v1";export const agentAutomationMaterializationV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_MATERIALIZATION_V1),id:i,scope:s,preview:t,definition:t,application:t,installation:t,installationRevision:e.number().int().positive(),authorityDecision:t,policyDecisions:e.array(t).min(1),canonicalConversation:t,trigger:p,parameterBindings:e.array(m),deliveryChannelRef:i.optional(),deliveryProfile:t.optional(),initialState:e.enum(["active","paused"]),materializedAt:a,expiresAt:a,effectAuthority:e.literal("none"),materializationDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.expiresAt)<=Date.parse(o.materializedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Automation materialization must expire after activation"});if(Boolean(o.deliveryChannelRef)!==Boolean(o.deliveryProfile))n.addIssue({code:e.ZodIssueCode.custom,path:["deliveryProfile"],message:"Delivery channel and profile must be selected together"})});export const agentAutomationStateV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_STATE_V1),id:i,scope:s,materialization:t,revision:e.number().int().positive(),status:e.enum(["active","paused","expired","revoked","completed","reconciliation_required"]),nextRunAt:a.optional(),runCount:e.number().int().nonnegative(),activeClaim:t.optional(),lastRunReceipt:t.optional(),updatedAt:a,stateDigest:r}).strict().superRefine((o,n)=>{if(["expired","revoked","completed"].includes(o.status)&&(o.nextRunAt||o.activeClaim))n.addIssue({code:e.ZodIssueCode.custom,path:["status"],message:"Terminal automation state cannot retain future or active work"});if((o.status==="active"||o.status==="paused")&&!o.nextRunAt)n.addIssue({code:e.ZodIssueCode.custom,path:["nextRunAt"],message:"Runnable automation state requires its next occurrence"});if(o.status==="reconciliation_required"&&!o.activeClaim)n.addIssue({code:e.ZodIssueCode.custom,path:["activeClaim"],message:"Reconciliation state requires the unresolved claim"})});export const agentAutomationTransitionV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_TRANSITION_V1),id:i,scope:s,automationRef:i,fromState:t,toState:t,action:e.enum(["pause","resume","revoke","expire"]),actorRef:i,authorityDecision:t,idempotencyKey:i,evidence:e.array(c).min(1),transitionedAt:a,receiptDigest:r}).strict();export const agentAutomationClaimV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_CLAIM_V1),id:i,scope:s,automationRef:i,materialization:t,state:t,stateRevision:e.number().int().positive(),occurrenceRef:i,runRef:i,canonicalConversation:t,scheduledFor:a,claimedAt:a,leaseExpiresAt:a,idempotencyKey:i,authorityDecision:t,evidence:e.array(c).min(1),effectAuthority:e.literal("none"),claimDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.leaseExpiresAt)<=Date.parse(o.claimedAt))n.addIssue({code:e.ZodIssueCode.custom,path:["leaseExpiresAt"],message:"Automation claim lease must expire after claim time"})});export const agentAutomationRunReceiptV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_RUN_RECEIPT_V1),id:i,scope:s,claim:t,run:t,terminalDecision:t,outcome:e.enum(["completed","blocked","failed","cancelled","indeterminate"]),evidence:e.array(c).min(1),completedAt:a,receiptDigest:r}).strict();export const agentAutomationFollowUpV1Schema=e.object({schemaVersion:e.literal(AGENT_AUTOMATION_FOLLOW_UP_V1),id:i,scope:s,automationRef:i,runReceipt:t,canonicalConversation:t,deliveryIntent:t,policyDecision:t,notBefore:a,expiresAt:a,idempotencyKey:i,evidence:e.array(c).min(1),status:e.literal("requested"),effectAuthority:e.literal("none"),followUpDigest:r}).strict().superRefine((o,n)=>{if(Date.parse(o.expiresAt)<=Date.parse(o.notBefore))n.addIssue({code:e.ZodIssueCode.custom,path:["expiresAt"],message:"Automation follow-up must expire after its earliest delivery"})});

package/dist/agent/protocol/automation/run-validation.d.ts

@@ -0,0 +1,17 @@
+import type { AgentAutomationClaimV1, AgentAutomationFollowUpV1, AgentAutomationMaterializationV1, AgentAutomationRunReceiptV1, AgentAutomationStateV1 } from './lifecycle.js';
+export declare function validateAgentAutomationRunReceiptV1(input: {
+    claim: AgentAutomationClaimV1;
+    receipt: AgentAutomationRunReceiptV1;
+}): string[];
+export declare function validateAgentAutomationFollowUpV1(input: {
+    claim: AgentAutomationClaimV1;
+    receipt: AgentAutomationRunReceiptV1;
+    followUp: AgentAutomationFollowUpV1;
+}): string[];
+export declare function validateAgentAutomationRunStateV1(input: {
+    materialization: AgentAutomationMaterializationV1;
+    prior: AgentAutomationStateV1;
+    current: AgentAutomationStateV1;
+    claim: AgentAutomationClaimV1;
+    receipt: AgentAutomationRunReceiptV1;
+}): string[];

package/dist/agent/protocol/automation/run-validation.js

@@ -0,0 +1 @@
+import{validateAgentScopeExactV1 as m}from"../common.js";import{verifyAgentAutomationDigestV1 as u}from"./digests.js";import{validateAgentAutomationStateV1 as c}from"./lifecycle-validation.js";export function validateAgentAutomationRunReceiptV1(n){const{claim:i,receipt:e}=n,t=m({expected:i.scope,observed:e.scope});if(!u(i,"claimDigest"))t.push("Automation claim digest is invalid");if(!u(e,"receiptDigest"))t.push("Automation run receipt digest is invalid");if(e.claim.ref!==i.id||e.claim.digest!==i.claimDigest||e.run.ref!==i.runRef)t.push("Automation run receipt claim or run binding does not match");if(Date.parse(e.completedAt)<Date.parse(i.claimedAt))t.push("Automation run receipt predates its claim");return[...new Set(t)]}export function validateAgentAutomationFollowUpV1(n){const{claim:i,receipt:e,followUp:t}=n,o=validateAgentAutomationRunReceiptV1({claim:i,receipt:e});if(!u(t,"followUpDigest"))o.push("Automation follow-up digest is invalid");if(t.automationRef!==i.automationRef||t.runReceipt.ref!==e.id||t.runReceipt.digest!==e.receiptDigest||t.canonicalConversation.ref!==i.canonicalConversation.ref||t.canonicalConversation.digest!==i.canonicalConversation.digest)o.push("Automation follow-up binding does not match");if(e.outcome==="indeterminate"||Date.parse(t.notBefore)<Date.parse(e.completedAt))o.push("Automation follow-up is unsafe for the run outcome");return[...new Set(o)]}export function validateAgentAutomationRunStateV1(n){const{materialization:i,prior:e,current:t,claim:o,receipt:a}=n,r=[...validateAgentAutomationRunReceiptV1({claim:o,receipt:a}),...c({materialization:i,state:e}),...c({materialization:i,state:t})],s=a.outcome==="indeterminate";if(e.activeClaim?.ref!==o.id||e.activeClaim?.digest!==o.claimDigest||t.revision!==e.revision+1||t.lastRunReceipt?.ref!==a.id||t.lastRunReceipt?.digest!==a.receiptDigest||t.runCount!==e.runCount+(s?0:1)||(s?t.status!=="reconciliation_required"||t.activeClaim?.digest!==o.claimDigest:Boolean(t.activeClaim)))r.push("Automation run state transition is invalid");if(Date.parse(t.updatedAt)<Date.parse(a.completedAt))r.push("Automation run state predates its receipt");return[...new Set(r)]}

package/dist/agent/protocol/automation/validation.d.ts

@@ -0,0 +1,3 @@
+export * from './definition-validation.js';
+export * from './lifecycle-validation.js';
+export * from './run-validation.js';

package/dist/agent/protocol/automation/validation.js

@@ -0,0 +1 @@
+export*from"./definition-validation.js";export*from"./lifecycle-validation.js";export*from"./run-validation.js";

package/dist/agent/protocol/bindings.d.ts

@@ -0,0 +1,25 @@
+import type { AgentCheckpointV1 } from './execution.js';
+import type { AgentModelFallbackDecisionV1, AgentModelSelectionV1 } from './model-routing.js';
+import { type AgentModelCandidateViewV1 } from './model-selection-validation.js';
+import type { AgentExecutionPlanV1 } from './planning.js';
+export * from './application.js';
+export type { AgentModelCandidateViewV1 } from './model-selection-validation.js';
+export { validateAgentModelSelectionBindingV1, validateModelCandidateV1, } from './model-selection-validation.js';
+export interface AgentModelEligibilityViewV1 {
+    route: AgentModelSelectionV1['selectedRoute'];
+    status: 'eligible' | 'ineligible' | 'unknown';
+    evidence: {
+        ref: string;
+        digest: string;
+    };
+}
+export declare function validateAgentModelFallbackEquivalenceV1(input: {
+    plan: AgentExecutionPlanV1;
+    selection: AgentModelSelectionV1;
+    decision: AgentModelFallbackDecisionV1;
+    checkpoint: AgentCheckpointV1;
+    from: AgentModelCandidateViewV1;
+    to: AgentModelCandidateViewV1;
+    consideredCandidates: AgentModelCandidateViewV1[];
+    eligibility: AgentModelEligibilityViewV1[];
+}): string[];

package/dist/agent/protocol/bindings.js

@@ -0,0 +1 @@
+import{validateAgentModelFallbackOriginV1 as g}from"./model-fallback-validation.js";import{routeBindingMatchesModelCandidateV1 as s,validateAgentModelSelectionBindingV1 as b,validateModelCandidateV1 as c}from"./model-selection-validation.js";export*from"./application.js";export{validateAgentModelSelectionBindingV1,validateModelCandidateV1}from"./model-selection-validation.js";export function validateAgentModelFallbackEquivalenceV1(e){const t=g(e);t.push(...b({plan:e.plan,selection:e.selection,candidate:e.from}).map((i)=>`Fallback source ${i}`));const r=e.consideredCandidates.map((i)=>i.route.id),d=e.decision.consideredRoutes.map((i)=>i.ref);if(new Set(d).size!==d.length)t.push("Fallback considered routes must be unique");for(const[i,n]of e.decision.consideredRoutes.entries()){const o=e.consideredCandidates[i],l=e.eligibility[i];if(!o||!s(n,o))t.push(`Fallback considered route has a stale binding: ${n.ref}`);if(!o||!l||!s(l.route,o)||n.eligibility!==l.status||n.eligibilityEvidence.ref!==l.evidence.ref||n.eligibilityEvidence.digest!==l.evidence.digest)t.push(`Fallback eligibility binding is stale: ${n.ref}`)}if(JSON.stringify(r)!==JSON.stringify(d))t.push("Fallback considered-route order does not match evaluated candidates");const a=e.consideredCandidates.find((i,n)=>e.eligibility[n]?.status==="eligible"&&c({plan:e.plan,selection:e.selection,candidate:i}).length===0);t.push(...c({plan:e.plan,selection:e.selection,candidate:e.to}).map((i)=>`Fallback ${i.replace("Model route","route")}`));if(!a||a.route.id!==e.to.route.id)t.push("Fallback target is not the first eligible considered route");if(e.decision.decision==="allowed"&&t.length>0)t.push("Fallback cannot be allowed when equivalence checks fail");return t}

package/dist/agent/protocol/budget.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export declare const AGENT_RUN_BUDGET_V1: 'contractspec.agent.run-budget.v1';
+export declare const agentRunBudgetV1Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"contractspec.agent.run-budget.v1">;
+    id: z.ZodString;
+    revision: z.ZodNumber;
+    runRef: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        spaceId: z.ZodString;
+        productKey: z.ZodString;
+        applicationRef: z.ZodString;
+        purpose: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    authorizedByRef: z.ZodString;
+    authorizedAt: z.ZodString;
+    supersedesRef: z.ZodOptional<z.ZodString>;
+    maxInputTokens: z.ZodNumber;
+    maxOutputTokens: z.ZodNumber;
+    maxModelCalls: z.ZodNumber;
+    maxToolCalls: z.ZodNumber;
+    maxEffects: z.ZodNumber;
+    maxCostMinorUnits: z.ZodNumber;
+    costCurrency: z.ZodString;
+    maxRetries: z.ZodNumber;
+    maxReplans: z.ZodNumber;
+    maxConcurrentAgents: z.ZodNumber;
+    maxParticipants: z.ZodNumber;
+    maxTaskNodes: z.ZodNumber;
+    maxDelegationDepth: z.ZodNumber;
+    maxStepsBetweenReflections: z.ZodNumber;
+    maxEpochActiveComputeSeconds: z.ZodNumber;
+    maxActiveComputeSeconds: z.ZodNumber;
+    maxWallClockSeconds: z.ZodNumber;
+    checkpointIntervalSeconds: z.ZodNumber;
+    approvalExpirySeconds: z.ZodNumber;
+    leaseHeartbeatSeconds: z.ZodNumber;
+    humanCheckInConditionRefs: z.ZodArray<z.ZodString>;
+    qualificationRef: z.ZodOptional<z.ZodString>;
+    budgetDigest: z.ZodString;
+}, z.core.$strict>;
+export type AgentRunBudgetV1 = z.infer<typeof agentRunBudgetV1Schema>;
+export declare function validateAgentChildBudgetV1(input: {
+    parent: AgentRunBudgetV1;
+    child: AgentRunBudgetV1;
+}): string[];

package/dist/agent/protocol/budget.js

@@ -0,0 +1 @@
+import{z as o}from"zod";import{agentProtocolDigestSchema as i,agentProtocolRefSchema as s,agentProtocolTimestampSchema as r,agentScopeV1Schema as d,validateAgentScopeNarrowingV1 as l}from"./common.js";export const AGENT_RUN_BUDGET_V1="contractspec.agent.run-budget.v1";const t=o.number().int().positive();const c=o.number().int().nonnegative();export const agentRunBudgetV1Schema=o.object({schemaVersion:o.literal(AGENT_RUN_BUDGET_V1),id:s,revision:t,runRef:s,scope:d,authorizedByRef:s,authorizedAt:r,supersedesRef:s.optional(),maxInputTokens:t,maxOutputTokens:t,maxModelCalls:t,maxToolCalls:c,maxEffects:c,maxCostMinorUnits:c,costCurrency:o.string().regex(/^[A-Z]{3}$/),maxRetries:c,maxReplans:c,maxConcurrentAgents:t,maxParticipants:t,maxTaskNodes:t,maxDelegationDepth:c,maxStepsBetweenReflections:t.max(10),maxEpochActiveComputeSeconds:t.max(900),maxActiveComputeSeconds:t,maxWallClockSeconds:t,checkpointIntervalSeconds:t,approvalExpirySeconds:t,leaseHeartbeatSeconds:t,humanCheckInConditionRefs:o.array(s).min(1),qualificationRef:s.optional(),budgetDigest:i}).strict().superRefine((e,a)=>{if(e.scope.runId&&e.scope.runId!==e.runRef)a.addIssue({code:o.ZodIssueCode.custom,path:["scope","runId"],message:"Budget scope runId must match its run reference"});if((e.maxConcurrentAgents>4||e.maxParticipants>8||e.maxTaskNodes>32||e.maxDelegationDepth>2||e.maxActiveComputeSeconds>7200||e.maxWallClockSeconds>86400)&&!e.qualificationRef)a.addIssue({code:o.ZodIssueCode.custom,path:["qualificationRef"],message:"Budgets above protocol V1 defaults require qualification"});if(e.checkpointIntervalSeconds>300)a.addIssue({code:o.ZodIssueCode.custom,path:["checkpointIntervalSeconds"],message:"Active work must checkpoint at least every five minutes"})});const m=["maxInputTokens","maxOutputTokens","maxModelCalls","maxToolCalls","maxEffects","maxCostMinorUnits","maxRetries","maxReplans","maxConcurrentAgents","maxParticipants","maxTaskNodes","maxDelegationDepth","maxStepsBetweenReflections","maxEpochActiveComputeSeconds","maxActiveComputeSeconds","maxWallClockSeconds","approvalExpirySeconds"];export function validateAgentChildBudgetV1(e){const a=[];if(e.child.runRef!==e.parent.runRef)a.push("Child budget changes the parent run");if(e.child.costCurrency!==e.parent.costCurrency)a.push("Child budget changes the parent cost currency");a.push(...l({parent:e.parent.scope,child:e.child.scope}).map((n)=>`Child budget ${n.replace("Child scope","scope")}`));for(const n of m)if(e.child[n]>e.parent[n])a.push(`Child budget ${n} exceeds parent budget`);if(e.child.checkpointIntervalSeconds>e.parent.checkpointIntervalSeconds)a.push("Child checkpoint interval is weaker than parent budget");if(e.child.leaseHeartbeatSeconds>e.parent.leaseHeartbeatSeconds)a.push("Child heartbeat interval is weaker than parent budget");for(const n of e.parent.humanCheckInConditionRefs)if(!e.child.humanCheckInConditionRefs.includes(n))a.push(`Child budget drops human check-in condition: ${n}`);return a}

package/dist/agent/protocol/common.d.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+export declare const AGENT_PROTOCOL_V1: 'contractspec.agent.protocol.v1';
+export declare const agentProtocolRefSchema: z.ZodString;
+export declare const agentProtocolTimestampSchema: z.ZodString;
+export declare const agentProtocolDigestSchema: z.ZodString;
+export declare const agentProtocolReleaseShaSchema: z.ZodString;
+export declare const agentProtocolEvidencePointerSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        eval_result: "eval_result";
+        human_feedback: "human_feedback";
+        policy_decision: "policy_decision";
+        redaction_decision: "redaction_decision";
+        replay_bundle: "replay_bundle";
+        retrieval_context: "retrieval_context";
+        rollback_version: "rollback_version";
+        source_message: "source_message";
+        tool_receipt: "tool_receipt";
+    }>;
+    ref: z.ZodString;
+    sourcePackage: z.ZodString;
+    redactionStatus: z.ZodEnum<{
+        none: "none";
+        redacted: "redacted";
+        restricted: "restricted";
+    }>;
+    ontologyRef: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+    artifactHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentRiskTierV1Schema: z.ZodEnum<{
+    R0: "R0";
+    R1: "R1";
+    R2: "R2";
+    R3: "R3";
+}>;
+export declare const agentScopeV1Schema: z.ZodObject<{
+    tenantId: z.ZodString;
+    spaceId: z.ZodString;
+    productKey: z.ZodString;
+    applicationRef: z.ZodString;
+    purpose: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentVersionSetV1Schema: z.ZodObject<{
+    applicationVersion: z.ZodString;
+    promptVersion: z.ZodString;
+    modelRouteVersion: z.ZodString;
+    toolSchemaVersions: z.ZodArray<z.ZodString>;
+    policyVersion: z.ZodString;
+    contextCompilerVersion: z.ZodString;
+    evaluatorVersion: z.ZodString;
+    sandboxDigest: z.ZodString;
+    releaseSha: z.ZodString;
+}, z.core.$strict>;
+export declare const agentConfidenceV1Schema: z.ZodObject<{
+    score: z.ZodNumber;
+    calibrationRef: z.ZodString;
+    uncertaintyRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentEffectProposalV1Schema: z.ZodObject<{
+    id: z.ZodString;
+    capabilityRef: z.ZodString;
+    operationRef: z.ZodString;
+    riskTier: z.ZodEnum<{
+        R0: "R0";
+        R1: "R1";
+        R2: "R2";
+        R3: "R3";
+    }>;
+    approvalRequirementRef: z.ZodOptional<z.ZodString>;
+    connectDecisionRef: z.ZodOptional<z.ZodString>;
+    runtimeWorkOrderRef: z.ZodOptional<z.ZodString>;
+    idempotencyRef: z.ZodString;
+}, z.core.$strict>;
+export declare const agentCriterionResultV1Schema: z.ZodObject<{
+    criterionRef: z.ZodString;
+    satisfied: z.ZodBoolean;
+    evidenceRefs: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const agentArtifactBindingV1Schema: z.ZodObject<{
+    ref: z.ZodString;
+    digest: z.ZodString;
+}, z.core.$strict>;
+/** Opaque bindings only; Execution Lanes owns verifier identity and approval. */
+export declare const agentExecutionVerificationBindingV1Schema: z.ZodObject<{
+    verificationPolicyRef: z.ZodString;
+    executionLaneCompletion: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+    verifierSignoff: z.ZodObject<{
+        ref: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AgentScopeV1 = z.infer<typeof agentScopeV1Schema>;
+export type AgentVersionSetV1 = z.infer<typeof agentVersionSetV1Schema>;
+export type AgentRiskTierV1 = z.infer<typeof agentRiskTierV1Schema>;
+export type AgentConfidenceV1 = z.infer<typeof agentConfidenceV1Schema>;
+export type AgentEffectProposalV1 = z.infer<typeof agentEffectProposalV1Schema>;
+export type AgentCriterionResultV1 = z.infer<typeof agentCriterionResultV1Schema>;
+export type AgentArtifactBindingV1 = z.infer<typeof agentArtifactBindingV1Schema>;
+export type AgentExecutionVerificationBindingV1 = z.infer<typeof agentExecutionVerificationBindingV1Schema>;
+export interface AgentExecutionVerificationViewV1 extends AgentExecutionVerificationBindingV1 {
+    status: 'approved' | 'rejected';
+}
+export type AgentProtocolEvidencePointer = z.infer<typeof agentProtocolEvidencePointerSchema>;
+/** Same-authority children may add a run/session boundary, never remove or change one. */
+export declare function validateAgentScopeNarrowingV1(input: {
+    parent: AgentScopeV1;
+    child: AgentScopeV1;
+}): string[];
+export declare function validateAgentScopeExactV1(input: {
+    expected: AgentScopeV1;
+    observed: AgentScopeV1;
+}): string[];
+export declare function validateAgentExecutionVerificationV1(input: {
+    expectedPolicyRef: string;
+    binding?: AgentExecutionVerificationBindingV1;
+    canonical?: AgentExecutionVerificationViewV1;
+}): string[];
+export interface AgentGraphNodeLike {
+    id: string;
+    dependsOn: string[];
+}
+export declare function validateAgentDirectedAcyclicGraph(nodes: AgentGraphNodeLike[], maxNodes: number): string[];

package/dist/agent/protocol/common.js

@@ -0,0 +1 @@
+import{z as i}from"zod";import{agentStepEvidencePointerSchema as g}from"../../agent-step-observability/validation.js";export const AGENT_PROTOCOL_V1="contractspec.agent.protocol.v1";export const agentProtocolRefSchema=i.string().trim().min(1);export const agentProtocolTimestampSchema=i.string().datetime({offset:!0});export const agentProtocolDigestSchema=i.string().regex(/^sha256:[a-f0-9]{64}$/);export const agentProtocolReleaseShaSchema=i.string().regex(/^[a-f0-9]{40}$/);export const agentProtocolEvidencePointerSchema=g.extend({timestamp:agentProtocolTimestampSchema,artifactHash:agentProtocolDigestSchema.optional()}).strict();export const agentRiskTierV1Schema=i.enum(["R0","R1","R2","R3"]);export const agentScopeV1Schema=i.object({tenantId:agentProtocolRefSchema,spaceId:agentProtocolRefSchema,productKey:agentProtocolRefSchema,applicationRef:agentProtocolRefSchema,purpose:agentProtocolRefSchema,sessionId:agentProtocolRefSchema.optional(),runId:agentProtocolRefSchema.optional()}).strict();export const agentVersionSetV1Schema=i.object({applicationVersion:agentProtocolRefSchema,promptVersion:agentProtocolRefSchema,modelRouteVersion:agentProtocolRefSchema,toolSchemaVersions:i.array(agentProtocolRefSchema),policyVersion:agentProtocolRefSchema,contextCompilerVersion:agentProtocolRefSchema,evaluatorVersion:agentProtocolRefSchema,sandboxDigest:agentProtocolDigestSchema,releaseSha:agentProtocolReleaseShaSchema}).strict();export const agentConfidenceV1Schema=i.object({score:i.number().min(0).max(1),calibrationRef:agentProtocolRefSchema,uncertaintyRefs:i.array(agentProtocolRefSchema)}).strict();export const agentEffectProposalV1Schema=i.object({id:agentProtocolRefSchema,capabilityRef:agentProtocolRefSchema,operationRef:agentProtocolRefSchema,riskTier:agentRiskTierV1Schema,approvalRequirementRef:agentProtocolRefSchema.optional(),connectDecisionRef:agentProtocolRefSchema.optional(),runtimeWorkOrderRef:agentProtocolRefSchema.optional(),idempotencyRef:agentProtocolRefSchema}).strict().superRefine((e,o)=>{if((e.riskTier==="R2"||e.riskTier==="R3")&&!e.approvalRequirementRef)o.addIssue({code:i.ZodIssueCode.custom,path:["approvalRequirementRef"],message:"R2 and R3 effects require an approval requirement reference"})});export const agentCriterionResultV1Schema=i.object({criterionRef:agentProtocolRefSchema,satisfied:i.boolean(),evidenceRefs:i.array(agentProtocolRefSchema)}).strict();export const agentArtifactBindingV1Schema=i.object({ref:agentProtocolRefSchema,digest:agentProtocolDigestSchema}).strict();export const agentExecutionVerificationBindingV1Schema=i.object({verificationPolicyRef:agentProtocolRefSchema,executionLaneCompletion:agentArtifactBindingV1Schema,verifierSignoff:agentArtifactBindingV1Schema}).strict();const d=["tenantId","spaceId","productKey","applicationRef","purpose"];export function validateAgentScopeNarrowingV1(e){const o=[];for(const t of d)if(e.parent[t]!==e.child[t])o.push(`Child scope changes parent ${t}`);for(const t of["sessionId","runId"]){const r=e.parent[t],a=e.child[t];if(r&&a!==r)o.push(`Child scope removes or changes parent ${t}`)}return o}export function validateAgentScopeExactV1(e){const o=[];for(const t of[...d,"sessionId","runId"])if(e.expected[t]!==e.observed[t])o.push(`Observed scope does not match expected ${t}`);return o}export function validateAgentExecutionVerificationV1(e){if(!e.binding)return["Execution verification binding is missing"];if(!e.canonical)return["Canonical execution verification is missing"];const o=[];if(e.binding.verificationPolicyRef!==e.expectedPolicyRef||e.canonical.verificationPolicyRef!==e.expectedPolicyRef)o.push("Execution verification policy does not match");for(const t of["executionLaneCompletion","verifierSignoff"])if(e.binding[t].ref!==e.canonical[t].ref||e.binding[t].digest!==e.canonical[t].digest)o.push(`Execution verification ${t} binding does not match`);if(e.canonical.status!=="approved")o.push("Canonical execution verification is not approved");return o}export function validateAgentDirectedAcyclicGraph(e,o){const t=[];if(e.length>o)t.push(`Graph has ${e.length} nodes; maximum is ${o}`);const r=new Set;for(const n of e){if(r.has(n.id))t.push(`Duplicate graph node id: ${n.id}`);r.add(n.id)}for(const n of e)for(const c of n.dependsOn){if(!r.has(c))t.push(`Node ${n.id} has unknown dependency: ${c}`);if(c===n.id)t.push(`Node ${n.id} cannot depend on itself`)}const a=new Set,s=new Set,p=new Map(e.map((n)=>[n.id,n])),f=(n)=>{if(a.has(n)){t.push(`Graph contains a dependency cycle at ${n}`);return}if(s.has(n))return;a.add(n);for(const c of p.get(n)?.dependsOn??[])if(p.has(c))f(c);a.delete(n);s.add(n)};for(const n of r)f(n);return[...new Set(t)]}