@proposit/proposit-core 0.9.1 → 0.10.0

package/dist/lib/core/claim-citation-library.js

@@ -0,0 +1,336 @@
+import { Value } from "typebox/value";
+import { CoreClaimCitationSchema } from "../schemata/claim-citation.js";
+import { DEFAULT_CHECKSUM_CONFIG } from "../consts.js";
+import { entityChecksum } from "./checksum.js";
+import { CITATION_SCHEMA_INVALID, CITATION_DUPLICATE_ID, CITATION_CITING_REF_NOT_FOUND, CITATION_SOURCE_REF_NOT_FOUND, CITATION_SOURCE_NOT_CITATION_TYPE, CITATION_CYCLE_DETECTED, } from "../types/validation.js";
+import { InvariantViolationError } from "./invariant-violation-error.js";
+export class ClaimCitationLibrary {
+    citations;
+    citingClaimToCitations;
+    sourceClaimToCitations;
+    claimLookup;
+    checksumConfig;
+    constructor(claimLookup, options) {
+        this.citations = new Map();
+        this.citingClaimToCitations = new Map();
+        this.sourceClaimToCitations = new Map();
+        this.claimLookup = claimLookup;
+        this.checksumConfig = options?.checksumConfig;
+    }
+    restoreFromSnapshot(snap) {
+        this.citations = new Map();
+        this.citingClaimToCitations = new Map();
+        this.sourceClaimToCitations = new Map();
+        for (const citation of snap.claimCitations) {
+            this.citations.set(citation.id, citation);
+        }
+        for (const [id, citation] of this.citations) {
+            const citingKey = citation.citingClaimId;
+            if (!this.citingClaimToCitations.has(citingKey)) {
+                this.citingClaimToCitations.set(citingKey, new Set());
+            }
+            this.citingClaimToCitations.get(citingKey).add(id);
+            const sourceKey = citation.sourceClaimId;
+            if (!this.sourceClaimToCitations.has(sourceKey)) {
+                this.sourceClaimToCitations.set(sourceKey, new Set());
+            }
+            this.sourceClaimToCitations.get(sourceKey).add(id);
+        }
+    }
+    withValidation(fn) {
+        const snap = this.snapshot();
+        try {
+            const result = fn();
+            const validation = this.validate();
+            if (!validation.ok) {
+                this.restoreFromSnapshot(snap);
+                throw new InvariantViolationError(validation.violations);
+            }
+            return result;
+        }
+        catch (e) {
+            if (!(e instanceof InvariantViolationError)) {
+                this.restoreFromSnapshot(snap);
+            }
+            throw e;
+        }
+    }
+    add(citation) {
+        return this.withValidation(() => {
+            if (this.citations.has(citation.id)) {
+                throw new InvariantViolationError([
+                    {
+                        code: CITATION_DUPLICATE_ID,
+                        message: `Citation with id ${citation.id} already exists`,
+                        entityType: "citation",
+                        entityId: citation.id,
+                    },
+                ]);
+            }
+            const citingClaim = this.claimLookup.get(citation.citingClaimId, citation.citingClaimVersion);
+            if (!citingClaim) {
+                throw new InvariantViolationError([
+                    {
+                        code: CITATION_CITING_REF_NOT_FOUND,
+                        message: `Citation references unknown citing claim ${citation.citingClaimId}@${citation.citingClaimVersion}`,
+                        entityType: "citation",
+                        entityId: citation.id,
+                    },
+                ]);
+            }
+            const sourceClaim = this.claimLookup.get(citation.sourceClaimId, citation.sourceClaimVersion);
+            if (!sourceClaim) {
+                throw new InvariantViolationError([
+                    {
+                        code: CITATION_SOURCE_REF_NOT_FOUND,
+                        message: `Citation references unknown source claim ${citation.sourceClaimId}@${citation.sourceClaimVersion}`,
+                        entityType: "citation",
+                        entityId: citation.id,
+                    },
+                ]);
+            }
+            if (sourceClaim.type !== "citation") {
+                throw new InvariantViolationError([
+                    {
+                        code: CITATION_SOURCE_NOT_CITATION_TYPE,
+                        message: `Citation source claim ${citation.sourceClaimId} has type='${sourceClaim.type}'; only 'citation' is permitted on the source side`,
+                        entityType: "citation",
+                        entityId: citation.id,
+                    },
+                ]);
+            }
+            if (this.wouldCreateCycle(citation.citingClaimId, citation.sourceClaimId)) {
+                throw new InvariantViolationError([
+                    {
+                        code: CITATION_CYCLE_DETECTED,
+                        message: `Adding citation from ${citation.citingClaimId} to ${citation.sourceClaimId} would create a cycle in the claim citation graph`,
+                        entityType: "citation",
+                        entityId: citation.id,
+                    },
+                ]);
+            }
+            const full = { ...citation, checksum: "" };
+            full.checksum = this.computeChecksum(full);
+            this.citations.set(full.id, full);
+            let citingSet = this.citingClaimToCitations.get(full.citingClaimId);
+            if (!citingSet) {
+                citingSet = new Set();
+                this.citingClaimToCitations.set(full.citingClaimId, citingSet);
+            }
+            citingSet.add(full.id);
+            let sourceSet = this.sourceClaimToCitations.get(full.sourceClaimId);
+            if (!sourceSet) {
+                sourceSet = new Set();
+                this.sourceClaimToCitations.set(full.sourceClaimId, sourceSet);
+            }
+            sourceSet.add(full.id);
+            return full;
+        });
+    }
+    remove(id) {
+        return this.withValidation(() => {
+            const citation = this.citations.get(id);
+            if (!citation) {
+                throw new Error(`ClaimCitation "${id}" not found.`);
+            }
+            this.citations.delete(id);
+            const citingSet = this.citingClaimToCitations.get(citation.citingClaimId);
+            if (citingSet) {
+                citingSet.delete(id);
+            }
+            const sourceSet = this.sourceClaimToCitations.get(citation.sourceClaimId);
+            if (sourceSet) {
+                sourceSet.delete(id);
+            }
+            return citation;
+        });
+    }
+    getCitationsForCitingClaim(citingClaimId) {
+        const ids = this.citingClaimToCitations.get(citingClaimId);
+        if (!ids)
+            return [];
+        return Array.from(ids)
+            .map((id) => this.citations.get(id))
+            .filter(Boolean);
+    }
+    getCitationsForSourceClaim(sourceClaimId) {
+        const ids = this.sourceClaimToCitations.get(sourceClaimId);
+        if (!ids)
+            return [];
+        return Array.from(ids)
+            .map((id) => this.citations.get(id))
+            .filter(Boolean);
+    }
+    get(id) {
+        return this.citations.get(id);
+    }
+    getAll() {
+        return Array.from(this.citations.values());
+    }
+    filter(predicate) {
+        return this.getAll().filter(predicate);
+    }
+    snapshot() {
+        return { claimCitations: this.getAll() };
+    }
+    /** Restores a claim-citation library from a snapshot, re-indexing all citations. */
+    static fromSnapshot(snapshot, claimLookup, options) {
+        const lib = new ClaimCitationLibrary(claimLookup, options);
+        for (const citation of snapshot.claimCitations) {
+            lib.citations.set(citation.id, citation);
+            let citingSet = lib.citingClaimToCitations.get(citation.citingClaimId);
+            if (!citingSet) {
+                citingSet = new Set();
+                lib.citingClaimToCitations.set(citation.citingClaimId, citingSet);
+            }
+            citingSet.add(citation.id);
+            let sourceSet = lib.sourceClaimToCitations.get(citation.sourceClaimId);
+            if (!sourceSet) {
+                sourceSet = new Set();
+                lib.sourceClaimToCitations.set(citation.sourceClaimId, sourceSet);
+            }
+            sourceSet.add(citation.id);
+        }
+        return lib;
+    }
+    validate() {
+        const violations = [];
+        for (const [id, citation] of this.citations) {
+            if (!Value.Check(CoreClaimCitationSchema, citation)) {
+                violations.push({
+                    code: CITATION_SCHEMA_INVALID,
+                    message: `Citation "${id}" does not conform to schema`,
+                    entityType: "citation",
+                    entityId: id,
+                });
+            }
+            if (!this.claimLookup.get(citation.citingClaimId, citation.citingClaimVersion)) {
+                violations.push({
+                    code: CITATION_CITING_REF_NOT_FOUND,
+                    message: `Citation "${id}" references non-existent citing claim "${citation.citingClaimId}" version ${citation.citingClaimVersion}`,
+                    entityType: "citation",
+                    entityId: id,
+                });
+            }
+            if (!this.claimLookup.get(citation.sourceClaimId, citation.sourceClaimVersion)) {
+                violations.push({
+                    code: CITATION_SOURCE_REF_NOT_FOUND,
+                    message: `Citation "${id}" references non-existent source claim "${citation.sourceClaimId}" version ${citation.sourceClaimVersion}`,
+                    entityType: "citation",
+                    entityId: id,
+                });
+            }
+        }
+        // Strict source-side type: every citation's source claim must have
+        // type='citation'. Catches tampered snapshots loaded via fromSnapshot.
+        for (const citation of this.citations.values()) {
+            const sourceClaim = this.claimLookup.get(citation.sourceClaimId, citation.sourceClaimVersion);
+            if (sourceClaim && sourceClaim.type !== "citation") {
+                violations.push({
+                    code: CITATION_SOURCE_NOT_CITATION_TYPE,
+                    message: `Citation ${citation.id} source claim ${citation.sourceClaimId} has type='${sourceClaim.type}'; only 'citation' is permitted on the source side`,
+                    entityType: "citation",
+                    entityId: citation.id,
+                });
+            }
+        }
+        // Acyclicity: walk the entire citation graph (ID-only) and detect
+        // cycles. Catches cycles introduced by snapshot tampering.
+        const cycleViolations = this.detectAllCycles();
+        for (const v of cycleViolations)
+            violations.push(v);
+        return { ok: violations.length === 0, violations };
+    }
+    /**
+     * Detects all cycles in the ID-only projection of the citation graph.
+     * Returns one violation per cycle (deduped by the citation that closes
+     * each detected cycle).
+     */
+    detectAllCycles() {
+        const violations = [];
+        const visited = new Set();
+        const inProgress = new Set();
+        const reportedCycleIds = new Set();
+        const visit = (node, path) => {
+            if (inProgress.has(node)) {
+                // Cycle detected: report the citation that closes it.
+                // Find the citation linking the previous node to this one.
+                const prev = path[path.length - 1];
+                for (const citation of this.citations.values()) {
+                    if (citation.citingClaimId === prev &&
+                        citation.sourceClaimId === node &&
+                        !reportedCycleIds.has(citation.id)) {
+                        violations.push({
+                            code: CITATION_CYCLE_DETECTED,
+                            message: `Citation graph contains a cycle involving claim ${node}`,
+                            entityType: "citation",
+                            entityId: citation.id,
+                        });
+                        reportedCycleIds.add(citation.id);
+                    }
+                }
+                return;
+            }
+            if (visited.has(node))
+                return;
+            visited.add(node);
+            inProgress.add(node);
+            const outgoing = this.citingClaimToCitations.get(node);
+            if (outgoing) {
+                for (const cid of outgoing) {
+                    const c = this.citations.get(cid);
+                    if (c)
+                        visit(c.sourceClaimId, [...path, node]);
+                }
+            }
+            inProgress.delete(node);
+        };
+        for (const node of this.citingClaimToCitations.keys()) {
+            if (!visited.has(node))
+                visit(node, []);
+        }
+        return violations;
+    }
+    /**
+     * Returns true if adding an edge from `citingClaimId` to `sourceClaimId`
+     * would create a cycle in the claim-citation graph. Edges go from citing
+     * to source; a cycle exists when the citing claim is reachable from the
+     * proposed source claim by following outgoing source edges.
+     */
+    wouldCreateCycle(citingClaimId, sourceClaimId) {
+        // Optimization: if citing-side has type "normal", it can never appear
+        // on the source side, so no cycle is reachable. Type is immutable
+        // post-creation, so v0's type is authoritative.
+        const citingClaimType = this.claimLookup.get(citingClaimId, 0)?.type;
+        if (citingClaimType === "normal")
+            return false;
+        // DFS from sourceClaimId following outgoing source edges via the
+        // citingClaimToCitations index (avoids scanning all citations).
+        const visited = new Set();
+        const stack = [sourceClaimId];
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (node === citingClaimId)
+                return true;
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            const outgoingIds = this.citingClaimToCitations.get(node);
+            if (outgoingIds) {
+                for (const cid of outgoingIds) {
+                    const c = this.citations.get(cid);
+                    if (c) {
+                        stack.push(c.sourceClaimId);
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    computeChecksum(citation) {
+        const fields = this.checksumConfig?.claimCitationFields ??
+            DEFAULT_CHECKSUM_CONFIG.claimCitationFields;
+        return entityChecksum(citation, fields);
+    }
+}
+//# sourceMappingURL=claim-citation-library.js.map

package/dist/lib/core/claim-citation-library.js.map

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

package/dist/lib/core/claim-library.d.ts

@@ -2,6 +2,15 @@ import type { TCoreClaim } from "../schemata/claim.js";
 import type { TCoreChecksumConfig } from "../types/checksum.js";
 import type { TClaimLibraryManagement, TClaimLibrarySnapshot } from "./interfaces/library.interfaces.js";
 import { VersionedLibrary } from "./versioned-library.js";
+/**
+ * Input shape for {@link ClaimLibrary.create}. The `type` field is required
+ * (and immutable thereafter); `id` is auto-generated when omitted. Other
+ * extension fields on `TClaim` are passed through as-is, matching the base
+ * {@link VersionedLibrary.create} contract.
+ */
+export type TClaimCreateInput<TClaim extends TCoreClaim = TCoreClaim> = Omit<TClaim, "version" | "frozen" | "checksum"> | (Omit<TClaim, "id" | "version" | "frozen" | "checksum"> & {
+    id?: string;
+});
 export declare class ClaimLibrary<TClaim extends TCoreClaim = TCoreClaim> extends VersionedLibrary<TClaim> implements TClaimLibraryManagement<TClaim> {
     protected readonly entityLabel = "Claim";
     protected readonly entityType: "claim";
@@ -10,14 +19,37 @@ export declare class ClaimLibrary<TClaim extends TCoreClaim = TCoreClaim> extend
         version: import("typebox").TNumber;
         frozen: import("typebox").TBoolean;
         checksum: import("typebox").TString;
+        type: import("typebox").TUnion<[import("typebox").TLiteral<"normal">, import("typebox").TLiteral<"citation">]>;
     }>;
     protected readonly checksumFieldsKey: "claimFields";
     protected readonly schemaInvalidCode = "CLAIM_SCHEMA_INVALID";
     protected readonly frozenSuccessorCode = "CLAIM_FROZEN_NO_SUCCESSOR";
+    private readonly generateId;
+    constructor(options?: {
+        checksumConfig?: TCoreChecksumConfig;
+        generateId?: () => string;
+    });
+    /**
+     * Creates a new claim at version 0. The `type` field is required and is
+     * immutable across the claim's lifetime. `id` is auto-generated when omitted.
+     */
+    create(input: TClaimCreateInput<TClaim>): TClaim;
+    /**
+     * Applies partial updates to the latest version of a claim. Rejects any
+     * update that would change the immutable `type` field.
+     */
+    update(id: string, updates: Partial<Omit<TClaim, "id" | "version" | "frozen" | "checksum">>): TClaim;
     snapshot(): TClaimLibrarySnapshot<TClaim>;
-    /** Restores a claim library from a previously captured snapshot. */
+    /**
+     * Restores a claim library from a previously captured snapshot.
+     * Pre-screens for legacy (pre-v0.10.0) claim entries that lack the
+     * required `type` field and emits {@link LEGACY_CLAIM_MISSING_TYPE} so
+     * the caller gets a clear migration signal rather than a generic schema
+     * error.
+     */
     static fromSnapshot<TClaim extends TCoreClaim = TCoreClaim>(snapshot: TClaimLibrarySnapshot<TClaim>, options?: {
         checksumConfig?: TCoreChecksumConfig;
+        generateId?: () => string;
     }): ClaimLibrary<TClaim>;
 }
 //# sourceMappingURL=claim-library.d.ts.map

package/dist/lib/core/claim-library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-library.d.ts","sourceRoot":"","sources":["../../../src/lib/core/claim-library.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EACR,uBAAuB,EACvB,qBAAqB,EACxB,MAAM,oCAAoC,CAAA;AAK3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,qBAAa,YAAY,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,CAC5D,SAAQ,gBAAgB,CAAC,MAAM,CAC/B,YAAW,uBAAuB,CAAC,MAAM,CAAC;IAE1C,SAAS,CAAC,QAAQ,CAAC,WAAW,WAAU;IACxC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAG,OAAO,CAAS;IAChD,SAAS,CAAC,QAAQ,CAAC,MAAM;;;;;OAAkB;IAC3C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAG,aAAa,CAAS;IAC7D,SAAS,CAAC,QAAQ,CAAC,iBAAiB,0BAAuB;IAC3D,SAAS,CAAC,QAAQ,CAAC,mBAAmB,+BAA4B;IAE3D,QAAQ,IAAI,qBAAqB,CAAC,MAAM,CAAC;IAIhD,oEAAoE;WACtD,YAAY,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAC7D,QAAQ,EAAE,qBAAqB,CAAC,MAAM,CAAC,EACvC,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,mBAAmB,CAAA;KAAE,GACnD,YAAY,CAAC,MAAM,CAAC;CAK1B"}
+{"version":3,"file":"claim-library.d.ts","sourceRoot":"","sources":["../../../src/lib/core/claim-library.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,KAAK,EACR,uBAAuB,EACvB,qBAAqB,EACxB,MAAM,oCAAoC,CAAA;AAS3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,IAC9D,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,GAC/C,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEhF,qBAAa,YAAY,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,CAC5D,SAAQ,gBAAgB,CAAC,MAAM,CAC/B,YAAW,uBAAuB,CAAC,MAAM,CAAC;IAE1C,SAAS,CAAC,QAAQ,CAAC,WAAW,WAAU;IACxC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAG,OAAO,CAAS;IAChD,SAAS,CAAC,QAAQ,CAAC,MAAM;;;;;;OAAkB;IAC3C,SAAS,CAAC,QAAQ,CAAC,iBAAiB,EAAG,aAAa,CAAS;IAC7D,SAAS,CAAC,QAAQ,CAAC,iBAAiB,0BAAuB;IAC3D,SAAS,CAAC,QAAQ,CAAC,mBAAmB,+BAA4B;IAElE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;gBAE7B,OAAO,CAAC,EAAE;QAClB,cAAc,CAAC,EAAE,mBAAmB,CAAA;QACpC,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;KAC5B;IAKD;;;OAGG;IACa,MAAM,CAAC,KAAK,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,MAAM;IAUhE;;;OAGG;IACa,MAAM,CAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC,GACzE,MAAM;IAmBF,QAAQ,IAAI,qBAAqB,CAAC,MAAM,CAAC;IAIhD;;;;;;OAMG;WACW,YAAY,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAC7D,QAAQ,EAAE,qBAAqB,CAAC,MAAM,CAAC,EACvC,OAAO,CAAC,EAAE;QACN,cAAc,CAAC,EAAE,mBAAmB,CAAA;QACpC,UAAU,CAAC,EAAE,MAAM,MAAM,CAAA;KAC5B,GACF,YAAY,CAAC,MAAM,CAAC;CA8B1B"}

package/dist/lib/core/claim-library.js

@@ -1,5 +1,7 @@
 import { CoreClaimSchema } from "../schemata/claim.js";
-import { CLAIM_SCHEMA_INVALID, CLAIM_FROZEN_NO_SUCCESSOR, } from "../types/validation.js";
+import { CLAIM_SCHEMA_INVALID, CLAIM_FROZEN_NO_SUCCESSOR, CLAIM_TYPE_IMMUTABLE, LEGACY_CLAIM_MISSING_TYPE, } from "../types/validation.js";
+import { InvariantViolationError } from "./invariant-violation-error.js";
+import { defaultGenerateId } from "./argument-engine.js";
 import { VersionedLibrary } from "./versioned-library.js";
 export class ClaimLibrary extends VersionedLibrary {
     entityLabel = "Claim";
@@ -8,13 +10,79 @@ export class ClaimLibrary extends VersionedLibrary {
     checksumFieldsKey = "claimFields";
     schemaInvalidCode = CLAIM_SCHEMA_INVALID;
     frozenSuccessorCode = CLAIM_FROZEN_NO_SUCCESSOR;
+    generateId;
+    constructor(options) {
+        super(options);
+        this.generateId = options?.generateId ?? defaultGenerateId;
+    }
+    /**
+     * Creates a new claim at version 0. The `type` field is required and is
+     * immutable across the claim's lifetime. `id` is auto-generated when omitted.
+     */
+    create(input) {
+        const inputId = input.id;
+        const id = inputId ?? this.generateId();
+        const entity = {
+            ...input,
+            id,
+        };
+        return super.create(entity);
+    }
+    /**
+     * Applies partial updates to the latest version of a claim. Rejects any
+     * update that would change the immutable `type` field.
+     */
+    update(id, updates) {
+        const existing = this.getCurrent(id);
+        if (existing !== undefined &&
+            updates.type !== undefined &&
+            updates.type !== existing.type) {
+            throw new InvariantViolationError([
+                {
+                    code: CLAIM_TYPE_IMMUTABLE,
+                    message: `Claim "${id}" type is immutable; cannot change type from '${existing.type}' to '${updates.type}'`,
+                    entityType: "claim",
+                    entityId: id,
+                },
+            ]);
+        }
+        return super.update(id, updates);
+    }
     snapshot() {
         return { claims: this.getAll() };
     }
-    /** Restores a claim library from a previously captured snapshot. */
+    /**
+     * Restores a claim library from a previously captured snapshot.
+     * Pre-screens for legacy (pre-v0.10.0) claim entries that lack the
+     * required `type` field and emits {@link LEGACY_CLAIM_MISSING_TYPE} so
+     * the caller gets a clear migration signal rather than a generic schema
+     * error.
+     */
     static fromSnapshot(snapshot, options) {
+        const claims = snapshot.claims ?? [];
+        for (const claim of claims) {
+            if (claim === null ||
+                typeof claim !== "object" ||
+                !("type" in claim) ||
+                claim.type === undefined) {
+                const claimId = claim !== null &&
+                    typeof claim === "object" &&
+                    "id" in claim &&
+                    typeof claim.id === "string"
+                    ? claim.id
+                    : "<unknown>";
+                throw new InvariantViolationError([
+                    {
+                        code: LEGACY_CLAIM_MISSING_TYPE,
+                        message: `Claim "${claimId}" is missing the 'type' field, indicating pre-v0.10.0 data. Migration required.`,
+                        entityType: "claim",
+                        entityId: claimId,
+                    },
+                ]);
+            }
+        }
         const lib = new ClaimLibrary(options);
-        lib.restoreFromEntities(snapshot.claims);
+        lib.restoreFromEntities(claims);
         return lib;
     }
 }

package/dist/lib/core/claim-library.js.map

@@ -1 +1 @@
-{"version":3,"file":"claim-library.js","sourceRoot":"","sources":["../../../src/lib/core/claim-library.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAMtD,OAAO,EACH,oBAAoB,EACpB,yBAAyB,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAEzD,MAAM,OAAO,YACT,SAAQ,gBAAwB;IAGb,WAAW,GAAG,OAAO,CAAA;IACrB,UAAU,GAAG,OAAgB,CAAA;IAC7B,MAAM,GAAG,eAAe,CAAA;IACxB,iBAAiB,GAAG,aAAsB,CAAA;IAC1C,iBAAiB,GAAG,oBAAoB,CAAA;IACxC,mBAAmB,GAAG,yBAAyB,CAAA;IAE3D,QAAQ;QACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAA;IACpC,CAAC;IAED,oEAAoE;IAC7D,MAAM,CAAC,YAAY,CACtB,QAAuC,EACvC,OAAkD;QAElD,MAAM,GAAG,GAAG,IAAI,YAAY,CAAS,OAAO,CAAC,CAAA;QAC7C,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;QACxC,OAAO,GAAG,CAAA;IACd,CAAC;CACJ"}
+{"version":3,"file":"claim-library.js","sourceRoot":"","sources":["../../../src/lib/core/claim-library.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAMtD,OAAO,EACH,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,yBAAyB,GAC5B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AACxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAYzD,MAAM,OAAO,YACT,SAAQ,gBAAwB;IAGb,WAAW,GAAG,OAAO,CAAA;IACrB,UAAU,GAAG,OAAgB,CAAA;IAC7B,MAAM,GAAG,eAAe,CAAA;IACxB,iBAAiB,GAAG,aAAsB,CAAA;IAC1C,iBAAiB,GAAG,oBAAoB,CAAA;IACxC,mBAAmB,GAAG,yBAAyB,CAAA;IAEjD,UAAU,CAAc;IAEzC,YAAY,OAGX;QACG,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,iBAAiB,CAAA;IAC9D,CAAC;IAED;;;OAGG;IACa,MAAM,CAAC,KAAgC;QACnD,MAAM,OAAO,GAAI,KAAyB,CAAC,EAAE,CAAA;QAC7C,MAAM,EAAE,GAAG,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAA;QACvC,MAAM,MAAM,GAAG;YACX,GAAG,KAAK;YACR,EAAE;SAC8C,CAAA;QACpD,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC/B,CAAC;IAED;;;OAGG;IACa,MAAM,CAClB,EAAU,EACV,OAAwE;QAExE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;QACpC,IACI,QAAQ,KAAK,SAAS;YACrB,OAA+B,CAAC,IAAI,KAAK,SAAS;YAClD,OAA+B,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EACzD,CAAC;YACC,MAAM,IAAI,uBAAuB,CAAC;gBAC9B;oBACI,IAAI,EAAE,oBAAoB;oBAC1B,OAAO,EAAE,UAAU,EAAE,iDAAiD,QAAQ,CAAC,IAAI,SAAU,OAA+B,CAAC,IAAI,GAAG;oBACpI,UAAU,EAAE,OAAO;oBACnB,QAAQ,EAAE,EAAE;iBACf;aACJ,CAAC,CAAA;QACN,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IAEM,QAAQ;QACX,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAA;IACpC,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,YAAY,CACtB,QAAuC,EACvC,OAGC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAA;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,IACI,KAAK,KAAK,IAAI;gBACd,OAAO,KAAK,KAAK,QAAQ;gBACzB,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;gBACjB,KAA4B,CAAC,IAAI,KAAK,SAAS,EAClD,CAAC;gBACC,MAAM,OAAO,GACT,KAAK,KAAK,IAAI;oBACd,OAAO,KAAK,KAAK,QAAQ;oBACzB,IAAI,IAAI,KAAK;oBACb,OAAQ,KAA0B,CAAC,EAAE,KAAK,QAAQ;oBAC9C,CAAC,CAAE,KAAwB,CAAC,EAAE;oBAC9B,CAAC,CAAC,WAAW,CAAA;gBACrB,MAAM,IAAI,uBAAuB,CAAC;oBAC9B;wBACI,IAAI,EAAE,yBAAyB;wBAC/B,OAAO,EAAE,UAAU,OAAO,iFAAiF;wBAC3G,UAAU,EAAE,OAAO;wBACnB,QAAQ,EAAE,OAAO;qBACpB;iBACJ,CAAC,CAAA;YACN,CAAC;QACL,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,YAAY,CAAS,OAAO,CAAC,CAAA;QAC7C,GAAG,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;QAC/B,OAAO,GAAG,CAAA;IACd,CAAC;CACJ"}

package/dist/lib/core/fork-library.d.ts

@@ -1,26 +1,35 @@
-import type { TCoreArgumentForkRecord, TCorePremiseForkRecord, TCoreExpressionForkRecord, TCoreVariableForkRecord, TCoreClaimForkRecord, TCoreSourceForkRecord } from "../schemata/fork.js";
+import type { TCoreArgumentForkRecord, TCorePremiseForkRecord, TCoreExpressionForkRecord, TCoreVariableForkRecord, TCoreClaimForkRecord } from "../schemata/fork.js";
 import { ForkNamespace } from "./fork-namespace.js";
 import type { TForkLibrarySnapshot } from "./interfaces/library.interfaces.js";
 import type { TInvariantValidationResult } from "../types/validation.js";
 /**
  * Aggregate container for fork provenance across all entity types.
- * Holds six {@link ForkNamespace} instances — one per entity kind
- * (arguments, premises, expressions, variables, claims, sources).
+ * Holds five {@link ForkNamespace} instances — one per entity kind
+ * (arguments, premises, expressions, variables, claims).
  * Fork records are immutable after creation and carry no checksums.
+ *
+ * As of v0.10.0 the legacy `sources` namespace has been folded into
+ * `claims` — sources are now claims with `type: "citation"`.
  */
-export declare class ForkLibrary<TArgFork extends TCoreArgumentForkRecord = TCoreArgumentForkRecord, TPremiseFork extends TCorePremiseForkRecord = TCorePremiseForkRecord, TExprFork extends TCoreExpressionForkRecord = TCoreExpressionForkRecord, TVarFork extends TCoreVariableForkRecord = TCoreVariableForkRecord, TClaimFork extends TCoreClaimForkRecord = TCoreClaimForkRecord, TSourceFork extends TCoreSourceForkRecord = TCoreSourceForkRecord> {
+export declare class ForkLibrary<TArgFork extends TCoreArgumentForkRecord = TCoreArgumentForkRecord, TPremiseFork extends TCorePremiseForkRecord = TCorePremiseForkRecord, TExprFork extends TCoreExpressionForkRecord = TCoreExpressionForkRecord, TVarFork extends TCoreVariableForkRecord = TCoreVariableForkRecord, TClaimFork extends TCoreClaimForkRecord = TCoreClaimForkRecord> {
     readonly arguments: ForkNamespace<TArgFork>;
     readonly premises: ForkNamespace<TPremiseFork>;
     readonly expressions: ForkNamespace<TExprFork>;
     readonly variables: ForkNamespace<TVarFork>;
     readonly claims: ForkNamespace<TClaimFork>;
-    readonly sources: ForkNamespace<TSourceFork>;
     constructor();
-    /** Returns a serializable snapshot of all six namespaces. */
-    snapshot(): TForkLibrarySnapshot<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork, TSourceFork>;
-    /** Restores a full library from a previously captured snapshot. */
-    static fromSnapshot<TArgFork extends TCoreArgumentForkRecord = TCoreArgumentForkRecord, TPremiseFork extends TCorePremiseForkRecord = TCorePremiseForkRecord, TExprFork extends TCoreExpressionForkRecord = TCoreExpressionForkRecord, TVarFork extends TCoreVariableForkRecord = TCoreVariableForkRecord, TClaimFork extends TCoreClaimForkRecord = TCoreClaimForkRecord, TSourceFork extends TCoreSourceForkRecord = TCoreSourceForkRecord>(snapshot: TForkLibrarySnapshot<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork, TSourceFork>): ForkLibrary<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork, TSourceFork>;
-    /** Validates all six namespaces and returns the combined result. */
+    /** Returns a serializable snapshot of all five namespaces. */
+    snapshot(): TForkLibrarySnapshot<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork>;
+    /**
+     * Restores a full library from a previously captured snapshot.
+     *
+     * Pre-v0.10.0 snapshots that contained a `sources` namespace are not
+     * supported here — callers must convert them via the CLI migration
+     * (Phase 14) before invoking `fromSnapshot`. Any stray `sources` key on
+     * an input snapshot is silently ignored.
+     */
+    static fromSnapshot<TArgFork extends TCoreArgumentForkRecord = TCoreArgumentForkRecord, TPremiseFork extends TCorePremiseForkRecord = TCorePremiseForkRecord, TExprFork extends TCoreExpressionForkRecord = TCoreExpressionForkRecord, TVarFork extends TCoreVariableForkRecord = TCoreVariableForkRecord, TClaimFork extends TCoreClaimForkRecord = TCoreClaimForkRecord>(snapshot: TForkLibrarySnapshot<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork>): ForkLibrary<TArgFork, TPremiseFork, TExprFork, TVarFork, TClaimFork>;
+    /** Validates all five namespaces and returns the combined result. */
     validate(): TInvariantValidationResult;
 }
 //# sourceMappingURL=fork-library.d.ts.map

package/dist/lib/core/fork-library.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fork-library.d.ts","sourceRoot":"","sources":["../../../src/lib/core/fork-library.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACxB,MAAM,qBAAqB,CAAA;AAO5B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA;AAC9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAExE;;;;;GAKG;AACH,qBAAa,WAAW,CACpB,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,YAAY,SAAS,sBAAsB,GAAG,sBAAsB,EACpE,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,EACvE,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,UAAU,SAAS,oBAAoB,GAAG,oBAAoB,EAC9D,WAAW,SAAS,qBAAqB,GAAG,qBAAqB;IAEjE,SAAgB,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;IAClD,SAAgB,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IACrD,SAAgB,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IACrD,SAAgB,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;IAClD,SAAgB,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IACjD,SAAgB,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;;IAiBnD,6DAA6D;IACtD,QAAQ,IAAI,oBAAoB,CACnC,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,CACd;IAWD,mEAAmE;WACrD,YAAY,CACtB,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,YAAY,SAAS,sBAAsB,GAAG,sBAAsB,EACpE,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,EACvE,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,UAAU,SAAS,oBAAoB,GAAG,oBAAoB,EAC9D,WAAW,SAAS,qBAAqB,GAAG,qBAAqB,EAEjE,QAAQ,EAAE,oBAAoB,CAC1B,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,CACd,GACF,WAAW,CACV,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,CACd;IAgCD,oEAAoE;IAC7D,QAAQ,IAAI,0BAA0B;CAWhD"}
+{"version":3,"file":"fork-library.d.ts","sourceRoot":"","sources":["../../../src/lib/core/fork-library.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,EACvB,MAAM,qBAAqB,CAAA;AAM5B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAA;AAC9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAExE;;;;;;;;GAQG;AACH,qBAAa,WAAW,CACpB,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,YAAY,SAAS,sBAAsB,GAAG,sBAAsB,EACpE,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,EACvE,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,UAAU,SAAS,oBAAoB,GAAG,oBAAoB;IAE9D,SAAgB,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;IAClD,SAAgB,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;IACrD,SAAgB,WAAW,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IACrD,SAAgB,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;IAClD,SAAgB,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;;IAcjD,8DAA8D;IACvD,QAAQ,IAAI,oBAAoB,CACnC,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,UAAU,CACb;IAUD;;;;;;;OAOG;WACW,YAAY,CACtB,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,YAAY,SAAS,sBAAsB,GAAG,sBAAsB,EACpE,SAAS,SAAS,yBAAyB,GAAG,yBAAyB,EACvE,QAAQ,SAAS,uBAAuB,GAAG,uBAAuB,EAClE,UAAU,SAAS,oBAAoB,GAAG,oBAAoB,EAE9D,QAAQ,EAAE,oBAAoB,CAC1B,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,UAAU,CACb,GACF,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC;IA4BvE,qEAAqE;IAC9D,QAAQ,IAAI,0BAA0B;CAUhD"}

package/dist/lib/core/fork-library.js

@@ -1,10 +1,13 @@
-import { CoreEntityForkRecordSchema, CoreExpressionForkRecordSchema, CoreClaimForkRecordSchema, CoreSourceForkRecordSchema, } from "../schemata/fork.js";
+import { CoreEntityForkRecordSchema, CoreExpressionForkRecordSchema, CoreClaimForkRecordSchema, } from "../schemata/fork.js";
 import { ForkNamespace } from "./fork-namespace.js";
 /**
  * Aggregate container for fork provenance across all entity types.
- * Holds six {@link ForkNamespace} instances — one per entity kind
- * (arguments, premises, expressions, variables, claims, sources).
+ * Holds five {@link ForkNamespace} instances — one per entity kind
+ * (arguments, premises, expressions, variables, claims).
  * Fork records are immutable after creation and carry no checksums.
+ *
+ * As of v0.10.0 the legacy `sources` namespace has been folded into
+ * `claims` — sources are now claims with `type: "citation"`.
  */
 export class ForkLibrary {
     arguments;
@@ -12,16 +15,14 @@ export class ForkLibrary {
     expressions;
     variables;
     claims;
-    sources;
     constructor() {
         this.arguments = new ForkNamespace(CoreEntityForkRecordSchema);
         this.premises = new ForkNamespace(CoreEntityForkRecordSchema);
         this.expressions = new ForkNamespace(CoreExpressionForkRecordSchema);
         this.variables = new ForkNamespace(CoreEntityForkRecordSchema);
         this.claims = new ForkNamespace(CoreClaimForkRecordSchema);
-        this.sources = new ForkNamespace(CoreSourceForkRecordSchema);
     }
-    /** Returns a serializable snapshot of all six namespaces. */
+    /** Returns a serializable snapshot of all five namespaces. */
     snapshot() {
         return {
             arguments: this.arguments.snapshot(),
@@ -29,10 +30,16 @@ export class ForkLibrary {
             expressions: this.expressions.snapshot(),
             variables: this.variables.snapshot(),
             claims: this.claims.snapshot(),
-            sources: this.sources.snapshot(),
         };
     }
-    /** Restores a full library from a previously captured snapshot. */
+    /**
+     * Restores a full library from a previously captured snapshot.
+     *
+     * Pre-v0.10.0 snapshots that contained a `sources` namespace are not
+     * supported here — callers must convert them via the CLI migration
+     * (Phase 14) before invoking `fromSnapshot`. Any stray `sources` key on
+     * an input snapshot is silently ignored.
+     */
     static fromSnapshot(snapshot) {
         const lib = new ForkLibrary();
         for (const record of snapshot.arguments) {
@@ -50,12 +57,9 @@ export class ForkLibrary {
         for (const record of snapshot.claims) {
             lib.claims.create(record);
         }
-        for (const record of snapshot.sources) {
-            lib.sources.create(record);
-        }
         return lib;
     }
-    /** Validates all six namespaces and returns the combined result. */
+    /** Validates all five namespaces and returns the combined result. */
     validate() {
         const allViolations = [
             ...this.arguments.validate().violations,
@@ -63,7 +67,6 @@ export class ForkLibrary {
             ...this.expressions.validate().violations,
             ...this.variables.validate().violations,
             ...this.claims.validate().violations,
-            ...this.sources.validate().violations,
         ];
         return { ok: allViolations.length === 0, violations: allViolations };
     }