@aletheia-labs/core 0.1.0

package/dist/runtime/retrieval-router.js

@@ -0,0 +1,223 @@
+/**
+ * RetrievalRouter — authority-first recall.
+ *
+ * This is deliberately not semantic search. Routing order is permission,
+ * status/scope/type, conflict state, then optional host-provided exact topic
+ * matching. Without a topic matcher, topic queries fail closed.
+ */
+import { RecallQuerySchema } from '../types/index.js';
+import { SYSTEM_CLOCK, decision } from './decision-helpers.js';
+import { DENY_ALL_VISIBILITY_POLICY } from './visibility-policy.js';
+const DEFAULT_RECALL_STATUSES = ['verified', 'trusted'];
+export class RetrievalRouter {
+    options;
+    visibilityPolicy;
+    clock;
+    /**
+     * Create an authority-first recall router.
+     *
+     * @remarks
+     * The optional topic matcher is an exact host-provided predicate, not an
+     * embedding or semantic ranking hook. If a topic query is supplied without a
+     * matcher, recall fails closed.
+     */
+    constructor(options) {
+        this.options = options;
+        this.visibilityPolicy = options.visibilityPolicy ?? DENY_ALL_VISIBILITY_POLICY;
+        this.clock = options.clock ?? SYSTEM_CLOCK;
+    }
+    /**
+     * Recall atoms that are visible, in scope, currently valid, and actionable.
+     *
+     * @remarks
+     * Implementation order is permission before semantics: caller visibility is
+     * resolved first, then the store query applies scope/status/freshness, then
+     * optional type/topic filtering, then conflict checks. The returned decision
+     * must be inspected before passing atoms to a model.
+     */
+    async recall(query) {
+        const emittedAt = this.clock.now();
+        const queryResult = RecallQuerySchema.safeParse(query);
+        if (!queryResult.success) {
+            return {
+                decision: decision('fetch_abstain', [
+                    {
+                        kind: 'tuple_incomplete',
+                        missingFields: schemaIssuePaths(queryResult.error.issues, 'query'),
+                    },
+                ], [], [], emittedAt),
+                atoms: [],
+                conflicts: [],
+            };
+        }
+        const validQuery = queryResult.data;
+        const permitted = this.visibilityPolicy.permittedVisibilitiesForAgent(validQuery.agentId);
+        if (permitted.length === 0) {
+            return {
+                decision: decision('fetch_abstain', [
+                    {
+                        kind: 'visibility_denied',
+                        detail: 'caller has no permitted visibility planes',
+                    },
+                ], [], [], emittedAt),
+                atoms: [],
+                conflicts: [],
+            };
+        }
+        if (validQuery.topic !== undefined && this.options.topicMatcher === undefined) {
+            return {
+                decision: decision('fetch_abstain', [{ kind: 'tuple_incomplete', missingFields: ['topicIndex'] }], [], [], emittedAt),
+                atoms: [],
+                conflicts: [],
+            };
+        }
+        const loadedAtoms = await this.loadAtoms(validQuery, permitted, emittedAt);
+        if (!loadedAtoms.ok) {
+            return {
+                decision: decision('fetch_abstain', [loadedAtoms.reason], [], [], emittedAt),
+                atoms: [],
+                conflicts: [],
+            };
+        }
+        const atoms = loadedAtoms.atoms;
+        if (atoms.length === 0) {
+            return {
+                decision: decision('fetch_abstain', [{ kind: 'tuple_incomplete', missingFields: ['memoryAtoms'] }], [], [], emittedAt),
+                atoms: [],
+                conflicts: [],
+            };
+        }
+        const nonActionableReason = firstNonActionableReason(atoms);
+        if (nonActionableReason !== null) {
+            return {
+                decision: decision(nonActionableReason.outcome, [nonActionableReason.reason], atoms.map((atom) => atom.memoryId), [], emittedAt),
+                atoms,
+                conflicts: [],
+            };
+        }
+        const memoryIds = atoms.map((atom) => atom.memoryId);
+        const conflicts = await this.options.conflictRegistry.query({
+            touchingMemoryIds: memoryIds,
+            statuses: ['unresolved', 'requires_human'],
+            scope: validQuery.scope,
+            permittedVisibilities: permitted,
+        });
+        if (conflicts.length > 0) {
+            return {
+                decision: decision('conflict_boundary_packet', conflicts.map((conflict) => ({
+                    kind: 'unresolved_conflict',
+                    conflictId: conflict.conflictId,
+                })), memoryIds, conflicts.map((conflict) => conflict.conflictId), emittedAt),
+                atoms,
+                conflicts,
+            };
+        }
+        return {
+            decision: decision('allow_local_shadow', [{ kind: 'all_checks_passed', citedMemoryIds: memoryIds }], memoryIds, [], emittedAt),
+            atoms,
+            conflicts,
+        };
+    }
+    async loadAtoms(query, permittedVisibilities, validAt) {
+        const atoms = await this.options.memoryStore.query({
+            statuses: query.requiredStatus ?? DEFAULT_RECALL_STATUSES,
+            scope: query.scope,
+            permittedVisibilities,
+            validAt,
+        });
+        const filtered = atoms.filter((atom) => {
+            if (query.memoryTypes !== undefined && !query.memoryTypes.includes(atom.memoryType)) {
+                return false;
+            }
+            if (query.topic !== undefined) {
+                return this.options.topicMatcher?.(atom, query.topic) ?? false;
+            }
+            return true;
+        });
+        const lineageFiltered = omitSupersededAtoms(filtered);
+        const rankedResult = this.options.authorityScorer === undefined
+            ? { ok: true, atoms: lineageFiltered }
+            : rankByAuthority(lineageFiltered, this.options.authorityScorer, validAt);
+        if (!rankedResult.ok) {
+            return {
+                ok: false,
+                reason: {
+                    kind: 'promotion_boundary_blocked',
+                    detail: `authority scorer failed: ${rankedResult.error}`,
+                },
+            };
+        }
+        const limited = query.limit !== undefined ? rankedResult.atoms.slice(0, query.limit) : rankedResult.atoms;
+        return { ok: true, atoms: limited };
+    }
+}
+function omitSupersededAtoms(atoms) {
+    const superseded = new Set(atoms.flatMap((atom) => atom.links
+        .filter((link) => link.relation === 'supersedes')
+        .map((link) => link.targetMemoryId)));
+    return atoms.filter((atom) => !superseded.has(atom.memoryId));
+}
+function rankByAuthority(atoms, scorer, now) {
+    const ranked = [];
+    for (const [index, atom] of atoms.entries()) {
+        try {
+            ranked.push({ atom, index, score: finiteScore(scorer(atom, now)) });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: err instanceof Error ? err.message : 'unknown scorer error',
+            };
+        }
+    }
+    return {
+        ok: true,
+        atoms: ranked
+            .sort((left, right) => {
+            const byScore = right.score - left.score;
+            return byScore !== 0 ? byScore : left.index - right.index;
+        })
+            .map((item) => item.atom),
+    };
+}
+function finiteScore(value) {
+    return Number.isFinite(value) ? value : 0;
+}
+function firstNonActionableReason(atoms) {
+    const humanRequired = atoms.find((atom) => atom.status === 'human_required' || atom.status === 'sealed');
+    if (humanRequired !== undefined) {
+        return {
+            outcome: 'ask_human',
+            reason: {
+                kind: 'promotion_boundary_blocked',
+                detail: `memory ${humanRequired.memoryId} requires human or sealed handling`,
+            },
+        };
+    }
+    const rejected = atoms.find((atom) => atom.status === 'rejected' || atom.status === 'deprecated');
+    if (rejected !== undefined) {
+        return {
+            outcome: 'deny',
+            reason: {
+                kind: 'promotion_boundary_blocked',
+                detail: `memory ${rejected.memoryId} is ${rejected.status}`,
+            },
+        };
+    }
+    const candidate = atoms.find((atom) => atom.status === 'candidate');
+    if (candidate !== undefined) {
+        return {
+            outcome: 'fetch_abstain',
+            reason: {
+                kind: 'tuple_incomplete',
+                missingFields: [`verifiedAuthority:${candidate.memoryId}`],
+            },
+        };
+    }
+    return null;
+}
+function schemaIssuePaths(issues, fallback) {
+    const paths = issues.map((issue) => issue.path.length > 0 ? issue.path.map(String).join('.') : fallback);
+    return paths.length > 0 ? paths : [fallback];
+}
+//# sourceMappingURL=retrieval-router.js.map

