cursedbelt 2.8.0 → 3.0.0

package/src/verify/frozenManifest.ts

@@ -1,158 +0,0 @@
-/**
- * `manifest.gen.json` — the FROZEN EffectiveManifest an export writes (02 §1.1).
- *
- * An `EffectiveManifest` is not JSON. Two of its fields hold live objects:
- * `instances[].ports[].spec.token` is a `TokenDef` carrying a **Zod schema**, and
- * `stagingCatalogs[].tokens` is a list of the same. `JSON.stringify` turns a Zod
- * schema into a meaningless bag of internals, so a naive `JSON.stringify(manifest)`
- * produces a file that LOOKS complete and silently isn't — the exact failure mode
- * this codebase keeps legislating against.
- *
- * So the freeze is explicit and lossy **by declaration**:
- *
- *   * every port keeps its identity (`id`, `direction`, `required`, `enabled`) and
- *     its **token id**; it loses the schema object and the `enabledWhen` predicate,
- *     both of which are compile-time artifacts that no runtime consumer reads;
- *   * staging catalogs keep their ids and drop their token schemas (an export can
- *     never contain staging anyway — V5 `staging-plugin-in-export`).
- *
- * That is safe because of what the frozen manifest is FOR:
- *
- *   1. provenance — the artifact a build diff is taken against;
- *   2. the **last-good bundle** the boot moment serves when a live re-verify
- *      fails (02 §4) — the server runtime reads `engines`, `instances[].id/
- *      engine/effective/routes/fills`, `cspConnectAllowlist` and `bundleKey`, and
- *      reads `ports` nowhere (only the V7 probe harness does);
- *   3. the input to client route codegen, which reads `instances[].routes`.
- *
- * A consumer that needs port SCHEMAS must re-run the pipeline (which the boot
- * moment does on the happy path); it must not reach into a frozen manifest and
- * find a half-hydrated Zod object. `readFrozenManifest` therefore rebuilds ports
- * with an explicitly stubbed token whose `schema`/`sample` are absent, so a
- * consumer that reads them fails visibly instead of validating everything through
- * a lie.
- */
-import type { z } from 'zod';
-import type { TokenDef } from '../core/tokens/registry';
-import type { EffectiveInstance, EffectiveManifest, MaterializedPort, PortSpec, StagingCatalog } from './types';
-
-/** A port as it survives the freeze: identity + token id, no schema, no predicate. */
-export interface FrozenPort {
-  id: string;
-  tokenId: string;
-  direction: 'in' | 'out';
-  required: boolean;
-  enabled: boolean;
-  subscribesAtMount?: boolean;
-  emission?: 'versioned';
-  scopes?: readonly string[];
-  scopeFilter?: readonly string[];
-  stormBudgetPerWindow?: number;
-}
-
-export interface FrozenInstance extends Omit<EffectiveInstance, 'ports'> {
-  ports: readonly FrozenPort[];
-}
-
-export interface FrozenStagingCatalog extends Omit<StagingCatalog, 'tokens'> {
-  /** Token ids only — the schemas do not survive JSON. */
-  tokenIds: readonly string[];
-}
-
-/** The JSON-safe projection of an `EffectiveManifest`. */
-export interface FrozenManifest extends Omit<EffectiveManifest, 'instances' | 'stagingCatalogs'> {
-  /** Bumped only when this projection's SHAPE changes, never per app. */
-  frozenVersion: 1;
-  instances: readonly FrozenInstance[];
-  stagingCatalogs: readonly FrozenStagingCatalog[];
-}
-
-export const FROZEN_MANIFEST_VERSION = 1;
-
-const freezePort = (port: MaterializedPort): FrozenPort => ({
-  id: port.spec.id,
-  tokenId: port.spec.token.id,
-  direction: port.spec.direction,
-  required: port.spec.required,
-  enabled: port.enabled,
-  ...(port.spec.subscribesAtMount === undefined ? {} : { subscribesAtMount: port.spec.subscribesAtMount }),
-  ...(port.spec.emission === undefined ? {} : { emission: port.spec.emission }),
-  ...(port.spec.scopes === undefined ? {} : { scopes: port.spec.scopes }),
-  ...(port.spec.scopeFilter === undefined ? {} : { scopeFilter: port.spec.scopeFilter }),
-  ...(port.spec.stormBudgetPerWindow === undefined ? {} : { stormBudgetPerWindow: port.spec.stormBudgetPerWindow }),
-});
-
-/** Project a compiled manifest into the JSON document an export writes. */
-export function toFrozenManifest(manifest: EffectiveManifest): FrozenManifest {
-  return {
-    ...manifest,
-    frozenVersion: FROZEN_MANIFEST_VERSION,
-    instances: manifest.instances.map((instance) => ({ ...instance, ports: instance.ports.map(freezePort) })),
-    stagingCatalogs: manifest.stagingCatalogs.map((catalog) => {
-      const { tokens, ...rest } = catalog;
-      return { ...rest, tokenIds: tokens.map((token) => token.id) };
-    }),
-  };
-}
-
-/** `manifest.gen.json`'s text — stable key order via the projection, 2-space indent. */
-export const serializeFrozenManifest = (manifest: EffectiveManifest): string =>
-  `${JSON.stringify(toFrozenManifest(manifest), null, 2)}\n`;
-
-/**
- * A token stub for a re-hydrated port. `schema` and `sample` are deliberately
- * ABSENT (not `z.any()`): a consumer that validates through them would be
- * validating through a fabrication, and the whole point of the freeze contract is
- * that the loss is visible rather than plausible.
- */
-const stubToken = (id: string): TokenDef =>
-  ({ id, mode: 'value', description: 'stub — re-hydrated from manifest.gen.json (schema not serialized)' }) as unknown as TokenDef<z.ZodType>;
-
-const thawPort = (port: FrozenPort): MaterializedPort => {
-  const spec: PortSpec = {
-    id: port.id,
-    token: stubToken(port.tokenId),
-    direction: port.direction,
-    required: port.required,
-    ...(port.subscribesAtMount === undefined ? {} : { subscribesAtMount: port.subscribesAtMount }),
-    ...(port.emission === undefined ? {} : { emission: port.emission }),
-    ...(port.scopes === undefined ? {} : { scopes: port.scopes }),
-    ...(port.scopeFilter === undefined ? {} : { scopeFilter: port.scopeFilter }),
-    ...(port.stormBudgetPerWindow === undefined ? {} : { stormBudgetPerWindow: port.stormBudgetPerWindow }),
-  };
-  return { spec, enabled: port.enabled };
-};
-
-export class FrozenManifestError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'FrozenManifestError';
-  }
-}
-
-/**
- * Read `manifest.gen.json` back into an `EffectiveManifest` usable as the boot
- * moment's last-good bundle. Throws on a document this build cannot interpret —
- * a silently-half-read manifest would serve a surface nobody declared.
- */
-export function readFrozenManifest(document: unknown): EffectiveManifest {
-  if (document === null || typeof document !== 'object')
-    throw new FrozenManifestError('manifest.gen.json is not an object — regenerate the app (gen-app --engine-model).');
-  const frozen = document as Partial<FrozenManifest>;
-  if (frozen.frozenVersion !== FROZEN_MANIFEST_VERSION)
-    throw new FrozenManifestError(
-      `manifest.gen.json declares frozenVersion ${String(frozen.frozenVersion)}; this build reads ${FROZEN_MANIFEST_VERSION}. Regenerate the app rather than booting an artifact from a different compiler.`,
-    );
-  if (!Array.isArray(frozen.instances) || !Array.isArray(frozen.engines))
-    throw new FrozenManifestError('manifest.gen.json is missing `engines`/`instances` — the artifact is truncated.');
-
-  const { frozenVersion: _version, instances, stagingCatalogs, ...rest } = frozen as FrozenManifest;
-  return {
-    ...(rest as Omit<EffectiveManifest, 'instances' | 'stagingCatalogs'>),
-    instances: instances.map((instance) => ({ ...instance, ports: (instance.ports ?? []).map(thawPort) })),
-    stagingCatalogs: (stagingCatalogs ?? []).map((catalog) => {
-      const { tokenIds, ...catalogRest } = catalog;
-      return { ...catalogRest, tokens: tokenIds.map(stubToken) };
-    }),
-  };
-}

