@opengsd/gsd-core 1.2.0 → 1.3.0

package/gsd-core/bin/lib/install-profiles.cjs

@@ -0,0 +1,526 @@
+"use strict";
+/**
+ * Skill Surface Budget Module — single source of truth for which skills/agents
+ * are written to the runtime config dirs (ADR-0011).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/install-profiles.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ---------------------------------------------------------------------------
+// Profile definitions
+// ---------------------------------------------------------------------------
+/**
+ * PROFILES maps profile name → base skill set (array) or '*' sentinel (full).
+ *
+ * The effective set for any profile is CLOSURE(base, requires: manifest).
+ * standard is a superset of core; full is the identity (all skills).
+ *
+ * Composition: --profile=core,audit resolves to union(closure(core), closure(audit)).
+ */
+const PROFILES = Object.freeze({
+    core: Object.freeze([
+        'new-project',
+        'discuss-phase',
+        'plan-phase',
+        'execute-phase',
+        'phase',
+        'help',
+        'update',
+        'surface',
+    ]),
+    standard: Object.freeze([
+        // Core loop
+        'new-project',
+        'discuss-phase',
+        'plan-phase',
+        'execute-phase',
+        'help',
+        'update',
+        'surface',
+        // Phase management (hot nodes from audit — required by 38+ skills)
+        'phase',
+        'review',
+        'config',
+        'progress',
+        // Workspace / state
+        'resume-work',
+        'pause-work',
+        'workspace',
+    ]),
+    full: '*',
+});
+// ---------------------------------------------------------------------------
+// Manifest parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the requires: field from YAML frontmatter.
+ * Handles: "requires: [a, b, c]" (flow style) and absent field.
+ * Returns string[] — empty array if no requires: field.
+ *
+ * No external YAML parser dependency — hand-parse the single line
+ * since GSD enforces flow-style arrays for requires:.
+ */
+function parseRequires(content) {
+    const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/m);
+    if (!fmMatch)
+        return [];
+    const fm = fmMatch[1];
+    const line = fm.match(/^requires:\s*(.+)$/m);
+    if (!line)
+        return [];
+    const val = line[1].trim();
+    // Flow-style: [a, b, c]
+    if (val.startsWith('[') && val.endsWith(']')) {
+        const inner = val.slice(1, -1).trim();
+        if (!inner)
+            return [];
+        return inner.split(',').map((s) => s.trim()).filter(Boolean);
+    }
+    // Single bare value (not currently used, but defensive)
+    return val ? [val] : [];
+}
+/**
+ * Parse agent references from a skill file's body text.
+ * Scans the full content for `gsd-<stem>` patterns that correspond to
+ * real agent files. Returns all unique `gsd-*` stems found in the body.
+ *
+ * The caller is responsible for filtering by which agents actually exist —
+ * this function returns all syntactically valid `gsd-*` matches.
+ */
+function parseCallsAgents(content) {
+    // Match word-boundary gsd-<stem> patterns; stems are lowercase letters and hyphens.
+    // We use a regex that matches `gsd-` followed by one or more lowercase-alpha-or-hyphen chars.
+    // This catches `gsd-planner`, `gsd-plan-checker`, etc. in prose and code.
+    const matches = content.match(/\bgsd-[a-z][a-z-]*/g);
+    if (!matches)
+        return [];
+    // Deduplicate
+    return [...new Set(matches)];
+}
+/**
+ * Load the requires: dependency graph from a commands/gsd directory.
+ * Also derives calls_agents for each skill by scanning the body text for
+ * `gsd-*` agent name references. Agent stems are stored under the special
+ * key `_calls_agents_<stem>` so they don't conflict with skill stems.
+ */
+function loadSkillsManifest(commandsDir) {
+    const manifest = new Map();
+    if (!node_fs_1.default.existsSync(commandsDir))
+        return manifest;
+    const entries = node_fs_1.default.readdirSync(commandsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        const stem = entry.name.slice(0, -3);
+        try {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(commandsDir, entry.name), 'utf8');
+            manifest.set(stem, parseRequires(content));
+            // Derive agent references from body text
+            const agentRefs = parseCallsAgents(content);
+            manifest.set(`_calls_agents_${stem}`, agentRefs);
+        }
+        catch {
+            manifest.set(stem, []);
+            manifest.set(`_calls_agents_${stem}`, []);
+        }
+    }
+    return manifest;
+}
+// ---------------------------------------------------------------------------
+// Profile resolution (transitive closure)
+// ---------------------------------------------------------------------------
+/**
+ * Compute the transitive closure of a set of skill stems over the manifest.
+ */
+function computeClosure(base, manifest) {
+    const closed = new Set(base);
+    const queue = [...closed];
+    while (queue.length > 0) {
+        const stem = queue.pop();
+        const deps = manifest.get(stem) || [];
+        for (const dep of deps) {
+            if (!closed.has(dep)) {
+                closed.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return closed;
+}
+/**
+ * Resolve a profile (or composed profiles) to a typed result object.
+ */
+function resolveProfile({ modes, manifest, _profilesOverride } = {}) {
+    const profiles = _profilesOverride || PROFILES;
+    const activeModes = (modes && modes.length > 0) ? modes : ['full'];
+    const normalizedModes = activeModes
+        .flatMap((mode) => String(mode).split(','))
+        .map((mode) => mode.trim())
+        .filter(Boolean);
+    const modesToResolve = normalizedModes.length > 0 ? normalizedModes : ['full'];
+    // If any mode is 'full', the result is the full sentinel
+    if (modesToResolve.includes('full')) {
+        return { name: 'full', skills: '*', agents: new Set() };
+    }
+    const validModes = modesToResolve.filter((mode) => Object.prototype.hasOwnProperty.call(profiles, mode));
+    if (validModes.length === 0) {
+        // Invalid/corrupt marker fallback: avoid empty installs by defaulting to full.
+        return { name: 'full', skills: '*', agents: new Set() };
+    }
+    const man = manifest || new Map();
+    const unionSkills = new Set();
+    for (const mode of validModes) {
+        const base = profiles[mode];
+        if (base === '*') {
+            // This profile is full — sentinel short-circuit
+            return { name: 'full', skills: '*', agents: new Set() };
+        }
+        const closure = computeClosure(base, man);
+        for (const s of closure)
+            unionSkills.add(s);
+    }
+    // Derive agents: union of all agent names referenced in the body text of
+    // every skill in unionSkills. Agent names are stored in the manifest under
+    // _calls_agents_<stem> keys (populated by loadSkillsManifest).
+    const unionAgents = new Set();
+    for (const skillStem of unionSkills) {
+        const agentRefs = man.get(`_calls_agents_${skillStem}`) || [];
+        for (const agentStem of agentRefs) {
+            unionAgents.add(agentStem);
+        }
+    }
+    const name = validModes.length === 1 ? validModes[0] : validModes.join(',');
+    return { name, skills: unionSkills, agents: unionAgents };
+}
+// ---------------------------------------------------------------------------
+// Staging — skills
+// ---------------------------------------------------------------------------
+// Stage dirs created during this process — cleaned up on exit.
+// 13 runtime dispatch sites in install.js can each call stageSkillsForMode,
+// so accumulating them in a single set avoids leaks without forcing each
+// site to track its own cleanup handle.
+const STAGED_DIRS = new Set();
+let exitHandlerRegistered = false;
+function cleanupStagedSkills() {
+    for (const dir of STAGED_DIRS) {
+        try {
+            node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort: missing dir or permission error shouldn't crash a
+            // successful install. The OS reaps tmpdir eventually.
+        }
+    }
+    STAGED_DIRS.clear();
+}
+// Signals we register a cleanup handler for in addition to the natural
+// 'exit' event. `process.on('exit')` does NOT fire on these — an installer
+// is exactly the kind of process users abort mid-run, so without explicit
+// signal handling Ctrl+C would leave staged tmp dirs behind.
+const CLEANUP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+function ensureExitCleanup() {
+    if (exitHandlerRegistered)
+        return;
+    exitHandlerRegistered = true;
+    process.on('exit', cleanupStagedSkills);
+    for (const sig of CLEANUP_SIGNALS) {
+        // `once` so re-raising the signal below isn't intercepted by us a second
+        // time — the OS-default handler should take over and exit with the right
+        // status code (so CI sees the abort, scripts see 130 for SIGINT, etc.).
+        process.once(sig, () => {
+            cleanupStagedSkills();
+            process.kill(process.pid, sig);
+        });
+    }
+}
+/**
+ * Stage a filtered copy of commands/gsd for a resolved profile.
+ * In full mode (skills === '*') returns srcDir unchanged (no-op).
+ */
+function stageSkillsForProfile(srcDir, resolvedProfile) {
+    if (resolvedProfile.skills === '*')
+        return srcDir;
+    if (!node_fs_1.default.existsSync(srcDir))
+        return srcDir;
+    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-skills-'));
+    try {
+        const entries = node_fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const stem = entry.name.slice(0, -3);
+            if (!(resolvedProfile.skills).has(stem))
+                continue;
+            node_fs_1.default.copyFileSync(node_path_1.default.join(srcDir, entry.name), node_path_1.default.join(stageDir, entry.name));
+        }
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    STAGED_DIRS.add(stageDir);
+    ensureExitCleanup();
+    return stageDir;
+}
+/**
+ * Stage a filtered copy of the agents directory for a resolved profile.
+ * For 'full', returns srcAgentsDir unchanged.
+ * For tiered profiles, copies only agents whose full stem (e.g. 'gsd-planner')
+ * is in resolvedProfile.agents — which is populated by resolveProfile() from
+ * the _calls_agents_* entries in the manifest.
+ */
+function stageAgentsForProfile(srcAgentsDir, resolvedProfile) {
+    if (resolvedProfile.skills === '*')
+        return srcAgentsDir;
+    if (!node_fs_1.default.existsSync(srcAgentsDir))
+        return srcAgentsDir;
+    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-agents-'));
+    try {
+        if (resolvedProfile.agents instanceof Set && resolvedProfile.agents.size > 0) {
+            const entries = node_fs_1.default.readdirSync(srcAgentsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.md'))
+                    continue;
+                // Agent stem is the full filename without extension, e.g. "gsd-planner"
+                const stem = entry.name.slice(0, -3);
+                if (!resolvedProfile.agents.has(stem))
+                    continue;
+                node_fs_1.default.copyFileSync(node_path_1.default.join(srcAgentsDir, entry.name), node_path_1.default.join(stageDir, entry.name));
+            }
+        }
+        // If agents is empty Set, we produce an empty stageDir (no agents for this profile)
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    STAGED_DIRS.add(stageDir);
+    ensureExitCleanup();
+    return stageDir;
+}
+function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix) {
+    if (!node_fs_1.default.existsSync(srcCommandsDir))
+        return srcCommandsDir;
+    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-skills-'));
+    try {
+        const entries = node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const stem = entry.name.slice(0, -3);
+            if (resolvedProfile.skills !== '*' && !(resolvedProfile.skills).has(stem))
+                continue;
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
+            const skillName = `${prefix}${stem}`;
+            const converted = converter(content, skillName);
+            const destDir = node_path_1.default.join(stageDir, skillName);
+            node_fs_1.default.mkdirSync(destDir, { recursive: true });
+            node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
+        }
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    STAGED_DIRS.add(stageDir);
+    ensureExitCleanup();
+    return stageDir;
+}
+// ---------------------------------------------------------------------------
+// Profile marker persistence
+// ---------------------------------------------------------------------------
+const PROFILE_MARKER_NAME = '.gsd-profile';
+/**
+ * Read the active profile from a runtime config directory.
+ */
+function readActiveProfile(runtimeConfigDir) {
+    const markerPath = node_path_1.default.join(runtimeConfigDir, PROFILE_MARKER_NAME);
+    try {
+        const raw = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+        if (!raw)
+            return null;
+        // Validate that it looks like a profile name (alphanumeric + hyphens + commas)
+        if (!/^[a-z0-9,_-]+$/i.test(raw))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the active profile to a runtime config directory.
+ */
+function writeActiveProfile(runtimeConfigDir, profileName) {
+    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(runtimeConfigDir, PROFILE_MARKER_NAME), profileName + '\n');
+}
+// ---------------------------------------------------------------------------
+// Profile resolution helpers for install / update flows
+// ---------------------------------------------------------------------------
+/**
+ * Rank ordering for profiles (lower index = more restrictive / smaller skill set).
+ * Unknown profiles default to the permissive end (treated as 'full').
+ */
+const PROFILE_RANK = Object.freeze(['core', 'standard', 'full']);
+/**
+ * Given an array of profile names (one per runtime), return the most-restrictive
+ * profile — i.e. the one with the smallest effective skill set.
+ *
+ * Ordering (most to least restrictive): core < standard < full.
+ * Composed profiles (e.g. 'core,audit') and unknown profiles are treated as
+ * 'full' for this comparison.
+ */
+function mostRestrictiveProfile(profileNames) {
+    if (!profileNames || profileNames.length === 0)
+        return 'full';
+    // Initialize with the least-restrictive rank (one past the end of PROFILE_RANK)
+    let bestRank = PROFILE_RANK.length;
+    let bestName = 'full';
+    for (const name of profileNames) {
+        const rank = PROFILE_RANK.indexOf(name);
+        // Unknown/composed profiles are treated as the permissive 'full' rank.
+        const effectiveRank = rank === -1 ? PROFILE_RANK.indexOf('full') : rank;
+        if (effectiveRank < bestRank) {
+            bestRank = effectiveRank;
+            bestName = rank === -1 ? 'full' : name;
+        }
+    }
+    return bestName;
+}
+/**
+ * Resolve the effective profile name for an install() run.
+ *
+ * Priority:
+ *   1. Explicit flag (requestedProfileName != null) → use it as-is.
+ *   2. Marker exists in targetDir and is not 'full' → use marker.
+ *   3. Else → 'full' (back-compat for fresh non-interactive installs).
+ */
+function resolveEffectiveProfile({ requestedProfileName, targetDir }) {
+    // 1. Explicit flag overrides everything
+    if (requestedProfileName != null)
+        return requestedProfileName;
+    // 2. Marker-driven (gsd update path)
+    const marker = readActiveProfile(targetDir);
+    if (marker && marker !== 'full')
+        return marker;
+    // 3. Default
+    return 'full';
+}
+// ---------------------------------------------------------------------------
+// Back-compat shims (deprecated — use profile-based API instead)
+// ---------------------------------------------------------------------------
+/**
+ * @deprecated Use PROFILES.core instead.
+ * Preserved for callers in install.js and existing tests.
+ */
+const MINIMAL_SKILL_ALLOWLIST = Object.freeze([...PROFILES.core]);
+const MINIMAL_ALLOWLIST_SET = new Set(MINIMAL_SKILL_ALLOWLIST);
+/**
+ * @deprecated Use resolveProfile({ modes: ['core'] }) instead.
+ */
+function isMinimalMode(mode) {
+    return mode === 'minimal' || mode === 'core-only';
+}
+/**
+ * Overloaded for back-compat.
+ * - If resolvedProfileOrMode is a string: legacy mode check (full/minimal)
+ * - If resolvedProfileOrMode is an object with .skills: new profile API
+ *
+ * @deprecated String-mode form; use resolvedProfile object form instead.
+ */
+function shouldInstallSkill(skillBaseName, resolvedProfileOrMode) {
+    if (typeof resolvedProfileOrMode === 'object' && resolvedProfileOrMode !== null) {
+        const { skills } = resolvedProfileOrMode;
+        if (skills === '*')
+            return true;
+        return skills instanceof Set && skills.has(skillBaseName);
+    }
+    // Legacy string mode
+    const mode = resolvedProfileOrMode;
+    if (!isMinimalMode(mode))
+        return true;
+    return MINIMAL_ALLOWLIST_SET.has(skillBaseName);
+}
+/**
+ * Stage a filtered copy of the source commands/gsd directory.
+ * Back-compat wrapper: maps 'minimal' → core profile, 'full' → full.
+ *
+ * @deprecated Use stageSkillsForProfile with a resolved profile instead.
+ */
+function stageSkillsForMode(srcDir, mode) {
+    if (!isMinimalMode(mode))
+        return srcDir;
+    if (!node_fs_1.default.existsSync(srcDir))
+        return srcDir;
+    const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-minimal-skills-'));
+    try {
+        const entries = node_fs_1.default.readdirSync(srcDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const baseName = entry.name.replace(/\.md$/, '');
+            if (!shouldInstallSkill(baseName, mode))
+                continue;
+            node_fs_1.default.copyFileSync(node_path_1.default.join(srcDir, entry.name), node_path_1.default.join(stageDir, entry.name));
+        }
+    }
+    catch (err) {
+        try {
+            node_fs_1.default.rmSync(stageDir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+        throw err;
+    }
+    STAGED_DIRS.add(stageDir);
+    ensureExitCleanup();
+    return stageDir;
+}
+module.exports = {
+    // New profile API (ADR-0011)
+    PROFILES,
+    PROFILE_RANK,
+    loadSkillsManifest,
+    resolveProfile,
+    resolveEffectiveProfile,
+    mostRestrictiveProfile,
+    stageSkillsForProfile,
+    stageAgentsForProfile,
+    stageSkillsForRuntimeAsSkills,
+    STAGED_DIRS,
+    readActiveProfile,
+    writeActiveProfile,
+    // Shared internals
+    cleanupStagedSkills,
+    // Back-compat / deprecated
+    MINIMAL_SKILL_ALLOWLIST,
+    isMinimalMode,
+    shouldInstallSkill,
+    stageSkillsForMode,
+};

package/gsd-core/bin/lib/installer-migration-authoring.cjs

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Installer Migration Authoring — validation helpers for installer migration records and actions.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migration-authoring.cjs collapsed to a TypeScript source
+ * of truth. Behaviour is preserved byte-for-behaviour from the prior
+ * hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInstallerMigrationRecord = validateInstallerMigrationRecord;
+exports.validateInstallerMigrationActions = validateInstallerMigrationActions;
+const node_path_1 = __importDefault(require("node:path"));
+function getStr(record, field) {
+    const v = record[field];
+    return typeof v === 'string' ? v : '';
+}
+function requireNonEmptyString(record, field, source) {
+    const v = record[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+        throw new Error(`migration record must include a non-empty ${field}: ${source}`);
+    }
+}
+function isNonEmptyStringArray(arr) {
+    return Array.isArray(arr) && arr.length > 0 && arr.every((v) => typeof v === 'string' && v.trim() !== '');
+}
+function validateStringArray(record, field, source) {
+    if (record[field] === undefined)
+        return;
+    if (!isNonEmptyStringArray(record[field])) {
+        throw new Error(`migration record ${field} must be a non-empty string array when provided: ${source}`);
+    }
+}
+function requireStringArray(record, field, source) {
+    if (!isNonEmptyStringArray(record[field])) {
+        throw new Error(`migration record ${field} must be a non-empty string array: ${source}`);
+    }
+}
+function recordSource(record, fallback) {
+    const id = getStr(record, 'id');
+    return fallback ?? (id.trim() ? id : '<unknown>');
+}
+function actionSource(migration, action) {
+    const migrationId = getStr(migration, 'id') || '<unknown>';
+    const relPath = getStr(action, 'relPath') || '<unknown>';
+    return `${migrationId} ${relPath}`;
+}
+function requireActionEvidence(action, field, migration) {
+    const v = action[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+        throw new Error(`migration action ${getStr(action, 'type')} must include ${field}: ${actionSource(migration, action)}`);
+    }
+}
+function validateSafeRelPath(relPath, migration, actionType) {
+    const source = actionSource(migration, { relPath });
+    const normalized = relPath.replace(/\\/g, '/');
+    if (node_path_1.default.isAbsolute(normalized) || node_path_1.default.win32.isAbsolute(normalized)) {
+        throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
+    }
+    const segments = normalized.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
+    }
+}
+function validateInstallerMigrationRecord(record, source) {
+    const rec = record;
+    const displaySource = recordSource(rec, source);
+    if (!record || typeof record !== 'object') {
+        throw new Error(`migration record must export an object: ${displaySource}`);
+    }
+    // Authoring contract follows docs/installer-migrations.md#authoring-workflow
+    // and docs/adr/0008-installer-migration-module.md#decision.
+    requireNonEmptyString(rec, 'id', displaySource);
+    requireNonEmptyString(rec, 'title', displaySource);
+    requireNonEmptyString(rec, 'description', displaySource);
+    requireNonEmptyString(rec, 'introducedIn', displaySource);
+    if (typeof rec['destructive'] !== 'boolean') {
+        throw new Error(`migration record must declare destructive as a boolean: ${displaySource}`);
+    }
+    validateStringArray(rec, 'runtimes', displaySource);
+    requireStringArray(rec, 'scopes', displaySource);
+    if (typeof rec['plan'] !== 'function') {
+        throw new Error(`migration record must include a plan function: ${displaySource}`);
+    }
+    return rec;
+}
+function validateInstallerMigrationActions(actions, migration) {
+    if (!Array.isArray(actions)) {
+        throw new Error(`migration ${getStr(migration, 'id')} plan must return an array`);
+    }
+    for (const action of actions) {
+        if (!action || typeof action !== 'object') {
+            throw new Error(`migration action must be an object: ${getStr(migration, 'id')}`);
+        }
+        const act = action;
+        const actType = getStr(act, 'type');
+        const actRelPath = getStr(act, 'relPath');
+        if (!actType || actType.trim() === '') {
+            throw new Error(`migration action must include a non-empty type: ${getStr(migration, 'id')}`);
+        }
+        if (!actRelPath || actRelPath.trim() === '') {
+            throw new Error(`migration action ${actType} must include a non-empty relPath: ${getStr(migration, 'id')}`);
+        }
+        validateSafeRelPath(actRelPath, migration, actType);
+        // Ownership and runtime-contract evidence are required by
+        // docs/installer-migrations.md#action-types and
+        // docs/adr/0008-installer-migration-module.md#runtime-contract-decision.
+        if (actType === 'remove-managed' || actType === 'rewrite-json') {
+            requireActionEvidence(act, 'ownershipEvidence', migration);
+        }
+        if (actType === 'rewrite-json') {
+            const rc = getStr(migration, 'runtimeContract');
+            if (!rc || rc.trim() === '') {
+                throw new Error(`migration action rewrite-json requires migration runtimeContract: ${actionSource(migration, act)}`);
+            }
+        }
+    }
+    return actions;
+}