@aletheia-labs/core 0.1.0

package/dist/types/conflict.js

@@ -0,0 +1,47 @@
+/**
+ * ConflictRecord — first-class contradictions.
+ * Source: specs/aletheia-memory-authority-v0.md §6 "Conflict Registry".
+ *
+ * Rule: contradictions are NEVER overwritten by summaries. They remain
+ * queryable until explicitly resolved (or superseded by a later restrictive
+ * event).
+ */
+import { z } from 'zod';
+import { FreshnessSchema, ScopeSchema } from './enums.js';
+import { ConflictIdSchema, IsoTimestampSchema, MemoryIdSchema } from './primitives.js';
+export const ConflictStatusSchema = z.enum([
+    'unresolved',
+    'resolved',
+    'superseded',
+    'requires_human',
+]);
+export const ConflictDecisionPolicySchema = z.enum([
+    'surface_conflict',
+    'prefer_latest_authoritative',
+    'ask_human',
+    'abstain',
+]);
+/**
+ * One side of a conflict: which memory makes what claim, with what authority.
+ */
+export const ConflictClaimSchema = z.object({
+    memoryId: MemoryIdSchema,
+    /** The value the claim asserts (string serialization of any type). */
+    value: z.string(),
+    /** Authority score of this claim at the time the conflict was recorded. */
+    authority: z.number().min(0).max(1),
+    freshness: FreshnessSchema,
+});
+export const ConflictRecordSchema = z.object({
+    conflictId: ConflictIdSchema,
+    /** Topic of the conflict — what the claims disagree about. */
+    topic: z.string().min(1).max(1024),
+    scope: ScopeSchema,
+    /** All claims in conflict (typically 2, sometimes more). */
+    claims: z.array(ConflictClaimSchema).min(2),
+    status: ConflictStatusSchema,
+    decisionPolicy: ConflictDecisionPolicySchema,
+    recordedAt: IsoTimestampSchema,
+    resolvedAt: IsoTimestampSchema.nullable(),
+});
+//# sourceMappingURL=conflict.js.map

package/dist/types/conflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.js","sourceRoot":"","sources":["../../src/types/conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEvF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC;IACzC,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,gBAAgB;CACjB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IACjD,kBAAkB;IAClB,6BAA6B;IAC7B,WAAW;IACX,SAAS;CACV,CAAC,CAAC;AAGH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,QAAQ,EAAE,cAAc;IACxB,sEAAsE;IACtE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,2EAA2E;IAC3E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,SAAS,EAAE,eAAe;CAC3B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,UAAU,EAAE,gBAAgB;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAClC,KAAK,EAAE,WAAW;IAClB,4DAA4D;IAC5D,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,EAAE,oBAAoB;IAC5B,cAAc,EAAE,4BAA4B;IAC5C,UAAU,EAAE,kBAAkB;IAC9B,UAAU,EAAE,kBAAkB,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}

package/dist/types/coverage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Coverage receipt (specs/memory-authority-receipt-v0.md — "Receipt classes").
+ *
+ * Tells a receiver which high-boundary claims should have been retrieved and
+ * which are missing. Missing high-boundary digests are absence-of-retrieval,
+ * not permission to ignore them.
+ */
+import { z } from 'zod';
+export declare const CoverageDecisionSchema: z.ZodEnum<["complete", "partial", "critical_gap", "absent"]>;
+export type CoverageDecision = z.infer<typeof CoverageDecisionSchema>;
+export declare const CoverageReceiptSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    /** Number of high-boundary/must-surface claims in this scope. */
+    highBoundaryTotal: z.ZodNumber;
+    /** Number of high-boundary claims actually retrieved in this packet. */
+    retrievedHighBoundary: z.ZodNumber;
+    /** Digests of high-boundary claims that should have been retrieved but weren't. */
+    missingHighBoundaryDigests: z.ZodArray<z.ZodString, "many">;
+    /** Receiver-side decision based on the above. */
+    coverageDecision: z.ZodEnum<["complete", "partial", "critical_gap", "absent"]>;
+}, "strip", z.ZodTypeAny, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}>, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}>, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}, {
+    highBoundaryTotal: number;
+    retrievedHighBoundary: number;
+    missingHighBoundaryDigests: string[];
+    coverageDecision: "partial" | "complete" | "critical_gap" | "absent";
+}>;
+export type CoverageReceipt = z.infer<typeof CoverageReceiptSchema>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/types/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/types/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,sBAAsB,8DAA4D,CAAC;AAChG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,qBAAqB;IAE9B,iEAAiE;;IAEjE,wEAAwE;;IAExE,mFAAmF;;IAEnF,iDAAiD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAalD,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/types/coverage.js

