@intentius/chant 0.124.52 → 0.124.54

package/dist/lifecycle/index-diff.d.ts

@@ -0,0 +1,224 @@
+import { type CoverageEntry, type IndexDocument } from "./index-document.js";
+import type { SnapshotStore } from "./snapshot-store.js";
+/** The first chant that exports the index diff and `chant index diff`. */
+export declare const INDEX_DIFF_FLOOR = "0.124.54";
+/**
+ * The words a comparison against an index uses (#4533, shared with #4526).
+ * `not-observed` is the drift record's word for the same thing
+ * (../drift-record.ts `DriftStatus`): the read could not say, and the
+ * coverage verdict says why.
+ */
+export type IndexChangeKind = "added" | "removed" | "changed" | "not-observed";
+export declare const INDEX_CHANGE_KINDS: readonly IndexChangeKind[];
+/** A coverage entry as the diff reads it: chant's `CoverageEntry`, or the same shape with any verdict string. */
+export interface IndexDiffCoverageEntry {
+    listedType: string;
+    location: string;
+    verdict: CoverageEntry["verdict"] | (string & {});
+    detail?: string;
+}
+/** The parts of an index node the diff reads. An `IRNode` is one. */
+export interface IndexDiffNode {
+    id: string;
+    kind: string;
+    lexicon?: string;
+    attrs?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    listedType?: string;
+    location?: string;
+    nativeId?: string;
+    physicalId?: string;
+}
+/** The parts of an index edge the diff reads. An `IREdge` is one. */
+export interface IndexDiffEdge {
+    from: string;
+    to: string;
+    kind?: string;
+    viaAttr?: string;
+    relation?: string;
+    origin?: string;
+    rule?: string;
+}
+/** The parts of an index version the diff reads. An {@link IndexDocument} is one. */
+export interface IndexDiffDocument {
+    index: string;
+    stamp: {
+        scopeKey: string;
+        observedAt: string;
+        completedAt?: string;
+        digest: string;
+        source?: {
+            kind: string;
+            name: string;
+            version?: string;
+        };
+    };
+    coverage: readonly IndexDiffCoverageEntry[];
+    graph: {
+        nodes: readonly IndexDiffNode[];
+        edges: readonly IndexDiffEdge[];
+    };
+}
+/** Two versions of different scopes. Refused by name, never diffed. */
+export declare class IndexScopeMismatch extends Error {
+    readonly fromScopeKey: string;
+    readonly toScopeKey: string;
+    readonly code = "index-scope-mismatch";
+    constructor(fromScopeKey: string, toScopeKey: string);
+}
+/** A document that is not an index version, or a reference no store holds. */
+export declare class NotAnIndexVersion extends Error {
+    readonly code = "not-an-index-version";
+    constructor(message: string);
+}
+export interface IndexDiffStamp {
+    scopeKey: string;
+    observedAt: string;
+    completedAt?: string;
+    digest: string;
+    source?: {
+        kind: string;
+        name: string;
+        version?: string;
+    };
+    /** The version name, when the caller knows it. */
+    version?: string;
+}
+export interface IndexNodeRef {
+    key: string;
+    kind: string;
+    listedType: string;
+    location: string;
+}
+export interface IndexPropertyChange {
+    path: string;
+    before?: unknown;
+    after?: unknown;
+}
+export interface IndexNodeChanged extends IndexNodeRef {
+    properties: IndexPropertyChange[];
+}
+/** A node one read has and the other did not observe. `side` names the read that did not observe it. */
+export interface IndexNodeNotObserved extends IndexNodeRef {
+    side: "from" | "to";
+    /** The coverage verdict for its (type, location) in that read, or `not-in-coverage`. */
+    verdict: string;
+    detail?: string;
+}
+export interface IndexEdgeRef {
+    from: string;
+    to: string;
+    kind: string;
+    viaAttr?: string;
+    relation: string;
+    origin?: string;
+    rule?: string;
+}
+export interface IndexEdgeNotObserved extends IndexEdgeRef {
+    side: "from" | "to";
+    /** The end whose (type, location) was not observed in that read. */
+    unobservedEnd: string;
+    verdict: string;
+}
+export interface IndexDiff {
+    diff: "v1";
+    scopeKey: string;
+    from: IndexDiffStamp;
+    to: IndexDiffStamp;
+    /** Same digest: same graph and coverage. */
+    unchanged: boolean;
+    nodes: {
+        added: IndexNodeRef[];
+        removed: IndexNodeRef[];
+        changed: IndexNodeChanged[];
+        notObserved: IndexNodeNotObserved[];
+    };
+    edges: {
+        added: IndexEdgeRef[];
+        removed: IndexEdgeRef[];
+        notObserved: IndexEdgeNotObserved[];
+    };
+    /** (type, location) pairs whose verdict moved between the reads. */
+    coverage: Array<{
+        listedType: string;
+        location: string;
+        before?: string;
+        after?: string;
+    }>;
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+        properties: number;
+        notObserved: number;
+        edgesAdded: number;
+        edgesRemoved: number;
+        edgesNotObserved: number;
+    };
+}
+export interface IndexDiffOptions {
+    /** Version names, for the stamps. */
+    fromVersion?: string;
+    toVersion?: string;
+}
+/**
+ * A node's (type, location): its own `listedType` and `location` (#4521
+ * writes both), else the path-style id's fourth and third segments
+ * (behold#1025 Q2, `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`),
+ * else its kind at every location.
+ */
+export declare function indexNodeTypeAndLocation(n: IndexDiffNode): {
+    listedType: string;
+    location: string;
+};
+/** What an index's coverage says about a (type, location) that holds no node. */
+export type IndexAbsence = {
+    kind: "removed";
+} | {
+    kind: "not-observed";
+    verdict: string;
+    detail?: string;
+};
+/**
+ * The rule for an absent node (#4533, shared with #4526): absent counts as
+ * gone (`removed`) only where the read's coverage says `listed` for the
+ * node's (type, location); anywhere else it is `not-observed`, with the
+ * verdict, or `not-in-coverage` when no entry speaks for it.
+ */
+export declare function indexAbsence(coverage: readonly IndexDiffCoverageEntry[], listedType: string, location: string): IndexAbsence;
+/** The property changes of one node between two reads. */
+export declare function indexNodePropertyChanges(before: IndexDiffNode, after: IndexDiffNode): IndexPropertyChange[];
+/**
+ * What changed from `from` to `to`, two versions of one index scope.
+ * Throws {@link IndexScopeMismatch} when their scope keys differ, and
+ * {@link NotAnIndexVersion} for a document of another shape.
+ */
+export declare function diffIndexVersions(from: IndexDiffDocument, to: IndexDiffDocument, o?: IndexDiffOptions): IndexDiff;
+/** A parsed version reference: `<scopeKey>/<version>`, or `<scopeKey>` alone for its latest. */
+export interface IndexVersionRef {
+    scopeKey: string;
+    /** Absent: the scope's latest version. */
+    version?: string;
+}
+/**
+ * Parse `<scopeKey>/<version>` or `<scopeKey>`. A bare version name (no
+ * scope) takes `inScope`'s scope, so `--against <version>` can name another
+ * version of the first argument's scope.
+ */
+export declare function parseIndexVersionRef(ref: string, inScope?: string): IndexVersionRef;
+/** One version read from a store, with the name it is stored under. */
+export interface StoredIndexVersion {
+    scopeKey: string;
+    version: string;
+    doc: IndexDocument;
+}
+/** Read one version (or a scope's latest) through the store. Throws {@link NotAnIndexVersion} when the store has none. */
+export declare function readIndexVersionRef(store: Pick<SnapshotStore, "kind" | "listIndex" | "readIndexAt">, ref: IndexVersionRef): Promise<StoredIndexVersion>;
+/**
+ * Diff two stored versions. `to` absent: `from` names a scope (or a version
+ * in one), and the diff is the scope's last two versions, or the version
+ * before `from` against `from`. Two references under different scope paths
+ * are refused before either is read.
+ */
+export declare function diffIndexVersionRefs(store: Pick<SnapshotStore, "kind" | "listIndex" | "readIndexAt">, from: IndexVersionRef, to?: IndexVersionRef): Promise<IndexDiff>;
+//# sourceMappingURL=index-diff.d.ts.map