package/src/verify/index.ts

@@ -1,56 +0,0 @@
-/**
- * `cursedbelt/verify` — the V0–V7 verification pipeline (04).
- *
- * Engine generation (Phase 2) is blocked until this pipeline and its fixture
- * corpus run green, so this is the entry point every moment goes through:
- * the studio on each edit, `gen-app` at export, `resolveBootConfig` at boot, and
- * the CI hook before tsc/test/build.
- */
-export { parseEndpoint, type PipelineState, type ResolvedWire, type WireEndpoint } from './context';
-export { ccError, ccInfo, ccWarning, DiagnosticBag, sortDiagnostics } from './diagnostics';
-export { baseRegistry, ENGINE_CATALOG, engineCatalogIndex, STORM_BUDGET_PER_WINDOW } from './engines';
-export {
-  FROZEN_MANIFEST_VERSION,
-  type FrozenInstance,
-  type FrozenManifest,
-  FrozenManifestError,
-  type FrozenPort,
-  type FrozenStagingCatalog,
-  readFrozenManifest,
-  serializeFrozenManifest,
-  toFrozenManifest,
-} from './frozenManifest';
-export {
-  LEGACY_DESIGN_REMAP,
-  type LegacyDesignMapping,
-  migrationHintFor,
-  RETIRED_PLUGIN_IDS,
-} from './legacyDesigns';
-export {
-  detectPluginLoaderCode,
-  findPluginLoaderViolations,
-  type GeneratedSource,
-  type PluginLoaderViolation,
-} from './pluginLoader';
-export {
-  createPipelineState,
-  formatDiagnostics,
-  resolveBootConfig,
-  toArtifacts,
-  type VerifyArtifacts,
-  verifyAppConfig,
-} from './pipeline';
-export {
-  defineTokenExtension,
-  harvestStagingCatalogs,
-  HARVEST_RETRY_DELAYS_MS,
-  type HarvestResult,
-  readStagingFileWithRetry,
-  type StagingFileReader,
-  type StagingModuleDefinition,
-} from './staging/harvest';
-export { computeBundleKey } from './stages/v5Export';
-export * from './types';
-
-// ── promotion: the only path from `/staging` to production (02 §3.3) ────────
-export * from './promotion';