@@ -0,0 +1,30 @@
+/**
+ * Coverage receipt (specs/memory-authority-receipt-v0.md — "Receipt classes").
+ *
+ * Tells a receiver which high-boundary claims should have been retrieved and
+ * which are missing. Missing high-boundary digests are absence-of-retrieval,
+ * not permission to ignore them.
+ */
+import { z } from 'zod';
+import { HashDigestSchema } from './primitives.js';
+export const CoverageDecisionSchema = z.enum(['complete', 'partial', 'critical_gap', 'absent']);
+export const CoverageReceiptSchema = z
+    .object({
+    /** Number of high-boundary/must-surface claims in this scope. */
+    highBoundaryTotal: z.number().int().nonnegative(),
+    /** Number of high-boundary claims actually retrieved in this packet. */
+    retrievedHighBoundary: z.number().int().nonnegative(),
+    /** Digests of high-boundary claims that should have been retrieved but weren't. */
+    missingHighBoundaryDigests: z.array(HashDigestSchema),
+    /** Receiver-side decision based on the above. */
+    coverageDecision: CoverageDecisionSchema,
+})
+    .refine((c) => c.retrievedHighBoundary <= c.highBoundaryTotal, {
+    message: 'retrievedHighBoundary cannot exceed highBoundaryTotal',
+    path: ['retrievedHighBoundary'],
+})
+    .refine((c) => c.missingHighBoundaryDigests.length === c.highBoundaryTotal - c.retrievedHighBoundary, {
+    message: 'missingHighBoundaryDigests count must equal (total - retrieved)',
+    path: ['missingHighBoundaryDigests'],
+});
+//# sourceMappingURL=coverage.js.map

package/dist/types/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/types/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGhG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,iEAAiE;IACjE,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACjD,wEAAwE;IACxE,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrD,mFAAmF;IACnF,0BAA0B,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IACrD,iDAAiD;IACjD,gBAAgB,EAAE,sBAAsB;CACzC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,qBAAqB,IAAI,CAAC,CAAC,iBAAiB,EAAE;IAC7D,OAAO,EAAE,uDAAuD;IAChE,IAAI,EAAE,CAAC,uBAAuB,CAAC;CAChC,CAAC;KACD,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,0BAA0B,CAAC,MAAM,KAAK,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,qBAAqB,EAC5F;IACE,OAAO,EAAE,iEAAiE;IAC1E,IAAI,EAAE,CAAC,4BAA4B,CAAC;CACrC,CACF,CAAC"}

package/dist/types/decision.d.ts