package/dist/runtime/retrieval-router.js.map

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

package/dist/runtime/scope-helpers.d.ts

@@ -0,0 +1,22 @@
+import { type Scope, type Visibility } from '../types/index.js';
+/**
+ * Compare two scope discriminated unions by their canonical index key.
+ *
+ * @remarks
+ * Use this anywhere runtime logic needs exact scope equality. It intentionally
+ * does not implement hierarchy or inheritance between scopes.
+ */
+export declare function sameScope(a: Scope, b: Scope): boolean;
+/**
+ * Compare two visibility discriminated unions by their canonical index key.
+ */
+export declare function sameVisibility(a: Visibility, b: Visibility): boolean;
+/**
+ * Return true when a requested visibility plane is explicitly permitted.
+ *
+ * @remarks
+ * This is exact matching only; hosts that want broader visibility inheritance
+ * must encode it in their `VisibilityPolicy` by returning all permitted planes.
+ */
+export declare function includesVisibility(permitted: readonly Visibility[], requested: Visibility): boolean;
+//# sourceMappingURL=scope-helpers.d.ts.map

package/dist/runtime/scope-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/scope-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,UAAU,EAA2B,MAAM,mBAAmB,CAAC;AAEzF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,SAAS,EAAE,UAAU,GACpB,OAAO,CAGT"}