package/src/verify/interceptorGraph.spec.ts

@@ -1,113 +0,0 @@
-/**
- * A REAL interceptor registry produces REAL V4 edges (05 §B2).
- *
- * The point of this file is that the cycle is found from things somebody
- * REGISTERED, not from a handler list somebody typed into a fixture. Before the
- * pipeline landed, `eventbus-cycle` could only ever see hand-authored
- * declarations — so the audit was green on every app that had a genuine
- * interceptor loop, because no interceptor had ever contributed an edge.
- */
-import { describe, expect, it } from 'bun:test';
-import { type CCHookInterceptor, createInterceptorPipeline } from 'cwip/storage';
-import { interceptorHandlerDecls, withInterceptorEdges } from './interceptorGraph';
-import { verifyAppConfig } from './pipeline';
-import type { EventHandlerDecl } from './types';
-
-/** A minimal, valid app — the cycle under test is in the handler graph, not here. */
-const CONFIG = {
-  configVersion: 1,
-  app: { id: 'interceptor-graph', title: 'interceptor-graph' },
-  engines: ['knowledge'],
-  instances: [{ engine: 'knowledge', id: 'notes', features: { notes: true } }],
-};
-
-/**
- * Drive the REAL pipeline rather than the V4 stage directly (Law #4: green means
- * reachable through the real pipeline). A stage called in isolation can be green
- * while the pipeline never reaches it.
- */
-const cycles = async (eventHandlers: readonly EventHandlerDecl[]): Promise<string[]> => {
-  const result = await verifyAppConfig({ config: CONFIG, moment: 'boot', code: { eventHandlers } });
-  return result.diagnostics.filter((d) => d.code === 'eventbus-cycle').map((d) => d.message);
-};
-
-const hook = (id: string, targetAction: string, emits: string[], depthGuarded?: boolean): CCHookInterceptor => ({
-  id,
-  targetAction,
-  emits,
-  ...(depthGuarded === undefined ? {} : { depthGuarded }),
-  after: () => undefined,
-});
-
-describe('interceptorHandlerDecls', () => {
-  it('maps targetAction to `subscribes` and keeps a wildcard literal', () => {
-    // Collapsing `contacts.*` to the ops that exist today would make the graph a
-    // function of the current op catalogue: a cycle would appear and disappear
-    // as ops are added, instead of being reported against what was declared.
-    expect(interceptorHandlerDecls([hook('audit', 'contacts.*', ['contacts.createAuditEntry'])])).toEqual([
-      { id: 'audit', subscribes: 'contacts.*', emits: ['contacts.createAuditEntry'] },
-    ]);
-  });
-
-  it('gives an interceptor with no emits a leaf node rather than dropping it', () => {
-    // Dropping it would be tempting and wrong: a leaf is what proves the walk
-    // terminates, and an audit sink (the common case) is exactly a leaf.
-    const registry = createInterceptorPipeline({ onAfterError: () => undefined });
-    registry.register({ id: 'meter', targetAction: 'media.*', after: () => undefined });
-    expect(interceptorHandlerDecls(registry.interceptors)).toEqual([
-      { id: 'meter', subscribes: 'media.*', emits: [] },
-    ]);
-  });
-
-  it('carries depthGuarded through, because it is what breaks a reported cycle', () => {
-    expect(interceptorHandlerDecls([hook('terminal', 'a', ['b'], true)])[0]).toMatchObject({ depthGuarded: true });
-  });
-});
-
-describe('the V4 cycle audit, over registered interceptors', () => {
-  it('reports a two-interceptor mutation loop', async () => {
-    // The failure this whole seam exists to make visible: each hook is locally
-    // reasonable, and together they are an unbounded write loop that ends as a
-    // wedged transaction or a runaway bill.
-    const registry = createInterceptorPipeline({ onAfterError: () => undefined });
-    registry.register(hook('mirror-to-audit', 'contacts.createContact', ['audit.record']));
-    registry.register(hook('audit-touches-contact', 'audit.record', ['contacts.createContact']));
-
-    const found = await cycles(interceptorHandlerDecls(registry.interceptors));
-    expect(found).toHaveLength(1);
-    expect(found[0]).toMatch(/closes a cycle with no depth-guard exit/);
-  });
-
-  it('does not report the same loop once a hook declares its depth guard', async () => {
-    // The negative control. Without it, a passing cycle test proves only that
-    // the walk reports SOMETHING, not that it reports the right thing.
-    const registry = createInterceptorPipeline({ onAfterError: () => undefined });
-    registry.register(hook('mirror-to-audit', 'contacts.createContact', ['audit.record']));
-    registry.register(hook('audit-touches-contact', 'audit.record', ['contacts.createContact'], true));
-
-    expect(await cycles(interceptorHandlerDecls(registry.interceptors))).toEqual([]);
-  });
-
-  it('does not report an interceptor chain that terminates', async () => {
-    const registry = createInterceptorPipeline({ onAfterError: () => undefined });
-    registry.register(hook('a', 'contacts.createContact', ['audit.record']));
-    registry.register(hook('b', 'audit.record', ['metrics.increment']));
-    registry.register({ id: 'c', targetAction: 'metrics.increment', after: () => undefined });
-
-    expect(await cycles(interceptorHandlerDecls(registry.interceptors))).toEqual([]);
-  });
-
-  it('finds a cycle that runs engine subscriber → interceptor → engine subscriber', async () => {
-    // The reason `withInterceptorEdges` exists. Walking the two lists separately
-    // sees a terminating engine chain and a terminating interceptor chain and
-    // reports nothing, while the merged graph closes. This is the most likely
-    // real cycle there is, and it is invisible to either list alone.
-    const declared: EventHandlerDecl[] = [{ id: 'organizer', subscribes: 'NOTE_SAVED', emits: ['contacts.createContact'] }];
-    const registry = createInterceptorPipeline({ onAfterError: () => undefined });
-    registry.register(hook('contact-echo', 'contacts.createContact', ['NOTE_SAVED']));
-
-    expect(await cycles(declared)).toEqual([]);
-    expect(await cycles(interceptorHandlerDecls(registry.interceptors))).toEqual([]);
-    expect(await cycles(withInterceptorEdges(declared, registry.interceptors))).toHaveLength(1);
-  });
-});

