skill-family-engineering-kit 0.1.0

package/src/migration.mjs

@@ -0,0 +1,427 @@
+import { lstat } from "node:fs/promises";
+import { findSchemaByObject } from "skill-family-contracts";
+import { HarnessError, readFileContained, resolveContained, validateContractDocument } from "skill-family-harness-node";
+import { normalizeRelPath, readOptionalJson } from "./workspace.mjs";
+
+/**
+ * Migration closure facts for adopt-plan (FND-070, formalized by the
+ * migration manifest contract).
+ *
+ * Everything here is strictly read-only and pure: adoption never mutates
+ * the target, and completion is a judgement computed from filesystem facts
+ * plus the target's own migration manifest. The kit never deletes legacy
+ * implementations itself — it only reports whether they have exited.
+ *
+ * The target declares its migration state in `skill-family.migration.json`,
+ * which is a formal Contract (migration-manifest, Contracts 1.1.1):
+ *
+ *   {
+ *     "schemaVersion": 1,
+ *     "kind": "skill-family.migration-manifest",
+ *     "legacyInfra": [ { "path": "scripts/old-validator.mjs", "replacedBy": "sf-kit check" } ],
+ *     "exceptions": [ { "owner": "...", "reason": "...", "deadline": "2026-12-31", "migrationTarget": "..." } ]
+ *   }
+ *
+ * The manifest loader distinguishes missing / parse-failed / schema-invalid /
+ * valid; only a valid manifest counts as declared. Temporary exceptions are
+ * only accepted when all four fields are present and non-blank; a missing
+ * field fails the plan (conflict), an expired deadline is never auto-renewed
+ * (risk + completion blocker). Every user-provided legacy path is assessed
+ * through harness containment: escapes fail closed and never reveal whether
+ * an outside path exists.
+ */
+
+/** Where a target declares its legacy exit list and temporary exceptions. */
+export const MIGRATION_MANIFEST_PATH = "skill-family.migration.json";
+
+export const MIGRATION_MANIFEST_KIND = "skill-family.migration-manifest";
+
+/** Registered schema $id of the migration-manifest contract. */
+export const MIGRATION_MANIFEST_SCHEMA_ID = findSchemaByObject("migration-manifest").$id;
+
+/** Loader outcome vocabulary: exactly one state per manifest file. */
+export const MIGRATION_MANIFEST_STATES = Object.freeze([
+  "missing",
+  "parse-failed",
+  "schema-invalid",
+  "valid",
+]);
+
+/** Every temporary exception must carry all four fields; one missing fails. */
+export const EXCEPTION_REQUIRED_FIELDS = Object.freeze([
+  "owner",
+  "reason",
+  "deadline",
+  "migrationTarget",
+]);
+
+/**
+ * Loads and validates the target's migration manifest against the formal
+ * migration-manifest contract (read-only). Returns:
+ *   { status: "missing" }                              — no manifest file;
+ *   { status: "parse-failed" }                         — not parseable JSON;
+ *   { status: "schema-invalid", problems }             — contract violation;
+ *   { status: "valid", manifest }                      — contract-conforming.
+ * Only "valid" counts as a declared manifest for planning and completion.
+ */
+export async function loadMigrationManifestState(root) {
+  const result = await readOptionalJson(root, MIGRATION_MANIFEST_PATH);
+  if (!result.ok) {
+    return { status: result.reason === "missing" ? "missing" : "parse-failed" };
+  }
+  const outcome = validateContractDocument(result.value, { schemaId: MIGRATION_MANIFEST_SCHEMA_ID });
+  if (!outcome.valid) {
+    return {
+      status: "schema-invalid",
+      problems: outcome.errors.map((error) => error.message ?? "schema violation"),
+      errorCode: outcome.errorCode,
+    };
+  }
+  return { status: "valid", manifest: result.value };
+}
+
+/**
+ * Loads the target's migration manifest (read-only, tolerant). Kept for
+ * callers that only need the parsed object: returns it when the manifest is
+ * contract-valid, otherwise null. Prefer loadMigrationManifestState, which
+ * distinguishes every failure state.
+ */
+export async function loadMigrationManifest(root) {
+  const state = await loadMigrationManifestState(root);
+  return state.status === "valid" ? state.manifest : null;
+}
+
+/**
+ * Validates one temporary exception. Returns finding descriptors:
+ * - { kind: "exception-incomplete", missing } when any required field is absent/blank;
+ * - { kind: "exception-invalid-deadline" } when deadline is not parseable;
+ * - { kind: "exception-expired" } when the deadline lies before `nowMs`.
+ * Expired exceptions are never renewed by tooling; they simply keep blocking.
+ */
+export function validateException(exception, index, nowMs) {
+  const missing = EXCEPTION_REQUIRED_FIELDS.filter(
+    (field) => typeof exception?.[field] !== "string" || exception[field].trim() === "",
+  );
+  if (missing.length > 0) {
+    return [{ index, kind: "exception-incomplete", missing }];
+  }
+  const deadlineMs = Date.parse(exception.deadline);
+  if (Number.isNaN(deadlineMs)) {
+    return [{ index, kind: "exception-invalid-deadline", deadline: exception.deadline }];
+  }
+  if (deadlineMs < nowMs) {
+    return [{ index, kind: "exception-expired", deadline: exception.deadline }];
+  }
+  return [];
+}
+
+/**
+ * Embedded repositories: only a nested `.git` entry is repository evidence
+ * (read-only Git evidence probe). A `.git` directory below the target root, or a `.git` *file*
+ * (the gitfile form used by submodules and linked worktrees), both count;
+ * `node_modules` and any other opaque directory is never repository
+ * evidence. The target's own root `.git` is not a nested repository. The
+ * plan reports the containing paths as risks; adoption never operates
+ * inside a nested repository.
+ */
+export function findNestedRepositories(entries) {
+  const repositories = [];
+  for (const entry of entries) {
+    const segments = entry.path.split("/");
+    if (segments[segments.length - 1] !== ".git") continue;
+    if (entry.path === ".git") continue;
+    const isGitDirectory = entry.kind === "directory-opaque";
+    const isGitFile = entry.kind === "file"; // gitfile: submodule/worktree link
+    if (isGitDirectory || isGitFile) repositories.push(segments.slice(0, -1).join("/"));
+  }
+  return repositories.sort();
+}
+
+/**
+ * Assesses the legacy exit list: one entry per declared legacy path with
+ * status "present" (still on disk), "absent" (already removed) or "invalid"
+ * (path rejected by harness containment or unreadable — fail-closed).
+ *
+ * Path containment: every user-provided path is resolved through
+ * the harness containment layer, which rejects absolute paths, `..`
+ * traversal, Windows drive/UNC/backslash forms and symlink escapes BEFORE
+ * any outside access; an invalid entry therefore never reveals whether a
+ * path outside the target root exists. Nothing is deleted by this function.
+ */
+export async function assessLegacyExitList(root, legacyItems) {
+  const list = [];
+  if (!Array.isArray(legacyItems)) return list;
+  for (const item of legacyItems) {
+    if (!item || typeof item.path !== "string" || item.path.trim() === "") {
+      list.push({ path: null, replacedBy: null, status: "invalid", invalidKind: "malformed-entry" });
+      continue;
+    }
+    const rel = normalizeRelPath(item.path);
+    const replacedBy = typeof item.replacedBy === "string" && item.replacedBy.trim() !== "" ? item.replacedBy : null;
+    if (replacedBy === null) {
+      list.push({ path: rel, replacedBy: null, status: "invalid", invalidKind: "empty-replaced-by" });
+      continue;
+    }
+    let resolved;
+    try {
+      resolved = await resolveContained(root, rel);
+    } catch (cause) {
+      // Containment rejection (traversal, absolute/UNC/drive forms, symlink
+      // escape) is decided without probing outside the root: fail closed and
+      // report the stable harness kind, never an existence oracle.
+      list.push({
+        path: rel,
+        replacedBy,
+        status: "invalid",
+        invalidKind: cause instanceof HarnessError && cause.details?.kind ? cause.details.kind : "containment-rejected",
+      });
+      continue;
+    }
+    let status = "absent";
+    try {
+      await lstat(resolved);
+      status = "present";
+    } catch {
+      status = "absent";
+    }
+    list.push({ path: rel, replacedBy, status });
+  }
+  return list;
+}
+
+/**
+ * Migration state machine. States advance monotonically as facts
+ * are proven; completion is the final state only. No tool ever advances a
+ * state by writing — states are judgements over read-only evidence.
+ *
+ *   not-declared  no contract-valid migration manifest exists;
+ *   declared      a contract-valid manifest exists, adoption unproven;
+ *   adopted       Foundation bytes proven on disk (digests match), no
+ *                 pending write actions, every legacy entry exited, no
+ *                 invalid/expired exceptions, no unresolved conflicts;
+ *   verified      adopted, and the Foundation check gate is green;
+ *   complete      verified, and all four verification evidence documents
+ *                 (unit, integration, consumer, independent audit) exist
+ *                 with matching project identity.
+ */
+export const MIGRATION_STATES = Object.freeze([
+  "not-declared",
+  "declared",
+  "adopted",
+  "verified",
+  "complete",
+]);
+
+/** Every Foundation package a complete migration must bind exactly. */
+export const REQUIRED_FOUNDATION_PACKAGES = Object.freeze([
+  "skill-family-contracts",
+  "skill-family-harness-node",
+  "skill-family-engineering-kit",
+]);
+
+/** The four evidence kinds a complete migration must prove. */
+export const VERIFICATION_EVIDENCE_KINDS = Object.freeze([
+  "unit",
+  "integration",
+  "consumer",
+  "independentAudit",
+]);
+
+/**
+ * Assesses the adoption binding declared by a contract-valid manifest
+ * (pure): the adopted profile id must equal the planned profile id, and
+ * every required Foundation package must be pinned to an exact version and
+ * sha256 digest. Returns { profileDeclared, profileMatches, covered,
+ * missingPackages }.
+ */
+export function assessAdoptionBinding(manifest, plannedProfileId) {
+  const declared = typeof manifest?.targetProfile === "string" && manifest.targetProfile.trim() !== "";
+  const profileMatches = declared && manifest.targetProfile === plannedProfileId;
+  const packages = Array.isArray(manifest?.foundationPackages) ? manifest.foundationPackages : [];
+  const boundNames = new Set(
+    packages
+      .filter(
+        (pkg) =>
+          pkg &&
+          typeof pkg.name === "string" &&
+          typeof pkg.version === "string" &&
+          /^[0-9]+\.[0-9]+\.[0-9]+$/.test(pkg.version) &&
+          typeof pkg.digest === "string" &&
+          /^sha256:[a-f0-9]{64}$/.test(pkg.digest),
+      )
+      .map((pkg) => pkg.name),
+  );
+  const missingPackages = REQUIRED_FOUNDATION_PACKAGES.filter((name) => !boundNames.has(name));
+  return { profileDeclared: declared, profileMatches, covered: [...boundNames].sort(), missingPackages };
+}
+
+/**
+ * Assesses the four verification evidence documents declared by the manifest
+ * (read-only, fail-closed). For each kind the outcome is one of:
+ *   undeclared       the manifest declares no path for this kind;
+ *   invalid-path     the path escapes containment (never an existence oracle);
+ *   missing          the declared file does not exist;
+ *   unreadable       not parseable JSON — evidence must be machine-checkable;
+ *   identity-mismatch  parses, but its projectId does not match the plan;
+ *   proven           exists and its projectId matches the plan's project id.
+ */
+export async function assessVerificationEvidence(rootAbs, verification, plannedProjectId) {
+  const declared = verification && typeof verification === "object" ? verification : {};
+  const facts = [];
+  for (const kind of VERIFICATION_EVIDENCE_KINDS) {
+    const rel = declared[kind];
+    if (typeof rel !== "string" || rel.trim() === "") {
+      facts.push({ kind, path: null, status: "undeclared" });
+      continue;
+    }
+    const pathValue = normalizeRelPath(rel);
+    let bytes;
+    try {
+      // Contained read: rejection or absence both fail closed without
+      // revealing anything about paths outside the target root.
+      bytes = await readFileContained(rootAbs, pathValue);
+    } catch {
+      facts.push({ kind, path: pathValue, status: "invalid-path" });
+      continue;
+    }
+    if (bytes === null) {
+      facts.push({ kind, path: pathValue, status: "missing" });
+      continue;
+    }
+    let document;
+    try {
+      document = JSON.parse(bytes.toString("utf8"));
+    } catch {
+      facts.push({ kind, path: pathValue, status: "unreadable" });
+      continue;
+    }
+    if (!document || document.projectId !== plannedProjectId) {
+      facts.push({ kind, path: pathValue, status: "identity-mismatch" });
+      continue;
+    }
+    facts.push({ kind, path: pathValue, status: "proven" });
+  }
+  return facts;
+}
+
+/**
+ * Migration completion gate (pure). Completion requires ALL of:
+ * - a contract-valid declared migration manifest;
+ * - the adoption binding proven: the declared targetProfile equals the
+ *   planned profile id and every required Foundation package is pinned to
+ *   an exact version plus sha256 digest;
+ * - the Project Manifest, managed lock, identity record and every managed
+ *   skeleton file present on disk with matching digests (adoptionProof);
+ * - no pending create/replace/project action left in the writeSet;
+ * - the Foundation check gate green;
+ * - every legacy implementation removed or provably absent — an invalid
+ *   (containment-rejected or malformed) entry fails closed like a present
+ *   one; dual-track wiring alone is not completion;
+ * - no incomplete/invalid/expired temporary exceptions;
+ * - no unresolved adoption conflicts;
+ * - all four verification evidence documents proven with matching identity.
+ *
+ * Returns { complete, state, blockers } where state is one of
+ * MIGRATION_STATES and blockers are stable, human-readable strings.
+ * Inputs that are absent are judged exactly like failed proofs: this gate
+ * only ever advances on presented evidence.
+ */
+export function evaluateMigrationCompletion({
+  manifestDeclared,
+  legacyExitList,
+  exceptionFindings,
+  conflicts,
+  binding,
+  adoptionProof,
+  pendingWrites = 0,
+  checkGreen,
+  verificationFacts,
+}) {
+  const adoptionBlockers = [];
+  const verificationBlockers = [];
+  const evidenceBlockers = [];
+
+  if (binding) {
+    if (!binding.profileMatches) {
+      adoptionBlockers.push(
+        binding.profileDeclared
+          ? "declared targetProfile does not match the planned profile id"
+          : "no targetProfile binding declared in the migration manifest",
+      );
+    }
+    if (binding.missingPackages?.length > 0) {
+      adoptionBlockers.push(
+        `Foundation packages not bound to exact version+digest: ${binding.missingPackages.join(", ")}`,
+      );
+    }
+  } else {
+    adoptionBlockers.push("adoption binding not assessed");
+  }
+
+  if (adoptionProof) {
+    if (adoptionProof.missing?.length > 0) {
+      adoptionBlockers.push(
+        `${adoptionProof.missing.length} managed skeleton file(s) absent on disk: ${adoptionProof.missing.join(", ")}`,
+      );
+    }
+    if (adoptionProof.mismatched?.length > 0) {
+      adoptionBlockers.push(
+        `${adoptionProof.mismatched.length} managed file(s) drifted from the planned digests: ${adoptionProof.mismatched.join(", ")}`,
+      );
+    }
+  } else {
+    adoptionBlockers.push("adoption proof not assessed");
+  }
+
+  const pending = typeof pendingWrites === "number" ? pendingWrites : (pendingWrites ?? []).length;
+  if (pending > 0) {
+    adoptionBlockers.push(`${pending} pending write action(s) remain in the writeSet`);
+  }
+
+  for (const item of legacyExitList ?? []) {
+    if (item.status === "present") {
+      adoptionBlockers.push(`legacy implementation still present: ${item.path}`);
+    } else if (item.status === "invalid") {
+      adoptionBlockers.push(`legacy entry cannot be verified (fail-closed): ${item.path ?? "<malformed>"} (${item.invalidKind ?? "unknown"})`);
+    }
+  }
+  for (const finding of exceptionFindings ?? []) {
+    if (finding.kind === "exception-incomplete") {
+      adoptionBlockers.push(`exception #${finding.index} missing required fields: ${finding.missing.join(", ")}`);
+    } else if (finding.kind === "exception-invalid-deadline") {
+      adoptionBlockers.push(`exception #${finding.index} has an unparseable deadline: ${finding.deadline}`);
+    } else if (finding.kind === "exception-expired") {
+      adoptionBlockers.push(`exception #${finding.index} expired at ${finding.deadline}; tooling never renews exceptions`);
+    }
+  }
+  if ((conflicts ?? []).length > 0) {
+    adoptionBlockers.push(`${conflicts.length} unresolved adoption conflict(s) remain`);
+  }
+
+  if (checkGreen !== true) {
+    verificationBlockers.push("the Foundation check gate is not green");
+  }
+
+  for (const fact of verificationFacts ?? []) {
+    if (fact.status === "proven") continue;
+    evidenceBlockers.push(`verification evidence ${fact.kind} is ${fact.status}${fact.path ? ` (${fact.path})` : ""}`);
+  }
+  if (!Array.isArray(verificationFacts)) {
+    evidenceBlockers.push("verification evidence not assessed");
+  }
+
+  let state = "not-declared";
+  if (manifestDeclared) {
+    if (adoptionBlockers.length > 0) state = "declared";
+    else if (verificationBlockers.length > 0) state = "adopted";
+    else if (evidenceBlockers.length > 0) state = "verified";
+    else state = "complete";
+  }
+
+  const blockers = [];
+  if (!manifestDeclared) {
+    blockers.push(`no contract-valid migration manifest declared at ${MIGRATION_MANIFEST_PATH}`);
+  }
+  blockers.push(...adoptionBlockers, ...verificationBlockers, ...evidenceBlockers);
+  return { complete: state === "complete", state, blockers };
+}