@intentius/chant 0.124.52 → 0.124.54

package/dist/lifecycle/index-import.js

@@ -0,0 +1,515 @@
+/**
+ * `chant import --index` (#4524, the step from tier 1 to tier 2 of
+ * INTENTIUS/behold#1025): typed source for indexed resources. Nothing is
+ * applied and nothing is written to the cloud.
+ *
+ * {@link planIndexImport} is the pure part. It takes the documents of one
+ * index read, a selection and the lexicons, and returns one import IR per
+ * output group plus the report. The caller (../cli/commands/import-index.ts)
+ * hands each IR to the lexicon's own `templateGenerator()`, the codegen
+ * `chant import <template>` uses, and writes the files.
+ *
+ * Rules:
+ * - each selected node goes to the lexicon its kind belongs to. A lexicon
+ *   writes it only through its `indexImport` seam ({@link IndexImportCodegen}).
+ *   A node of unknown kind, or of a lexicon with no seam, is reported as
+ *   unsupported by name and written nowhere;
+ * - a node already declared in the project (the identity matcher, #4523,
+ *   bound an entity to it) is reported as declared with the entity's name and
+ *   is not imported again ({@link declaredNodes});
+ * - a derived edge (#4522, `origin: "derived"`) becomes a reference when its
+ *   target is imported into the same group and the lexicon can spell the
+ *   value as a reference to it. Otherwise the value stays a literal, and a
+ *   comment in the file names the edge and why;
+ * - a value the listing masked (`[REDACTED]`) is never written. Each one
+ *   becomes a parameter to fill in;
+ * - output is deterministic: nodes, edges, parameters and logical ids are
+ *   ordered by id, so the same index and selection give the same IR, and the
+ *   same files.
+ *
+ * The report names each resource's identity (substrate, scope id, listed
+ * type, location, native id) and cloud ids, for the adoption step that
+ * follows (INTENTIUS/choudoufu#2284).
+ */
+import { createHash } from "node:crypto";
+import { MASKED } from "../deep-observation.js";
+import { readPath } from "../graph-refs.js";
+import { matchDeclaredToIndex } from "./identity-match.js";
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** Locations that hold global types, as derive-edges.ts reads them. */
+const GLOBAL_LOCATIONS = new Set(["global", "cluster", ""]);
+function canonicalSelection(sel) {
+    const sortU = (xs) => (xs && xs.length > 0 ? [...new Set(xs)].sort(byString) : undefined);
+    const out = {};
+    if (sel.all)
+        out.all = true;
+    const types = sortU(sel.types);
+    if (types)
+        out.types = types;
+    const names = sortU(sel.names);
+    if (names)
+        out.names = names;
+    const nodes = sortU(sel.nodes);
+    if (nodes)
+        out.nodes = nodes;
+    if (sel.tags && Object.keys(sel.tags).length > 0) {
+        out.tags = Object.fromEntries(Object.keys(sel.tags).sort(byString).map((k) => [k, sel.tags[k]]));
+    }
+    return out;
+}
+/** True when the selection names nothing: no `all` and no filter. An empty selection selects no node. */
+export function selectionIsEmpty(sel) {
+    const c = canonicalSelection(sel);
+    return !c.all && !c.types && !c.names && !c.nodes && !c.tags;
+}
+/** Whether a node is selected. */
+export function nodeSelected(node, sel) {
+    if (selectionIsEmpty(sel))
+        return false;
+    if (sel.all)
+        return true;
+    if (sel.types && sel.types.length > 0 && !sel.types.includes(node.listedType ?? node.kind) && !sel.types.includes(node.kind))
+        return false;
+    if (sel.names && sel.names.length > 0 && !sel.names.includes(node.nativeId ?? "") && !sel.names.includes(node.id))
+        return false;
+    if (sel.nodes && sel.nodes.length > 0 && !sel.nodes.includes(node.id))
+        return false;
+    if (sel.tags) {
+        for (const [k, v] of Object.entries(sel.tags))
+            if (node.tags?.[k] !== v)
+                return false;
+    }
+    return true;
+}
+/**
+ * The indexed nodes the project already declares, keyed by node id, with
+ * the entity's name: the identity matcher (#4523) run once per location the
+ * index holds, for each lexicon that declares an `indexIdentity`. A node two
+ * entities bind keeps the first by entity name.
+ */
+export function declaredNodes(docs, entitiesByLexicon, identities) {
+    const out = new Map();
+    if (docs.length === 0)
+        return out;
+    const scope = docs[0].stamp.scope;
+    if (scope.kind !== "cloud")
+        return out;
+    const locations = [...new Set(docs.flatMap((d) => d.graph.nodes.map((n) => n.location ?? "")))]
+        .filter((l) => !GLOBAL_LOCATIONS.has(l))
+        .sort(byString);
+    for (const { name, indexIdentity } of [...identities].sort((a, b) => byString(a.name, b.name))) {
+        if (!indexIdentity || indexIdentity.substrate !== scope.substrate)
+            continue;
+        const entities = entitiesByLexicon.get(name) ?? [];
+        if (entities.length === 0)
+            continue;
+        // A global type matches at `global` whatever the region; one pass with no region covers it.
+        for (const region of locations.length > 0 ? locations : [undefined]) {
+            const { matches } = matchDeclaredToIndex(entities, docs, indexIdentity, region ? { region } : {});
+            for (const m of Object.values(matches)) {
+                if (m.verdict === "bound" && !out.has(m.node))
+                    out.set(m.node, m.entity);
+            }
+        }
+    }
+    return out;
+}
+function pascalWords(s) {
+    return s
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join("");
+}
+function shortHash(s) {
+    return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+/** The kind's last `::`, `/` or `.` segment: `Bucket` for `AWS::S3::Bucket`. */
+function defaultTypeLabel(node) {
+    const parts = node.kind.split(/::|\/|\./).filter(Boolean);
+    return pascalWords(parts[parts.length - 1] ?? "Resource") || "Resource";
+}
+/**
+ * `<TypeLabel><NativeId in PascalCase>`, letters and digits only. A long id
+ * keeps its tail and a hash of the node id. Collisions take a number, in
+ * node id order, so the names are stable.
+ */
+function assignLogicalIds(nodes, label) {
+    const out = new Map();
+    const used = new Set();
+    for (const n of [...nodes].sort((a, b) => byString(a.id, b.id))) {
+        const native = n.nativeId ?? n.id;
+        // An ARN or a URL: its last path segment names the object.
+        const tail = native.includes("/") ? native.slice(native.lastIndexOf("/") + 1) || native : native;
+        const prefix = label(n);
+        let words = tail.split(/[^A-Za-z0-9]+/).filter(Boolean);
+        // `vpc-0a1` under `VPC` reads `VPC0a1`, not `VPCVpc0a1`.
+        if (words.length > 1 && words[0].toLowerCase() === prefix.toLowerCase())
+            words = words.slice(1);
+        let id = pascalWords(words.join("-"));
+        if (id.length > 48)
+            id = `${id.slice(-40)}${shortHash(n.id)}`;
+        let base = `${prefix}${id}`;
+        if (!/^[A-Za-z]/.test(base))
+            base = `R${base}`;
+        let name = base;
+        for (let i = 2; used.has(name); i++)
+            name = `${base}${i}`;
+        used.add(name);
+        out.set(n.id, name);
+    }
+    return out;
+}
+/** The path a derived edge's rule names on its holder, or undefined (identity-match and tag rules name none). */
+export function edgeRulePath(edge, holder) {
+    const rule = edge.rule;
+    if (!rule)
+        return undefined;
+    const prefix = `${holder.lexicon}:${holder.kind}:`;
+    if (!rule.startsWith(prefix))
+        return undefined;
+    const path = rule.slice(prefix.length);
+    return path.startsWith("tag:") ? undefined : path;
+}
+/**
+ * Rewrite the string leaves at `path` (`a.b`, `arr[].id`, as readPath reads
+ * it). A path that ends on an array rewrites its string elements. Returns
+ * the new tree and the dotted paths it changed.
+ */
+function rewriteAtPath(tree, path, fn) {
+    const changed = [];
+    const parts = path.split(".");
+    const walk = (value, i, at) => {
+        if (i === parts.length) {
+            if (typeof value === "string") {
+                const r = fn(value);
+                if (r !== undefined) {
+                    changed.push(at);
+                    return r;
+                }
+                return value;
+            }
+            if (Array.isArray(value))
+                return value.map((v, j) => walk(v, i, `${at}[${j}]`));
+            return value;
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return value;
+        const part = parts[i];
+        const isArr = part.endsWith("[]");
+        const key = isArr ? part.slice(0, -2) : part;
+        const obj = value;
+        if (!(key in obj))
+            return value;
+        const here = at === "" ? key : `${at}.${key}`;
+        const child = obj[key];
+        let next;
+        if (isArr) {
+            if (!Array.isArray(child))
+                return value;
+            next = child.map((c, j) => walk(c, i + 1, `${here}[${j}]`));
+        }
+        else {
+            next = walk(child, i + 1, here);
+        }
+        return next === child ? value : { ...obj, [key]: next };
+    };
+    return { tree: walk(tree, 0, ""), changed };
+}
+/** Every string leaf, outside `Tags`, as a dotted path (identity-match edges name no path). */
+function stringLeafPaths(tree, at = "") {
+    if (typeof tree === "string")
+        return [at];
+    if (Array.isArray(tree))
+        return tree.flatMap((v, j) => stringLeafPaths(v, `${at}[${j}]`));
+    if (tree === null || typeof tree !== "object")
+        return [];
+    return Object.keys(tree)
+        .sort(byString)
+        .filter((k) => !(at === "" && (k === "Tags" || k === "tags")))
+        .flatMap((k) => stringLeafPaths(tree[k], at === "" ? k : `${at}.${k}`));
+}
+/** A path with explicit indices (`a[2].b`) as readPath/rewriteAtPath segments over one leaf. */
+function exactPathParts(path) {
+    const out = [];
+    for (const seg of path.split(".")) {
+        const m = /^([^[]*)((?:\[\d+\])*)$/.exec(seg);
+        if (!m) {
+            out.push(seg);
+            continue;
+        }
+        if (m[1] !== "")
+            out.push(m[1]);
+        for (const idx of m[2].matchAll(/\[(\d+)\]/g))
+            out.push(Number(idx[1]));
+    }
+    return out;
+}
+function setExact(tree, parts, value) {
+    if (parts.length === 0)
+        return value;
+    const [head, ...rest] = parts;
+    if (typeof head === "number") {
+        if (!Array.isArray(tree))
+            return tree;
+        const copy = [...tree];
+        copy[head] = setExact(copy[head], rest, value);
+        return copy;
+    }
+    if (tree === null || typeof tree !== "object" || Array.isArray(tree))
+        return tree;
+    const obj = tree;
+    return { ...obj, [head]: setExact(obj[head], rest, value) };
+}
+function getExact(tree, parts) {
+    let cur = tree;
+    for (const p of parts) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+/** Every masked leaf, as a dotted path with indices, in key order. */
+function maskedPaths(tree, at = "") {
+    if (tree === MASKED)
+        return [at];
+    if (Array.isArray(tree))
+        return tree.flatMap((v, j) => maskedPaths(v, `${at}[${j}]`));
+    if (tree === null || typeof tree !== "object")
+        return [];
+    return Object.keys(tree)
+        .sort(byString)
+        .flatMap((k) => maskedPaths(tree[k], at === "" ? k : `${at}.${k}`));
+}
+function identityOf(doc, node) {
+    const scope = doc.stamp.scope;
+    return {
+        substrate: scope.kind === "cloud" ? scope.substrate : node.lexicon,
+        scopeId: scope.kind === "cloud" ? scope.scopeId : doc.stamp.scopeKey,
+        listedType: node.listedType ?? node.kind,
+        location: node.location ?? "",
+        nativeId: node.nativeId ?? node.physicalId ?? node.id,
+    };
+}
+/**
+ * Plan an import from the documents of one index read. Pure; throws only on
+ * documents from two accounts or two reads, as derive-edges.ts does.
+ */
+export function planIndexImport(docs, selection, lexicons, options = {}) {
+    const first = docs[0]?.stamp;
+    for (const d of docs) {
+        if (first && (d.stamp.observedAt !== first.observedAt || JSON.stringify(scopeAccount(d)) !== JSON.stringify(scopeAccount(docs[0])))) {
+            throw new Error(`an index import reads one read of one account: ${first.scopeKey} and ${d.stamp.scopeKey} differ`);
+        }
+    }
+    const sel = canonicalSelection(selection);
+    const declared = options.declared ?? new Map();
+    const byLexicon = new Map(lexicons.map((l) => [l.name, l]));
+    const docOf = new Map();
+    const nodes = [];
+    for (const d of docs) {
+        for (const n of d.graph.nodes) {
+            if (docOf.has(n.id))
+                continue;
+            docOf.set(n.id, d);
+            nodes.push(n);
+        }
+    }
+    nodes.sort((a, b) => byString(a.id, b.id));
+    const nodeById = new Map(nodes.map((n) => [n.id, n]));
+    const edges = docs
+        .flatMap((d) => d.graph.edges)
+        .filter((e) => e.origin === "derived")
+        .sort((a, b) => byString(`${a.from}\u0000${a.rule ?? ""}\u0000${a.to}`, `${b.from}\u0000${b.rule ?? ""}\u0000${b.to}`));
+    const reports = new Map();
+    const writable = [];
+    for (const node of nodes) {
+        if (!nodeSelected(node, sel))
+            continue;
+        const doc = docOf.get(node.id);
+        const base = {
+            node: node.id,
+            identity: identityOf(doc, node),
+            cloudIds: (node.facts?.cloudIds ?? []).map((c) => ({ kind: c.kind, value: c.value })),
+            ...(node.facts?.markers ? { markers: node.facts.markers } : {}),
+            lexicon: node.lexicon,
+            kind: node.kind,
+            status: "unsupported",
+        };
+        const entity = declared.get(node.id);
+        if (entity !== undefined) {
+            reports.set(node.id, { ...base, status: "declared", entity, reason: `already declared as ${entity}; not imported again` });
+            continue;
+        }
+        if (node.unmappedKind) {
+            reports.set(node.id, { ...base, reason: `no lexicon kind maps the listed type ${node.listedType ?? node.kind}` });
+            continue;
+        }
+        const lexicon = byLexicon.get(node.lexicon);
+        if (!lexicon) {
+            reports.set(node.id, { ...base, reason: `the ${node.lexicon} lexicon is not loaded` });
+            continue;
+        }
+        if (!lexicon.indexImport) {
+            reports.set(node.id, { ...base, reason: `the ${node.lexicon} lexicon has no index import codegen (indexImport)` });
+            continue;
+        }
+        const r = lexicon.indexImport.resource(node);
+        if ("unsupported" in r) {
+            reports.set(node.id, { ...base, reason: r.unsupported });
+            continue;
+        }
+        reports.set(node.id, { ...base, status: "imported" });
+        writable.push({ node, codegen: lexicon.indexImport, type: r.type, properties: r.properties, ...(r.attributes ? { attributes: r.attributes } : {}) });
+    }
+    // Groups: lexicon + location. Global nodes join their lexicon's only regional group, when there is one.
+    const regional = new Map();
+    for (const w of writable) {
+        const loc = w.node.location ?? "";
+        if (!GLOBAL_LOCATIONS.has(loc))
+            (regional.get(w.node.lexicon) ?? regional.set(w.node.lexicon, new Set()).get(w.node.lexicon)).add(loc);
+    }
+    const groupLocation = (n) => {
+        const loc = n.location ?? "";
+        if (!GLOBAL_LOCATIONS.has(loc))
+            return loc;
+        const regions = regional.get(n.lexicon);
+        return regions && regions.size === 1 ? [...regions][0] : loc === "" ? "global" : loc;
+    };
+    const groupKeys = [...new Set(writable.map((w) => `${w.node.lexicon}/${groupLocation(w.node)}`))].sort(byString);
+    const single = groupKeys.length === 1;
+    const groupDir = (n) => (single ? "" : `${n.lexicon}/${groupLocation(n)}`);
+    const logicalIds = new Map();
+    for (const key of groupKeys) {
+        const members = writable.filter((w) => `${w.node.lexicon}/${groupLocation(w.node)}` === key);
+        const codegen = members[0].codegen;
+        const label = (n) => codegen.typeLabel?.(n) ?? defaultTypeLabel(n);
+        for (const [id, name] of assignLogicalIds(members.map((m) => m.node), label))
+            logicalIds.set(id, name);
+    }
+    const groups = [];
+    const parameterReports = [];
+    for (const key of groupKeys) {
+        const members = writable.filter((w) => `${w.node.lexicon}/${groupLocation(w.node)}` === key);
+        const dir = groupDir(members[0].node);
+        const header = [];
+        const resources = [];
+        const parameters = [];
+        const usedParams = new Set();
+        for (const w of members) {
+            const logicalId = logicalIds.get(w.node.id);
+            const report = reports.get(w.node.id);
+            report.logicalId = logicalId;
+            report.group = dir;
+            let props = w.properties;
+            const references = [];
+            for (const e of edges.filter((x) => x.from === w.node.id)) {
+                const target = nodeById.get(e.to);
+                const path = edgeRulePath(e, w.node);
+                const literal = (reason) => {
+                    const at = path ?? e.viaAttr ?? "";
+                    references.push({ path: at, target: e.to, ...(e.rule ? { rule: e.rule } : {}), written: "literal", reason });
+                    const values = path ? readPath(props, path) : [];
+                    header.push(`${logicalId}.${at}${values.length > 0 ? ` = ${values.map((v) => JSON.stringify(v)).join(", ")}` : ""} stays a literal: ` +
+                        `derived edge ${e.rule ?? "(no rule)"} to ${e.to}; ${reason}`);
+                };
+                if (e.rule && edgeRulePath(e, w.node) === undefined && e.rule.startsWith(`${w.node.lexicon}:${w.node.kind}:tag:`)) {
+                    literal("a tag rule names no property to reference");
+                    continue;
+                }
+                if (!target) {
+                    literal("the target is not in the index");
+                    continue;
+                }
+                const targetDeclared = declared.get(target.id);
+                if (targetDeclared !== undefined) {
+                    literal(`the target is already declared as ${targetDeclared}`);
+                    continue;
+                }
+                const targetReport = reports.get(target.id);
+                if (!targetReport) {
+                    literal("the target is not in the selection");
+                    continue;
+                }
+                if (targetReport.status !== "imported") {
+                    literal(`the target is not imported (${targetReport.reason ?? targetReport.status})`);
+                    continue;
+                }
+                if (groupDir(target) !== dir || target.lexicon !== w.node.lexicon) {
+                    literal(`the target is written to another group (${groupDir(target) || "."})`);
+                    continue;
+                }
+                const t = { logicalId: logicalIds.get(target.id), node: target };
+                const changed = [];
+                if (path) {
+                    const r = rewriteAtPath(props, path, (v) => w.codegen.reference(v, t));
+                    props = r.tree;
+                    changed.push(...r.changed);
+                }
+                else {
+                    for (const leaf of stringLeafPaths(props)) {
+                        const parts = exactPathParts(leaf);
+                        const v = getExact(props, parts);
+                        if (typeof v !== "string")
+                            continue;
+                        const ref = w.codegen.reference(v, t);
+                        if (ref === undefined)
+                            continue;
+                        props = setExact(props, parts, ref);
+                        changed.push(leaf);
+                    }
+                }
+                if (changed.length === 0) {
+                    literal(`the ${w.node.lexicon} lexicon cannot spell the value as a reference to ${t.logicalId}`);
+                    continue;
+                }
+                for (const at of changed)
+                    references.push({ path: at, target: e.to, ...(e.rule ? { rule: e.rule } : {}), written: "reference" });
+            }
+            const params = [];
+            for (const at of maskedPaths(props)) {
+                let name = `${logicalId}${pascalWords(at)}`;
+                for (let i = 2; usedParams.has(name); i++)
+                    name = `${logicalId}${pascalWords(at)}${i}`;
+                usedParams.add(name);
+                parameters.push(w.codegen.secretParameter(name, { node: w.node, logicalId, path: at }));
+                props = setExact(props, exactPathParts(at), w.codegen.parameterReference(name));
+                params.push(name);
+                parameterReports.push({ name, node: w.node.id, path: at, group: dir });
+                header.push(`${logicalId}.${at} was masked in the index; fill in the parameter ${name}`);
+            }
+            if (references.length > 0)
+                report.references = references;
+            if (params.length > 0)
+                report.parameters = params;
+            resources.push({ logicalId, type: w.type, properties: props, ...(w.attributes && Object.keys(w.attributes).length > 0 ? { attributes: w.attributes } : {}) });
+        }
+        const [lexicon, ...loc] = key.split("/");
+        groups.push({ dir, lexicon, location: loc.join("/"), ir: { resources, parameters }, header });
+    }
+    const report = {
+        report: "chant-index-import/v1",
+        index: [...docs]
+            .map((d) => ({ scopeKey: d.stamp.scopeKey, observedAt: d.stamp.observedAt, digest: d.stamp.digest, source: d.stamp.source.name }))
+            .sort((a, b) => byString(a.scopeKey, b.scopeKey)),
+        selection: sel,
+        resources: [...reports.values()].sort((a, b) => byString(a.node, b.node)),
+        parameters: parameterReports,
+        groups: groups.map((g) => ({ group: g.dir, lexicon: g.lexicon, location: g.location, resources: g.ir.resources.length })),
+    };
+    return { groups, report };
+}
+function scopeAccount(d) {
+    const s = d.stamp.scope;
+    return s.kind === "cloud" ? [s.substrate, s.scopeId] : [s.kind, d.stamp.scopeKey];
+}
+/** The header comment for a group's first file. Same plan, same text. */
+export function indexImportHeader(plan, group) {
+    const lines = [
+        "Generated by chant import --index. Nothing was applied. Review before committing.",
+        ...plan.report.index.map((i) => `index ${i.scopeKey} read ${i.observedAt} (digest ${i.digest.slice(0, 12)})`),
+        ...group.header,
+    ];
+    return lines.map((l) => `// ${l.replace(/\r?\n/g, " ")}`).join("\n") + "\n\n";
+}

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

@@ -0,0 +1,129 @@
+/**
+ * `chant search --index <ref>` (#4525): an index version as the observed side
+ * of a search, joined to the declared rows.
+ *
+ * Two halves, both pure apart from {@link readIndexRef}'s store read:
+ *
+ * - a ref names one index version in the store (#4519, ./index-document.ts):
+ *   `<scope key>`, `<scope key>@latest`, `<scope key>@<version>` or
+ *   `<scope key>/<version>.json`, where the scope key is `stamp.scopeKey`
+ *   (`cloud/aws/<account>/<scope digest>`) and a version is a name the store
+ *   lists (`20261026T091403Z-<digest12>`, with or without `.json`);
+ * - {@link joinDeclaredToIndex} gives every declared node a join verdict
+ *   and lays the bound indexed nodes over the declared canvas, the way
+ *   `--live` lays a live read over it (`sourceOverlayGraphs`).
+ *
+ * The join goes through each lexicon's own index match, its plugin's
+ * `indexIdentity` (#4523, ./identity-match.ts). aws has one; a lexicon with
+ * none gets `not-observed`, reason `unsupported-kind`, on every row, never a
+ * guessed match. The verdicts:
+ *
+ * - `bound`: one indexed node carries the identity the declaration spells;
+ * - `absent`: none does, and the index's coverage says it listed that type
+ *   and location;
+ * - `not-observed`: the index did not look (coverage `filtered`,
+ *   `not-reached`, a read failure), the lexicon has no index match, or the
+ *   index is of another substrate. Always with the reason and a detail;
+ * - `no-binding`: the declaration does not spell an identity (a
+ *   server-assigned id, a Ref), or the entity names no region and nothing
+ *   matched;
+ * - `ambiguous`: two or more indexed nodes carry the identity. None is bound.
+ *
+ * Indexed nodes no declared row binds stay out of a project's answer, as an
+ * undeclared resource stays out of a `--live` one; with no project the index
+ * is the whole graph ({@link indexOnlyGraph}).
+ */
+import { type GraphIR } from "../graph-ir.js";
+import type { UnobservedReason } from "../observation.js";
+import { type IndexIdentity } from "./identity-match.js";
+import { type IndexDocument } from "./index-document.js";
+import type { SnapshotStore } from "./snapshot-store.js";
+/** One index version, as a ref names it. */
+export interface IndexRef {
+    /** `stamp.scopeKey`: `<source path>/<scope path>`. */
+    scopeKey: string;
+    /** `latest`, or a version name with its `.json`. */
+    version: string;
+}
+/** Parse `--index <ref>`, or say why it is not one. */
+export declare function parseIndexRef(ref: string): IndexRef | {
+    error: string;
+    hint: string;
+};
+/** The ref as one string, version resolved: `<scope key>@<version name without .json>`. */
+export declare function formatIndexRef(scopeKey: string, versionName: string): string;
+export type IndexRead = {
+    doc: IndexDocument;
+    ref: IndexRef;
+    version: string;
+} | {
+    error: string;
+    hint?: string;
+};
+/**
+ * Read the version a ref names. A stamp that disagrees with itself or with
+ * the key it was read under is refused: the answer would be about another
+ * scope than the one asked for.
+ */
+export declare function readIndexRef(store: SnapshotStore, ref: IndexRef): Promise<IndexRead>;
+interface JoinBase {
+    /** The listed type and identifier the declaration spells, when it spells one. */
+    listedType?: string;
+    identifier?: string;
+    location?: string;
+}
+/** One declared row's join verdict. */
+export type IndexJoin = (JoinBase & {
+    verdict: "bound";
+    node: string;
+    nativeId: string;
+}) | (JoinBase & {
+    verdict: "absent";
+}) | (JoinBase & {
+    verdict: "not-observed";
+    reason: UnobservedReason;
+    detail: string;
+}) | (JoinBase & {
+    verdict: "no-binding";
+    detail: string;
+}) | (JoinBase & {
+    verdict: "ambiguous";
+    candidates: string[];
+    detail: string;
+});
+export type IndexJoinVerdict = IndexJoin["verdict"];
+/** Every verdict, in the order a summary lists them. */
+export declare const INDEX_JOIN_VERDICTS: readonly IndexJoinVerdict[];
+/** What the join needs of a lexicon: its name and its index match. */
+export interface JoinLexicon {
+    name: string;
+    indexIdentity?: IndexIdentity;
+}
+export interface JoinOptions {
+    /** The region of a declared node, from the stack it belongs to. */
+    regionOf?: (id: string) => string | undefined;
+}
+export interface IndexJoinResult {
+    /** The declared canvas with the bound indexed nodes laid over it. */
+    ir: GraphIR;
+    /** Every declared node's verdict, by node id. */
+    joins: Record<string, IndexJoin>;
+}
+/**
+ * Join every declared node to an index version. Pure: the lexicons come in
+ * as data. The canvas keeps every declared node and edge; a bound node takes
+ * the indexed node's physical id, attributes and facts, as `--live` gives a
+ * node its read's.
+ */
+export declare function joinDeclaredToIndex(declared: GraphIR, doc: IndexDocument, lexicons: readonly JoinLexicon[], options?: JoinOptions): IndexJoinResult;
+/**
+ * The index alone, for a search with no project: every indexed node, each
+ * with its native id as its physical id.
+ */
+export declare function indexOnlyGraph(doc: IndexDocument): GraphIR;
+/** How many rows carry each verdict, for the provenance line. */
+export declare function countJoins(joins: Record<string, IndexJoin>, ids: readonly string[]): Record<IndexJoinVerdict, number>;
+/** A row's verdict where a physical id would go: `(absent)`, `(not observed: filtered)`, `(ambiguous: 2 candidates)`. */
+export declare function joinCell(j: IndexJoin): string | undefined;
+export {};
+//# sourceMappingURL=index-join.d.ts.map

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

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