package/src/verify/interceptorGraph.ts

@@ -1,62 +0,0 @@
-/**
- * Registered interceptors → V4 graph edges (05 §B2).
- *
- * `EventHandlerDecl.id`'s doc comment has said "an engine subscriber or a
- * `CCHookInterceptor`" since the V4 graph audit was written, and until the
- * pipeline landed that was aspirational: the audit reserved a node type for a
- * construct with no runtime, so `eventbus-cycle` could only ever see the
- * handlers somebody had typed into a fixture by hand. This is the function that
- * closes the loop — a REAL registry becomes real edges, so the cycle the audit
- * exists to catch is caught in the app that actually has it.
- *
- * ## Why the emits are declared rather than discovered
- *
- * An interceptor that reacts to `contacts.createContact` by writing a
- * `contacts.createAuditEntry` is fine. Two of them pointed at each other is an
- * unbounded mutation loop that ends as a wedged transaction, a full disk, or a
- * runaway bill — and it is not detectable from the hook bodies without executing
- * them, which is exactly what a static audit cannot do. So `emits` is part of
- * the registration contract: you say what you trigger, and V4 checks the shape
- * of what everyone said.
- *
- * An interceptor with no `emits` is a leaf and contributes no outgoing edge,
- * which is the common case (audit sinks, cache invalidation, metering) and costs
- * its author nothing.
- */
-import type { CCHookInterceptor } from 'cwip/storage';
-import type { EventHandlerDecl } from './types';
-
-/**
- * Map interceptors onto the declarations V4's cycle walk consumes.
- *
- * The `subscribes` edge is the hook's `targetAction`; a wildcard registration
- * keeps its literal form (`contacts.*`), because collapsing it to the ops it
- * happens to match today would make the graph depend on which ops exist rather
- * than on what was declared — and a cycle that appears the moment somebody adds
- * an op is precisely the cycle worth reporting up front.
- *
- * Interceptors with neither `emits` nor a chain to join contribute a leaf node,
- * which is harmless: `v4Graph` walks from every subscriber, and a node with no
- * outgoing edges terminates the walk immediately.
- */
-export const interceptorHandlerDecls = (interceptors: readonly CCHookInterceptor[]): readonly EventHandlerDecl[] =>
-  interceptors.map((interceptor) => ({
-    id: interceptor.id,
-    subscribes: interceptor.targetAction,
-    emits: interceptor.emits ?? [],
-    ...(interceptor.depthGuarded === true ? { depthGuarded: true } : {}),
-  }));
-
-/**
- * Merge interceptor edges into a config's existing `eventHandlers` for a V4 run.
- *
- * Kept as its own function rather than left to each caller's spread: the two
- * sources have to end up in ONE array or the cycle walk sees two disconnected
- * graphs and reports nothing — a chain that runs engine subscriber → interceptor
- * → engine subscriber is the most likely real cycle there is, and it is invisible
- * to a walk over either list alone.
- */
-export const withInterceptorEdges = (
-  declared: readonly EventHandlerDecl[] | undefined,
-  interceptors: readonly CCHookInterceptor[],
-): readonly EventHandlerDecl[] => [...(declared ?? []), ...interceptorHandlerDecls(interceptors)];

