martin-loop 0.1.4 → 1.3.0

package/dist/vendor/contracts/post-phase15.d.ts

@@ -0,0 +1,240 @@
+export type FuturePlanTier = "starter" | "pro" | "enterprise";
+export type FutureCapabilityId = "hosted_dashboard_basic" | "shared_team_visibility" | "cost_history" | "loop_heatmap" | "basic_routing_analytics" | "basic_exports" | "finance_board" | "engineering_board" | "failure_taxonomy_reports" | "forecasting_and_variance" | "artifact_drilldown" | "product_intelligence_consent_controls" | "advanced_routing_intelligence" | "approvals_and_policy_workflows" | "audit_exports" | "benchmark_controls" | "org_level_data_sharing_controls" | "enterprise_governance_controls";
+export type PostPhase15ToggleKey = "service_operation" | "aggregate_product_intelligence" | "benchmark_participation" | "advanced_artifact_contribution" | "model_improvement_contribution" | "support_diagnostics";
+export type PostPhase15BoardId = "finance" | "engineering" | "routing" | "failures" | "benchmarks";
+export type PostPhase15SettingsSection = "data-privacy" | "consent-history" | "eligibility";
+export type PostPhase15ViewerRole = "admin" | "workspace";
+export type PostPhase15EligibilityKey = "benchmark_eligible" | "model_improvement_eligible";
+export type PostPhase15EligibilityStatus = "eligible" | "blocked";
+export type PostPhase15DashboardExportFormat = "json" | "csv";
+export type PostPhase15CoverageStatus = "complete" | "partial" | "none";
+export type PostPhase15ConfidenceLevel = "high" | "medium" | "low" | "n/a";
+export type PostPhase15DashboardOutcomeView = "all" | "successful" | "failed";
+export type PostPhase15DashboardAccountingView = "all" | "exact" | "estimated";
+export type PostPhase15DashboardExactness = "exact_only" | "mixed" | "estimated_only" | "unavailable";
+export type PostPhase15DashboardDataState = "no_live_query_wiring" | "artifact_backed_summary" | "hardened_query_wiring" | "eligibility_blocked";
+export type PostPhase15ArtifactFreshnessStatus = "fresh" | "aging" | "stale";
+export type PostPhase15LegalDocumentId = "privacy" | "terms" | "benchmarking-disclosure" | "data-processing-addendum";
+export interface PostPhase15ToggleDefinition {
+    key: PostPhase15ToggleKey;
+    label: string;
+    defaultValue: boolean;
+    scope: "workspace" | "organization";
+    policySection: string;
+    requiresExplicitConfirmation: boolean;
+    description: string;
+}
+export interface PostPhase15ToggleState {
+    key: PostPhase15ToggleKey;
+    label: string;
+    defaultValue: boolean;
+    currentValue: boolean;
+    editable: boolean;
+    scope: "workspace" | "organization";
+    policySection: string;
+    requiresExplicitConfirmation: boolean;
+}
+export interface PostPhase15SettingsControlGroup {
+    key: "benchmarking" | "product-intelligence" | "support-diagnostics";
+    title: string;
+    description: string;
+    toggleKeys: PostPhase15ToggleKey[];
+    documentId: PostPhase15LegalDocumentId;
+}
+export interface PostPhase15PolicyLink {
+    key: "privacy_policy" | "terms" | "benchmarking_disclosure" | "data_processing_addendum";
+    label: string;
+    href: string;
+    documentId: PostPhase15LegalDocumentId;
+    sectionId: string | null;
+}
+export interface PostPhase15RetentionSummary {
+    retentionPolicyId: string;
+    defaultWindowDays: number;
+    supportDiagnosticsWindowDays: number;
+    benchmarkWindowDays: number;
+    modelImprovementWindowDays: number;
+    summary: string;
+}
+export interface PostPhase15DisabledResponse {
+    error: "Not Found";
+    feature: "post-phase15";
+    enabled: false;
+}
+export interface PostPhase15ScopedResponseFields {
+    workspaceId: string;
+    viewerRole: PostPhase15ViewerRole;
+}
+export interface PostPhase15DataPrivacyHardenedResponse extends PostPhase15ScopedResponseFields {
+    status: "hardened";
+    section: "data-privacy";
+    toggles: PostPhase15ToggleState[];
+    controlGroups: PostPhase15SettingsControlGroup[];
+    policyLinks: PostPhase15PolicyLink[];
+    retentionSummary: PostPhase15RetentionSummary;
+    provenanceRule: string;
+    exactnessRule: string;
+    persistence: "default_contract" | "persisted";
+}
+export interface PostPhase15ConsentHistoryHardenedResponse extends PostPhase15ScopedResponseFields {
+    status: "hardened";
+    section: "consent-history";
+    events: Array<{
+        eventId: string;
+        toggleKey: PostPhase15ToggleKey;
+        oldValue: boolean;
+        newValue: boolean;
+        actorId: string;
+        actorRole: PostPhase15ViewerRole;
+        effectiveAt: string;
+        consentVersion: number;
+        createdAt: string;
+    }>;
+    requiredFields: string[];
+    persistence: "default_contract" | "persisted";
+}
+export interface PostPhase15EligibilityHardenedResponse extends PostPhase15ScopedResponseFields {
+    status: "hardened";
+    section: "eligibility";
+    derivedEligibility: PostPhase15EligibilityDecision[];
+    safeDefault: "drop_unknown_rows";
+    evidenceMode: "consent_and_system_readiness";
+}
+export type PostPhase15SettingsGetResponse = PostPhase15DataPrivacyHardenedResponse | PostPhase15ConsentHistoryHardenedResponse | PostPhase15EligibilityHardenedResponse;
+export interface PostPhase15SettingsPatchResponse {
+    workspaceId: string;
+    viewerRole: PostPhase15ViewerRole;
+    status: "hardened";
+    section: PostPhase15SettingsSection;
+    persistence: "persisted" | "not_persisted";
+    applied: false;
+    updates: PostPhase15ToggleUpdate[];
+}
+export interface PostPhase15ToggleUpdate {
+    key: PostPhase15ToggleKey;
+    value: boolean;
+}
+export interface PostPhase15BoardMetric {
+    key: string;
+    label: string;
+    value: number | null;
+    unit: "usd" | "count" | "pct" | "ratio" | "seconds";
+    provenance: "actual" | "estimated" | "modeled" | "unavailable";
+    coverageStatus: PostPhase15CoverageStatus;
+    confidenceLevel: PostPhase15ConfidenceLevel;
+    source: string;
+}
+export interface PostPhase15BoardBreakdown {
+    key: string;
+    label: string;
+    value: number | null;
+    provenance: "actual" | "estimated" | "modeled" | "unavailable";
+    coverageStatus: PostPhase15CoverageStatus;
+    confidenceLevel: PostPhase15ConfidenceLevel;
+    source: string;
+}
+export interface PostPhase15EligibilityRequirement {
+    key: string;
+    label: string;
+    satisfied: boolean;
+    blocking: boolean;
+    source: "consent_setting" | "system_readiness";
+    detail: string;
+}
+export interface PostPhase15EligibilityDecision {
+    key: PostPhase15EligibilityKey;
+    status: PostPhase15EligibilityStatus;
+    summary: string;
+    requirements: PostPhase15EligibilityRequirement[];
+}
+export interface PostPhase15DashboardFilterState {
+    from: string | null;
+    to: string | null;
+    outcomeView: PostPhase15DashboardOutcomeView;
+    provider: string | null;
+    model: string | null;
+    accountingView: PostPhase15DashboardAccountingView;
+}
+export interface PostPhase15ArtifactFreshness {
+    source: "benchmark_report";
+    sourceLabel: string;
+    generatedAt: string;
+    sourceUpdatedAt: string | null;
+    ageMinutes: number;
+    staleAfterMinutes: number;
+    status: PostPhase15ArtifactFreshnessStatus;
+}
+export interface PostPhase15ArtifactEvidence {
+    kind: "event" | "violation" | "budget_metric";
+    label: string;
+    detail: string;
+    timestamp: string;
+}
+export interface PostPhase15ArtifactDrilldownItem {
+    drawerKey: string;
+    runId: string;
+    attemptIndex: number | null;
+    title: string;
+    providerId: string | null;
+    model: string | null;
+    status: string | null;
+    patchDecision: string | null;
+    failureClass: string | null;
+    actualUsd: number | null;
+    modeledAvoidedUsd: number | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    evidence: PostPhase15ArtifactEvidence[];
+}
+export interface PostPhase15RoutingRecommendation {
+    routeKey: string;
+    providerId: string | null;
+    model: string | null;
+    taskClass: string;
+    confidence: PostPhase15ConfidenceLevel;
+    summary: string;
+    reason: string;
+    routeWinRate: number | null;
+    costPerSuccessUsd: number | null;
+    medianLatencySeconds: number | null;
+}
+export interface PostPhase15DashboardSummaryHardenedResponse extends PostPhase15ScopedResponseFields {
+    status: "hardened";
+    board: PostPhase15BoardId;
+    kpiFamilies: string[];
+    provenanceRule: string;
+    dataState: PostPhase15DashboardDataState;
+    viewExactness: PostPhase15DashboardExactness;
+    exportFormats: PostPhase15DashboardExportFormat[];
+    filters: PostPhase15DashboardFilterState;
+    artifactFreshness?: PostPhase15ArtifactFreshness;
+    recommendation?: PostPhase15RoutingRecommendation;
+    statusDetail?: string;
+    metrics?: PostPhase15BoardMetric[];
+    breakdowns?: PostPhase15BoardBreakdown[];
+}
+export interface PostPhase15DashboardDrilldownResponse extends PostPhase15ScopedResponseFields {
+    status: "hardened";
+    board: PostPhase15BoardId;
+    metric: string | null;
+    filters: PostPhase15DashboardFilterState;
+    dataState: "no_live_query_wiring" | "hardened_query_wiring";
+    items: PostPhase15ArtifactDrilldownItem[];
+}
+export type PostPhase15DataPrivacyScaffoldResponse = PostPhase15DataPrivacyHardenedResponse;
+export type PostPhase15ConsentHistoryScaffoldResponse = PostPhase15ConsentHistoryHardenedResponse;
+export type PostPhase15EligibilityScaffoldResponse = PostPhase15EligibilityHardenedResponse;
+export type PostPhase15DashboardSummaryScaffoldResponse = PostPhase15DashboardSummaryHardenedResponse;
+export type PostPhase15DashboardDrilldownScaffoldResponse = PostPhase15DashboardDrilldownResponse;
+export declare const FUTURE_CAPABILITY_MAP: Readonly<Record<FuturePlanTier, readonly FutureCapabilityId[]>>;
+export declare const FUTURE_CAPABILITY_IDS: FutureCapabilityId[];
+export declare const POST_PHASE15_TOGGLE_DEFAULTS: Readonly<Record<PostPhase15ToggleKey, PostPhase15ToggleDefinition>>;
+export declare const POST_PHASE15_KPI_FAMILIES: Readonly<Record<PostPhase15BoardId, readonly string[]>>;
+export declare const POST_PHASE15_PROVENANCE_RULE = "Every post-phase-15 metric must declare whether it is artifact-backed exact, artifact-backed estimated, or unavailable.";
+export declare const POST_PHASE15_EXACTNESS_RULE = "If a value is modeled, the response must label it as estimated and cite the modeling source instead of silently blending it with exact artifact data.";
+export declare const POST_PHASE15_SETTINGS_SECTIONS: readonly PostPhase15SettingsSection[];
+export declare const POST_PHASE15_DASHBOARD_EXPORT_FORMATS: readonly PostPhase15DashboardExportFormat[];
+export declare const POST_PHASE15_DASHBOARD_OUTCOME_VIEWS: readonly PostPhase15DashboardOutcomeView[];
+export declare const POST_PHASE15_DASHBOARD_ACCOUNTING_VIEWS: readonly PostPhase15DashboardAccountingView[];
+export declare function getFuturePlanCapabilities(tier: FuturePlanTier): FutureCapabilityId[];
+export declare function futureTierIncludes(tier: FuturePlanTier, capability: FutureCapabilityId): boolean;

