@north-light/crouter 0.3.227 → 0.3.228

package/dist/migrations/003-repository-root-memory-identity/index.js

@@ -0,0 +1,513 @@
+// 003 — replace per-store project identity with one repository-root declaration.
+//
+// The migration freezes both pre-003 identity shapes, resolves consumers against
+// that old corpus, then writes consumers before the repository identity cut.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, matchesGlob } from 'node:path';
+import { realpathOrSelf } from '../../core/fs-utils.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { loadStoreMemoryDocs, openProjectMemoryStore } from '../../core/memory-resolver.js';
+import { canonicalSegments, composeCanonicalName, explicitLocalName, INDEX_SEGMENT, localNameFromPath, normalizeDocName, normalizeNameSegment, resolveLocalName, stripNamespace, validateExplicitLocalName, validateNamespace, } from '../../core/memory/identity.js';
+import { lintMemoryStore, MEMORY_LINT_IDENTITY_RULES, resolvableCanonicalNames } from '../../core/memory/lint.js';
+import { completeRootFrontDoor, demoteLeafSurfaces, planFrontDoors, rootIndexSource, } from './front-door.js';
+import { planRepositories, } from './repository-facts.js';
+import { applySplices, itemFor, keyLineSpan, linkRewrites, OldCorpus, renderScalar, routeRewrites, valueSpan, viewsForStore, yamlBlock, yamlMap, } from './references.js';
+let planned = { links: [], routes: [], wrote: new Set(), repositories: [] };
+function emptyPlan(blockers = []) {
+    return {
+        blockers,
+        consumers: [],
+        identities: [],
+        repositories: [],
+        storePrefixes: [],
+        renames: [],
+        references: [],
+    };
+}
+/** Frozen pre-003 path-derived name: no project prefix and no INDEX collapse. */
+function pathNameNoCollapse(relPath) {
+    return canonicalSegments(relPath.replace(/\\/g, '/').replace(/\.md$/i, ''))
+        .map(normalizeNameSegment)
+        .join('/');
+}
+function rawExplicitName(doc) {
+    const raw = doc.frontmatter?.['name'];
+    return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : null;
+}
+function ownerDirOf(store) {
+    return store.descriptor.ownerDir ?? dirname(dirname(store.descriptor.storeRoot));
+}
+function isProjectStore(descriptor) {
+    return descriptor.scope === 'project' && descriptor.plugin === undefined;
+}
+function fallbackPrefix(store) {
+    const effectivePrefix = store.descriptor.namespace;
+    const ownerDir = ownerDirOf(store);
+    const oldPrefix = store.descriptor.plugin ?? '';
+    return {
+        store,
+        storeKey: store.key,
+        storeRoot: store.snapshot.root,
+        ownerDir,
+        repositoryKey: '',
+        repositoryRoot: ownerDir,
+        ownerRelativePath: '',
+        oldPrefix,
+        oldRule: 'pre-003',
+        effectivePrefix,
+        nestedDeclarationAction: 'none',
+        legacyDeclaration: null,
+    };
+}
+function repositoryForPrefix(prefix, repositories) {
+    return repositories.find((repository) => repository.repositoryRoot === prefix.repositoryRoot);
+}
+function buildDocFacts(store, prefix, repositories, blockers) {
+    const repository = repositoryForPrefix(prefix, repositories);
+    const facts = [];
+    if (store.snapshot.docs.length === 0)
+        return facts;
+    if (store.descriptor.plugin !== undefined) {
+        const valid = validateNamespace(prefix.effectivePrefix);
+        if (!valid.ok) {
+            blockers.push({
+                kind: 'namespace',
+                message: `plugin \`${store.descriptor.plugin}\` mounts its memory under \`${prefix.effectivePrefix}\`, which is not a valid namespace (${valid.reason}) — fix the plugin package and re-run`,
+                storeRoot: store.key,
+                name: prefix.effectivePrefix,
+            });
+        }
+    }
+    for (const doc of store.snapshot.docs) {
+        const pathLocal = localNameFromPath(doc.relPath);
+        if (pathLocal === '' && !isProjectStore(store.descriptor) && store.descriptor.plugin === undefined) {
+            blockers.push({
+                kind: 'namespace',
+                message: `a root ${INDEX_SEGMENT}.md in a ${store.descriptor.scope} store composes to the empty canonical name — only a project store's root document answers at its effective prefix; rename this file to a named document (\`<topic>.md\`) or fold its content into the docs it introduces, then re-run`,
+                storeRoot: store.key,
+                path: doc.path,
+            });
+        }
+        const raw = rawExplicitName(doc);
+        const frozenLocal = raw === null ? pathNameNoCollapse(doc.relPath) : normalizeDocName(raw);
+        const oldName = prefix.oldRule === 'per-store-declaration'
+            ? composeCanonicalName(prefix.oldPrefix, resolveLocalName(doc.frontmatter, pathLocal))
+            : composeCanonicalName(prefix.oldPrefix, frozenLocal);
+        let finalLocal = pathLocal;
+        let nameEdit = null;
+        if (pathLocal === '') {
+            if (raw !== null)
+                nameEdit = 'remove';
+        }
+        else {
+            const explicit = explicitLocalName(doc.frontmatter);
+            if (explicit !== null) {
+                const localized = stripNamespace(explicit, prefix.effectivePrefix) ?? explicit;
+                if (localized === '' || localized === pathLocal) {
+                    nameEdit = 'remove';
+                }
+                else {
+                    const valid = validateExplicitLocalName(localized, prefix.effectivePrefix);
+                    if (!valid.ok) {
+                        blockers.push({
+                            kind: 'namespace',
+                            message: `explicit \`name: ${raw}\` cannot become a store-local name (${valid.reason}) — correct it and re-run`,
+                            storeRoot: store.key,
+                            path: doc.path,
+                            name: raw ?? localized,
+                        });
+                    }
+                    finalLocal = localized;
+                    if (localized !== raw)
+                        nameEdit = { value: localized };
+                }
+            }
+        }
+        let namespaceEdit = null;
+        if (pathLocal === '' && isProjectStore(store.descriptor)) {
+            if (prefix.ownerRelativePath === '') {
+                const declared = doc.frontmatter?.['namespace'];
+                if (repository !== undefined && declared !== repository.namespace) {
+                    namespaceEdit = { value: repository.namespace };
+                }
+            }
+            else if (prefix.nestedDeclarationAction !== 'none') {
+                namespaceEdit = 'remove';
+            }
+        }
+        facts.push({
+            doc,
+            storeKey: store.key,
+            realPath: realpathOrSelf(doc.path),
+            oldName,
+            finalName: composeCanonicalName(prefix.effectivePrefix, finalLocal),
+            finalLocal,
+            nameEdit,
+            namespaceEdit,
+            oldPrefix: prefix.oldPrefix,
+            deleted: prefix.nestedDeclarationAction === 'synthetic-index-removed' && pathLocal === '',
+        });
+    }
+    return facts;
+}
+function addFinalCollisions(store, facts, blockers) {
+    const byFinalName = new Map();
+    for (const fact of facts) {
+        const bucket = byFinalName.get(fact.finalName);
+        if (bucket === undefined)
+            byFinalName.set(fact.finalName, [fact]);
+        else
+            bucket.push(fact);
+    }
+    for (const [name, bucket] of byFinalName) {
+        if (bucket.length < 2)
+            continue;
+        blockers.push({
+            kind: 'collision',
+            message: `${bucket.length} documents in this store would own canonical name \`${name}\` (${bucket.map((fact) => fact.doc.relPath).join(', ')}) — merge them into one document or rename one, then re-run`,
+            storeRoot: store.key,
+            name,
+            paths: bucket.map((fact) => fact.doc.path),
+        });
+    }
+}
+function packageOwnedCorpusMessage(store, fact) {
+    const owner = store.descriptor.plugin !== undefined ? `plugin \`${store.descriptor.plugin}\`` : "crouter's builtin corpus";
+    const remedy = store.descriptor.plugin !== undefined
+        ? `update the plugin package (\`crtr pkg plugin update ${store.descriptor.plugin}\`) once it ships the corrected corpus`
+        : 'update crouter (`crtr sys update`) to a release whose builtin corpus already uses repository-root identity';
+    return `${fact.doc.relPath} needs an identity rewrite (\`${fact.oldName}\` → \`${fact.finalName}\`) in ${owner}, a package-owned store this migration never writes — ${remedy}`;
+}
+function identityRewrites(source, store, fact, result) {
+    if (fact.nameEdit === null && fact.namespaceEdit === null)
+        return [];
+    const block = yamlBlock(source);
+    if (block === null) {
+        if (fact.namespaceEdit === null || fact.namespaceEdit === 'remove')
+            return [];
+        return [{ start: 0, end: 0, text: `---\nnamespace: ${renderScalar(fact.namespaceEdit.value)}\n---\n` }];
+    }
+    const map = yamlMap(block.raw);
+    if (map === null) {
+        result.blockers.push({
+            kind: 'parse-failure',
+            message: `${fact.doc.relPath}: frontmatter is not a YAML mapping, so its identity fields cannot be rewritten — fix the file and re-run`,
+            storeRoot: store.key,
+            path: fact.doc.path,
+        });
+        return [];
+    }
+    const splices = [];
+    if (fact.namespaceEdit !== null) {
+        const item = itemFor(map, 'namespace');
+        if (fact.namespaceEdit === 'remove') {
+            if (item !== null) {
+                const span = keyLineSpan(block.raw, item);
+                if (span !== null)
+                    splices.push({ start: block.base + span[0], end: block.base + span[1], text: '' });
+            }
+        }
+        else if (item === null) {
+            splices.push({
+                start: block.base,
+                end: block.base,
+                text: `namespace: ${renderScalar(fact.namespaceEdit.value)}\n`,
+            });
+        }
+        else {
+            const span = valueSpan(block.raw, item);
+            if (span !== null) {
+                splices.push({
+                    start: block.base + span[0],
+                    end: block.base + span[1],
+                    text: renderScalar(fact.namespaceEdit.value),
+                });
+            }
+        }
+    }
+    if (fact.nameEdit !== null) {
+        const item = itemFor(map, 'name');
+        if (item !== null) {
+            if (fact.nameEdit === 'remove') {
+                const span = keyLineSpan(block.raw, item);
+                if (span !== null)
+                    splices.push({ start: block.base + span[0], end: block.base + span[1], text: '' });
+            }
+            else {
+                const span = valueSpan(block.raw, item);
+                if (span !== null) {
+                    splices.push({
+                        start: block.base + span[0],
+                        end: block.base + span[1],
+                        text: renderScalar(fact.nameEdit.value),
+                    });
+                }
+            }
+        }
+    }
+    return splices;
+}
+function storePrefixRow(prefix, plans) {
+    const frontDoorAction = prefix.ownerRelativePath === ''
+        ? (plans.find((plan) => plan.storeKey === prefix.storeKey)?.action ?? 'none')
+        : 'none';
+    return {
+        storeRoot: prefix.storeRoot,
+        ownerDir: prefix.ownerDir,
+        repositoryRoot: prefix.repositoryRoot,
+        ownerRelativePath: prefix.ownerRelativePath,
+        oldPrefix: prefix.oldPrefix,
+        oldRule: prefix.oldRule,
+        effectivePrefix: prefix.effectivePrefix,
+        nestedDeclarationAction: prefix.nestedDeclarationAction,
+        frontDoorAction,
+    };
+}
+function repositoryRow(decision) {
+    return {
+        repositoryRoot: decision.repositoryRoot,
+        repositoryKey: decision.repositoryKey,
+        declarationPath: decision.declarationPath,
+        namespace: decision.namespace,
+        source: decision.source,
+        action: decision.action,
+    };
+}
+function plan(snapshot) {
+    planned = { links: [], routes: [], wrote: new Set(), repositories: [] };
+    const result = emptyPlan();
+    const repositoryPlan = planRepositories(snapshot);
+    if (repositoryPlan.blockers.length > 0)
+        return emptyPlan(repositoryPlan.blockers);
+    const docsByStoreKey = new Map();
+    const prefixByStoreKey = new Map();
+    for (const store of snapshot.stores) {
+        const prefix = repositoryPlan.prefixes.get(store.key) ?? fallbackPrefix(store);
+        prefixByStoreKey.set(store.key, prefix);
+        const facts = buildDocFacts(store, prefix, repositoryPlan.repositories, result.blockers);
+        docsByStoreKey.set(store.key, facts);
+        addFinalCollisions(store, facts, result.blockers);
+    }
+    const oldCorpus = new OldCorpus(docsByStoreKey);
+    const finalNameByPath = new Map();
+    for (const facts of docsByStoreKey.values()) {
+        for (const fact of facts)
+            finalNameByPath.set(fact.realPath, fact.finalName);
+    }
+    const frontDoorResult = planFrontDoors(repositoryPlan.repositories, repositoryPlan.prefixes, snapshot, (realPath) => finalNameByPath.get(realpathOrSelf(realPath)));
+    result.blockers.push(...frontDoorResult.blockers);
+    result.repositories.push(...repositoryPlan.repositories.map(repositoryRow));
+    result.storePrefixes.push(...[...repositoryPlan.prefixes.values()].map((prefix) => storePrefixRow(prefix, frontDoorResult.plans)));
+    const completeRoot = new Set(frontDoorResult.plans
+        .filter((frontDoor) => frontDoor.rootAction === 'completed')
+        .map((frontDoor) => realpathOrSelf(frontDoor.rootDocPath)));
+    const demotedLeaf = new Set(frontDoorResult.plans
+        .map((frontDoor) => frontDoor.leafDocPath)
+        .filter((path) => path !== null)
+        .map(realpathOrSelf));
+    const identityChanges = new Map();
+    for (const store of snapshot.stores) {
+        const prefix = prefixByStoreKey.get(store.key);
+        const facts = docsByStoreKey.get(store.key) ?? [];
+        const views = store.writable ? viewsForStore(snapshot, store) : [];
+        for (const fact of facts) {
+            const consumerSplices = store.writable
+                ? [
+                    ...linkRewrites(oldCorpus, views, store, fact, result, planned.links),
+                    ...routeRewrites(oldCorpus, views, store, fact, prefix, result, planned.routes),
+                ]
+                : [];
+            const text1 = applySplices(fact.doc.source, consumerSplices);
+            if (fact.deleted && store.writable) {
+                identityChanges.set(fact.realPath, { path: fact.doc.path, after: null });
+                continue;
+            }
+            const text2 = completeRoot.has(fact.realPath)
+                ? completeRootFrontDoor(text1, fact.doc.path)
+                : demotedLeaf.has(fact.realPath)
+                    ? demoteLeafSurfaces(text1, fact.doc.path)
+                    : text1;
+            const ownSplices = identityRewrites(text2, store, fact, result);
+            const finalText = applySplices(text2, ownSplices);
+            if (!store.writable) {
+                const prefixMoved = fact.oldPrefix !== prefix.effectivePrefix;
+                if ((prefixMoved || ownSplices.length > 0) && fact.oldName !== fact.finalName) {
+                    result.blockers.push({
+                        kind: 'package-owned-corpus',
+                        message: packageOwnedCorpusMessage(store, fact),
+                        storeRoot: store.key,
+                        path: fact.doc.path,
+                        name: fact.finalName,
+                    });
+                }
+                continue;
+            }
+            if (consumerSplices.length > 0)
+                result.consumers.push({ path: fact.doc.path, after: text1 });
+            if (text2 !== text1 || ownSplices.length > 0)
+                identityChanges.set(fact.realPath, { path: fact.doc.path, after: finalText });
+            const identityMoved = fact.oldPrefix !== prefix.effectivePrefix || fact.nameEdit !== null || fact.namespaceEdit !== null;
+            if (identityMoved && fact.oldName !== fact.finalName) {
+                result.renames.push({
+                    storeRoot: store.key,
+                    path: fact.doc.path,
+                    from: fact.oldName,
+                    to: fact.finalName,
+                });
+            }
+        }
+    }
+    // FrontDoorPlan alone creates repository-root indexes. Root writes precede
+    // leaf demotions so an interrupted phase always leaves an authoritative door.
+    for (const frontDoor of frontDoorResult.plans) {
+        if (frontDoor.rootAction === 'created') {
+            const repository = repositoryPlan.repositories.find((candidate) => candidate.repositoryRoot === frontDoor.repositoryRoot);
+            if (repository === undefined) {
+                throw new Error(`migration 003: no repository decision for ${frontDoor.repositoryRoot}`);
+            }
+            result.identities.push({
+                path: frontDoor.rootDocPath,
+                after: rootIndexSource(repository.namespace, frontDoor.leafCanonicalName),
+            });
+        }
+        else {
+            const rootKey = realpathOrSelf(frontDoor.rootDocPath);
+            const rootChange = identityChanges.get(rootKey);
+            if (rootChange !== undefined) {
+                result.identities.push(rootChange);
+                identityChanges.delete(rootKey);
+            }
+        }
+    }
+    for (const frontDoor of frontDoorResult.plans) {
+        if (frontDoor.leafDocPath === null)
+            continue;
+        const leafKey = realpathOrSelf(frontDoor.leafDocPath);
+        const leafChange = identityChanges.get(leafKey);
+        if (leafChange !== undefined) {
+            result.identities.push(leafChange);
+            identityChanges.delete(leafKey);
+        }
+    }
+    result.identities.push(...identityChanges.values());
+    for (const change of [...result.consumers, ...result.identities])
+        planned.wrote.add(change.path);
+    planned.repositories = result.repositories.map((row) => ({ ...row }));
+    return result;
+}
+function freshDescriptor(store) {
+    return isProjectStore(store.descriptor) ? openProjectMemoryStore(ownerDirOf(store)) : store.descriptor;
+}
+function sameSet(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const value of a)
+        if (!b.has(value))
+            return false;
+    return true;
+}
+function safeGlob(target, glob) {
+    try {
+        return matchesGlob(target, glob);
+    }
+    catch {
+        return false;
+    }
+}
+function verify(snapshot) {
+    const findings = [];
+    for (const repository of planned.repositories) {
+        if (!existsSync(repository.declarationPath)) {
+            findings.push({
+                kind: 'verification',
+                message: `repository declaration ${repository.declarationPath} was not written`,
+                path: repository.declarationPath,
+                name: repository.namespace,
+            });
+            continue;
+        }
+        try {
+            const declared = parseFrontmatterGeneric(readFileSync(repository.declarationPath, 'utf8')).data?.['namespace'];
+            if (declared === repository.namespace)
+                continue;
+            findings.push({
+                kind: 'verification',
+                message: `repository declaration ${repository.declarationPath} declares ${JSON.stringify(declared)}, not the planned namespace \`${repository.namespace}\``,
+                path: repository.declarationPath,
+                name: repository.namespace,
+            });
+        }
+        catch (error) {
+            findings.push({
+                kind: 'verification',
+                message: `repository declaration ${repository.declarationPath} cannot be parsed after the write (${error instanceof Error ? error.message : String(error)})`,
+                path: repository.declarationPath,
+                name: repository.namespace,
+            });
+        }
+    }
+    for (const store of snapshot.stores) {
+        if (!store.writable || store.snapshot.docs.length === 0)
+            continue;
+        for (const finding of lintMemoryStore(freshDescriptor(store)).errors) {
+            const damage = finding.rule === 'yaml' && planned.wrote.has(finding.path);
+            if (!MEMORY_LINT_IDENTITY_RULES.has(finding.rule) && !damage)
+                continue;
+            findings.push({
+                kind: 'verification',
+                message: `${finding.rule}: ${finding.message}`,
+                storeRoot: store.key,
+                path: finding.path,
+                ...(finding.name === undefined ? {} : { name: finding.name }),
+            });
+        }
+    }
+    const viewCache = new Map();
+    const viewFor = (targetId) => {
+        const cached = viewCache.get(targetId);
+        if (cached !== undefined)
+            return cached;
+        const docs = snapshot.storesForTarget(targetId).flatMap((store) => loadStoreMemoryDocs(freshDescriptor(store), true));
+        const view = {
+            names: resolvableCanonicalNames(docs),
+            docs: docs.map((doc) => ({ name: doc.name, realPath: realpathOrSelf(doc.path) })),
+        };
+        viewCache.set(targetId, view);
+        return view;
+    };
+    for (const proof of planned.links) {
+        if (viewFor(proof.targetId).names.has(proof.name))
+            continue;
+        findings.push({
+            kind: 'verification',
+            message: `rewritten link [[${proof.name}]] resolves to no document in target ${proof.targetId} after the write phases`,
+            path: proof.carrier,
+            targetId: proof.targetId,
+            name: proof.name,
+        });
+    }
+    for (const proof of planned.routes) {
+        const view = viewFor(proof.targetId);
+        const actual = new Set();
+        for (const doc of view.docs) {
+            if (proof.globs.some((glob) => safeGlob(doc.name, glob)))
+                actual.add(doc.realPath);
+        }
+        if (sameSet(actual, new Set(proof.expected)))
+            continue;
+        findings.push({
+            kind: 'verification',
+            message: `rewritten memory-read route \`${proof.globs.join(', ')}\` names ${actual.size} document(s) in target ${proof.targetId}, not the ${proof.expected.length} it named before the cut`,
+            path: proof.carrier,
+            targetId: proof.targetId,
+        });
+    }
+    return findings;
+}
+export const repositoryRootMemoryIdentityMigration = {
+    id: '003-repository-root-memory-identity',
+    lane: 'corpus',
+    description: 'repository-root memory identity: one namespace per repository, nested stores derive their prefix from their path under it',
+    plan,
+    verify,
+};