package/src/verify/legacyDesigns.ts

@@ -1,272 +0,0 @@
-/**
- * The design re-mapper: every legacy plugin id in the cursedshell catalog mapped
- * onto its consolidated destination (02 §1). A saved design that still names
- * `video-gallery` is not a mystery to be guessed at — V1 names the engine,
- * feature and view it became, or says plainly that no engine absorbed it and why.
- *
- * **The key space is the CATALOG ID** — the `id` a plugin's `src/provisioning.ts`
- * declares, which is exactly the string a legacy `app-config.json` puts in
- * `plugins[].name` and a saved `AppDesign` puts in an item's `pluginId`. Nothing
- * else. This was not true until 03 §2b: fifteen rows were keyed by prose names
- * that no plugin ever answered to (`kanban-board` for `board`, `apps` for
- * `app-registry`, `database` for `dbadmin`, `mandelbrot-fractal` for `fractal`,
- * …) and two named packages that have never existed on disk (`image-studio`,
- * `plugin-openclaw`), while fifteen real plugins had no row at all. A migrator
- * driven by that table would have refused every real app.
- *
- * **The table is exhaustive and a gate says so.** cursedshell's
- * `engine-app/migrate.test.ts` fails if this key set and the generated
- * `PLUGIN_CATALOG` key set differ in either direction — a new plugin lands
- * without a disposition, or a row outlives its package. The gate lives there
- * rather than here because the catalog is a cursedshell artifact and cursedbelt
- * may not import upward.
- *
- * **`deleted` is a DISPOSITION, not a claim about disk**, and `retired` is the
- * claim about disk. They are independent: `deleted` means "no engine absorbed this
- * plugin, so a migration drops its surface"; `retired` means "the package is no
- * longer in the workspace". A plugin can be absorbed AND retired (`board` → the
- * knowledge engine's kanban surface, package gone), deleted AND retired
- * (`fractal`), or absorbed and still shipping (`notes`).
- *
- * **Why a retired row STAYS in this table.** A legacy `app-config.json` out in the
- * world still names `board` or `fractal`, and that config is exactly the input this
- * table exists to translate. Dropping the row would make `migrateLegacyConfig`
- * answer "unknown plugin id: board" — a dead end — instead of "board became the
- * knowledge engine's kanban view". The row is the migration knowledge; the package
- * was only its old implementation. Deleting the knowledge with the code would make
- * every retired plugin an un-migratable app.
- */
-import type { EngineId } from '../config/appConfig';
-
-export interface LegacyDesignMapping {
-  engine?: EngineId;
-  feature?: string;
-  /** The engine view id this plugin's surface became. Absent = the plugin
-   *  contributes a FEATURE with no route of its own (a capability the engine's
-   *  other surfaces use, or — `stopwatch`, `notifications` — a dashboard fill). */
-  view?: string;
-  /** Set when no engine absorbed the plugin (02 §1.4, §1.6). Dropped by a
-   *  migration with this reason. Orthogonal to {@link retired}. */
-  deleted?: string;
-  /** Set when the PACKAGE is gone from the workspace (03 §4 decommission), with
-   *  the date it went. The mapping stays valid and keeps translating legacy
-   *  configs that still name it — see this module's header. */
-  retired?: string;
-}
-
-/** The ids whose packages left the workspace in the 03 §4 decommission, with the
- *  landing that removed them.
- *
- *  **Since wave 3 this list must equal this table's key set EXACTLY**, in both
- *  directions — cursedshell's `engine-app/migrate.test.ts` is the gate. It used to be
- *  "this list ∪ the live `PLUGIN_CATALOG`", because a row could outlive its package
- *  while other packages were still live; wave 3 retired the last plugin, so the
- *  catalog is gone and that union collapsed to this list alone. The invariant got
- *  STRICTER rather than weaker: it still catches a phantom row (the defect 03 §2b
- *  found fifteen of), and it now also catches a row deleted alongside its package —
- *  which would silently turn a migratable legacy config into "unknown plugin id",
- *  the exact dead end this table exists to prevent. */
-export const RETIRED_PLUGIN_IDS: readonly string[] = [
-  // 2026-07-26 — the first decommission landing (owner decisions E1/E2/E3).
-  // `apps/demos` (the 61-plugin showcase) and `apps/orch-host` were deleted, which
-  // took these 16 from "consumed" to "zero code consumers", plus the three
-  // deleted-disposition packages the owner named. `family-data` and
-  // `person-profiles` then fell out as a CASCADE: their only code consumer was
-  // `oral-history` (and each other), so the same pass drained them too.
-  'board',
-  'bookmarks',
-  'breadcrumbs',
-  'contacts',
-  'dashboard',
-  'externalAgent',
-  'family-data',
-  'family-tree-canvas',
-  'format-lab',
-  'fractal',
-  'line-filter',
-  'nes',
-  'ocr',
-  'oral-history',
-  'person-profiles',
-  'request-builder',
-  'stopwatch',
-  'text-compare',
-  'timeline-analytics',
-  'timeoff',
-  'worklog',
-  // 2026-07-26 — the SECOND wave, unblocked by owner decision D13. `apps/studio`
-  // no longer boots the legacy plugin runtime, and its whole-catalog builder
-  // palette was the last code consumer of these five. Each is absorbed by a
-  // landed dev/asset engine feature (see the rows above) — which is why the rows
-  // STAY: they are the migration knowledge for a legacy config still naming them.
-  'config-files',
-  'dbadmin',
-  'dev-portal',
-  'disk-usage',
-  'media-vault',
-  // 2026-07-26 — the THIRD and FINAL wave (owner decision E24/D18). `apps/orch2`,
-  // `orch2-companion`, `apps/p`, `apps/local-gallery` and `apps/core-site` were
-  // retired together with the legacy plugin RUNTIME, the v1 generator and the nine
-  // legacy engine packages, so every remaining plugin lost its last code consumer at
-  // once — there was no cascade left to wait for. The catalog no longer exists and
-  // `apps/studio` on the engine model is the only app this workspace ships, so every
-  // row in the table below now carries a `retired` stamp and this list IS its key set.
-  'admin',
-  'alias-manager',
-  'app-info',
-  'app-registry',
-  'backup',
-  'builder',
-  'calendar',
-  'commands',
-  'control-center',
-  'credentials-vault',
-  'deploy',
-  'docs-engine',
-  'file-gallery',
-  'files',
-  'folder-knowledge',
-  'git',
-  'knowledge',
-  'lists',
-  'media-gallery',
-  'notes',
-  'notes-organizer',
-  'notifications',
-  'orchChat',
-  'orchestrator',
-  'photo-gallery',
-  'pipeline-builder',
-  'prompt-builder',
-  'screenshots',
-  'task-sources',
-  'todo',
-  'unlock',
-  'vault',
-  'video-editor',
-  'video-gallery',
-];
-
-/** The decommission landing that removed the 21-package first wave. */
-const RETIRED = '2026-07-26 (03 §4)';
-/** The second wave, unblocked by owner decision D13 (the studio swap). Dated
- *  separately from {@link RETIRED} so the ledger can tell which landing drained
- *  a plugin — the two waves had different blockers and different evidence. */
-const RETIRED_D13 = '2026-07-26 (03 §4, wave 2 — D13)';
-/** The third and final wave (owner decision E24/D18): the five legacy apps, the
- *  plugin runtime, the v1 generator and the nine legacy engine packages went in one
- *  landing, which drained every plugin that was still live. */
-const RETIRED_WAVE3 = '2026-07-26 (03 §4, wave 3 — E24/D18)';
-
-/** The 2026-07-28 dead-schema-key sweep (plugin-catalog evaluation, owner
- *  decision P5): these plugins' target feature keys (`profiles`, `timelines`,
- *  `commands`, `git`, `promptBuilder`) were declared in `FeaturesByEngine` but
- *  consumed by no view, op, port, route or fill — config surface that did
- *  nothing. The keys are gone from the schema, so a migration DROPS these
- *  surfaces with this reason instead of emitting a config V0 refuses with
- *  `unknown-config-key`. */
-const NEVER_CONSUMED =
-  'its target feature key was schema-only (no view/op/route ever consumed it) and was removed 2026-07-28 (plugin-catalog evaluation P5); nothing absorbed the surface';
-
-export const LEGACY_DESIGN_REMAP: Readonly<Record<string, LegacyDesignMapping>> = {
-  // AssetStudio
-  'media-gallery': { engine: 'asset', feature: 'gallery', view: 'gallery', retired: RETIRED_WAVE3 },
-  'photo-gallery': { engine: 'asset', feature: 'gallery', view: 'gallery', retired: RETIRED_WAVE3 },
-  'video-gallery': { engine: 'asset', feature: 'video', view: 'video-feed', retired: RETIRED_WAVE3 },
-  'media-vault': { engine: 'asset', feature: 'vaultSource', view: 'gallery', retired: RETIRED_D13 },
-  'file-gallery': { engine: 'asset', feature: 'fileBrowser', view: 'file-browser', retired: RETIRED_WAVE3 },
-  files: { engine: 'asset', feature: 'taggedFiles', view: 'file-browser', retired: RETIRED_WAVE3 },
-  'video-editor': { engine: 'asset', feature: 'editor', view: 'video-editor', retired: RETIRED_WAVE3 },
-  ocr: { engine: 'asset', feature: 'ocr', retired: RETIRED },
-  // KnowledgeStudio
-  notes: { engine: 'knowledge', feature: 'notes', view: 'notes', retired: RETIRED_WAVE3 },
-  'notes-organizer': { engine: 'knowledge', feature: 'aiOrganizer', retired: RETIRED_WAVE3 },
-  todo: { engine: 'knowledge', feature: 'todos', view: 'todos', retired: RETIRED_WAVE3 },
-  lists: { engine: 'knowledge', feature: 'airtableStyleLists', view: 'lists', retired: RETIRED_WAVE3 },
-  board: { engine: 'knowledge', feature: 'kanban', view: 'kanban', retired: RETIRED },
-  contacts: { engine: 'knowledge', feature: 'contacts', view: 'contacts', retired: RETIRED },
-  'oral-history': { engine: 'knowledge', feature: 'oralHistory', view: 'oral-history', retired: RETIRED },
-  'text-compare': { engine: 'knowledge', feature: 'textCompare', view: 'text-compare', retired: RETIRED },
-  knowledge: { engine: 'knowledge', feature: 'ragChat', view: 'conversation', retired: RETIRED_WAVE3 },
-  'folder-knowledge': { engine: 'knowledge', feature: 'ragDiskIndexing', retired: RETIRED_WAVE3 },
-  bookmarks: { engine: 'knowledge', feature: 'bookmarks', retired: RETIRED },
-  worklog: { engine: 'knowledge', feature: 'worklog', retired: RETIRED },
-  'family-data': { engine: 'knowledge', feature: 'family', view: 'family-tree', retired: RETIRED },
-  'family-tree-canvas': { engine: 'knowledge', feature: 'family', view: 'family-tree', retired: RETIRED },
-  'person-profiles': { deleted: NEVER_CONSUMED, retired: RETIRED },
-  'timeline-analytics': { deleted: NEVER_CONSUMED, retired: RETIRED },
-  // DevStudio
-  'app-registry': { engine: 'dev', feature: 'appRegistry', view: 'apps', retired: RETIRED_WAVE3 },
-  'app-info': { engine: 'dev', feature: 'appRegistry', view: 'app-detail', retired: RETIRED_WAVE3 },
-  'dev-portal': { engine: 'dev', feature: 'appRegistry', view: 'apps', retired: RETIRED_D13 },
-  'config-files': { engine: 'dev', feature: 'configEditor', view: 'config-editor', retired: RETIRED_D13 },
-  deploy: { engine: 'dev', feature: 'deploy', view: 'deploy', retired: RETIRED_WAVE3 },
-  'control-center': { engine: 'dev', feature: 'fleet', view: 'fleet', retired: RETIRED_WAVE3 },
-  'pipeline-builder': { engine: 'dev', feature: 'pipelines', view: 'pipelines', retired: RETIRED_WAVE3 },
-  'alias-manager': { deleted: NEVER_CONSUMED, retired: RETIRED_WAVE3 },
-  commands: { deleted: NEVER_CONSUMED, retired: RETIRED_WAVE3 },
-  git: { deleted: NEVER_CONSUMED, retired: RETIRED_WAVE3 },
-  'docs-engine': { engine: 'dev', feature: 'docs', view: 'docs', retired: RETIRED_WAVE3 },
-  screenshots: { engine: 'dev', feature: 'screenshots', view: 'screenshots', retired: RETIRED_WAVE3 },
-  'disk-usage': { engine: 'dev', feature: 'diskUsage', retired: RETIRED_D13 },
-  dbadmin: { engine: 'dev', feature: 'dbAdmin', view: 'db-admin', retired: RETIRED_D13 },
-  backup: { engine: 'dev', feature: 'dbAdmin', view: 'db-admin', retired: RETIRED_WAVE3 },
-  orchestrator: { engine: 'dev', feature: 'orchestration', view: 'orchestration', retired: RETIRED_WAVE3 },
-  orchChat: { engine: 'dev', feature: 'orchestration', view: 'orchestration', retired: RETIRED_WAVE3 },
-  'task-sources': { engine: 'dev', feature: 'orchestration', view: 'orchestration', retired: RETIRED_WAVE3 },
-  'prompt-builder': { deleted: NEVER_CONSUMED, retired: RETIRED_WAVE3 },
-  // GuardEngine (02 §1.4 — the deletions)
-  vault: {
-    deleted:
-      'storage replaced by registry secret envelopes (01 §3.3); the UI is GuardEngine’s secrets panel (credentials-vault)',
-    retired: RETIRED_WAVE3,
-  },
-  'credentials-vault': { engine: 'guard', feature: 'secretsPanel', view: 'secrets', retired: RETIRED_WAVE3 },
-  unlock: { engine: 'guard', feature: 'privateMode', view: 'unlock', retired: RETIRED_WAVE3 },
-  admin: { engine: 'guard', feature: 'accounts', view: 'account', retired: RETIRED_WAVE3 },
-  // SystemUtility
-  dashboard: { engine: 'system', feature: 'dashboard', view: 'dashboard', retired: RETIRED },
-  calendar: { engine: 'system', feature: 'calendar', view: 'calendar', retired: RETIRED_WAVE3 },
-  notifications: { engine: 'system', feature: 'notifications', view: 'notifications', retired: RETIRED_WAVE3 },
-  stopwatch: { engine: 'system', feature: 'stopwatch', retired: RETIRED },
-  timeoff: { engine: 'system', feature: 'timeOff', view: 'time-off', retired: RETIRED },
-  'format-lab': { engine: 'system', feature: 'formatLab', view: 'utilities', retired: RETIRED },
-  'line-filter': { engine: 'system', feature: 'lineFilter', view: 'utilities', retired: RETIRED },
-  'request-builder': { engine: 'system', feature: 'httpClient', view: 'utilities', retired: RETIRED },
-  breadcrumbs: {
-    deleted: 'superseded by the cb navigation component + the nav:path token',
-    retired: RETIRED,
-  },
-  // Absorbed by no engine (02 §1.6)
-  fractal: {
-    deleted: 'pruned from the core catalog; the package was migrated to the standalone orch repo',
-    retired: RETIRED,
-  },
-  nes: {
-    deleted: 'pruned from the core catalog; the package was migrated to the standalone orch repo',
-    retired: RETIRED,
-  },
-  externalAgent: {
-    deleted: 'pruned; its SSE proxy is a CognitiveGateway driver config (03 §7.2)',
-    retired: RETIRED,
-  },
-  builder: {
-    deleted:
-      'the visual app builder is not an app surface — the Studio authors AppConfig directly (03 §3) and is never mounted inside a generated app',
-    retired: RETIRED_WAVE3,
-  },
-};
-
-export function migrationHintFor(legacyId: string): string | null {
-  const mapping = LEGACY_DESIGN_REMAP[legacyId];
-  if (!mapping) return null;
-  // The retirement is stated LAST and only as a parenthetical: what a migrating
-  // author needs first is where their surface went. "The package is gone" is the
-  // answer to a question they did not ask, and leading with it reads as a refusal.
-  const retired = mapping.retired ? ` (its package was retired ${mapping.retired})` : '';
-  if (mapping.deleted) return `'${legacyId}' was DELETED: ${mapping.deleted}${retired}.`;
-  const parts = [`engine '${mapping.engine}'`];
-  if (mapping.feature) parts.push(`features.${mapping.feature}`);
-  if (mapping.view) parts.push(`view '${mapping.view}'`);
-  return `'${legacyId}' became ${parts.join(' · ')}${retired}.`;
-}