package/dist/vendor/contracts/post-phase15.js

@@ -0,0 +1,166 @@
+export const FUTURE_CAPABILITY_MAP = {
+    starter: [
+        "hosted_dashboard_basic",
+        "shared_team_visibility",
+        "cost_history",
+        "loop_heatmap",
+        "basic_routing_analytics",
+        "basic_exports"
+    ],
+    pro: [
+        "hosted_dashboard_basic",
+        "shared_team_visibility",
+        "cost_history",
+        "loop_heatmap",
+        "basic_routing_analytics",
+        "basic_exports",
+        "finance_board",
+        "engineering_board",
+        "failure_taxonomy_reports",
+        "forecasting_and_variance",
+        "artifact_drilldown",
+        "product_intelligence_consent_controls"
+    ],
+    enterprise: [
+        "hosted_dashboard_basic",
+        "shared_team_visibility",
+        "cost_history",
+        "loop_heatmap",
+        "basic_routing_analytics",
+        "basic_exports",
+        "finance_board",
+        "engineering_board",
+        "failure_taxonomy_reports",
+        "forecasting_and_variance",
+        "artifact_drilldown",
+        "product_intelligence_consent_controls",
+        "advanced_routing_intelligence",
+        "approvals_and_policy_workflows",
+        "audit_exports",
+        "benchmark_controls",
+        "org_level_data_sharing_controls",
+        "enterprise_governance_controls"
+    ]
+};
+export const FUTURE_CAPABILITY_IDS = Array.from(new Set(Object.values(FUTURE_CAPABILITY_MAP).flat()));
+export const POST_PHASE15_TOGGLE_DEFAULTS = {
+    service_operation: {
+        key: "service_operation",
+        label: "Service operation",
+        defaultValue: true,
+        scope: "workspace",
+        policySection: "Service Operation",
+        requiresExplicitConfirmation: false,
+        description: "Required for Martin Loop to operate the workspace safely."
+    },
+    aggregate_product_intelligence: {
+        key: "aggregate_product_intelligence",
+        label: "Aggregate product intelligence",
+        defaultValue: false,
+        scope: "organization",
+        policySection: "Aggregate Product Intelligence",
+        requiresExplicitConfirmation: true,
+        description: "Allows scrubbed aggregate learning outside the single customer boundary."
+    },
+    benchmark_participation: {
+        key: "benchmark_participation",
+        label: "Benchmark participation",
+        defaultValue: false,
+        scope: "organization",
+        policySection: "Benchmark Participation",
+        requiresExplicitConfirmation: true,
+        description: "Allows the workspace to contribute to cohort benchmark calculations."
+    },
+    advanced_artifact_contribution: {
+        key: "advanced_artifact_contribution",
+        label: "Advanced artifact contribution",
+        defaultValue: false,
+        scope: "workspace",
+        policySection: "Advanced Artifact Contribution",
+        requiresExplicitConfirmation: true,
+        description: "Allows richer derived artifacts to be used in future aggregate reporting flows."
+    },
+    model_improvement_contribution: {
+        key: "model_improvement_contribution",
+        label: "Model improvement contribution",
+        defaultValue: false,
+        scope: "organization",
+        policySection: "Model Improvement Contribution",
+        requiresExplicitConfirmation: true,
+        description: "Allows eligible data to contribute to future model-improvement programs."
+    },
+    support_diagnostics: {
+        key: "support_diagnostics",
+        label: "Support diagnostics",
+        defaultValue: false,
+        scope: "workspace",
+        policySection: "Support Diagnostics",
+        requiresExplicitConfirmation: true,
+        description: "Allows time-bounded diagnostic artifacts to be retained for support investigation."
+    }
+};
+export const POST_PHASE15_KPI_FAMILIES = {
+    finance: [
+        "spend_this_period",
+        "budget_variance",
+        "forecast_variance",
+        "protected_spend_usd",
+        "modeled_avoidance_usd"
+    ],
+    engineering: [
+        "run_count",
+        "success_rate",
+        "grounding_violation_rate",
+        "rollback_success_rate",
+        "time_to_verified_outcome"
+    ],
+    routing: [
+        "route_mix",
+        "policy_override_rate",
+        "latency_p95",
+        "routing_efficiency_score",
+        "fallback_rate"
+    ],
+    failures: [
+        "failure_cost_usd",
+        "retry_waste_score",
+        "attempts_before_exit",
+        "protected_spend_usd",
+        "failure_family_rate"
+    ],
+    benchmarks: [
+        "spend_efficiency_score",
+        "retry_waste_score",
+        "rollback_success_score",
+        "routing_efficiency_score",
+        "cohort_comparability_score"
+    ]
+};
+export const POST_PHASE15_PROVENANCE_RULE = "Every post-phase-15 metric must declare whether it is artifact-backed exact, artifact-backed estimated, or unavailable.";
+export const POST_PHASE15_EXACTNESS_RULE = "If a value is modeled, the response must label it as estimated and cite the modeling source instead of silently blending it with exact artifact data.";
+export const POST_PHASE15_SETTINGS_SECTIONS = [
+    "data-privacy",
+    "consent-history",
+    "eligibility"
+];
+export const POST_PHASE15_DASHBOARD_EXPORT_FORMATS = [
+    "json",
+    "csv"
+];
+export const POST_PHASE15_DASHBOARD_OUTCOME_VIEWS = [
+    "all",
+    "successful",
+    "failed"
+];
+export const POST_PHASE15_DASHBOARD_ACCOUNTING_VIEWS = [
+    "all",
+    "exact",
+    "estimated"
+];
+export function getFuturePlanCapabilities(tier) {
+    return [...FUTURE_CAPABILITY_MAP[tier]];
+}
+export function futureTierIncludes(tier, capability) {
+    return FUTURE_CAPABILITY_MAP[tier].includes(capability);
+}
+//# sourceMappingURL=post-phase15.js.map

