quixos-protocol/src/capability-model/migrations.ts

import { contentDigest } from "./evolution.js";
import type { PersistentAttachment } from "./types.js";

/** Portable storage shape: local owner/slot/projection identities are supplied
 * by the consuming workspace's explicit bindings, never baked into this hash. */
export const migrationPortContract = (attachment: PersistentAttachment): unknown => {
  if (attachment.kind === "state") return {kind: "state", valueType: attachment.valueType, storagePolicy: attachment.storagePolicy,
    ...(attachment.defaultValue === undefined ? {} : {defaultValue: attachment.defaultValue})};
  const endpoint = (value: typeof attachment.endpoints[number]) => ({constraint: value.constraint, cardinality: value.cardinality,
    ordered: value.ordered, onDelete: value.onDelete ?? "restrict", retainOther: value.retainOther ?? false,
    ...(value.keyType ? {keyType: value.keyType} : {}), ...(value.publicTraversal ? {publicTraversal: true} : {})});
  return {kind: "edge", first: endpoint(attachment.endpoints[0]), second: endpoint(attachment.endpoints[1])};
};

export type MigrationDeclaration = {
  id: string;
  scopeId: string;
  from: string;
  to: string;
  implementation: { exportId: string; file: string; digest: string };
  predecessors: string[];
  ports: { name: string; view: "old" | "new"; access: ("read" | "write" | "create" | "edge")[]; contractDigest: string }[];
  preservesOldReaders?: boolean;
  preservesOldWriters?: boolean;
};
export type MigrationCatalog = {
  schemaVersion: 1;
  contracts: Record<string, unknown>;
  migrations: MigrationDeclaration[];
};
export const validateMigrationCatalog = (value: unknown, exportIds?: ReadonlySet<string>): MigrationCatalog => {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Migration catalog must be an object");
  const catalog = value as MigrationCatalog;
  if (catalog.schemaVersion !== 1 || !catalog.contracts || Array.isArray(catalog.contracts) || !Array.isArray(catalog.migrations)) throw new Error("Unsupported migration catalog");
  for (const [digest, contract] of Object.entries(catalog.contracts)) if (contentDigest(contract) !== digest) throw new Error(`Migration contract digest mismatch: ${digest}`);
  const ids = new Set<string>();
  for (const migration of catalog.migrations) {
    if (!migration.id || !migration.scopeId || ids.has(migration.id)) throw new Error("Migration IDs must be stable and unique");
    ids.add(migration.id);
    if (!catalog.contracts[migration.from] || !catalog.contracts[migration.to] || migration.from === migration.to) throw new Error(`Migration ${migration.id} requires distinct retained source and target contracts`);
    if (!migration.implementation?.exportId || !/^sha256:[0-9a-f]{64}$/.test(migration.implementation.digest)) throw new Error(`Migration ${migration.id} requires an exact implementation digest`);
    if (!migration.implementation.file || migration.implementation.file.startsWith("/") || migration.implementation.file.split(/[\\/]/).some((part) => !part || part === "." || part === "..")) throw new Error("Migration implementation must be a relative package file");
    if (exportIds && !exportIds.has(migration.implementation.exportId)) throw new Error(`Migration ${migration.id} refers to an undeclared package export`);
    if (!Array.isArray(migration.predecessors) || !Array.isArray(migration.ports)) throw new Error(`Migration ${migration.id} requires predecessors and ports`);
    if (new Set(migration.predecessors).size !== migration.predecessors.length) throw new Error(`Duplicate predecessor in ${migration.id}`);
    for (const promise of [migration.preservesOldReaders, migration.preservesOldWriters]) if (promise !== undefined && typeof promise !== "boolean") throw new Error("Migration compatibility promises must be booleans");
    const ports = new Set<string>();
    for (const port of migration.ports) {
      if (!port.name || ports.has(port.name) || !["old", "new"].includes(port.view) || !Array.isArray(port.access) || !port.access.length
        || port.access.some((access) => !["read", "write", "create", "edge"].includes(access)) || !catalog.contracts[port.contractDigest]) throw new Error(`Invalid migration port in ${migration.id}`);
      if (port.view === "old" && port.access.some((access) => access !== "read")) throw new Error("Old migration views are read-only");
      ports.add(port.name);
    }
  }
  for (const migration of catalog.migrations) for (const predecessor of migration.predecessors) if (!ids.has(predecessor)) throw new Error(`Missing retained predecessor ${predecessor}`);
  // Catalogs are retained across releases. Reject impossible histories at
  // publication/check time, not only when someone tries to select a path.
  const remaining = new Map(catalog.migrations.map((entry) => [entry.id, new Set(entry.predecessors)]));
  const ready = [...remaining].filter(([, dependencies]) => dependencies.size === 0).map(([id]) => id);
  for (let index = 0; index < ready.length; index++) {
    remaining.delete(ready[index]);
    for (const [id, dependencies] of remaining) if (dependencies.delete(ready[index]) && dependencies.size === 0) ready.push(id);
  }
  if (remaining.size) throw new Error(`Cyclic migration predecessors: ${[...remaining.keys()].join(", ")}`);
  return catalog;
};

export type MigrationSelection = {
  scopeId: string; from: string; to: string; path: string[];
  bindings: Record<string, string>;
};
/** Explicit paths, not shortest-path guesses. Receipts identify code plus local scope mapping. */
export const selectMigrationPath = (catalog: MigrationCatalog, selection: MigrationSelection, previousReceipts: ReadonlyMap<string, string> = new Map()) => {
  validateMigrationCatalog(catalog);
  let current = selection.from;
  const seen = new Set<string>();
  const transitions = [];
  for (const id of selection.path) {
    const declaration = catalog.migrations.find((entry) => entry.id === id);
    if (!declaration || declaration.scopeId !== selection.scopeId || declaration.from !== current || seen.has(id)) throw new Error(`Invalid selected migration transition ${id}`);
    for (const predecessor of declaration.predecessors) if (!seen.has(predecessor) && !previousReceipts.has(predecessor)) throw new Error(`Unsatisfied predecessor ${predecessor}`);
    const usedBindings: Record<string, string> = {};
    for (const port of declaration.ports) {
      if (!selection.bindings[port.name]) throw new Error(`Missing local migration binding ${port.name}`);
      usedBindings[port.name] = selection.bindings[port.name];
    }
    const digest = contentDigest({ declaration, bindings: usedBindings });
    const previous = previousReceipts.get(id);
    if (previous && previous !== digest) throw new Error(`Migration identity ${id} was previously used with different code or scope`);
    transitions.push({ declaration, bindings: usedBindings, digest, alreadyApplied: Boolean(previous) });
    seen.add(id);
    current = declaration.to;
  }
  if (current !== selection.to) throw new Error("Selected migration path does not cover the target storage contract");
  return transitions;
};