@sublang/slc 0.3.0 → 0.5.0

package/dist/runner.js

@@ -9,21 +9,26 @@
  * injected so a host wires the real pipeline resolution and Cligent agent while
  * tests supply fakes. See specs/dev/pipeline.md and specs/dev/phase-execution.md.
  */
-import { mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, readFile, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { artifactDir, planArtifacts, parseSource } from './artifacts.js';
+import { encodeLocator, invalidateBuildHistory, loadBuildHistory, recordBuild, verifiedInput, } from './build-history.js';
 import { emitEntryModule } from './entry-module.js';
 import { unresolvableRelativeImports } from './emitted-imports.js';
-import { formatFailureReport, runPhase, } from './execution.js';
+import { messageOf } from './errors.js';
+import { assertSafeTarget, formatFailureReport, pathsAlias, runPhase, } from './execution.js';
+import { hashBytes, isHash } from './hash.js';
 import { parseInvocation } from './invocation.js';
+import { unifiedLineDiff } from './line-diff.js';
 import { linkedArtifactPath, loadLinkFile } from './link.js';
-import { evaluatePin, evaluatePinFile } from './pin-currency.js';
-import { PinError, loadPinFile } from './pins.js';
+import { deriveClosure } from './pin-closure.js';
+import { evaluatePin, evaluatePinFile, hashTree } from './pin-currency.js';
+import { PINS_FILE, PinError, loadPinFile, } from './pins.js';
 import { loadPipeline, resolvePipeline, } from './pipeline.js';
 import { defaultPlaybookLinkTarget, isReservedPipeline } from './resolver.js';
 import { emitFsmCoverageTest, emitFsmIntrospectionTest, emitGearsFsmConformanceTest, emitPromptContractTest, } from './verify.js';
-import { VERIFIER_SUPPORT_MODULE, emitVerifierSupport, } from './verify-support.js';
+import { VERIFIER_SUPPORT_MODULE, emitVerifierSupport, verifierSupportFiles, } from './verify-support.js';
 /**
  * Parses argv and runs the requested pipeline, phase, or link end-to-end.
  * Never rejects: malformed invocations, refusals, and phase failures all return
@@ -65,47 +70,67 @@ export async function runSlc(argv, deps) {
     }
 }
 async function runFull(invocation, deps) {
+    const cwd = runCwd(deps);
     const pipeline = await loadPipeline(await resolvePipeline(invocation.pipeline, deps.resolver));
     const entry = pipeline.phases[0];
+    const source = resolve(cwd, invocation.source);
     const { basename, raw } = parseSource({
-        path: invocation.source,
+        path: source,
         sourceFormat: entry.source.format,
         ext: entry.source.ext,
         entry: true,
     });
-    const artDir = artifactDir(runCwd(deps), basename, invocation.pipeline);
+    const artDir = artifactDir(cwd, basename, invocation.pipeline);
     await mkdir(artDir, { recursive: true });
     const plan = planArtifacts({
         phases: pipeline.phases,
         basename,
         artDir,
-        output: invocation.output ?? undefined,
+        output: invocation.output === null ? undefined : resolve(cwd, invocation.output),
     });
     const steps = buildCompileSteps({
         pipeline,
         plan,
-        source: invocation.source,
+        source,
         artDir,
         basename,
         optimize: !invocation.noOptimize,
         normalize: invocation.normalize || raw,
     });
-    const result = await executeSteps(steps, pipeline, deps);
-    return emitVerification(result, {
+    const verification = {
         pipeline: invocation.pipeline,
         plan,
         artDir,
         basename,
+    };
+    return executeSteps(steps, pipeline, deps, {
+        incremental: incrementalRun(invocation, artDir, source),
+        hostTargets: verificationHostTargets(verification),
+        complete: (result, guardTarget) => emitVerification(result, verification, guardTarget),
     });
 }
+/** History covers only canonical full/full-link runs outside the `slc` meta-pipeline. */
+function incrementalRun(invocation, artDir, source) {
+    if (invocation.output !== null || invocation.pipeline === 'slc') {
+        return undefined;
+    }
+    return {
+        artDir,
+        source,
+        pipelineName: invocation.pipeline,
+        rebuild: invocation.rebuild === true,
+    };
+}
 async function runSinglePhase(invocation, deps) {
+    const cwd = runCwd(deps);
     const pipeline = await loadPipeline(await resolvePipeline(invocation.pipeline, deps.resolver));
     const phase = [...pipeline.phases, ...pipeline.passes].find((candidate) => candidate.name === invocation.phase);
     if (phase === undefined) {
         return failure(`phase "${invocation.phase}" is not part of pipeline "${invocation.pipeline}"`);
     }
+    const source = resolve(cwd, invocation.source);
     const { basename, raw } = parseSource({
-        path: invocation.source,
+        path: source,
         sourceFormat: phase.source.format,
         ext: phase.source.ext,
         entry: pipeline.phases[0] === phase,
@@ -115,14 +140,14 @@ async function runSinglePhase(invocation, deps) {
         // path into the phase's declared source format here.
         return failure(`source "${invocation.source}" is a raw input; run the full pipeline to normalize it`);
     }
-    const artDir = artifactDir(runCwd(deps), basename, invocation.pipeline);
+    const artDir = artifactDir(cwd, basename, invocation.pipeline);
     await mkdir(artDir, { recursive: true });
     if (phase.pass) {
         // A standalone pass run cannot overwrite its own source: it writes the
         // `.opt` sibling unless `-o` relocates it (DR-013).
-        const target = invocation.output ??
+        const target = (invocation.output === null ? null : resolve(cwd, invocation.output)) ??
             join(artDir, `${basename}.${phase.target.format}.opt${phase.target.ext}`);
-        const step = compileStep(pipeline, phase, invocation.source, target);
+        const step = compileStep(pipeline, phase, source, target);
         return executeSteps([step], pipeline, deps);
     }
     // Plan over the whole chain so the named phase keeps its pipeline role: a
@@ -132,58 +157,62 @@ async function runSinglePhase(invocation, deps) {
         phases: pipeline.phases,
         basename,
         artDir,
-        output: invocation.output ?? undefined,
+        output: invocation.output === null ? undefined : resolve(cwd, invocation.output),
     });
     const artifact = plan[pipeline.phases.indexOf(phase)];
-    const step = compileStep(pipeline, phase, invocation.source, artifact.path);
+    const step = compileStep(pipeline, phase, source, artifact.path);
     return executeSteps([step], pipeline, deps);
 }
 async function runDirectLink(invocation, deps) {
+    const cwd = runCwd(deps);
     const pipeline = await loadPipeline(await resolvePipeline(invocation.pipeline, deps.resolver));
     const link = await requireLink(pipeline, invocation.pipeline);
     const linked = linkedArtifactPath({
         kind: 'link',
         pipeline: invocation.pipeline,
-        objects: invocation.objects,
+        objects: invocation.objects.map((path) => resolve(cwd, path)),
         source: link.source,
         linked: link.target,
-        output: invocation.output,
-        cwd: runCwd(deps),
+        output: invocation.output === null ? null : resolve(cwd, invocation.output),
+        cwd,
     });
     await mkdir(dirname(linked), { recursive: true });
     const step = {
         request: {
             kind: 'link',
             definitionPath: pipeline.linkFile,
-            objects: invocation.objects,
-            linkTarget: invocation.linkTarget,
+            objects: invocation.objects.map((path) => resolve(cwd, path)),
+            linkTarget: resolve(cwd, invocation.linkTarget),
             options: invocation.options,
             linked,
         },
         phase: 'link',
+        pinKey: 'link',
         targetExt: link.target.ext,
     };
     return executeSteps([step], pipeline, deps);
 }
 async function runFullLink(invocation, deps) {
+    const cwd = runCwd(deps);
     const pipeline = await loadPipeline(await resolvePipeline(invocation.pipeline, deps.resolver));
     const link = await requireLink(pipeline, invocation.pipeline);
     const entry = pipeline.phases[0];
+    const source = resolve(cwd, invocation.source);
     const { basename, raw } = parseSource({
-        path: invocation.source,
+        path: source,
         sourceFormat: entry.source.format,
         ext: entry.source.ext,
         entry: true,
     });
     const normalize = invocation.normalize || raw;
-    const artDir = artifactDir(runCwd(deps), basename, invocation.pipeline);
+    const artDir = artifactDir(cwd, basename, invocation.pipeline);
     await mkdir(artDir, { recursive: true });
     // Compile chain: the exit artifact becomes the object artifact (PIPE-15).
     const plan = planArtifacts({ phases: pipeline.phases, basename, artDir });
     const compileSteps = buildCompileSteps({
         pipeline,
         plan,
-        source: invocation.source,
+        source,
         artDir,
         basename,
         optimize: !invocation.noOptimize,
@@ -194,64 +223,88 @@ async function runFullLink(invocation, deps) {
         artDir,
         basename,
         linked: link.target,
-        output: invocation.output,
+        output: invocation.output === null ? null : resolve(cwd, invocation.output),
     });
     const linkStep = {
         request: {
             kind: 'link',
             definitionPath: pipeline.linkFile,
             objects: [plan[plan.length - 1].path],
-            linkTarget: invocation.linkTarget,
+            linkTarget: resolve(cwd, invocation.linkTarget),
             options: invocation.options,
             linked,
         },
         phase: 'link',
+        pinKey: 'link',
         targetExt: link.target.ext,
     };
-    const result = await executeSteps([...compileSteps, linkStep], pipeline, deps);
-    const verified = await emitVerification(result, {
+    const steps = [...compileSteps, linkStep];
+    const gearsPlan = plan.find((artifact) => artifact.phase.target.format === 'gears');
+    const entryCandidate = invocation.pipeline === 'playbook' &&
+        invocation.output === null &&
+        gearsPlan !== undefined
+        ? resolve(cwd, `${basename}.ts`)
+        : null;
+    const entryAliasesSource = entryCandidate !== null && (await pathsAlias(entryCandidate, source));
+    const entryPath = entryAliasesSource ? null : entryCandidate;
+    const verification = {
         pipeline: invocation.pipeline,
         plan,
         artDir,
         basename,
-    });
-    // Entry-module emission (DR-014, SELFHOST-15): only the playbook pipeline,
-    // only with the linked artifact at its canonical path.
-    if (verified.ok &&
-        invocation.pipeline === 'playbook' &&
-        invocation.output === null) {
-        const gearsPlan = plan.find((artifact) => artifact.phase.target.format === 'gears');
-        if (gearsPlan !== undefined) {
-            const textPath = normalize
-                ? join(artDir, `${basename}.${entry.source.format}${entry.source.ext}`)
-                : invocation.source;
-            const entryPath = await emitEntryModule({
-                cwd: runCwd(deps),
-                basename,
-                pipeline: invocation.pipeline,
-                gearsPath: gearsPlan.path,
-                textPath,
-            });
-            const missing = await unresolvableRelativeImports(entryPath);
-            if (missing.length > 0) {
+    };
+    return executeSteps(steps, pipeline, deps, {
+        incremental: incrementalRun(invocation, artDir, source),
+        hostTargets: [
+            ...verificationHostTargets(verification),
+            ...(entryPath === null ? [] : [{ path: entryPath }]),
+        ],
+        complete: async (result, guardTarget) => {
+            const verified = await emitVerification(result, verification, guardTarget);
+            if (verified.ok && entryCandidate !== null && entryAliasesSource) {
                 return {
-                    ok: false,
-                    outputs: verified.outputs,
+                    ...verified,
                     diagnostics: [
                         ...verified.diagnostics,
-                        `entry module ${entryPath} has unresolvable relative imports: ` +
-                            `${missing.join(', ')} (VERIFY-18)`,
+                        `entry module ${entryCandidate} not emitted because it aliases the invocation source`,
                     ],
                 };
             }
-            return { ...verified, outputs: [...verified.outputs, entryPath] };
-        }
-    }
-    return verified;
+            // Entry-module emission (DR-014, SELFHOST-15): only the playbook
+            // pipeline, only with the linked artifact at its canonical path.
+            if (verified.ok && entryPath !== null && gearsPlan !== undefined) {
+                await guardTarget(entryPath);
+                const textPath = normalize
+                    ? join(artDir, `${basename}.${entry.source.format}${entry.source.ext}`)
+                    : source;
+                await emitEntryModule({
+                    cwd,
+                    basename,
+                    pipeline: invocation.pipeline,
+                    gearsPath: gearsPlan.path,
+                    textPath,
+                });
+                const missing = await unresolvableRelativeImports(entryPath);
+                if (missing.length > 0) {
+                    return {
+                        ok: false,
+                        outputs: verified.outputs,
+                        diagnostics: [
+                            ...verified.diagnostics,
+                            `entry module ${entryPath} has unresolvable relative imports: ` +
+                                `${missing.join(', ')} (VERIFY-18)`,
+                        ],
+                    };
+                }
+                return { ...verified, outputs: [...verified.outputs, entryPath] };
+            }
+            return verified;
+        },
+    });
 }
 /** The invocation working directory anchoring artifact placement (DR-014). */
 function runCwd(deps) {
-    return deps.cwd ?? process.cwd();
+    return resolve(deps.cwd ?? process.cwd());
 }
 /**
  * After a reserved-pipeline full run produces a `gears` intermediate and an `fsm`
@@ -267,28 +320,35 @@ function runCwd(deps) {
  * to a diagnostic when the artifact cannot be loaded, leaving the run outcome
  * unchanged — the conformance test still fails at test time on a broken module.
  */
-async function emitVerification(result, ctx) {
-    if (!result.ok || !isReservedPipeline(ctx.pipeline))
-        return result;
-    const fsm = ctx.plan.find((artifact) => artifact.phase.target.format === 'fsm');
-    const hasGears = ctx.plan.some((artifact) => artifact.phase.target.format === 'gears');
-    if (fsm === undefined || !hasGears)
+async function emitVerification(result, ctx, guardTarget) {
+    if (!result.ok)
         return result;
-    // The emitted tests import the canonical sibling FSM through the NodeNext
-    // `./<basename>.fsm.js` specifier; skip when `-o` relocated the physical FSM
-    // elsewhere (PIPE-8), so that edge never targets a missing sibling artifact.
-    const canonicalFsm = join(ctx.artDir, `${ctx.basename}.fsm${fsm.phase.target.ext}`);
-    if (fsm.path !== canonicalFsm)
+    const hostTargets = verificationHostTargets(ctx);
+    if (hostTargets.length === 0)
         return result;
+    const fsm = ctx.plan.find((artifact) => artifact.phase.target.format === 'fsm');
+    if (fsm === undefined)
+        throw new Error('verification plan lost its FSM');
     const outputs = [...result.outputs];
     const diagnostics = [...result.diagnostics];
+    if (guardTarget !== undefined) {
+        for (const target of verifierSupportFiles(ctx.artDir)) {
+            await guardTarget(target.target);
+        }
+    }
     outputs.push(...(await emitVerifierSupport(ctx.artDir)));
+    if (guardTarget !== undefined) {
+        await guardTarget(join(ctx.artDir, `${ctx.basename}.gears-fsm.test.ts`));
+    }
     outputs.push(await emitGearsFsmConformanceTest({
         artifactDir: ctx.artDir,
         basename: ctx.basename,
         verifyModule: VERIFIER_SUPPORT_MODULE,
     }));
     try {
+        if (guardTarget !== undefined) {
+            await guardTarget(join(ctx.artDir, `${ctx.basename}.fsm.introspect.test.ts`));
+        }
         outputs.push(await emitFsmIntrospectionTest({
             artifactDir: ctx.artDir,
             basename: ctx.basename,
@@ -299,6 +359,9 @@ async function emitVerification(result, ctx) {
         diagnostics.push(`verification: introspection test not emitted: ${messageOf(error)}`);
     }
     try {
+        if (guardTarget !== undefined) {
+            await guardTarget(join(ctx.artDir, `${ctx.basename}.prompt-contract.test.ts`));
+        }
         const promptContract = await emitPromptContractTest({
             artifactDir: ctx.artDir,
             basename: ctx.basename,
@@ -311,6 +374,9 @@ async function emitVerification(result, ctx) {
         diagnostics.push(`verification: prompt-contract test not emitted: ${messageOf(error)}`);
     }
     try {
+        if (guardTarget !== undefined) {
+            await guardTarget(join(ctx.artDir, `${ctx.basename}.fsm.coverage.test.ts`));
+        }
         const coverage = await emitFsmCoverageTest({
             artifactDir: ctx.artDir,
             basename: ctx.basename,
@@ -324,6 +390,38 @@ async function emitVerification(result, ctx) {
     }
     return { ...result, outputs, diagnostics };
 }
+/** Exact deterministic writes attempted by {@link emitVerification}. */
+function verificationHostTargets(ctx) {
+    if (!isReservedPipeline(ctx.pipeline))
+        return [];
+    const fsm = ctx.plan.find((artifact) => artifact.phase.target.format === 'fsm');
+    const hasGears = ctx.plan.some((artifact) => artifact.phase.target.format === 'gears');
+    if (fsm === undefined || !hasGears)
+        return [];
+    const canonicalFsm = join(ctx.artDir, `${ctx.basename}.fsm${fsm.phase.target.ext}`);
+    if (fsm.path !== canonicalFsm)
+        return [];
+    return [
+        ...verifierSupportFiles(ctx.artDir).map(({ source, target }) => ({
+            path: target,
+            protectedInputs: [source],
+            allowVerifierOutput: true,
+        })),
+        { path: join(ctx.artDir, `${ctx.basename}.gears-fsm.test.ts`) },
+        {
+            path: join(ctx.artDir, `${ctx.basename}.fsm.introspect.test.ts`),
+            required: false,
+        },
+        {
+            path: join(ctx.artDir, `${ctx.basename}.prompt-contract.test.ts`),
+            required: false,
+        },
+        {
+            path: join(ctx.artDir, `${ctx.basename}.fsm.coverage.test.ts`),
+            required: false,
+        },
+    ];
+}
 /** Resolves the built-in pipeline-agnostic normalize definition (DR-013). */
 export function normalizeDefinitionPath() {
     return fileURLToPath(new URL('./normalize.md', import.meta.url));
@@ -389,6 +487,7 @@ function compileStep(pipeline, phase, source, target) {
             target,
         },
         phase: phase.name,
+        pinKey: phase.name,
         targetExt: phase.target.ext,
     };
 }
@@ -397,7 +496,9 @@ function compileStep(pipeline, phase, source, target) {
  * the pin index and stopping at the first failure with its report (PHEXEC-9,
  * PHEXEC-27). An unparseable pin file fails the run closed before any phase.
  */
-async function executeSteps(steps, pipeline, deps) {
+async function executeSteps(steps, pipeline, deps, opts = {}) {
+    const complete = opts.complete ?? (async (result) => result);
+    const pinInputs = new Set([join(pipeline.dir, PINS_FILE)]);
     let pinFile;
     try {
         pinFile = (await loadPinFile(pipeline.dir)).file;
@@ -409,7 +510,9 @@ async function executeSteps(steps, pipeline, deps) {
         throw error;
     }
     if (pinFile !== undefined) {
-        const verdicts = await evaluatePinFile(pipeline.dir, pinFile);
+        const verdicts = await evaluatePinFile(pipeline.dir, pinFile, {
+            observePath: (path) => pinInputs.add(resolve(path)),
+        });
         const malformed = Object.entries(verdicts).find(([, verdict]) => verdict.status === 'malformed');
         if (malformed !== undefined) {
             return {
@@ -423,13 +526,107 @@ async function executeSteps(steps, pipeline, deps) {
             };
         }
     }
-    const definitions = chainDefinitions(pipeline);
+    const definitions = [
+        ...new Set([
+            ...chainDefinitions(pipeline),
+            ...steps.map((step) => step.request.definitionPath),
+        ]),
+    ];
     const outputs = [];
     const diagnostics = [];
-    for (const step of steps) {
-        const target = step.request.kind === 'compile'
-            ? step.request.target
-            : step.request.linked;
+    const state = opts.incremental === undefined
+        ? undefined
+        : await loadIncremental(opts.incremental);
+    const invalidatedTargetDirs = new Set();
+    const targets = steps.map(stepTarget);
+    const declaredByStep = await Promise.all(steps.map((step) => stepDeclaredInputs(step, pipeline, pinFile)));
+    const declaredInputs = [
+        ...new Set(declaredByStep.flatMap((declared) => declared.paths)),
+    ];
+    const immutableInputs = externalInputPaths(steps);
+    const hostInputs = (opts.hostTargets ?? []).flatMap((target) => target.protectedInputs ?? []);
+    const protectedInputs = [
+        ...new Set([
+            ...immutableInputs,
+            ...definitions,
+            ...declaredInputs,
+            ...hostInputs,
+            ...pinInputs,
+        ]),
+    ];
+    const plannedTargets = opts.hostTargets ?? [];
+    for (let index = 0; index < plannedTargets.length; index++) {
+        const planned = plannedTargets[index];
+        try {
+            await assertSafeTarget(planned.path, [
+                ...protectedInputs,
+                ...targets,
+                ...(planned.protectedInputs ?? []),
+                ...plannedTargets
+                    .filter((_, candidate) => candidate !== index)
+                    .map((candidate) => candidate.path),
+            ], { allowVerifierOutput: planned.allowVerifierOutput });
+        }
+        catch (error) {
+            if (planned.required !== false)
+                return failure(messageOf(error));
+        }
+    }
+    const hostTargets = new Map((opts.hostTargets ?? []).map((target) => [resolve(target.path), target]));
+    const guardCompletionTarget = async (path) => {
+        const planned = hostTargets.get(resolve(path));
+        if (planned === undefined) {
+            throw new Error(`unplanned deterministic output: ${path}`);
+        }
+        await assertSafeTarget(planned.path, [...protectedInputs, ...targets, ...(planned.protectedInputs ?? [])], { allowVerifierOutput: planned.allowVerifierOutput });
+    };
+    for (let index = 0; index < steps.length; index++) {
+        const step = steps[index];
+        const target = targets[index];
+        const stepDeclared = declaredByStep[index];
+        const identity = state === undefined
+            ? null
+            : await stepIdentity(step, state, index, stepDeclared.complete ? stepDeclared.paths : null);
+        const mode = state === undefined
+            ? { mode: 'ordinary' }
+            : await selectStepMode(step, index, target, identity, state);
+        // Reuse still honors pin currency, but it constructs no executor because
+        // no phase runs. A stale/malformed pin can never be bypassed by history.
+        if (mode.mode === 'reuse') {
+            if (state === undefined) {
+                throw new Error('internal error: reuse selected without history state');
+            }
+            let reasons;
+            try {
+                reasons = await reusePinFailure(step.pinKey, pipeline.dir, pinFile);
+            }
+            catch (error) {
+                reasons = [messageOf(error)];
+            }
+            if (reasons !== null) {
+                const startedAt = Date.now();
+                deps.progress?.({ kind: 'phase-start', phase: step.phase, target });
+                deps.progress?.({
+                    kind: 'phase-fail',
+                    phase: step.phase,
+                    target,
+                    elapsedMs: Date.now() - startedAt,
+                });
+                diagnostics.push(formatFailureReport({ phase: step.phase, target, reasons }));
+                return { ok: false, outputs, diagnostics };
+            }
+            deps.progress?.({
+                kind: 'status',
+                text: `reusing ${step.phase} → ${target}`,
+            });
+            state.accepted.push({
+                step,
+                target,
+                inputs: identity?.inputs ?? null,
+                output: hashBytes(mode.bytes),
+            });
+            continue;
+        }
         // In-run progress (DR-019, CLI-32): announce the phase, then report its
         // outcome with the elapsed time.
         const startedAt = Date.now();
@@ -448,7 +645,7 @@ async function executeSteps(steps, pipeline, deps) {
         // phase and target from the report (CLI-4, CLI-32, PHEXEC-27).
         let selection;
         try {
-            selection = await selectExecutor(step.phase, pipeline.dir, pinFile, deps);
+            selection = await selectExecutor(step.phase, step.pinKey, pipeline.dir, pinFile, deps);
         }
         catch (error) {
             selection = { kind: 'fail', reasons: [messageOf(error)] };
@@ -462,12 +659,33 @@ async function executeSteps(steps, pipeline, deps) {
             }));
             return { ok: false, outputs, diagnostics };
         }
+        if (mode.mode === 'update') {
+            deps.progress?.({
+                kind: 'status',
+                text: `updating ${step.phase} → ${target}`,
+            });
+        }
+        const request = mode.mode === 'update' && step.request.kind === 'compile'
+            ? {
+                ...step.request,
+                update: { priorInput: mode.priorInput, diff: mode.diff },
+            }
+            : step.request;
         const result = await runPhase({
-            request: step.request,
+            request,
             phase: step.phase,
             targetExt: step.targetExt,
             executor: selection.executor,
             definitions,
+            protectedInputs: stepDeclared.paths,
+            aliasInputs: [
+                ...immutableInputs,
+                ...declaredInputs,
+                ...hostInputs,
+                ...pinInputs,
+                ...targets.filter((_, candidate) => candidate !== index),
+            ],
+            beforeExecute: () => invalidateForExecution(state, target, invalidatedTargetDirs),
             revalidate: () => revalidateChain(pipeline.dir),
             signal: deps.signal,
         });
@@ -511,8 +729,326 @@ async function executeSteps(steps, pipeline, deps) {
             elapsedMs: Date.now() - startedAt,
         });
         outputs.push(target);
+        if (state !== undefined) {
+            let output = null;
+            try {
+                output = hashBytes(await readFile(target));
+            }
+            catch {
+                // A successful compile remains successful when only history capture is
+                // unavailable; final publication reports the advisory diagnostic.
+            }
+            state.executed++;
+            state.accepted.push({
+                step,
+                target,
+                inputs: identity?.inputs ?? null,
+                output,
+            });
+        }
+    }
+    const selected = {
+        ok: true,
+        outputs,
+        diagnostics,
+        ...(state !== undefined &&
+            state.executed === 0 &&
+            steps.length > 0 &&
+            state.accepted.length === steps.length
+            ? { outcome: 'up-to-date' }
+            : {}),
+    };
+    const completed = await complete(selected, guardCompletionTarget);
+    return state === undefined
+        ? completed
+        : publishIncremental(completed, state, steps);
+}
+function stepTarget(step) {
+    return step.request.kind === 'compile'
+        ? step.request.target
+        : step.request.linked;
+}
+/**
+ * Inputs supplied from outside this schedule. A normal predecessor target may
+ * feed its successor, but source/reference/link operands supplied by the user
+ * remain protected even when they collide with some scheduled output.
+ */
+function externalInputPaths(steps) {
+    const produced = new Set();
+    const external = new Set();
+    for (const step of steps) {
+        if (step.request.kind === 'compile') {
+            const source = resolve(step.request.source);
+            if (!produced.has(source))
+                external.add(source);
+            for (const reference of step.request.references ?? []) {
+                external.add(resolve(reference));
+            }
+        }
+        else {
+            for (const object of step.request.objects) {
+                const path = resolve(object);
+                if (!produced.has(path))
+                    external.add(path);
+            }
+            external.add(resolve(step.request.linkTarget));
+        }
+        produced.add(resolve(stepTarget(step)));
+    }
+    return [...external];
+}
+async function loadIncremental(run) {
+    const sourceBytes = await readFile(run.source);
+    const active = await loadBuildHistory(run.artDir);
+    const sourceLocator = encodeLocator(run.artDir, run.source);
+    const history = !run.rebuild &&
+        active?.manifest.pipeline === run.pipelineName &&
+        active.manifest.source.path === sourceLocator
+        ? active
+        : null;
+    return {
+        ...run,
+        active: active !== null,
+        history,
+        sourceBytes,
+        invalidated: false,
+        executed: 0,
+        accepted: [],
+    };
+}
+async function stepIdentity(step, state, index, declared) {
+    if (declared === null)
+        return null;
+    try {
+        if (step.request.kind === 'compile') {
+            const chainedInput = index === 0 ? state.sourceBytes : await readFile(step.request.source);
+            const roots = [
+                step.request.definitionPath,
+                ...(step.request.references ?? []),
+            ];
+            const rootHashes = await Promise.all(roots.map(async (path) => hashBytes(await readFile(path))));
+            return {
+                chainedInput,
+                inputs: [
+                    hashBytes(chainedInput),
+                    ...rootHashes,
+                    ...(await Promise.all(declared.map(async (path) => hashBytes(await readFile(path))))),
+                ],
+            };
+        }
+        const inputs = [];
+        for (const object of step.request.objects) {
+            const path = resolve(object);
+            inputs.push(framedHash('object', encodeLocator(state.artDir, path), hashBytes(await readFile(path))));
+        }
+        inputs.push(hashBytes(await readFile(step.request.definitionPath)));
+        inputs.push(...(await Promise.all(declared.map(async (path) => hashBytes(await readFile(path))))));
+        const linkTarget = resolve(step.request.linkTarget);
+        const targetInfo = await stat(linkTarget);
+        let targetKind;
+        let targetIdentity;
+        if (targetInfo.isFile()) {
+            targetKind = 'file';
+            targetIdentity = hashBytes(await readFile(linkTarget));
+        }
+        else if (targetInfo.isDirectory()) {
+            targetKind = 'directory';
+            const identity = await hashTree(linkTarget);
+            if (!isHash(identity))
+                throw new Error('invalid link-target tree hash');
+            targetIdentity = identity;
+        }
+        else {
+            throw new Error('link target is neither a file nor directory');
+        }
+        inputs.push(framedHash('link-target', encodeLocator(state.artDir, linkTarget), targetKind, targetIdentity));
+        for (const option of step.request.options) {
+            inputs.push(framedHash('option', option.name, option.value));
+        }
+        return { inputs };
     }
-    return { ok: true, outputs, diagnostics };
+    catch {
+        return null;
+    }
+}
+async function stepDeclaredInputs(step, pipeline, pinFile) {
+    const roots = step.request.kind === 'compile'
+        ? [step.request.definitionPath, ...(step.request.references ?? [])]
+        : [step.request.definitionPath];
+    return declaredInputPaths(pipeline, pinFile, roots);
+}
+/** Current local semantic-input closure for definitions and references. */
+async function declaredInputPaths(pipeline, pinFile, roots) {
+    const boundary = pinFile?.pathBoundary.path ?? '.';
+    const base = new Set(roots.map((path) => resolve(path)));
+    const seen = new Set(base);
+    const inputs = [];
+    let complete = true;
+    const normalize = resolve(normalizeDefinitionPath());
+    for (const root of roots) {
+        const absolute = resolve(root);
+        if (!absolute.toLowerCase().endsWith('.md') || absolute === normalize) {
+            continue;
+        }
+        const locator = relative(pipeline.dir, absolute).split(sep).join('/');
+        const closure = new Set();
+        try {
+            await deriveClosure(pipeline.dir, boundary, locator, (path) => closure.add(path));
+        }
+        catch {
+            // This derivation exists only for incremental identity and best-effort
+            // target protection. Pin generation/currency remain fail-closed, while an
+            // otherwise interpretable phase degrades to Ordinary execution.
+            complete = false;
+        }
+        for (const path of closure) {
+            const absolutePath = resolve(path);
+            if (seen.has(absolutePath))
+                continue;
+            seen.add(absolutePath);
+            inputs.push(absolutePath);
+        }
+    }
+    return { paths: inputs, complete };
+}
+async function selectStepMode(step, index, target, identity, state) {
+    if (state.rebuild || state.history === null || identity === null) {
+        return { mode: 'ordinary' };
+    }
+    const record = state.history.manifest.steps[index];
+    const kind = step.request.kind;
+    if (record === undefined ||
+        record.kind !== kind ||
+        record.name !== step.phase ||
+        record.target !== encodeLocator(state.artDir, resolve(target))) {
+        return { mode: 'ordinary' };
+    }
+    let targetBytes;
+    try {
+        targetBytes = await readFile(target);
+    }
+    catch {
+        return { mode: 'ordinary' };
+    }
+    if (sameHashes(record.inputs, identity.inputs)) {
+        return { mode: 'reuse', bytes: targetBytes };
+    }
+    if (step.request.kind !== 'compile' || identity.chainedInput === undefined) {
+        return { mode: 'ordinary' };
+    }
+    const prior = await verifiedInput(state.history, index, record.inputs[0]);
+    if (prior === null)
+        return { mode: 'ordinary' };
+    const diff = record.inputs[0] === identity.inputs[0]
+        ? ''
+        : renderInputDiff(prior.bytes, identity.chainedInput);
+    return { mode: 'update', priorInput: prior.path, diff };
+}
+function renderInputDiff(prior, current) {
+    try {
+        const decoder = new TextDecoder('utf-8', { fatal: true });
+        return unifiedLineDiff(decoder.decode(prior), decoder.decode(current));
+    }
+    catch {
+        return null;
+    }
+}
+function framedHash(tag, ...fields) {
+    return hashBytes(Buffer.from(JSON.stringify([tag, ...fields]), 'utf8'));
+}
+function sameHashes(left, right) {
+    return (left.length === right.length &&
+        left.every((hash, index) => hash === right[index]));
+}
+async function reusePinFailure(pinKey, pipelineDir, pinFile) {
+    const record = ownPin(pinFile, pinKey);
+    if (pinFile === undefined || pinKey === undefined || record === undefined) {
+        return null;
+    }
+    const verdict = await evaluatePin(pipelineDir, pinFile, pinKey, record);
+    return verdict.status === 'current'
+        ? null
+        : [`pin is ${verdict.status}: ${verdict.reason}`];
+}
+/**
+ * Removes any complete snapshot that could otherwise bless this target after
+ * executor work. Eligible runs already know their artifact directory; excluded
+ * forms perform only this safety invalidation and never select from or publish
+ * history.
+ */
+async function invalidateForExecution(state, target, invalidatedTargetDirs) {
+    if (state !== undefined) {
+        if (state.invalidated)
+            return;
+        try {
+            await invalidateBuildHistory(state.artDir, state.active);
+            state.invalidated = true;
+            return;
+        }
+        catch (error) {
+            throw new Error(`active build history could not be invalidated: ${messageOf(error)}`, { cause: error });
+        }
+    }
+    const targetDir = dirname(resolve(target));
+    if (invalidatedTargetDirs.has(targetDir))
+        return;
+    const active = await loadBuildHistory(targetDir);
+    const targetLocator = encodeLocator(targetDir, resolve(target));
+    if (active !== null &&
+        active.manifest.steps.some((step) => step.target === targetLocator)) {
+        try {
+            await invalidateBuildHistory(targetDir, true);
+        }
+        catch (error) {
+            throw new Error(`active build history could not be invalidated: ${messageOf(error)}`, { cause: error });
+        }
+        invalidatedTargetDirs.add(targetDir);
+    }
+}
+async function publishIncremental(result, state, steps) {
+    if (!result.ok || state.executed === 0)
+        return result;
+    if (state.accepted.length !== steps.length ||
+        state.accepted.some((entry) => entry.inputs === null || entry.output === null)) {
+        return historyDiagnostic(result, 'one or more phase identities or output bytes were unavailable');
+    }
+    const records = [];
+    try {
+        for (const accepted of state.accepted) {
+            const bytes = await readFile(accepted.target);
+            if (hashBytes(bytes) !== accepted.output) {
+                return historyDiagnostic(result, `accepted output changed before publication: ${accepted.target}`);
+            }
+            records.push({
+                kind: accepted.step.request.kind,
+                name: accepted.step.phase,
+                target: accepted.target,
+                inputs: accepted.inputs,
+                output: accepted.output,
+                bytes,
+            });
+        }
+        await recordBuild({
+            artDir: state.artDir,
+            pipeline: state.pipelineName,
+            sourcePath: state.source,
+            sourceBytes: state.sourceBytes,
+            steps: records,
+        });
+        return result;
+    }
+    catch (error) {
+        return historyDiagnostic(result, messageOf(error));
+    }
+}
+function historyDiagnostic(result, reason) {
+    return {
+        ...result,
+        diagnostics: [
+            ...result.diagnostics,
+            `slc: build history not recorded: ${reason}`,
+        ],
+    };
 }
 /**
  * Selects a phase's execution strategy from the pin index (PHEXEC-27; DR-005,
@@ -520,12 +1056,12 @@ async function executeSteps(steps, pipeline, deps) {
  * artifact, and a stale or malformed pin fails closed and is never silently
  * interpreted.
  */
-async function selectExecutor(phase, pipelineDir, pinFile, deps) {
-    const record = pinFile?.pins[phase];
-    if (pinFile === undefined || record === undefined) {
+async function selectExecutor(phase, pinKey, pipelineDir, pinFile, deps) {
+    const record = ownPin(pinFile, pinKey);
+    if (pinFile === undefined || pinKey === undefined || record === undefined) {
         return { kind: 'run', executor: deps.executor };
     }
-    const verdict = await evaluatePin(pipelineDir, pinFile, phase, record);
+    const verdict = await evaluatePin(pipelineDir, pinFile, pinKey, record);
     if (verdict.status === 'current') {
         if (deps.compiled === undefined) {
             return {
@@ -537,7 +1073,7 @@ async function selectExecutor(phase, pipelineDir, pinFile, deps) {
         }
         return {
             kind: 'run',
-            executor: deps.compiled({ phase, pipelineDir, record }),
+            executor: deps.compiled({ phase: pinKey, pipelineDir, record }),
         };
     }
     return {
@@ -545,6 +1081,13 @@ async function selectExecutor(phase, pipelineDir, pinFile, deps) {
         reasons: [`pin is ${verdict.status}: ${verdict.reason}`],
     };
 }
+function ownPin(pinFile, pinKey) {
+    return pinFile !== undefined &&
+        pinKey !== undefined &&
+        Object.hasOwn(pinFile.pins, pinKey)
+        ? pinFile.pins[pinKey]
+        : undefined;
+}
 function phaseDefinition(pipeline, name) {
     return join(pipeline.dir, `${name}.md`);
 }
@@ -570,7 +1113,4 @@ async function revalidateChain(dir) {
 function failure(message) {
     return { ok: false, outputs: [], diagnostics: [message] };
 }
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 //# sourceMappingURL=runner.js.map