@odingard/guardian-sdk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/**
+ * WO-023: guardian.prerequisite.v1 — declarative prerequisites.
+ *
+ * A prerequisite is a human-authored pre-condition declared on an intent
+ * contract: it must settle — in declared order — before the action reaches
+ * the kernel (directive §13). Prerequisites are declarative inputs to the
+ * ONE authority kernel (§89, K15). No prerequisite may create, widen, or
+ * restore authority: this evaluator is pure and read-only — it can only
+ * report satisfied | pending | failed, and a failure denies with the failed
+ * rule named on the rejection evidence. Unknown or unwired types evaluate
+ * `failed` (PREREQUISITE_VERIFIER_UNAVAILABLE) and deny — fail closed.
+ */
+export declare const PREREQUISITE_CONTRACT_SCHEMA = "guardian.prerequisite.v1";
+/** Prerequisite types wired in this build. Unknown types deny (fail closed). */
+export declare const PrerequisiteTypeSchema: z.ZodEnum<{
+    merchant_verified: "merchant_verified";
+    counterparty_verified: "counterparty_verified";
+    budget_available: "budget_available";
+    capability_present: "capability_present";
+    address_authority: "address_authority";
+    human_approval: "human_approval";
+}>;
+export type PrerequisiteType = z.infer<typeof PrerequisiteTypeSchema>;
+export declare const PrerequisiteParamsSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
+export type PrerequisiteParams = z.infer<typeof PrerequisiteParamsSchema>;
+export declare const PrerequisiteSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        merchant_verified: "merchant_verified";
+        counterparty_verified: "counterparty_verified";
+        budget_available: "budget_available";
+        capability_present: "capability_present";
+        address_authority: "address_authority";
+        human_approval: "human_approval";
+    }>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
+}, z.core.$strict>;
+export type Prerequisite = z.infer<typeof PrerequisiteSchema>;
+export declare const PrerequisiteStateValueSchema: z.ZodEnum<{
+    satisfied: "satisfied";
+    pending: "pending";
+    failed: "failed";
+    not_applicable: "not_applicable";
+}>;
+export type PrerequisiteStateValue = z.infer<typeof PrerequisiteStateValueSchema>;
+export declare const PrerequisiteRuleSchema: z.ZodEnum<{
+    BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+    PENDING_HUMAN: "PENDING_HUMAN";
+    PREREQUISITE_SATISFIED: "PREREQUISITE_SATISFIED";
+    MERCHANT_UNVERIFIED: "MERCHANT_UNVERIFIED";
+    BUDGET_NOT_DECLARED: "BUDGET_NOT_DECLARED";
+    CAPABILITY_NOT_COVERED: "CAPABILITY_NOT_COVERED";
+    ADDRESS_NOT_AUTHORIZED: "ADDRESS_NOT_AUTHORIZED";
+    PREREQUISITE_PARAMS_INVALID: "PREREQUISITE_PARAMS_INVALID";
+    PREREQUISITE_VERIFIER_UNAVAILABLE: "PREREQUISITE_VERIFIER_UNAVAILABLE";
+}>;
+export type PrerequisiteRule = z.infer<typeof PrerequisiteRuleSchema>;
+export declare const PrerequisiteStateSchema: z.ZodObject<{
+    id: z.ZodString;
+    prerequisiteType: z.ZodString;
+    state: z.ZodEnum<{
+        satisfied: "satisfied";
+        pending: "pending";
+        failed: "failed";
+        not_applicable: "not_applicable";
+    }>;
+    rule: z.ZodEnum<{
+        BUDGET_EXCEEDED: "BUDGET_EXCEEDED";
+        PENDING_HUMAN: "PENDING_HUMAN";
+        PREREQUISITE_SATISFIED: "PREREQUISITE_SATISFIED";
+        MERCHANT_UNVERIFIED: "MERCHANT_UNVERIFIED";
+        BUDGET_NOT_DECLARED: "BUDGET_NOT_DECLARED";
+        CAPABILITY_NOT_COVERED: "CAPABILITY_NOT_COVERED";
+        ADDRESS_NOT_AUTHORIZED: "ADDRESS_NOT_AUTHORIZED";
+        PREREQUISITE_PARAMS_INVALID: "PREREQUISITE_PARAMS_INVALID";
+        PREREQUISITE_VERIFIER_UNAVAILABLE: "PREREQUISITE_VERIFIER_UNAVAILABLE";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PrerequisiteState = z.infer<typeof PrerequisiteStateSchema>;
+/** Read-only facts the evaluator may consult. It cannot mutate or mint. */
+export type PrerequisiteContext = Readonly<{
+    /** The action's declared counterparty (merchant) label, if any. */
+    merchantId?: string | undefined;
+    /** The action's resource ref. */
+    resource: string;
+    /** The action's declared value in cents, if any. */
+    valueCents?: number | undefined;
+    /** The action's material parameters (read-only). */
+    materialParameters?: Readonly<Record<string, unknown>> | undefined;
+    /** Counterparties declared on the enclosing intent (absent = none). */
+    intentCounterparties?: readonly string[] | undefined;
+    /** Resources declared on the enclosing intent (absent = unconstrained). */
+    intentResources?: readonly string[] | undefined;
+    /** Total issued-capability value cap declared on the intent. */
+    moneyBudgetCents?: number | undefined;
+    /** True when the narrowed authority chain still covers this action. */
+    chainCoversAction: boolean;
+}>;
+/**
+ * Pure prerequisite evaluation for one declared entry. Deterministic and
+ * read-only: the evaluator issues no authority and cannot enlarge a chain.
+ */
+export declare function evaluatePrerequisite(entry: Prerequisite, context: PrerequisiteContext): PrerequisiteState;
+export type PrerequisiteEvaluation = Readonly<{
+    /** Results recorded in declared order; evaluation halts at first failure. */
+    results: readonly PrerequisiteState[];
+    /** The first failed entry, when evaluation halted. */
+    firstFailure: PrerequisiteState | null;
+    /** True when any settled/pending entry requires human approval (ASK). */
+    forcesApproval: boolean;
+}>;
+/**
+ * Evaluate prerequisites strictly in declared order. Evaluation halts at the
+ * first failure — entries after it are never evaluated and a reevaluation
+ * only happens after all prerequisites settle (directive §13).
+ */
+export declare function evaluatePrerequisitesInOrder(prerequisites: readonly Prerequisite[], context: PrerequisiteContext): PrerequisiteEvaluation;
+/**
+ * Durable per-row shape for the obligation/prerequisite state table
+ * (packages/store-postgres `obligation_states`): one row per evaluated
+ * item, keyed by the action that carried it.
+ */
+export declare const ObligationStateRecordSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    actionRef: z.ZodString;
+    intentId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        obligation: "obligation";
+        prerequisite: "prerequisite";
+    }>;
+    obligation: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    state: z.ZodEnum<{
+        satisfied: "satisfied";
+        pending: "pending";
+        failed: "failed";
+        not_applicable: "not_applicable";
+        overdue: "overdue";
+    }>;
+    rule: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    dueEpochMs: z.ZodOptional<z.ZodNumber>;
+    completedAtEpochMs: z.ZodOptional<z.ZodNumber>;
+    createdAtEpochMs: z.ZodNumber;
+}, z.core.$strict>;
+export type ObligationStateRecord = z.infer<typeof ObligationStateRecordSchema>;