@@ -0,0 +1,345 @@
+/**
+ * Decision types emitted by the WriteGate, RetrievalRouter, and tryAct().
+ *
+ * Every decision carries: an outcome verb, a structured reason, and the
+ * evidence that supports it. Decisions are values, not exceptions —
+ * fail-closed never throws, it returns a structured refusal.
+ */
+import { z } from 'zod';
+export declare const DecisionOutcomeSchema: z.ZodEnum<["allow_local_shadow", "fetch_abstain", "ask_human", "block_local", "conflict_boundary_packet", "deny"]>;
+export type DecisionOutcome = z.infer<typeof DecisionOutcomeSchema>;
+/**
+ * Why the gate/router/tryAct produced a particular outcome. Discriminated
+ * union — every variant has the data needed to debug the decision.
+ */
+export declare const DecisionReasonSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"source_check_failed">;
+    detail: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "source_check_failed";
+    detail: string;
+}, {
+    kind: "source_check_failed";
+    detail: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"freshness_not_current">;
+    observed: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "freshness_not_current";
+    observed: string;
+}, {
+    kind: "freshness_not_current";
+    observed: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"scope_outside_boundary">;
+    requestedScope: z.ZodString;
+    allowedScope: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "scope_outside_boundary";
+    requestedScope: string;
+    allowedScope: string;
+}, {
+    kind: "scope_outside_boundary";
+    requestedScope: string;
+    allowedScope: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"promotion_boundary_blocked">;
+    detail: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "promotion_boundary_blocked";
+    detail: string;
+}, {
+    kind: "promotion_boundary_blocked";
+    detail: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"forbidden_effect_present">;
+    effect: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "forbidden_effect_present";
+    effect: string;
+}, {
+    kind: "forbidden_effect_present";
+    effect: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"later_restrictive_event">;
+    event: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "later_restrictive_event";
+    event: string;
+}, {
+    kind: "later_restrictive_event";
+    event: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"tuple_incomplete">;
+    missingFields: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    kind: "tuple_incomplete";
+    missingFields: string[];
+}, {
+    kind: "tuple_incomplete";
+    missingFields: string[];
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"sensitive_action">;
+    actionClass: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "sensitive_action";
+    actionClass: string;
+}, {
+    kind: "sensitive_action";
+    actionClass: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown_action">;
+    raw: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "unknown_action";
+    raw: string;
+}, {
+    kind: "unknown_action";
+    raw: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"unresolved_conflict">;
+    conflictId: z.ZodBranded<z.ZodString, "ConflictId">;
+}, "strip", z.ZodTypeAny, {
+    kind: "unresolved_conflict";
+    conflictId: string & z.BRAND<"ConflictId">;
+}, {
+    kind: "unresolved_conflict";
+    conflictId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"visibility_denied">;
+    detail: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "visibility_denied";
+    detail: string;
+}, {
+    kind: "visibility_denied";
+    detail: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"all_checks_passed">;
+    /** The atoms the action was authorized against. */
+    citedMemoryIds: z.ZodArray<z.ZodBranded<z.ZodString, "MemoryId">, "many">;
+}, "strip", z.ZodTypeAny, {
+    kind: "all_checks_passed";
+    citedMemoryIds: (string & z.BRAND<"MemoryId">)[];
+}, {
+    kind: "all_checks_passed";
+    citedMemoryIds: string[];
+}>]>;
+export type DecisionReason = z.infer<typeof DecisionReasonSchema>;
+export declare const DecisionSchema: z.ZodObject<{
+    outcome: z.ZodEnum<["allow_local_shadow", "fetch_abstain", "ask_human", "block_local", "conflict_boundary_packet", "deny"]>;
+    /** Why this outcome was chosen. Multiple reasons can stack. */
+    reasons: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"source_check_failed">;
+        detail: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "source_check_failed";
+        detail: string;
+    }, {
+        kind: "source_check_failed";
+        detail: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"freshness_not_current">;
+        observed: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "freshness_not_current";
+        observed: string;
+    }, {
+        kind: "freshness_not_current";
+        observed: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"scope_outside_boundary">;
+        requestedScope: z.ZodString;
+        allowedScope: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "scope_outside_boundary";
+        requestedScope: string;
+        allowedScope: string;
+    }, {
+        kind: "scope_outside_boundary";
+        requestedScope: string;
+        allowedScope: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"promotion_boundary_blocked">;
+        detail: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "promotion_boundary_blocked";
+        detail: string;
+    }, {
+        kind: "promotion_boundary_blocked";
+        detail: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"forbidden_effect_present">;
+        effect: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "forbidden_effect_present";
+        effect: string;
+    }, {
+        kind: "forbidden_effect_present";
+        effect: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"later_restrictive_event">;
+        event: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "later_restrictive_event";
+        event: string;
+    }, {
+        kind: "later_restrictive_event";
+        event: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"tuple_incomplete">;
+        missingFields: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "tuple_incomplete";
+        missingFields: string[];
+    }, {
+        kind: "tuple_incomplete";
+        missingFields: string[];
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"sensitive_action">;
+        actionClass: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "sensitive_action";
+        actionClass: string;
+    }, {
+        kind: "sensitive_action";
+        actionClass: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"unknown_action">;
+        raw: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "unknown_action";
+        raw: string;
+    }, {
+        kind: "unknown_action";
+        raw: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"unresolved_conflict">;
+        conflictId: z.ZodBranded<z.ZodString, "ConflictId">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "unresolved_conflict";
+        conflictId: string & z.BRAND<"ConflictId">;
+    }, {
+        kind: "unresolved_conflict";
+        conflictId: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"visibility_denied">;
+        detail: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "visibility_denied";
+        detail: string;
+    }, {
+        kind: "visibility_denied";
+        detail: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"all_checks_passed">;
+        /** The atoms the action was authorized against. */
+        citedMemoryIds: z.ZodArray<z.ZodBranded<z.ZodString, "MemoryId">, "many">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "all_checks_passed";
+        citedMemoryIds: (string & z.BRAND<"MemoryId">)[];
+    }, {
+        kind: "all_checks_passed";
+        citedMemoryIds: string[];
+    }>]>, "many">;
+    /** Atoms the decision references (cited, conflicted, etc.). */
+    relatedMemoryIds: z.ZodArray<z.ZodBranded<z.ZodString, "MemoryId">, "many">;
+    /** Conflicts the decision references. */
+    relatedConflictIds: z.ZodArray<z.ZodBranded<z.ZodString, "ConflictId">, "many">;
+    /** When the decision was emitted. */
+    emittedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    outcome: "ask_human" | "allow_local_shadow" | "fetch_abstain" | "block_local" | "conflict_boundary_packet" | "deny";
+    reasons: ({
+        kind: "source_check_failed";
+        detail: string;
+    } | {
+        kind: "freshness_not_current";
+        observed: string;
+    } | {
+        kind: "scope_outside_boundary";
+        requestedScope: string;
+        allowedScope: string;
+    } | {
+        kind: "promotion_boundary_blocked";
+        detail: string;
+    } | {
+        kind: "forbidden_effect_present";
+        effect: string;
+    } | {
+        kind: "later_restrictive_event";
+        event: string;
+    } | {
+        kind: "tuple_incomplete";
+        missingFields: string[];
+    } | {
+        kind: "sensitive_action";
+        actionClass: string;
+    } | {
+        kind: "unknown_action";
+        raw: string;
+    } | {
+        kind: "unresolved_conflict";
+        conflictId: string & z.BRAND<"ConflictId">;
+    } | {
+        kind: "visibility_denied";
+        detail: string;
+    } | {
+        kind: "all_checks_passed";
+        citedMemoryIds: (string & z.BRAND<"MemoryId">)[];
+    })[];
+    relatedMemoryIds: (string & z.BRAND<"MemoryId">)[];
+    relatedConflictIds: (string & z.BRAND<"ConflictId">)[];
+    emittedAt: string;
+}, {
+    outcome: "ask_human" | "allow_local_shadow" | "fetch_abstain" | "block_local" | "conflict_boundary_packet" | "deny";
+    reasons: ({
+        kind: "source_check_failed";
+        detail: string;
+    } | {
+        kind: "freshness_not_current";
+        observed: string;
+    } | {
+        kind: "scope_outside_boundary";
+        requestedScope: string;
+        allowedScope: string;
+    } | {
+        kind: "promotion_boundary_blocked";
+        detail: string;
+    } | {
+        kind: "forbidden_effect_present";
+        effect: string;
+    } | {
+        kind: "later_restrictive_event";
+        event: string;
+    } | {
+        kind: "tuple_incomplete";
+        missingFields: string[];
+    } | {
+        kind: "sensitive_action";
+        actionClass: string;
+    } | {
+        kind: "unknown_action";
+        raw: string;
+    } | {
+        kind: "unresolved_conflict";
+        conflictId: string;
+    } | {
+        kind: "visibility_denied";
+        detail: string;
+    } | {
+        kind: "all_checks_passed";
+        citedMemoryIds: string[];
+    })[];
+    relatedMemoryIds: string[];
+    relatedConflictIds: string[];
+    emittedAt: string;
+}>;
+export type Decision = z.infer<typeof DecisionSchema>;
+/** Decision returned by `WriteGate.evaluate(proposal)`. */
+export type WriteGateDecision = Decision;
+/** Decision returned by `RetrievalRouter.recall(query)`. */
+export type RetrievalDecision = Decision;
+/** Decision returned by `tryAct(action, ctx)`. */
+export type ActionDecision = Decision;
+//# sourceMappingURL=decision.d.ts.map

