@north-light/crouter 0.3.226 → 0.3.228

package/dist/migrations/corpus.js

@@ -0,0 +1,497 @@
+// The corpus-lane runner: discover EVERY memory store a machine can reach,
+// snapshot them together, let each corpus migration plan across the whole set,
+// then apply in two global phases.
+//
+// Why global: a document's canonical identity is an ADDRESS other stores point
+// at through `[[links]]` and `memory-read` routes. A per-store lane can rename
+// an identity it owns but cannot see the consumers that break, so the corpus
+// lane plans over every store at once — and one blocker anywhere writes nothing
+// anywhere, because a half-applied identity cut leaves dangling addresses.
+//
+// Why two phases: consumers are rewritten first, identities second, both across
+// the ENTIRE corpus. A store whose identity changed must not be readable at its
+// new address before every pointer to the old one has moved.
+//
+// Discovery is filesystem-only and never opens canvas.db. A migration runs
+// BEFORE the daemon on a cold home (Northlight's entrypoint does exactly that),
+// so node target metadata comes from each node's durable meta.json — the source
+// of truth the database index is rebuilt from — through its existing read-only
+// helper. Missing or corrupt metadata remains a global blocker.
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readMetaObject } from '../core/canvas/meta-file.js';
+import { nodeMetaPath, nodesRoot } from '../core/canvas/paths.js';
+import { atomicWriteText, listDirs, pathExists, realpathOrSelf, removePath, walkFiles } from '../core/fs-utils.js';
+import { memoryStoresInPrecedence, } from '../core/memory-resolver.js';
+import { descendantStoreRootsExhaustive } from '../core/nested-stores.js';
+import { profileMemoryDir } from '../core/profiles/manifest.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../core/resolver.js';
+import { memoryDir as nodeMemoryDir } from '../core/runtime/memory.js';
+import { NEUTRAL_PROJECT_MEMORY, pluginMemoryDir, projectScopeRoots, scopeRoot } from '../core/scope.js';
+import { CRTR_DIR_NAME } from '../types.js';
+import { foldDocChange, loadStoreSnapshot } from './convergent.js';
+import { STATE_MIGRATIONS } from './registry.js';
+function firstLine(e) {
+    return (e instanceof Error ? e.message : String(e)).split('\n')[0] ?? '';
+}
+function targetId(target) {
+    return `${target.profileId ?? '-'}:${target.nodeId ?? '-'}:${realpathOrSelf(target.cwd)}`;
+}
+function pluginStoreDescriptor(plugin) {
+    const storeRoot = pluginMemoryDir(plugin);
+    return {
+        scope: plugin.scope,
+        storeRoot,
+        namespace: plugin.name,
+        plugin: plugin.name,
+        mountStatus: pathExists(storeRoot) ? 'ready' : 'absent',
+        projectMemory: NEUTRAL_PROJECT_MEMORY,
+    };
+}
+function nodeStoreDescriptor(storeRoot) {
+    return {
+        scope: 'node',
+        storeRoot,
+        namespace: '',
+        mountStatus: pathExists(storeRoot) ? 'ready' : 'absent',
+        projectMemory: NEUTRAL_PROJECT_MEMORY,
+    };
+}
+/** Node stores holding at least one document. An empty node store contributes
+ *  no identity and no reference, so it stays out of the corpus — which is what
+ *  keeps discovery cheap across thousands of nodes AND keeps the daemon
+ *  optional on a home whose nodes have never written memory. */
+function nodeStoresWithDocs() {
+    const out = [];
+    for (const nodeId of listDirs(nodesRoot())) {
+        const storeRoot = nodeMemoryDir(nodeId);
+        if (!pathExists(storeRoot))
+            continue;
+        const docs = walkFiles(storeRoot, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d.startsWith('.'));
+        if (docs.length > 0)
+            out.push({ nodeId, storeRoot });
+    }
+    return out;
+}
+/** Discover the whole reachable corpus: every store, the targets that mount
+ *  them, and the frontier searched to find them. `profiles` are the manifest
+ *  lane's post-migration snapshots — a pre-migration manifest reads as corrupt,
+ *  so discovery must run after that lane, not against `listProfiles()`. */
+export async function discoverCorpus(opts) {
+    const cwd = realpathOrSelf(opts.cwd ?? process.cwd());
+    const selectedProfileId = process.env['CRTR_PROFILE_ID'] || null;
+    const explicitDirs = opts.explicitDirs ?? [];
+    const roots = [];
+    const rootSeen = new Set();
+    const addRoot = (row) => {
+        const key = `${row.reason}\u0000${realpathOrSelf(row.root)}\u0000${row.detail ?? ''}`;
+        if (rootSeen.has(key))
+            return;
+        rootSeen.add(key);
+        roots.push(row);
+    };
+    const projectRoots = new Map();
+    const addProjectRoot = (root, reason, profileId) => {
+        const key = realpathOrSelf(root);
+        let entry = projectRoots.get(key);
+        if (entry === undefined) {
+            entry = { root, reason, profileIds: [] };
+            projectRoots.set(key, entry);
+        }
+        if (!entry.profileIds.includes(profileId))
+            entry.profileIds.push(profileId);
+    };
+    const contexts = [
+        { reason: 'cwd-ancestor', profileId: selectedProfileId, roots: projectScopeRoots(cwd, selectedProfileId) },
+        ...opts.profiles.map(({ profileId, manifest }) => ({
+            reason: 'profile-project',
+            profileId,
+            detail: profileId,
+            roots: [
+                ...new Set(manifest.projects.flatMap((project) => [
+                    join(project.path, CRTR_DIR_NAME),
+                    ...projectScopeRoots(project.path, null),
+                ])),
+            ],
+        })),
+        ...explicitDirs.map((dir) => ({
+            reason: 'explicit-dir',
+            profileId: selectedProfileId,
+            detail: dir,
+            roots: [join(realpathOrSelf(dir), CRTR_DIR_NAME)],
+        })),
+    ];
+    const descendantCache = new Map();
+    /** Memoized by the root set: two profiles naming the same projects, or a
+     *  target-discovered root already walked, must not pay for the walk twice. */
+    const descendantsUnder = (rootsIn) => {
+        const key = rootsIn.map((root) => realpathOrSelf(root)).sort().join('\n');
+        let found = descendantCache.get(key);
+        if (found === undefined) {
+            found = descendantStoreRootsExhaustive([...rootsIn]);
+            descendantCache.set(key, found);
+        }
+        return found;
+    };
+    /** Take one set of project roots into discovery: the roots themselves, then
+     *  every store nested below them. Both kinds are project roots in their own
+     *  right — each earns a project target whose own precedence walk can reach
+     *  further roots, which is why the target loop below calls this again. */
+    const expandRoots = (rootsIn, reason, profileId, detail) => {
+        const detailRow = detail === undefined ? {} : { detail };
+        for (const root of rootsIn) {
+            addRoot({ reason, root, boundary: reason === 'explicit-dir' ? 'store' : 'ancestors', ...detailRow });
+            addProjectRoot(root, reason, profileId);
+        }
+        for (const descendant of descendantsUnder(rootsIn)) {
+            addRoot({ reason: 'descendant', root: descendant, boundary: 'descendants', ...detailRow });
+            addProjectRoot(descendant, 'descendant', profileId);
+        }
+    };
+    for (const context of contexts)
+        expandRoots(context.roots, context.reason, context.profileId, context.detail);
+    const blockers = [];
+    const stores = new Map();
+    const register = (descriptor, discovery, target) => {
+        const storeRoot = descriptor.storeRoot;
+        if (storeRoot === '' || !pathExists(storeRoot))
+            return;
+        const key = realpathOrSelf(storeRoot);
+        let record = stores.get(key);
+        if (record === undefined) {
+            record = {
+                key,
+                // First descriptor wins, matching the resolver's first-position dedup.
+                descriptor,
+                discovery: [],
+                discoverySeen: new Set(),
+                targets: [],
+                writable: descriptor.scope !== 'builtin',
+            };
+            stores.set(key, record);
+            try {
+                readdirSync(key);
+            }
+            catch (e) {
+                blockers.push({
+                    kind: 'inaccessible-root',
+                    message: `memory store cannot be listed (${firstLine(e)}) — discovery cannot see its documents; fix the permissions and re-run`,
+                    storeRoot: key,
+                });
+            }
+        }
+        const discoveryKey = `${discovery.reason}\u0000${discovery.root}\u0000${discovery.targetId ?? ''}`;
+        if (!record.discoverySeen.has(discoveryKey)) {
+            record.discoverySeen.add(discoveryKey);
+            record.discovery.push(discovery);
+        }
+        if (target !== undefined) {
+            if (!record.targets.includes(target.id))
+                record.targets.push(target.id);
+            if (!target.storeKeys.includes(key))
+                target.storeKeys.push(key);
+        }
+    };
+    const targets = [];
+    const targetsById = new Map();
+    const addTarget = (kind, origin, target) => {
+        const id = targetId(target);
+        if (targetsById.has(id))
+            return;
+        const record = { id, kind, origin, target, storeKeys: [] };
+        targetsById.set(id, record);
+        targets.push(record);
+    };
+    addTarget('cwd', cwd, { cwd, profileId: selectedProfileId, nodeId: null });
+    for (const { profileId, manifest } of opts.profiles) {
+        const home = manifest.home !== null && manifest.home !== '' ? manifest.home : null;
+        addTarget('profile', profileId, {
+            cwd: home ?? manifest.projects[0]?.path ?? cwd,
+            profileId,
+            nodeId: null,
+        });
+    }
+    /** One project target per (root, profile) membership. Re-run whenever the
+     *  root set grows: `addTarget` dedupes by target id. */
+    const addProjectTargets = () => {
+        for (const { root, profileIds } of [...projectRoots.values()]) {
+            for (const profileId of [...profileIds]) {
+                addTarget('project', dirname(root), { cwd: dirname(root), profileId, nodeId: null });
+            }
+        }
+    };
+    const nodeStores = nodeStoresWithDocs();
+    if (pathExists(nodesRoot()))
+        addRoot({ reason: 'node', root: nodesRoot(), boundary: 'nodes' });
+    const nodeMetadata = { available: true, nodes: 0 };
+    for (const { nodeId, storeRoot } of nodeStores) {
+        const metaPath = nodeMetaPath(nodeId);
+        const meta = readMetaObject(metaPath);
+        if (meta === null) {
+            nodeMetadata.available = false;
+            nodeMetadata.error ??= `unreadable metadata: ${metaPath}`;
+            blockers.push({
+                kind: 'inaccessible-target',
+                message: `node ${nodeId} holds memory documents but its durable metadata is unreadable at ${metaPath} — restore or repair that file, then re-run`,
+                storeRoot: realpathOrSelf(storeRoot),
+                path: metaPath,
+            });
+            register(nodeStoreDescriptor(storeRoot), { reason: 'node', root: storeRoot });
+            continue;
+        }
+        nodeMetadata.nodes += 1;
+        const nodeCwd = typeof meta['cwd'] === 'string' && meta['cwd'] !== '' ? meta['cwd'] : cwd;
+        const profileId = typeof meta['profile_id'] === 'string' && meta['profile_id'] !== '' ? meta['profile_id'] : null;
+        addTarget('node', nodeId, { cwd: nodeCwd, profileId, nodeId });
+    }
+    // Runtime default `includeDescendants: false`: this is the store stack a link
+    // or route actually resolves through. A descendant store is reached by its
+    // own owner-dir target instead.
+    const walkTarget = (target) => {
+        for (const descriptor of memoryStoresInPrecedence(target.target)) {
+            if (descriptor.plugin !== undefined) {
+                addRoot({ reason: 'plugin', root: descriptor.storeRoot, boundary: 'store', detail: descriptor.plugin });
+                register(descriptor, { reason: 'plugin', root: descriptor.storeRoot, targetId: target.id }, target);
+                continue;
+            }
+            if (descriptor.scope === 'project') {
+                const crtrRoot = dirname(descriptor.storeRoot);
+                const known = projectRoots.get(realpathOrSelf(crtrRoot));
+                if (known === undefined) {
+                    // Reached only through this target's own ancestor walk — a node's cwd
+                    // or a profile home outside every manifest project. It enters
+                    // discovery WHOLE: the stores nested below it are corpus too, and the
+                    // loop below gives it and them their own project targets.
+                    expandRoots([crtrRoot], 'cwd-ancestor', target.target.profileId, target.id);
+                }
+                register(descriptor, { reason: known?.reason ?? 'cwd-ancestor', root: crtrRoot, targetId: target.id }, target);
+                continue;
+            }
+            const reason = descriptor.scope === 'user'
+                ? 'user'
+                : descriptor.scope === 'profile'
+                    ? 'profile'
+                    : descriptor.scope === 'node'
+                        ? 'node'
+                        : 'builtin';
+            addRoot({ reason, root: descriptor.storeRoot, boundary: 'store' });
+            register(descriptor, { reason, root: descriptor.storeRoot, targetId: target.id }, target);
+        }
+    };
+    // Discovery runs to a FIXPOINT: a target's store walk can name a project root
+    // no manifest and no ancestor walk knew, that root's descendants are corpus
+    // too, and each of them gets a target whose own walk can name another root.
+    // Terminates because a root expands once (`projectRoots` dedupes by realpath)
+    // and a target is walked once.
+    const walkedTargets = new Set();
+    for (;;) {
+        addProjectTargets();
+        const pending = targets.filter((target) => !walkedTargets.has(target.id));
+        if (pending.length === 0)
+            break;
+        for (const target of pending) {
+            walkedTargets.add(target.id);
+            walkTarget(target);
+        }
+    }
+    // Stores no target walk reaches. A DISABLED plugin's documents still hold
+    // identities and still point at other stores, so the corpus must see them —
+    // `memoryStoresInPrecedence` mounts only enabled ones.
+    const userRoot = scopeRoot('user');
+    if (userRoot !== null)
+        addRoot({ reason: 'plugin', root: userRoot, boundary: 'plugins' });
+    const extraPlugins = [...listInstalledPlugins('user')];
+    for (const { root } of projectRoots.values()) {
+        addRoot({ reason: 'plugin', root, boundary: 'plugins' });
+        extraPlugins.push(...listInstalledPluginsInRoot('project', root));
+    }
+    for (const plugin of extraPlugins) {
+        const descriptor = pluginStoreDescriptor(plugin);
+        addRoot({ reason: 'plugin', root: descriptor.storeRoot, boundary: 'store', detail: plugin.name });
+        register(descriptor, { reason: 'plugin', root: descriptor.storeRoot });
+    }
+    // A profile store the selected profile never mounts (no target selects it).
+    for (const { profileId } of opts.profiles) {
+        const storeRoot = profileMemoryDir(profileId);
+        addRoot({ reason: 'profile', root: storeRoot, boundary: 'store', detail: profileId });
+        register({ scope: 'profile', storeRoot, namespace: '', mountStatus: pathExists(storeRoot) ? 'ready' : 'absent', projectMemory: NEUTRAL_PROJECT_MEMORY }, { reason: 'profile', root: storeRoot });
+    }
+    return {
+        roots,
+        stores: [...stores.values()].map((record) => ({
+            key: record.key,
+            descriptor: record.descriptor,
+            discovery: record.discovery,
+            targets: record.targets,
+            writable: record.writable,
+        })),
+        targets: targets.map((record) => ({
+            id: record.id,
+            kind: record.kind,
+            origin: record.origin,
+            target: record.target,
+            storeKeys: record.storeKeys,
+        })),
+        blockers,
+        nodeMetadata,
+    };
+}
+// ---------------------------------------------------------------------------
+// Snapshots
+// ---------------------------------------------------------------------------
+/** Read every discovered store's documents. `preloaded` supplies the per-store
+ *  convergent lane's FOLDED snapshots so the corpus plans against the bytes a
+ *  write run leaves behind — identical under `--dry-run`, where the same fold
+ *  ran and nothing was written. */
+export function loadCorpusSnapshots(discovery, opts = {}) {
+    const snapshots = new Map();
+    const skipped = [];
+    for (const store of discovery.stores) {
+        const preloaded = opts.preloaded?.get(store.key);
+        if (preloaded !== undefined) {
+            snapshots.set(store.key, preloaded);
+            continue;
+        }
+        const loaded = loadStoreSnapshot(store.descriptor.storeRoot);
+        snapshots.set(store.key, loaded.snapshot);
+        for (const row of loaded.skipped)
+            skipped.push({ storeRoot: store.key, ...row });
+    }
+    return { snapshots, skipped };
+}
+export function parseFailureBlockers(skipped) {
+    return skipped.map((row) => ({
+        kind: 'parse-failure',
+        message: `${row.relPath}: frontmatter is not valid YAML (${row.error}) — the document's identity cannot be read; fix the file and re-run`,
+        storeRoot: row.storeRoot,
+        path: join(row.storeRoot, row.relPath),
+    }));
+}
+function makeCorpusSnapshot(stores, targets, roots) {
+    const byKey = new Map(stores.map((store) => [store.key, store]));
+    const byTarget = new Map(targets.map((target) => [target.id, target]));
+    return {
+        stores,
+        targets,
+        roots,
+        store: (key) => byKey.get(key),
+        storesForTarget: (id) => (byTarget.get(id)?.storeKeys ?? [])
+            .map((key) => byKey.get(key))
+            .filter((store) => store !== undefined),
+    };
+}
+export function buildCorpusSnapshot(discovery, snapshots) {
+    const stores = discovery.stores.map((store) => ({
+        ...store,
+        snapshot: snapshots.get(store.key) ?? { root: store.descriptor.storeRoot, docs: [] },
+    }));
+    return makeCorpusSnapshot(stores, discovery.targets, discovery.roots);
+}
+// ---------------------------------------------------------------------------
+// The runner
+// ---------------------------------------------------------------------------
+function cloneCorpus(corpus) {
+    const stores = corpus.stores.map((store) => ({
+        ...store,
+        snapshot: { root: store.snapshot.root, docs: [...store.snapshot.docs] },
+    }));
+    return makeCorpusSnapshot(stores, corpus.targets, corpus.roots);
+}
+/** Fold a planned change into the working corpus so migration k+1 plans against
+ *  post-change state. A change outside every store is a migration defect, except
+ *  an identity change creating this plan's repository-root declaration: absent
+ *  root stores are intentionally not synthesized during planning. */
+function foldCorpusChange(corpus, change, allowedOutsidePaths = new Set()) {
+    let owner;
+    for (const store of corpus.stores) {
+        if (!change.path.startsWith(`${store.snapshot.root}/`))
+            continue;
+        if (owner === undefined || store.snapshot.root.length > owner.snapshot.root.length)
+            owner = store;
+    }
+    if (owner === undefined) {
+        if (allowedOutsidePaths.has(change.path))
+            return;
+        throw new Error(`corpus migration: planned change outside every discovered store: ${change.path}`);
+    }
+    foldDocChange(owner.snapshot, change);
+}
+/** Plan every corpus migration over the whole corpus, then — only when the
+ *  global plan is blocker-free — write every migration's consumer rewrites
+ *  before any identity rewrite. `rebuild` re-reads the corpus from file truth
+ *  for the post-write `verify` pass. */
+export function runCorpusMigrations(corpus, opts = {}) {
+    const migrations = (opts.migrations ?? STATE_MIGRATIONS).filter((m) => m.lane === 'corpus');
+    const blockers = [...(opts.blockers ?? [])];
+    const planned = [];
+    const repositories = [];
+    const storePrefixes = [];
+    const renames = [];
+    const references = [];
+    const consumers = [];
+    const identities = [];
+    const result = (verified, wrote) => ({
+        migrations: migrations.length,
+        blocked: blockers.length > 0 && migrations.length > 0,
+        blockers,
+        planned,
+        repositories,
+        storePrefixes,
+        renames,
+        references,
+        wrote,
+        verified,
+    });
+    const noWrites = { consumers: [], identities: [] };
+    if (migrations.length === 0)
+        return result(false, noWrites);
+    const working = cloneCorpus(corpus);
+    for (const migration of migrations) {
+        const plan = migration.plan(working);
+        blockers.push(...plan.blockers);
+        repositories.push(...plan.repositories);
+        storePrefixes.push(...plan.storePrefixes);
+        renames.push(...plan.renames);
+        references.push(...plan.references);
+        for (const change of plan.consumers)
+            foldCorpusChange(working, change);
+        const allowedOutsidePaths = new Set(plan.repositories.map((repository) => repository.declarationPath));
+        for (const change of plan.identities)
+            foldCorpusChange(working, change, allowedOutsidePaths);
+        consumers.push(...plan.consumers);
+        identities.push(...plan.identities);
+        planned.push({
+            migration: migration.description,
+            consumers: plan.consumers.map((c) => c.path),
+            identities: plan.identities.map((c) => c.path),
+        });
+    }
+    const wrote = { consumers: consumers.map((c) => c.path), identities: identities.map((c) => c.path) };
+    if (blockers.length > 0)
+        return result(false, noWrites);
+    if (opts.dryRun === true)
+        return result(false, wrote);
+    // The phase barrier is GLOBAL: every migration's consumer rewrites land
+    // before any identity rewrite, so no pointer resolves to a moved address.
+    for (const change of consumers) {
+        if (change.after === null)
+            removePath(change.path);
+        else
+            atomicWriteText(change.path, change.after);
+    }
+    for (const change of identities) {
+        if (change.after === null)
+            removePath(change.path);
+        else
+            atomicWriteText(change.path, change.after);
+    }
+    if (opts.rebuild === undefined)
+        return result(false, wrote);
+    const rebuilt = opts.rebuild();
+    for (const migration of migrations) {
+        for (const finding of migration.verify?.(rebuilt) ?? []) {
+            blockers.push({ ...finding, kind: 'verification' });
+        }
+    }
+    return result(true, wrote);
+}