package/dist/vendor/core/agent/mandates.d.ts

@@ -0,0 +1,46 @@
+import { type AgentEd25519Signature, type AgentSigningOptions } from "./signing.js";
+export interface AgentMandatePayload {
+    mandateId: string;
+    quoteId: string;
+    workspaceId: string;
+    agentPrincipalId: string;
+    repoAuthorityHash: string;
+    maxUsd: number;
+    maxIterations: number;
+    approvedBy: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export type AgentMandateSignature = AgentEd25519Signature;
+export type SignedAgentMandate = AgentMandatePayload & {
+    signature: AgentMandateSignature;
+};
+export type AgentMandateSignOptions = AgentSigningOptions;
+export interface AgentMandateVerifyOptions {
+    expectedQuoteId?: string;
+    expectedWorkspaceId?: string;
+    expectedAgentPrincipalId?: string;
+    expectedRepoAuthorityHash?: string;
+    expectedSignerKeyId?: string;
+    expectedSignerPublicKeyPem?: string;
+    trustedSignerKeyIds?: string[];
+    trustedSignerPublicKeys?: string[];
+    requestedUsd?: number;
+    requestedIterations?: number;
+    now?: string;
+}
+export interface AgentMandateVerificationResult {
+    verified: boolean;
+    mandateId: string | null;
+    quoteId: string | null;
+    workspaceId: string | null;
+    agentPrincipalId: string | null;
+    repoAuthorityHash: string | null;
+    maxUsd: number | null;
+    maxIterations: number | null;
+    expiresAt: string | null;
+    keyId?: string;
+    reasons: string[];
+}
+export declare function signAgentMandate(payload: AgentMandatePayload, options?: AgentMandateSignOptions): Promise<SignedAgentMandate>;
+export declare function verifyAgentMandate(mandate: unknown, options?: AgentMandateVerifyOptions): AgentMandateVerificationResult;

package/dist/vendor/core/agent/mandates.js

@@ -0,0 +1,178 @@
+import { agentKeyId, readAgentEd25519Signature, signCanonicalAgentPayload, verifyCanonicalAgentPayload } from "./signing.js";
+const MANDATE_KEY_NAMESPACE = "agent-mandates";
+export async function signAgentMandate(payload, options = {}) {
+    return {
+        ...payload,
+        signature: await signCanonicalAgentPayload(payload, MANDATE_KEY_NAMESPACE, options)
+    };
+}
+export function verifyAgentMandate(mandate, options = {}) {
+    const reasons = [];
+    if (!mandate || typeof mandate !== "object" || Array.isArray(mandate)) {
+        return {
+            verified: false,
+            mandateId: null,
+            quoteId: null,
+            workspaceId: null,
+            agentPrincipalId: null,
+            repoAuthorityHash: null,
+            maxUsd: null,
+            maxIterations: null,
+            expiresAt: null,
+            reasons: ["Agent mandate must be an object."]
+        };
+    }
+    const record = mandate;
+    const mandateId = readString(record.mandateId);
+    const quoteId = readString(record.quoteId);
+    const workspaceId = readString(record.workspaceId);
+    const agentPrincipalId = readString(record.agentPrincipalId);
+    const repoAuthorityHash = readString(record.repoAuthorityHash);
+    const maxUsd = readPositiveNumber(record.maxUsd);
+    const maxIterations = readPositiveInteger(record.maxIterations);
+    const approvedBy = readString(record.approvedBy);
+    const issuedAt = readString(record.issuedAt);
+    const expiresAt = readString(record.expiresAt);
+    const signature = readAgentEd25519Signature(record.signature);
+    if (!mandateId)
+        reasons.push("Agent mandate id is missing.");
+    if (!quoteId)
+        reasons.push("Agent mandate quote id is missing.");
+    if (!workspaceId)
+        reasons.push("Agent mandate workspace id is missing.");
+    if (!agentPrincipalId)
+        reasons.push("Agent mandate principal id is missing.");
+    if (!repoAuthorityHash)
+        reasons.push("Agent mandate repo authority hash is missing.");
+    if (maxUsd === null)
+        reasons.push("Agent mandate spend cap is missing.");
+    if (maxIterations === null)
+        reasons.push("Agent mandate iteration cap is missing.");
+    if (!approvedBy)
+        reasons.push("Agent mandate approver is missing.");
+    if (!issuedAt)
+        reasons.push("Agent mandate issued timestamp is missing.");
+    if (!expiresAt)
+        reasons.push("Agent mandate expiry is missing.");
+    if (!signature)
+        reasons.push("Agent mandate signature is missing.");
+    const timeWindow = validateMandateTimeWindow(issuedAt, expiresAt, options.now);
+    reasons.push(...timeWindow.reasons);
+    if (options.expectedQuoteId && quoteId && quoteId !== options.expectedQuoteId) {
+        reasons.push("Agent mandate quote binding does not match.");
+    }
+    if (options.expectedWorkspaceId && workspaceId && workspaceId !== options.expectedWorkspaceId) {
+        reasons.push("Agent mandate workspace binding does not match.");
+    }
+    if (options.expectedAgentPrincipalId &&
+        agentPrincipalId &&
+        agentPrincipalId !== options.expectedAgentPrincipalId) {
+        reasons.push("Agent mandate principal binding does not match.");
+    }
+    if (options.expectedRepoAuthorityHash &&
+        repoAuthorityHash &&
+        repoAuthorityHash !== options.expectedRepoAuthorityHash) {
+        reasons.push("Agent mandate repo authority binding does not match.");
+    }
+    if (options.requestedUsd !== undefined && maxUsd !== null && options.requestedUsd > maxUsd) {
+        reasons.push("Requested spend exceeds mandate cap.");
+    }
+    if (options.requestedIterations !== undefined &&
+        maxIterations !== null &&
+        options.requestedIterations > maxIterations) {
+        reasons.push("Requested iterations exceed mandate cap.");
+    }
+    if (signature) {
+        const expectedKeyId = agentKeyId(signature.publicKeyPem);
+        if (signature.keyId !== expectedKeyId) {
+            reasons.push("Agent mandate key id does not match public key.");
+        }
+        if (!isTrustedSigner(signature, options)) {
+            reasons.push("Agent mandate signer is untrusted.");
+        }
+        const payload = { ...record };
+        delete payload.signature;
+        try {
+            if (!verifyCanonicalAgentPayload(payload, signature)) {
+                reasons.push("Agent mandate signature verification failed.");
+            }
+        }
+        catch {
+            reasons.push("Agent mandate signature verification failed.");
+        }
+    }
+    return {
+        verified: reasons.length === 0,
+        mandateId,
+        quoteId,
+        workspaceId,
+        agentPrincipalId,
+        repoAuthorityHash,
+        maxUsd,
+        maxIterations,
+        expiresAt,
+        ...(signature ? { keyId: signature.keyId } : {}),
+        reasons
+    };
+}
+function validateMandateTimeWindow(issuedAt, expiresAt, now) {
+    const reasons = [];
+    const issuedMs = parseTimestamp(issuedAt);
+    const expiresMs = parseTimestamp(expiresAt);
+    const nowMs = parseTimestamp(now ?? new Date().toISOString());
+    if (issuedAt && issuedMs === null) {
+        reasons.push("Agent mandate issued timestamp is invalid.");
+    }
+    if (expiresAt && expiresMs === null) {
+        reasons.push("Agent mandate expiry is invalid.");
+    }
+    if (now !== undefined && nowMs === null) {
+        reasons.push("Verification clock is invalid.");
+    }
+    if (issuedMs !== null && expiresMs !== null && issuedMs > expiresMs) {
+        reasons.push("Agent mandate issued timestamp is after expiry.");
+    }
+    if (issuedMs !== null && nowMs !== null && nowMs < issuedMs) {
+        reasons.push("Agent mandate is not yet valid.");
+    }
+    if (expiresMs !== null && nowMs !== null && nowMs > expiresMs) {
+        reasons.push("Agent mandate is expired.");
+    }
+    return { reasons };
+}
+function isTrustedSigner(signature, options) {
+    if (options.expectedSignerPublicKeyPem &&
+        normalizePem(signature.publicKeyPem) === normalizePem(options.expectedSignerPublicKeyPem)) {
+        return true;
+    }
+    if (options.expectedSignerKeyId) {
+        return signature.keyId === options.expectedSignerKeyId;
+    }
+    if (options.trustedSignerPublicKeys?.some((key) => normalizePem(key) === normalizePem(signature.publicKeyPem))) {
+        return true;
+    }
+    if (options.trustedSignerKeyIds?.includes(signature.keyId)) {
+        return true;
+    }
+    return false;
+}
+function normalizePem(value) {
+    return value.replace(/\r\n/g, "\n").trim();
+}
+function parseTimestamp(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function readPositiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+function readPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+//# sourceMappingURL=mandates.js.map

package/dist/vendor/core/agent/receipts.d.ts

@@ -0,0 +1,38 @@
+import { type AgentEd25519Signature, type AgentSigningOptions } from "./signing.js";
+export interface AgentReceiptPayload {
+    receiptId: string;
+    runId: string;
+    quoteId: string;
+    mandateId: string;
+    status: "completed" | "failed" | "denied" | "expired";
+    ledgerHash: string;
+    createdAt: string;
+    actualUsd?: number;
+    attempts?: number;
+}
+export type AgentReceiptSignature = AgentEd25519Signature;
+export type SignedAgentReceipt = AgentReceiptPayload & {
+    signature: AgentReceiptSignature;
+};
+export interface AgentReceiptVerificationResult {
+    verified: boolean;
+    receiptId: string | null;
+    runId: string | null;
+    ledgerHash: string | null;
+    keyId?: string;
+    reasons: string[];
+}
+export type AgentReceiptSignOptions = AgentSigningOptions;
+export interface AgentReceiptVerifyOptions {
+    expectedLedgerHash?: string;
+    expectedRunId?: string;
+    expectedQuoteId?: string;
+    expectedMandateId?: string;
+    expectedStatus?: AgentReceiptPayload["status"];
+    expectedSignerKeyId?: string;
+    expectedSignerPublicKeyPem?: string;
+    trustedSignerKeyIds?: string[];
+    trustedSignerPublicKeys?: string[];
+}
+export declare function signAgentReceipt(payload: AgentReceiptPayload, options?: AgentReceiptSignOptions): Promise<SignedAgentReceipt>;
+export declare function verifyAgentReceipt(receipt: unknown, options?: AgentReceiptVerifyOptions): AgentReceiptVerificationResult;