package/dist/types/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/types/decision.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,qBAAqB,oHAOhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAgD7B,mDAAmD;;;;;;;;IAGrD,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,eAAO,MAAM,cAAc;;IAEzB,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAV7D,mDAAmD;;;;;;;;;IAYrD,+DAA+D;;IAE/D,yCAAyC;;IAEzC,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAErC,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAItD,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AACzC,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AACzC,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC"}

package/dist/types/decision.js

@@ -0,0 +1,88 @@
+/**
+ * Decision types emitted by the WriteGate, RetrievalRouter, and tryAct().
+ *
+ * Every decision carries: an outcome verb, a structured reason, and the
+ * evidence that supports it. Decisions are values, not exceptions —
+ * fail-closed never throws, it returns a structured refusal.
+ */
+import { z } from 'zod';
+import { ConflictIdSchema, MemoryIdSchema } from './primitives.js';
+// -- Decision outcomes (spec §"Retrieval Router outputs", "Receiver decision") -
+export const DecisionOutcomeSchema = z.enum([
+    'allow_local_shadow',
+    'fetch_abstain',
+    'ask_human',
+    'block_local',
+    'conflict_boundary_packet',
+    'deny',
+]);
+// -- Structured reasons -------------------------------------------------------
+/**
+ * Why the gate/router/tryAct produced a particular outcome. Discriminated
+ * union — every variant has the data needed to debug the decision.
+ */
+export const DecisionReasonSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('source_check_failed'),
+        detail: z.string().min(1).max(1024),
+    }),
+    z.object({
+        kind: z.literal('freshness_not_current'),
+        observed: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('scope_outside_boundary'),
+        requestedScope: z.string().min(1),
+        allowedScope: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('promotion_boundary_blocked'),
+        detail: z.string().min(1).max(1024),
+    }),
+    z.object({
+        kind: z.literal('forbidden_effect_present'),
+        effect: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('later_restrictive_event'),
+        event: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('tuple_incomplete'),
+        missingFields: z.array(z.string()).min(1),
+    }),
+    z.object({
+        kind: z.literal('sensitive_action'),
+        actionClass: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('unknown_action'),
+        raw: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('unresolved_conflict'),
+        conflictId: ConflictIdSchema,
+    }),
+    z.object({
+        kind: z.literal('visibility_denied'),
+        detail: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('all_checks_passed'),
+        /** The atoms the action was authorized against. */
+        citedMemoryIds: z.array(MemoryIdSchema),
+    }),
+]);
+// -- The decision envelope ----------------------------------------------------
+export const DecisionSchema = z.object({
+    outcome: DecisionOutcomeSchema,
+    /** Why this outcome was chosen. Multiple reasons can stack. */
+    reasons: z.array(DecisionReasonSchema).min(1),
+    /** Atoms the decision references (cited, conflicted, etc.). */
+    relatedMemoryIds: z.array(MemoryIdSchema),
+    /** Conflicts the decision references. */
+    relatedConflictIds: z.array(ConflictIdSchema),
+    /** When the decision was emitted. */
+    emittedAt: z.string().datetime({ offset: false }),
+});
+//# sourceMappingURL=decision.js.map

package/dist/types/decision.js.map

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