@north-light/crouter 0.3.227 → 0.3.228

package/dist/migrations/registry.d.ts

@@ -1,2 +1,7 @@
-import type { StateMigration } from './types.js';
+import type { OnDiskMigrationLane, StateMigration } from './types.js';
 export declare const STATE_MIGRATIONS: readonly StateMigration[];
+export interface OnDiskMigrationIdentity {
+    readonly id: string;
+    readonly lane: OnDiskMigrationLane;
+}
+export declare function onDiskMigrationIdentity(): readonly OnDiskMigrationIdentity[];

package/dist/migrations/registry.js

@@ -1,8 +1,8 @@
 // The ordered state-migration registry — ONE list for both lanes, so a cut
 // that spans canvas-db and document stores ships as adjacent entries.
 //
-// Authoring contract (each migration is one file, `NNN-<desc>.ts`, appended
-// here in order):
+// Authoring contract (each migration is one file, `NNN-<desc>.ts`, or one
+// directory, `NNN-<desc>/index.ts`, appended here in order):
 //   • Idempotent. A convergent or profile-manifest migration re-runs on every
 //     `crtr sys migrate`, so applying it to already-migrated state must plan
 //     zero changes. A journaled migration runs once per database via
@@ -18,7 +18,12 @@
 //     build's V-1 gate).
 import { surfacesFrontmatterMigration } from './001-surfaces-frontmatter.js';
 import { profileProjectMemoryMigration } from './002-profile-project-memory.js';
+import { repositoryRootMemoryIdentityMigration } from './003-repository-root-memory-identity/index.js';
 export const STATE_MIGRATIONS = [
     surfacesFrontmatterMigration,
     profileProjectMemoryMigration,
+    repositoryRootMemoryIdentityMigration,
 ];
+export function onDiskMigrationIdentity() {
+    return STATE_MIGRATIONS.filter((migration) => migration.lane !== 'journaled').map(({ id, lane }) => ({ id, lane }));
+}

package/dist/migrations/runner.d.ts

@@ -0,0 +1,41 @@
+import { type CorpusDiscovery } from './corpus.js';
+import type { CorpusBlocker, CorpusIdentityRename, CorpusRepositoryDecision, CorpusStorePrefix, CorpusReferenceRewrite, OnDiskMigrationLane, StoreSnapshot } from './types.js';
+export type OnDiskMigrationPhase = 'not-started' | 'planned' | 'written';
+export interface OnDiskMigrationApplied {
+    store: string;
+    lane: OnDiskMigrationLane;
+    migration: string;
+    files: string[];
+}
+export interface OnDiskMigrationSkipped {
+    store: string;
+    relPath: string;
+    error: string;
+}
+export interface OnDiskMigrationRunResult {
+    profiles: number;
+    discovery: CorpusDiscovery;
+    snapshots: ReadonlyMap<string, StoreSnapshot>;
+    changed: number;
+    applied: OnDiskMigrationApplied[];
+    skipped: OnDiskMigrationSkipped[];
+    blocked: boolean;
+    blockers: CorpusBlocker[];
+    corpusPhase: OnDiskMigrationPhase;
+    wrote: {
+        profileManifests: string[];
+        documents: string[];
+        corpusConsumers: string[];
+        corpusIdentities: string[];
+    };
+    repositories: CorpusRepositoryDecision[];
+    storePrefixes: CorpusStorePrefix[];
+    renames: CorpusIdentityRename[];
+    references: CorpusReferenceRewrite[];
+    finalVerificationSucceeded: boolean;
+    dryRun: boolean;
+}
+export declare function runOnDiskMigrations(opts?: {
+    dryRun?: boolean;
+    explicitDirs?: readonly string[];
+}): Promise<OnDiskMigrationRunResult>;

package/dist/migrations/runner.js