package/dist/migrations/003-repository-root-memory-identity/references.d.ts

@@ -0,0 +1,95 @@
+import { type Pair, type YAMLMap } from 'yaml';
+import type { CorpusPlan, CorpusSnapshot, CorpusStore, StoreDoc } from '../types.js';
+import type { StorePrefixFacts } from './repository-facts.js';
+export interface DocFacts {
+    doc: StoreDoc;
+    storeKey: string;
+    /** Realpath of the file: the identity a reference proof is keyed by. */
+    realPath: string;
+    /** The exact name this document answered at before this migration. */
+    oldName: string;
+    /** Its repository-root canonical name after this migration. */
+    finalName: string;
+    /** The store-local half of `finalName`; `''` for a store root document. */
+    finalLocal: string;
+    nameEdit: 'remove' | {
+        value: string;
+    } | null;
+    namespaceEdit: 'remove' | {
+        value: string;
+    } | null;
+    /** True when phase 2 deletes this exact synthetic nested INDEX document. */
+    deleted: boolean;
+    /** The prefix this document's store answered under before this migration. */
+    oldPrefix: string;
+}
+export interface Splice {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Right-to-left, widest-first at a shared start. A whole-key removal beginning
+ * at the YAML block base must run before a zero-width insertion there. */
+export declare function applySplices(source: string, splices: readonly Splice[]): string;
+/** Locate the raw YAML within a complete document source. */
+export declare function yamlBlock(source: string): {
+    base: number;
+    raw: string;
+} | null;
+export declare function yamlMap(raw: string): YAMLMap | null;
+export declare function itemFor(map: YAMLMap, key: string): Pair | null;
+/** Whole-line span of a mapping key, including its multiline value. */
+export declare function keyLineSpan(raw: string, item: Pair): [number, number] | null;
+/** Span of a mapping value with trailing whitespace excluded. */
+export declare function valueSpan(raw: string, item: Pair): [number, number] | null;
+export declare function renderScalar(value: string): string;
+/** Render one or several route globs without expanding a one-line value into a
+ * block sequence. */
+export declare function renderGlobList(globs: readonly string[]): string;
+export interface View {
+    signature: string;
+    storeKeys: readonly string[];
+    targetIds: readonly string[];
+}
+export declare function viewsForStore(corpus: CorpusSnapshot, store: CorpusStore): View[];
+export interface LinkProof {
+    targetId: string;
+    carrier: string;
+    name: string;
+}
+export interface RouteProof {
+    targetId: string;
+    carrier: string;
+    globs: readonly string[];
+    /** Realpaths the rewritten globs must still name exactly. */
+    expected: readonly string[];
+}
+/** Reference resolution under the frozen old corpus view. */
+export declare class OldCorpus {
+    private readonly facts;
+    private readonly matchCache;
+    constructor(docsByStoreKey: ReadonlyMap<string, DocFacts[]>);
+    /** The physical old-name winner in one view, including a synthetic document
+     * phase 2 will delete. The retired directory-index fallback is part of this
+     * frozen lookup. A virtual bare-directory prefix has no physical fact. */
+    resolveOldFact(view: View, written: string): DocFacts | null;
+    /** The final canonical name a written old name denoted in one view. Deleted
+     * physical winners have no final projection; dangling references and
+     * unprovable bare-directory mappings likewise return null. */
+    resolveOld(view: View, written: string): string | null;
+    /** Realpaths a glob names under old or final identity, plus the effective
+     * prefixes of stores contributing a match. */
+    matchSet(view: View, glob: string, phase: 'old' | 'final'): {
+        paths: Set<string>;
+        namespaces: Set<string>;
+    };
+    /** Candidate qualification for both accepted old models. A pre-003 store
+     * gains its final prefix; a superseded per-store declaration has its old
+     * prefix replaced by the repository-derived one. */
+    finalGlobSpellings(views: readonly View[], glob: string): string[];
+}
+/** The minimal glob list naming exactly the old match set under final identity,
+ * or null when no exact rewrite can be proved. */
+export declare function provenGlobs(corpus: OldCorpus, views: readonly View[], glob: string): string[] | null;
+export declare function linkRewrites(corpus: OldCorpus, views: readonly View[], store: CorpusStore, fact: DocFacts, result: CorpusPlan, proofs: LinkProof[]): Splice[];
+export declare function routeRewrites(corpus: OldCorpus, views: readonly View[], store: CorpusStore, fact: DocFacts, prefix: StorePrefixFacts, result: CorpusPlan, proofs: RouteProof[]): Splice[];