package/dist/runtime/scope-helpers.js

@@ -0,0 +1,29 @@
+import { scopeKey, visibilityKey } from '../types/index.js';
+/**
+ * Compare two scope discriminated unions by their canonical index key.
+ *
+ * @remarks
+ * Use this anywhere runtime logic needs exact scope equality. It intentionally
+ * does not implement hierarchy or inheritance between scopes.
+ */
+export function sameScope(a, b) {
+    return scopeKey(a) === scopeKey(b);
+}
+/**
+ * Compare two visibility discriminated unions by their canonical index key.
+ */
+export function sameVisibility(a, b) {
+    return visibilityKey(a) === visibilityKey(b);
+}
+/**
+ * Return true when a requested visibility plane is explicitly permitted.
+ *
+ * @remarks
+ * This is exact matching only; hosts that want broader visibility inheritance
+ * must encode it in their `VisibilityPolicy` by returning all permitted planes.
+ */
+export function includesVisibility(permitted, requested) {
+    const requestedKey = visibilityKey(requested);
+    return permitted.some((v) => visibilityKey(v) === requestedKey);
+}
+//# sourceMappingURL=scope-helpers.js.map

package/dist/runtime/scope-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-helpers.js","sourceRoot":"","sources":["../../src/runtime/scope-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,CAAQ,EAAE,CAAQ;IAC1C,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,CAAa,EAAE,CAAa;IACzD,OAAO,aAAa,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAgC,EAChC,SAAqB;IAErB,MAAM,YAAY,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC;AAClE,CAAC"}

package/dist/runtime/visibility-policy.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Visibility policy boundary for runtime components.
+ *
+ * Core does not know who an agent is allowed to see. The host application must
+ * provide that mapping explicitly; the default runtime behavior is fail-closed.
+ */
+import type { AgentId, Visibility } from '../types/index.js';
+export interface VisibilityPolicy {
+    /**
+     * Return the visibility planes an agent may access.
+     *
+     * @remarks
+     * Implementations should return an empty array when access cannot be proven.
+     * Runtime components interpret an empty result as fail-closed denial or
+     * abstention, never as "all visible".
+     */
+    permittedVisibilitiesForAgent(agentId: AgentId): readonly Visibility[];
+}
+export declare const DENY_ALL_VISIBILITY_POLICY: VisibilityPolicy;
+/**
+ * Build a fixed visibility policy for tests, demos, and simple single-user hosts.
+ *
+ * @remarks
+ * This helper ignores `agentId` by design. Production hosts should usually
+ * provide a policy that derives visibility from their own identity/session
+ * model.
+ */
+export declare function staticVisibilityPolicy(permittedVisibilities: readonly Visibility[]): VisibilityPolicy;
+//# sourceMappingURL=visibility-policy.d.ts.map

package/dist/runtime/visibility-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-policy.d.ts","sourceRoot":"","sources":["../../src/runtime/visibility-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,UAAU,EAAE,CAAC;CACxE;AAED,eAAO,MAAM,0BAA0B,EAAE,gBAExC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,qBAAqB,EAAE,SAAS,UAAU,EAAE,GAC3C,gBAAgB,CAIlB"}

package/dist/runtime/visibility-policy.js

@@ -0,0 +1,23 @@
+/**
+ * Visibility policy boundary for runtime components.
+ *
+ * Core does not know who an agent is allowed to see. The host application must
+ * provide that mapping explicitly; the default runtime behavior is fail-closed.
+ */
+export const DENY_ALL_VISIBILITY_POLICY = {
+    permittedVisibilitiesForAgent: () => [],
+};
+/**
+ * Build a fixed visibility policy for tests, demos, and simple single-user hosts.
+ *
+ * @remarks
+ * This helper ignores `agentId` by design. Production hosts should usually
+ * provide a policy that derives visibility from their own identity/session
+ * model.
+ */
+export function staticVisibilityPolicy(permittedVisibilities) {
+    return {
+        permittedVisibilitiesForAgent: () => permittedVisibilities,
+    };
+}
+//# sourceMappingURL=visibility-policy.js.map