@@ -0,0 +1,81 @@
+import { profilesRoot, withProfileManifestLock } from '../core/profiles/manifest.js';
+import { buildCorpusSnapshot, discoverCorpus, loadCorpusSnapshots, parseFailureBlockers, runCorpusMigrations, } from './corpus.js';
+import { runConvergentMigrations } from './convergent.js';
+import { runProfileManifestMigrations } from './profile-manifests.js';
+export async function runOnDiskMigrations(opts = {}) {
+    const dryRun = opts.dryRun === true;
+    const applied = [];
+    const skipped = [];
+    const profilesDir = profilesRoot();
+    const profileRun = runProfileManifestMigrations(profilesDir, { dryRun, withLock: withProfileManifestLock });
+    const profileBlockers = [];
+    for (const row of profileRun.applied) {
+        applied.push({ store: profilesDir, lane: 'profile-manifest', migration: row.migration, files: [row.path] });
+    }
+    for (const row of profileRun.skipped) {
+        const relPath = `${row.profileId}/profile.json`;
+        skipped.push({ store: profilesDir, relPath, error: row.error });
+        profileBlockers.push({
+            kind: 'parse-failure',
+            message: `${row.path}: profile manifest is not valid JSON (${row.error}) — its projects cannot be discovered; fix the file and re-run \`crtr sys migrate\``,
+            storeRoot: profilesDir,
+            path: row.path,
+        });
+    }
+    const discovery = await discoverCorpus({ profiles: profileRun.snapshots, explicitDirs: opts.explicitDirs });
+    const parseFailures = [];
+    const folded = new Map();
+    for (const store of discovery.stores) {
+        if (!store.writable)
+            continue;
+        const result = runConvergentMigrations(store.descriptor.storeRoot, { dryRun });
+        folded.set(store.key, result.snapshot);
+        for (const row of result.applied) {
+            applied.push({ store: store.key, lane: 'convergent', migration: row.migration, files: row.files });
+        }
+        for (const row of result.skipped)
+            parseFailures.push({ storeRoot: store.key, ...row });
+    }
+    const loaded = loadCorpusSnapshots(discovery, { preloaded: folded });
+    parseFailures.push(...loaded.skipped);
+    for (const row of parseFailures)
+        skipped.push({ store: row.storeRoot, relPath: row.relPath, error: row.error });
+    const corpusRun = runCorpusMigrations(buildCorpusSnapshot(discovery, loaded.snapshots), {
+        dryRun,
+        blockers: [...profileBlockers, ...discovery.blockers, ...parseFailureBlockers(parseFailures)],
+        rebuild: () => buildCorpusSnapshot(discovery, loadCorpusSnapshots(discovery).snapshots),
+    });
+    const corpusWrote = corpusRun.wrote.consumers.length > 0 || corpusRun.wrote.identities.length > 0;
+    if (corpusWrote) {
+        for (const row of corpusRun.planned) {
+            const files = [...row.consumers, ...row.identities];
+            if (files.length > 0)
+                applied.push({ store: 'corpus', lane: 'corpus', migration: row.migration, files });
+        }
+    }
+    const corpusPhase = dryRun ? 'planned' : corpusWrote ? 'written' : 'not-started';
+    const blocked = profileBlockers.length > 0 || corpusRun.blocked;
+    return {
+        profiles: profileRun.profiles,
+        discovery,
+        snapshots: loaded.snapshots,
+        changed: applied.reduce((count, row) => count + row.files.length, 0),
+        applied,
+        skipped,
+        blocked,
+        blockers: corpusRun.blockers,
+        corpusPhase,
+        wrote: {
+            profileManifests: applied.filter((row) => row.lane === 'profile-manifest').flatMap((row) => row.files),
+            documents: applied.filter((row) => row.lane === 'convergent').flatMap((row) => row.files),
+            corpusConsumers: corpusRun.wrote.consumers,
+            corpusIdentities: corpusRun.wrote.identities,
+        },
+        repositories: corpusRun.repositories,
+        storePrefixes: corpusRun.storePrefixes,
+        renames: corpusRun.renames,
+        references: corpusRun.references,
+        finalVerificationSucceeded: corpusRun.verified && !blocked,
+        dryRun,
+    };
+}

package/dist/migrations/types.d.ts

@@ -1,4 +1,6 @@
 import type { DatabaseSync } from 'node:sqlite';