package/dist/lifecycle/index-diff.d.ts.map

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

package/dist/lifecycle/index-diff.js

@@ -0,0 +1,327 @@
+/**
+ * What changed between two versions of one index scope (#4533, moved from
+ * INTENTIUS/behold#1028's src/graph-db/index-diff.ts under the ruling that
+ * behold is a control plane and every model lives in chant,
+ * INTENTIUS/behold#1024).
+ *
+ * A pure function over two index versions (./index-document.ts): nodes added
+ * and removed, properties changed, edges added and removed. It reads nothing
+ * and writes nothing; {@link readIndexVersionRef} and
+ * {@link diffIndexVersionRefs} load the two versions through a
+ * {@link SnapshotStore}, so every store kind (git ref, local, s3) diffs the
+ * same way.
+ *
+ * The lifecycle deep diff (./deep-diff.ts) compares a declared tree with a
+ * live one, and a live path no declaration claims is "unclaimed" there rather
+ * than a change. Two index versions are both observed, so this comparison is
+ * symmetric.
+ *
+ * Rules:
+ *
+ *  - One scope per diff. Two versions whose `stamp.scopeKey` differ are
+ *    refused by name with {@link IndexScopeMismatch}: a node missing from one
+ *    could just be out of its scope.
+ *  - A node is removed only when the later read listed its (type, location).
+ *    Otherwise it is `not-observed` in that read, with the coverage verdict
+ *    that says why. The other way round, a node is added only when the earlier
+ *    read listed its (type, location). Coverage is looked up with
+ *    {@link indexCoverageFor}, where `"*"` matches every type or location.
+ *    {@link indexAbsence} is that rule on its own, for #4526's drift from an
+ *    index, so both read "absent" the same way.
+ *  - An edge is removed (or added) only when both its ends were observed in
+ *    the read that lacks it; otherwise it is `not-observed`.
+ *  - Properties: `kind`, and each leaf path of `attrs` (arrays compare as
+ *    whole values). `tags` is compared only for a node whose `attrs` show no
+ *    change, because a lister's tags are a projection of the listed
+ *    properties: one tag edit is one changed property, not two. `facts` is
+ *    never compared (its `observedAt` moves on every read).
+ *  - Two versions with the same `stamp.digest` hold the same graph and
+ *    coverage: the diff is `unchanged` and nothing is walked.
+ */
+import { NEXT_RELEASE } from "../release-floors.js";
+import { indexCoverageFor, isIndexVersionName } from "./index-document.js";
+/** The first chant that exports the index diff and `chant index diff`. */
+export const INDEX_DIFF_FLOOR = NEXT_RELEASE;
+export const INDEX_CHANGE_KINDS = ["added", "removed", "changed", "not-observed"];
+/** Two versions of different scopes. Refused by name, never diffed. */
+export class IndexScopeMismatch extends Error {
+    constructor(fromScopeKey, toScopeKey) {
+        super(`refused: the two index versions have different scopes (${fromScopeKey} and ${toScopeKey}), and a node missing from one could just be out of its scope. Diff two versions of one scope.`);
+        this.fromScopeKey = fromScopeKey;
+        this.toScopeKey = toScopeKey;
+        this.code = "index-scope-mismatch";
+        this.name = "IndexScopeMismatch";
+    }
+}
+/** A document that is not an index version, or a reference no store holds. */
+export class NotAnIndexVersion extends Error {
+    constructor(message) {
+        super(message);
+        this.code = "not-an-index-version";
+        this.name = "NotAnIndexVersion";
+    }
+}
+/** The inverse of index-document.ts encodeIndexSegment; a segment that is not percent-encoded comes back as it is. */
+function decodeSegment(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+}
+/**
+ * A node's (type, location): its own `listedType` and `location` (#4521
+ * writes both), else the path-style id's fourth and third segments
+ * (behold#1025 Q2, `<substrate>/<scopeId>/<location>/<listedType>/<nativeId>`),
+ * else its kind at every location.
+ */
+export function indexNodeTypeAndLocation(n) {
+    if (n.listedType && n.location)
+        return { listedType: n.listedType, location: n.location };
+    const parts = n.id.split("/");
+    if (parts.length >= 5)
+        return { listedType: n.listedType ?? decodeSegment(parts[3]), location: n.location ?? decodeSegment(parts[2]) };
+    return { listedType: n.listedType ?? n.kind, location: n.location ?? "*" };
+}
+/**
+ * The rule for an absent node (#4533, shared with #4526): absent counts as
+ * gone (`removed`) only where the read's coverage says `listed` for the
+ * node's (type, location); anywhere else it is `not-observed`, with the
+ * verdict, or `not-in-coverage` when no entry speaks for it.
+ */
+export function indexAbsence(coverage, listedType, location) {
+    const e = indexCoverageFor(coverage, listedType, location);
+    if (e?.verdict === "listed")
+        return { kind: "removed" };
+    return e ? { kind: "not-observed", verdict: e.verdict, ...(e.detail ? { detail: e.detail } : {}) } : { kind: "not-observed", verdict: "not-in-coverage" };
+}
+function stampOf(doc, version) {
+    const s = doc.stamp;
+    return {
+        scopeKey: s.scopeKey,
+        observedAt: s.observedAt,
+        ...(s.completedAt ? { completedAt: s.completedAt } : {}),
+        digest: s.digest,
+        ...(s.source ? { source: s.source } : {}),
+        ...(version ? { version } : {}),
+    };
+}
+function check(doc, which) {
+    if (!doc || doc.index !== "v1" || typeof doc.stamp?.scopeKey !== "string" || !Array.isArray(doc.graph?.nodes)) {
+        throw new NotAnIndexVersion(`the ${which} document is not an index version (index: "v1" with a stamp and a graph)`);
+    }
+}
+const isPlain = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** JSON with keys sorted, so equal values compare equal. */
+function canon(v) {
+    return JSON.stringify(v, (_k, x) => (isPlain(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x)) ?? "undefined";
+}
+/** Leaf paths of an object; arrays and scalars are leaves. */
+function leaves(v, prefix, out) {
+    if (isPlain(v) && Object.keys(v).length > 0) {
+        for (const [k, x] of Object.entries(v))
+            leaves(x, prefix ? `${prefix}.${k}` : k, out);
+    }
+    else if (prefix) {
+        out.set(prefix, v);
+    }
+}
+function changedPaths(before, after, root) {
+    const a = new Map();
+    const b = new Map();
+    leaves(before ?? {}, root, a);
+    leaves(after ?? {}, root, b);
+    const out = [];
+    for (const path of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+        const x = a.get(path);
+        const y = b.get(path);
+        if (canon(x) === canon(y))
+            continue;
+        out.push({ path, ...(a.has(path) ? { before: x } : {}), ...(b.has(path) ? { after: y } : {}) });
+    }
+    return out;
+}
+/** The property changes of one node between two reads. */
+export function indexNodePropertyChanges(before, after) {
+    const out = [];
+    if (before.kind !== after.kind)
+        out.push({ path: "kind", before: before.kind, after: after.kind });
+    const attrs = changedPaths(before.attrs, after.attrs, "attrs");
+    out.push(...attrs);
+    if (attrs.length === 0)
+        out.push(...changedPaths(before.tags, after.tags, "tags"));
+    return out;
+}
+function edgeKey(e) {
+    return [e.from, e.to, e.kind ?? "", e.viaAttr ?? "", e.relation ?? "reference"].join("\u0000");
+}
+function edgeRef(e) {
+    return {
+        from: e.from,
+        to: e.to,
+        kind: e.kind ?? "",
+        ...(e.viaAttr ? { viaAttr: e.viaAttr } : {}),
+        relation: e.relation ?? "reference",
+        ...(e.origin ? { origin: e.origin } : {}),
+        ...(e.rule ? { rule: e.rule } : {}),
+    };
+}
+const refOf = (n) => ({ key: n.id, kind: n.kind, ...indexNodeTypeAndLocation(n) });
+const byKey = ([a], [b]) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * What changed from `from` to `to`, two versions of one index scope.
+ * Throws {@link IndexScopeMismatch} when their scope keys differ, and
+ * {@link NotAnIndexVersion} for a document of another shape.
+ */
+export function diffIndexVersions(from, to, o = {}) {
+    check(from, "first");
+    check(to, "second");
+    if (from.stamp.scopeKey !== to.stamp.scopeKey)
+        throw new IndexScopeMismatch(from.stamp.scopeKey, to.stamp.scopeKey);
+    const out = {
+        diff: "v1",
+        scopeKey: from.stamp.scopeKey,
+        from: stampOf(from, o.fromVersion),
+        to: stampOf(to, o.toVersion),
+        unchanged: false,
+        nodes: { added: [], removed: [], changed: [], notObserved: [] },
+        edges: { added: [], removed: [], notObserved: [] },
+        coverage: [],
+        counts: { added: 0, removed: 0, changed: 0, properties: 0, notObserved: 0, edgesAdded: 0, edgesRemoved: 0, edgesNotObserved: 0 },
+    };
+    if (from.stamp.digest && from.stamp.digest === to.stamp.digest) {
+        out.unchanged = true;
+        return out;
+    }
+    const absence = (doc, n) => {
+        const { listedType, location } = indexNodeTypeAndLocation(n);
+        return indexAbsence(doc.coverage, listedType, location);
+    };
+    const unobserved = (n, a, side) => ({
+        ...refOf(n),
+        side,
+        verdict: a.verdict,
+        ...(a.detail ? { detail: a.detail } : {}),
+    });
+    const before = new Map(from.graph.nodes.map((n) => [n.id, n]));
+    const after = new Map(to.graph.nodes.map((n) => [n.id, n]));
+    for (const [id, n] of [...before].sort(byKey)) {
+        const m = after.get(id);
+        if (m) {
+            const properties = indexNodePropertyChanges(n, m);
+            if (properties.length > 0)
+                out.nodes.changed.push({ ...refOf(m), properties });
+            continue;
+        }
+        const a = absence(to, n);
+        if (a.kind === "removed")
+            out.nodes.removed.push(refOf(n));
+        else
+            out.nodes.notObserved.push(unobserved(n, a, "to"));
+    }
+    for (const [id, n] of [...after].sort(byKey)) {
+        if (before.has(id))
+            continue;
+        const a = absence(from, n);
+        if (a.kind === "removed")
+            out.nodes.added.push(refOf(n));
+        else
+            out.nodes.notObserved.push(unobserved(n, a, "from"));
+    }
+    // An edge's ends are looked up in either read: a removed edge's ends may be gone from `to`.
+    const nodeFor = (id) => after.get(id) ?? before.get(id) ?? { id, kind: "" };
+    const edgesIn = (doc) => new Map(doc.graph.edges.map((e) => [edgeKey(e), e]));
+    const ea = edgesIn(from);
+    const eb = edgesIn(to);
+    const classify = (e, lacking, side, into) => {
+        for (const end of [e.from, e.to]) {
+            const a = absence(lacking, nodeFor(end));
+            if (a.kind === "not-observed") {
+                out.edges.notObserved.push({ ...edgeRef(e), side, unobservedEnd: end, verdict: a.verdict });
+                return;
+            }
+        }
+        into.push(edgeRef(e));
+    };
+    for (const [k, e] of [...ea].sort(byKey))
+        if (!eb.has(k))
+            classify(e, to, "to", out.edges.removed);
+    for (const [k, e] of [...eb].sort(byKey))
+        if (!ea.has(k))
+            classify(e, from, "from", out.edges.added);
+    const cov = new Map();
+    for (const e of from.coverage)
+        cov.set(`${e.listedType}\u0000${e.location}`, { listedType: e.listedType, location: e.location, before: e.verdict });
+    for (const e of to.coverage) {
+        const k = `${e.listedType}\u0000${e.location}`;
+        cov.set(k, { ...(cov.get(k) ?? { listedType: e.listedType, location: e.location }), after: e.verdict });
+    }
+    out.coverage = [...cov.values()]
+        .filter((c) => c.before !== c.after)
+        .sort((a, b) => (a.listedType + "\u0000" + a.location < b.listedType + "\u0000" + b.location ? -1 : 1));
+    out.counts = {
+        added: out.nodes.added.length,
+        removed: out.nodes.removed.length,
+        changed: out.nodes.changed.length,
+        properties: out.nodes.changed.reduce((s, c) => s + c.properties.length, 0),
+        notObserved: out.nodes.notObserved.length,
+        edgesAdded: out.edges.added.length,
+        edgesRemoved: out.edges.removed.length,
+        edgesNotObserved: out.edges.notObserved.length,
+    };
+    return out;
+}
+/**
+ * Parse `<scopeKey>/<version>` or `<scopeKey>`. A bare version name (no
+ * scope) takes `inScope`'s scope, so `--against <version>` can name another
+ * version of the first argument's scope.
+ */
+export function parseIndexVersionRef(ref, inScope) {
+    const trimmed = ref.replace(/^\/+|\/+$/g, "");
+    const slash = trimmed.lastIndexOf("/");
+    const last = slash < 0 ? trimmed : trimmed.slice(slash + 1);
+    if (isIndexVersionName(last)) {
+        if (slash >= 0)
+            return { scopeKey: trimmed.slice(0, slash), version: last };
+        if (!inScope)
+            throw new NotAnIndexVersion(`"${ref}" is a version name with no scope: name it as <scopeKey>/${last}`);
+        return { scopeKey: inScope, version: last };
+    }
+    if (!trimmed)
+        throw new NotAnIndexVersion("an empty index version reference");
+    return { scopeKey: trimmed };
+}
+/** Read one version (or a scope's latest) through the store. Throws {@link NotAnIndexVersion} when the store has none. */
+export async function readIndexVersionRef(store, ref) {
+    const version = ref.version ?? (await store.listIndex(ref.scopeKey)).pop();
+    if (!version)
+        throw new NotAnIndexVersion(`the ${store.kind} store holds no index version under ${ref.scopeKey}`);
+    const doc = await store.readIndexAt(ref.scopeKey, version);
+    if (!doc)
+        throw new NotAnIndexVersion(`the ${store.kind} store holds no index version ${ref.scopeKey}/${version}`);
+    return { scopeKey: ref.scopeKey, version, doc };
+}
+/**
+ * Diff two stored versions. `to` absent: `from` names a scope (or a version
+ * in one), and the diff is the scope's last two versions, or the version
+ * before `from` against `from`. Two references under different scope paths
+ * are refused before either is read.
+ */
+export async function diffIndexVersionRefs(store, from, to) {
+    let a = from;
+    let b = to;
+    if (!b) {
+        const versions = await store.listIndex(from.scopeKey);
+        const at = from.version ? versions.indexOf(from.version) : versions.length - 1;
+        if (at < 1)
+            throw new NotAnIndexVersion(`the ${store.kind} store holds no version before ${from.version ?? "the latest"} under ${from.scopeKey}: name two versions`);
+        a = { scopeKey: from.scopeKey, version: versions[at - 1] };
+        b = { scopeKey: from.scopeKey, version: versions[at] };
+    }
+    if (a.scopeKey !== b.scopeKey)
+        throw new IndexScopeMismatch(a.scopeKey, b.scopeKey);
+    const x = await readIndexVersionRef(store, a);
+    const y = await readIndexVersionRef(store, b);
+    return diffIndexVersions(x.doc, y.doc, { fromVersion: x.version, toVersion: y.version });
+}