package/dist/runtime/visibility-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-policy.js","sourceRoot":"","sources":["../../src/runtime/visibility-policy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH,MAAM,CAAC,MAAM,0BAA0B,GAAqB;IAC1D,6BAA6B,EAAE,GAAG,EAAE,CAAC,EAAE;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,qBAA4C;IAE5C,OAAO;QACL,6BAA6B,EAAE,GAAG,EAAE,CAAC,qBAAqB;KAC3D,CAAC;AACJ,CAAC"}

package/dist/runtime/write-gate.d.ts

@@ -0,0 +1,66 @@
+/**
+ * WriteGate — proposal-to-atom governance.
+ *
+ * Phase 1.3 implements the conservative path: validate sources, scope,
+ * visibility, explicit conflict markers, and promotion boundary before any
+ * MemoryAtom is inserted. The gate never upgrades a claim beyond `candidate`;
+ * human/sensitive/conflicted proposals become non-actionable `human_required`
+ * atoms instead.
+ */
+import type { ConflictRegistry, EventLedger, MemoryStore } from '../storage/index.js';
+import type { ConflictRecord, Event, MemoryAtom, MemoryId, MemoryProposal, WriteGateDecision } from '../types/index.js';
+import type { Clock } from './decision-helpers.js';
+import { type VisibilityPolicy } from './visibility-policy.js';
+export interface WriteGateStores {
+    readonly eventLedger: EventLedger;
+    readonly memoryStore: MemoryStore;
+    readonly conflictRegistry: ConflictRegistry;
+}
+export interface WriteGateOptions extends WriteGateStores {
+    readonly visibilityPolicy?: VisibilityPolicy;
+    readonly clock?: Clock;
+    readonly memoryIdForProposal?: (proposal: MemoryProposal) => MemoryId;
+}
+export interface WriteGateResult {
+    readonly decision: WriteGateDecision;
+    readonly atom: MemoryAtom | null;
+    readonly sourceEvents: readonly Event[];
+    readonly conflicts: readonly ConflictRecord[];
+}
+export declare class WriteGate {
+    private readonly options;
+    private readonly visibilityPolicy;
+    private readonly clock;
+    private readonly memoryIdForProposal;
+    /**
+     * Create a proposal gate over explicit storage ports.
+     *
+     * @remarks
+     * The gate is intentionally storage-agnostic. Implementations supply the
+     * event ledger, memory store, conflict registry, visibility policy, and
+     * optional deterministic clock.
+     */
+    constructor(options: WriteGateOptions);
+    /**
+     * Evaluate and persist a proposal when it passes the source/scope boundary.
+     *
+     * @remarks
+     * This is the consumer-facing alias for `evaluate()`. It records auditable
+     * human-required/conflicted atoms when the source evidence is valid but the
+     * proposal cannot become actionable yet.
+     */
+    propose(proposal: MemoryProposal): Promise<WriteGateResult>;
+    /**
+     * Run the full WriteGate pipeline for one proposal.
+     *
+     * @remarks
+     * Implementation order is deliberate: parse proposal, derive permitted
+     * visibility, verify write visibility, load source events, validate scope,
+     * query conflict state, construct a zod-validated atom, then insert. Model
+     * confidence, consensus, prose, and chain metadata never grant authority.
+     */
+    evaluate(proposal: MemoryProposal): Promise<WriteGateResult>;
+    private loadSourceEvents;
+    private conflictDecision;
+}
+//# sourceMappingURL=write-gate.d.ts.map

package/dist/runtime/write-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-gate.d.ts","sourceRoot":"","sources":["../../src/runtime/write-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAEV,cAAc,EAEd,KAAK,EACL,UAAU,EACV,QAAQ,EACR,cAAc,EAEd,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAInD,OAAO,EAA8B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,QAAQ,CAAC;CACvE;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,SAAS,KAAK,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;CAC/C;AAmDD,qBAAa,SAAS;IAaR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAE7E;;;;;;;OAOG;gBAC0B,OAAO,EAAE,gBAAgB;IAMtD;;;;;;;OAOG;IACG,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE;;;;;;;;OAQG;IACG,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;YAoQpD,gBAAgB;IAU9B,OAAO,CAAC,gBAAgB;CAwBzB"}