+import type { MemoryStoreDescriptor, MemoryTarget } from '../core/memory-resolver.js';
+import type { ProjectNamespaceSource } from '../core/memory/project-namespace.js';
 import type { ProfileManifest } from '../types.js';
 export interface JournaledMigration {
     lane: 'journaled';
@@ -8,17 +10,13 @@ export interface JournaledMigration {
      *  (a re-run after a partial application completes rather than corrupts). */
     apply(db: DatabaseSync, canvasHome: string): void;
 }
-export interface ConvergentMigrationContext {
-    /** Frozen pre-cut directory-INDEX resolution for this store's owning memory
-     *  corpus. Null means rewriting the bare ref would not preserve meaning. */
-    legacyDirectoryIndex(name: string): string | null;
-}
 export interface ConvergentMigration {
+    readonly id: string;
     lane: 'convergent';
     description: string;
     /** Pure planning: return the full new text of each doc to rewrite. The
      *  runner filters no-op changes and performs the writes. */
-    apply(store: StoreSnapshot, context?: ConvergentMigrationContext): DocChange[];
+    apply(store: StoreSnapshot): DocChange[];
 }
 /** One stored `profile.json` handed to the profile-manifest lane. */
 export interface ProfileManifestInput {
@@ -31,6 +29,7 @@ export interface ProfileManifestInput {
     raw: Record<string, unknown>;
 }
 export interface ProfileManifestMigration {
+    readonly id: string;
     lane: 'profile-manifest';
     description: string;
     /** Pure planning: the full replacement record, or null when this manifest is
@@ -38,7 +37,9 @@ export interface ProfileManifestMigration {
      *  run fails rather than persisting a guessed value. */
     apply(input: ProfileManifestInput): Record<string, unknown> | null;
 }
-export type StateMigration = JournaledMigration | ConvergentMigration | ProfileManifestMigration;
+export type OnDiskMigration = ConvergentMigration | ProfileManifestMigration | CorpusMigration;
+export type OnDiskMigrationLane = OnDiskMigration['lane'];
+export type StateMigration = JournaledMigration | OnDiskMigration;
 /** One profile's manifest after every profile-manifest migration folded —
  *  the bytes on disk after a write run, and the bytes a write run WOULD have
  *  produced under `--dry-run`. */
@@ -67,6 +68,144 @@ export interface StoreSnapshot {
 /** One planned rewrite: the full new file text for `path`. */
 export interface DocChange {
     path: string;
-    /** Complete replacement text for the file. */
-    after: string;
+    /** Complete replacement text for the file, or null to delete it. */
+    after: string | null;
+}
+/** Why a root or store entered the corpus. `cwd-ancestor` is the walk up from
+ *  the invoking directory, `profile-project` a project a profile manifest names,
+ *  `descendant` the exhaustive nested-store walk below either, `explicit-dir` a
+ *  `--dir` argument. */
+export type CorpusDiscoveryReason = 'user' | 'profile' | 'profile-project' | 'cwd-ancestor' | 'descendant' | 'node' | 'plugin' | 'builtin' | 'explicit-dir';
+/** How far discovery searched from one root: the root's own store only, the
+ *  ancestor walk above it, the exhaustive descendant walk below it, its
+ *  installed plugins, or the canvas node stores. */
+export type CorpusDiscoveryBoundary = 'store' | 'ancestors' | 'descendants' | 'plugins' | 'nodes';
+/** One place discovery looked, reported whether or not it yielded a store —
+ *  the frontier an operator reads to see what a run could NOT have seen. */
+export interface CorpusDiscoveryRoot {
+    reason: CorpusDiscoveryReason;
+    /** The directory searched: a `.crouter` root, a store dir, or a scan root. */
+    root: string;
+    boundary: CorpusDiscoveryBoundary;
+    /** Profile id, node id, or the `--dir` argument that produced this root. */
+    detail?: string;
+}
+/** One reason a store is in the corpus. A store reached several ways keeps
+ *  every reason — deduping physical stores must not erase why they matter. */
+export interface CorpusStoreDiscovery {
+    reason: CorpusDiscoveryReason;
+    root: string;
+    targetId?: string;
+}
+export interface CorpusStore {
+    /** Realpath of the memory dir: the dedup key, and the id every report row and
+     *  blocker cites this store by. */
+    key: string;
+    descriptor: MemoryStoreDescriptor;
+    /** Documents after the per-store convergent lane folded, so the corpus lane
+     *  plans against exactly the bytes a write run leaves on disk. */
+    snapshot: StoreSnapshot;
+    discovery: readonly CorpusStoreDiscovery[];
+    /** Ids of every target that mounts this store. Empty for a store no target
+     *  reaches — a disabled plugin, a node store whose metadata is unreadable. */
+    targets: readonly string[];
+    /** False for builtin: package-owned, regenerated on install, corpus INPUT
+     *  only (link resolution and lint validation), never written. */
+    writable: boolean;
+}
+export interface CorpusTarget {
+    /** `${profileId ?? '-'}:${nodeId ?? '-'}:${realCwd}`. */
+    id: string;
+    kind: 'cwd' | 'profile' | 'project' | 'node';
+    /** Profile id, node id, or the directory this target speaks for. */
+    origin: string;
+    target: MemoryTarget;
+    /** Store keys in this target's source precedence order. */
+    storeKeys: readonly string[];
+}
+export interface CorpusSnapshot {
+    stores: readonly CorpusStore[];
+    targets: readonly CorpusTarget[];
+    roots: readonly CorpusDiscoveryRoot[];
+    store(key: string): CorpusStore | undefined;
+    /** The target's stores in precedence order; empty for an unknown target. */
+    storesForTarget(targetId: string): CorpusStore[];
+}
+/** Why a corpus run may not write. `inaccessible-root`/`inaccessible-target`
+ *  mean discovery could not see all of the corpus; `package-owned-corpus` is a
+ *  store the run may only read (builtin, or a package handed in read-only)
+ *  whose documents still need an identity rewrite; `verification` is raised
+ *  after both write phases, against a corpus rebuilt from file truth. */
+export type CorpusBlockerKind = 'inaccessible-root' | 'inaccessible-target' | 'parse-failure' | 'namespace' | 'association' | 'front-door' | 'divergent-reference' | 'unsafe-route' | 'collision' | 'package-owned-corpus' | 'verification';
+export interface CorpusBlocker {
+    kind: CorpusBlockerKind;
+    /** What is wrong and what the operator does about it. */
+    message: string;
+    storeRoot?: string;
+    targetId?: string;
+    /** The one file at fault. */
+    path?: string;
+    /** The canonical name or namespace at fault. */
+    name?: string;
+    /** Every file at fault when the finding is a relationship between them. */
+    paths?: string[];
+}
+export interface CorpusRepositoryDecision {
+    repositoryRoot: string;
+    repositoryKey: string;
+    declarationPath: string;
+    namespace: string;
+    source: 'declared' | ProjectNamespaceSource;
+    action: 'kept' | 'created' | 'filled-linked-root';
+}
+export type FrontDoorAction = 'none' | 'kept-root' | 'created-root' | `transferred-from:${string}`;
+export interface CorpusStorePrefix {
+    storeRoot: string;
+    ownerDir: string;
+    repositoryRoot: string;
+    ownerRelativePath: string;
+    oldPrefix: string;
+    oldRule: 'pre-003' | 'per-store-declaration';
+    effectivePrefix: string;
+    nestedDeclarationAction: 'none' | 'removed' | 'synthetic-index-removed';
+    /** Only the repository-root store reports the repository's front-door action. */
+    frontDoorAction: FrontDoorAction;
+}
+export interface CorpusIdentityRename {
+    storeRoot: string;
+    path: string;
+    from: string;
+    to: string;
+}
+export interface CorpusReferenceRewrite {
+    storeRoot: string;
+    path: string;
+    kind: 'link' | 'memory-read';
+    from: string;
+    to: string;
+}
+export interface CorpusPlan {
+    /** A blocker anywhere stops the whole lane: nothing is written in any store. */
+    blockers: CorpusBlocker[];
+    /** Phase 1 — rewrites of authored links and routes that POINT AT an identity. */
+    consumers: DocChange[];
+    /** Phase 2 — rewrites that change a document's own identity. A non-null
+     *  `after` is the file's complete final text INCLUDING that same file's
+     *  phase-1 consumer rewrites: phase 2 writes last and would otherwise revert
+     *  them. A null `after` deletes an obsolete synthetic identity document. */
+    identities: DocChange[];
+    repositories: CorpusRepositoryDecision[];
+    storePrefixes: CorpusStorePrefix[];
+    renames: CorpusIdentityRename[];
+    references: CorpusReferenceRewrite[];
+}
+export interface CorpusMigration {
+    readonly id: string;
+    lane: 'corpus';
+    description: string;
+    /** Pure planning over every discovered store at once. */
+    plan(corpus: CorpusSnapshot): CorpusPlan;
+    /** Re-checked against a corpus rebuilt from file truth AFTER both write
+     *  phases; findings surface as `verification` blockers. */
+    verify?(corpus: CorpusSnapshot): CorpusBlocker[];
 }

package/dist/migrations/types.js

@@ -1,4 +1,4 @@
-// State-migration shapes. Three lanes, split by which store owns the state:
+// State-migration shapes. Four lanes, split by which store owns the state:
 //
 //   journaled        — canvas-db state. Runs inside the db's ordered migration
 //                      chain (core/canvas/db.ts appends these to MIGRATIONS), so
@@ -12,6 +12,13 @@
 //                      the document lane, but each manifest folds under the same
 //                      per-profile lock add/remove take, and a structure the
 //                      migration cannot convert throws instead of being guessed.
+//   corpus           — on-disk memory documents again, but planned across EVERY
+//                      discovered store at once: an identity a document changes
+//                      is an address other stores' links and routes point at, so
+//                      the plan is global (one blocker anywhere writes nothing
+//                      anywhere) and applies in two phases — every consumer
+//                      rewrite, then every identity rewrite.
 //
-// `crtr sys migrate` runs both on-disk lanes, profile manifests first.
+// `crtr sys migrate` runs all three on-disk lanes: profile manifests, then the
+// per-store convergent lane, then the corpus lane over the folded result.
 export {};