package/dist-dts/contracts/protected-data.d.ts

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { filePathWithinAllowlist } from "./files.js";
+/**
+ * WO-013 — protected data broker. The adapter injects protected values at
+ * execution time; the agent never receives reusable plaintext. The catalog
+ * below is declarative (which fields are protected, per connection /
+ * principal) — it is not a DLP or classification engine.
+ */
+export declare const PROTECTED_FIELD_REF_MAX_LENGTH = 64;
+export declare const PROTECTED_VALUE_MAX_LENGTH = 4096;
+export declare const PROTECTED_CATALOG_MAX_ENTRIES = 128;
+export declare const PROTECTED_USE_SINKS_MAX_ENTRIES = 16;
+export declare const PROTECTED_DISCLOSE_TARGETS_MAX_ENTRIES = 32;
+export declare const ProtectedFieldRefSchema: z.ZodString;
+export declare const ProtectedUseSinkSchema: z.ZodObject<{
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    pathPrefix: z.ZodString;
+}, z.core.$strict>;
+export type ProtectedUseSink = z.infer<typeof ProtectedUseSinkSchema>;
+/** A declared protected field on one connection (per principal). */
+export declare const ProtectedCatalogEntrySchema: z.ZodObject<{
+    fieldRef: z.ZodString;
+    label: z.ZodString;
+    maskedPreview: z.ZodString;
+    allowUse: z.ZodBoolean;
+    allowView: z.ZodBoolean;
+    allowPersist: z.ZodBoolean;
+    useSinks: z.ZodArray<z.ZodObject<{
+        connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+        pathPrefix: z.ZodString;
+    }, z.core.$strict>>;
+    discloseTargets: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ProtectedCatalogEntry = z.infer<typeof ProtectedCatalogEntrySchema>;
+export declare const ProtectedCatalogSchema: z.ZodArray<z.ZodObject<{
+    fieldRef: z.ZodString;
+    label: z.ZodString;
+    maskedPreview: z.ZodString;
+    allowUse: z.ZodBoolean;
+    allowView: z.ZodBoolean;
+    allowPersist: z.ZodBoolean;
+    useSinks: z.ZodArray<z.ZodObject<{
+        connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+        pathPrefix: z.ZodString;
+    }, z.core.$strict>>;
+    discloseTargets: z.ZodArray<z.ZodString>;
+}, z.core.$strict>>;
+export type ProtectedCatalog = readonly ProtectedCatalogEntry[];
+export declare const PROTECTED_USE_SCHEMA = "odingard.guardian.protected-data.use.v1";
+export declare const PROTECTED_VIEW_SCHEMA = "odingard.guardian.protected-data.view.v1";
+export declare const PROTECTED_DISCLOSE_SCHEMA = "odingard.guardian.protected-data.disclose.v1";
+export declare const PROTECTED_PERSIST_SCHEMA = "odingard.guardian.protected-data.persist.v1";
+export declare const ProtectedUseParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.use.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    fieldRef: z.ZodString;
+    sink: z.ZodObject<{
+        connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+        path: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ProtectedUseParametersV1 = z.infer<typeof ProtectedUseParametersV1Schema>;
+export declare const ProtectedViewParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.view.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    fieldRef: z.ZodString;
+}, z.core.$strict>;
+export type ProtectedViewParametersV1 = z.infer<typeof ProtectedViewParametersV1Schema>;
+export declare const ProtectedDiscloseParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.disclose.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    fieldRef: z.ZodString;
+    counterparty: z.ZodString;
+}, z.core.$strict>;
+export type ProtectedDiscloseParametersV1 = z.infer<typeof ProtectedDiscloseParametersV1Schema>;
+export declare const ProtectedPersistParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.persist.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    fieldRef: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type ProtectedPersistParametersV1 = z.infer<typeof ProtectedPersistParametersV1Schema>;
+export declare const PROTECTED_DERIVE_SCHEMA = "odingard.guardian.protected-data.derive.v1";
+export declare const PROTECTED_TRANSFORM_SCHEMA = "odingard.guardian.protected-data.transform.v1";
+export declare const PROTECTED_EXPORT_SCHEMA = "odingard.guardian.protected-data.export.v1";
+export declare const ProtectedDeriveParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.derive.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    dataObjectIds: z.ZodArray<z.core.$ZodBranded<z.ZodString, "DataObjectId", "out">>;
+    resultClassification: z.ZodOptional<z.ZodEnum<{
+        financial: "financial";
+        internal: "internal";
+        public: "public";
+        pii: "pii";
+        phi: "phi";
+        credential: "credential";
+        confidential: "confidential";
+    }>>;
+    transformation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        resultClassification: z.ZodEnum<{
+            financial: "financial";
+            internal: "internal";
+            public: "public";
+            pii: "pii";
+            phi: "phi";
+            credential: "credential";
+            confidential: "confidential";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProtectedDeriveParametersV1 = z.infer<typeof ProtectedDeriveParametersV1Schema>;
+export declare const ProtectedTransformParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.transform.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    dataObjectIds: z.ZodArray<z.core.$ZodBranded<z.ZodString, "DataObjectId", "out">>;
+    resultClassification: z.ZodOptional<z.ZodEnum<{
+        financial: "financial";
+        internal: "internal";
+        public: "public";
+        pii: "pii";
+        phi: "phi";
+        credential: "credential";
+        confidential: "confidential";
+    }>>;
+    transformation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        resultClassification: z.ZodEnum<{
+            financial: "financial";
+            internal: "internal";
+            public: "public";
+            pii: "pii";
+            phi: "phi";
+            credential: "credential";
+            confidential: "confidential";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProtectedTransformParametersV1 = z.infer<typeof ProtectedTransformParametersV1Schema>;
+export declare const ProtectedExportParametersV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"odingard.guardian.protected-data.export.v1">;
+    connectionId: z.core.$ZodBranded<z.ZodString, "ConnectionId", "out">;
+    dataObjectIds: z.ZodArray<z.core.$ZodBranded<z.ZodString, "DataObjectId", "out">>;
+    counterparty: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProtectedExportParametersV1 = z.infer<typeof ProtectedExportParametersV1Schema>;
+export declare function protectedDeriveVerificationProjection(input: ProtectedDeriveParametersV1): unknown;
+export declare function protectedTransformVerificationProjection(input: ProtectedTransformParametersV1): unknown;
+export declare function protectedExportVerificationProjection(input: ProtectedExportParametersV1): unknown;
+export declare function protectedCatalogField(catalog: readonly ProtectedCatalogEntry[] | undefined, fieldRef: string): ProtectedCatalogEntry | null;
+/** use sink is authorized only by an exact declared sink binding. */
+export declare function protectedSinkWithinUseSinks(sink: {
+    connectionId: string;
+    path: string;
+}, useSinks: readonly ProtectedUseSink[]): boolean;
+export declare function protectedUseVerificationProjection(input: ProtectedUseParametersV1): unknown;
+export declare function protectedViewVerificationProjection(input: ProtectedViewParametersV1): unknown;
+export declare function protectedDiscloseVerificationProjection(input: ProtectedDiscloseParametersV1): unknown;
+export declare function protectedPersistVerificationProjection(input: ProtectedPersistParametersV1): unknown;
+export { filePathWithinAllowlist };