package/dist/migrations/frontmatter-splice.d.ts

@@ -0,0 +1,15 @@
+/** Split a complete document into its raw frontmatter YAML and byte-preserved body. */
+export declare function splitDocSource(source: string, docPath: string): {
+    rawYaml: string;
+    body: string;
+};
+/** Remove complete top-level mapping-key lines, including multiline values. */
+export declare function dropTopLevelKeys(rawYaml: string, keys: readonly string[], docPath: string): string;
+/** Remove selected items from a top-level block sequence without re-rendering retained bytes. */
+export declare function dropSequenceItems(rawYaml: string, key: string, drop: (item: unknown) => boolean, docPath: string): string;
+/** Append a rendered top-level mapping pair while retaining existing YAML bytes. */
+export declare function appendRenderedKey(rawYaml: string, key: string, value: unknown, docPath: string): string;
+/** Prove that a transformed YAML block parses to exactly the expected mapping. */
+export declare function proveFrontmatterRoundTrip(after: string, expected: Record<string, unknown>, docPath: string): void;
+/** Replace only the YAML block in a complete document; the body remains byte-for-byte unchanged. */
+export declare function rebuildDocSource(source: string, newYaml: string, docPath: string): string;

package/dist/migrations/frontmatter-splice.js

@@ -0,0 +1,176 @@
+import { isMap, isSeq, parse as parseYaml, parseDocument, stringify } from 'yaml';
+import { parseFrontmatterGeneric } from '../core/frontmatter.js';
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((key) => deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+function yamlMap(rawYaml, docPath) {
+    if (rawYaml.trim() === '')
+        return [];
+    const document = parseDocument(rawYaml);
+    if (document.errors.length > 0 || !isMap(document.contents)) {
+        throw new Error(`frontmatter splice: unparseable frontmatter in ${docPath}`);
+    }
+    return document.contents.items;
+}
+function keyLineSpan(rawYaml, pair, docPath) {
+    const keyRange = pair.key?.range;
+    const valueRange = pair.value?.range;
+    if (keyRange === undefined)
+        throw new Error(`frontmatter splice: rangeless key in ${docPath}`);
+    const start = rawYaml.lastIndexOf('\n', keyRange[0] - 1) + 1;
+    let end = valueRange?.[2] ?? keyRange[2];
+    if (!(end > 0 && rawYaml[end - 1] === '\n')) {
+        while (end < rawYaml.length && (rawYaml[end] === ' ' || rawYaml[end] === '\t' || rawYaml[end] === '\r'))
+            end++;
+        if (rawYaml[end] === '\n')
+            end++;
+    }
+    return [start, end];
+}
+function parseRecord(rawYaml, docPath) {
+    yamlMap(rawYaml, docPath);
+    let parsed;
+    try {
+        parsed = parseYaml(rawYaml);
+    }
+    catch {
+        throw new Error(`frontmatter splice: unparseable frontmatter in ${docPath}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`frontmatter splice: frontmatter is not a mapping in ${docPath}`);
+    }
+    return parsed;
+}
+/** Split a complete document into its raw frontmatter YAML and byte-preserved body. */
+export function splitDocSource(source, docPath) {
+    let parsed;
+    try {
+        parsed = parseFrontmatterGeneric(source);
+    }
+    catch (error) {
+        throw new Error(`frontmatter splice: unparseable frontmatter in ${docPath}`, { cause: error });
+    }
+    if (parsed.raw === '' && parsed.body === source) {
+        throw new Error(`frontmatter splice: cannot locate frontmatter block in ${docPath}`);
+    }
+    return { rawYaml: parsed.raw, body: parsed.body };
+}
+/** Remove complete top-level mapping-key lines, including multiline values. */
+export function dropTopLevelKeys(rawYaml, keys, docPath) {
+    const pairs = yamlMap(rawYaml, docPath);
+    const names = new Set(keys);
+    const spans = pairs
+        .filter((pair) => names.has(String(pair.key)))
+        .map((pair) => keyLineSpan(rawYaml, pair, docPath))
+        .sort((a, b) => b[0] - a[0]);
+    let after = rawYaml;
+    for (const [start, end] of spans)
+        after = after.slice(0, start) + after.slice(end);
+    const expected = parseRecord(rawYaml, docPath);
+    for (const key of keys)
+        delete expected[key];
+    proveFrontmatterRoundTrip(after, expected, docPath);
+    return after;
+}
+/** Remove selected items from a top-level block sequence without re-rendering retained bytes. */
+export function dropSequenceItems(rawYaml, key, drop, docPath) {
+    const pairs = yamlMap(rawYaml, docPath);
+    const pair = pairs.find((candidate) => String(candidate.key) === key);
+    if (pair === undefined)
+        return rawYaml;
+    if (!isSeq(pair.value))
+        throw new Error(`frontmatter splice: ${key} is not a sequence in ${docPath}`);
+    const items = pair.value.items;
+    const dropped = items.map((item) => drop(item.toJSON?.()));
+    if (!dropped.some(Boolean))
+        return rawYaml;
+    const expected = parseRecord(rawYaml, docPath);
+    const original = expected[key];
+    if (!Array.isArray(original))
+        throw new Error(`frontmatter splice: ${key} is not a sequence in ${docPath}`);
+    const retained = original.filter((_, index) => !dropped[index]);
+    if (retained.length === 0) {
+        delete expected[key];
+        const after = dropTopLevelKeys(rawYaml, [key], docPath);
+        proveFrontmatterRoundTrip(after, expected, docPath);
+        return after;
+    }
+    const sequenceRange = pair.value.range;
+    if (sequenceRange === undefined)
+        throw new Error(`frontmatter splice: rangeless sequence in ${docPath}`);
+    const lineStarts = items.map((item) => {
+        const range = item.range;
+        if (range === undefined)
+            throw new Error(`frontmatter splice: rangeless sequence item in ${docPath}`);
+        return rawYaml.lastIndexOf('\n', range[0] - 1) + 1;
+    });
+    if (new Set(lineStarts).size !== lineStarts.length) {
+        throw new Error(`frontmatter splice: flow sequence cannot be spliced byte-precisely in ${docPath}`);
+    }
+    const spans = [];
+    for (let index = 0; index < items.length; index++) {
+        if (!dropped[index])
+            continue;
+        const start = lineStarts[index];
+        const end = lineStarts[index + 1] ?? sequenceRange[2];
+        spans.push([start, end]);
+    }
+    spans.sort((a, b) => b[0] - a[0]);
+    let after = rawYaml;
+    for (const [start, end] of spans)
+        after = after.slice(0, start) + after.slice(end);
+    expected[key] = retained;
+    proveFrontmatterRoundTrip(after, expected, docPath);
+    return after;
+}
+/** Append a rendered top-level mapping pair while retaining existing YAML bytes. */
+export function appendRenderedKey(rawYaml, key, value, docPath) {
+    const expected = parseRecord(rawYaml, docPath);
+    expected[key] = value;
+    const block = stringify({ [key]: value }, { lineWidth: 0 });
+    let after = rawYaml === '' ? block : (rawYaml.endsWith('\n') ? rawYaml : rawYaml + '\n') + block;
+    after = after.replace(/\r?\n$/, '');
+    proveFrontmatterRoundTrip(after, expected, docPath);
+    return after;
+}
+/** Prove that a transformed YAML block parses to exactly the expected mapping. */
+export function proveFrontmatterRoundTrip(after, expected, docPath) {
+    let actual;
+    try {
+        actual = parseYaml(after === '' ? '{}' : after);
+    }
+    catch (error) {
+        throw new Error(`frontmatter splice: transformed frontmatter does not parse in ${docPath}`, { cause: error });
+    }
+    if (!deepEqual(actual ?? {}, expected)) {
+        throw new Error(`frontmatter splice: spliced frontmatter does not round-trip in ${docPath}`);
+    }
+}
+/** Replace only the YAML block in a complete document; the body remains byte-for-byte unchanged. */
+export function rebuildDocSource(source, newYaml, docPath) {
+    const { rawYaml, body } = splitDocSource(source, docPath);
+    const bodyStart = source.length - body.length;
+    const firstNewline = source.indexOf('\n');
+    const rawStart = firstNewline < 0 ? -1 : firstNewline + 1;
+    const rawEnd = rawStart < 0 ? -1 : rawStart + rawYaml.length;
+    if (rawYaml === '' && bodyStart === source.length) {
+        throw new Error(`frontmatter splice: cannot locate frontmatter block in ${docPath}`);
+    }
+    if (rawStart < 0 || rawEnd > bodyStart)
+        throw new Error(`frontmatter splice: cannot locate frontmatter block in ${docPath}`);
+    return source.slice(0, rawStart) + newYaml + source.slice(rawEnd);
+}