akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/tasks/scheduler-sync.js

@@ -1,446 +1,147 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Pure whole-set scheduler reconciliation planning. */
-import { createHash } from "node:crypto";
+/**
+ * Scheduler reconciliation: compile the desired bindings from a bundle's
+ * task and workflow sources, then diff them against the rows the native
+ * scheduler holds.
+ *
+ * `compileSchedulerSources` reads each source once. One source that fails
+ * to parse or prepare is reported and skipped; every other source still
+ * compiles (#867). `planSchedulerSync` is pure: given the desired bindings,
+ * the installed rows, and the bundles this sync owns, it decides which rows
+ * to install, update, remove, or leave alone. Rows it cannot attribute to
+ * one of those bundles are never touched.
+ */
+import fs from "node:fs";
 import path from "node:path";
-import { loadAdapterExecutionSource } from "../commands/command/execution-source-loader.js";
-import { makeBundleRef } from "../core/asset/asset-ref.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
 import { compareCodePoints, toPosix } from "../core/common.js";
 import { UsageError } from "../core/errors.js";
 import { canonicalizeWorkflowName, WORKFLOW_EXTENSIONS } from "../core/recognition-util.js";
-import { captureGuardedDirectoryManifest, captureGuardedExecutionSource, GuardedExecutionSourceCollector, } from "../execution/guarded-source.js";
 import { applyInputDefaults, validateInputs } from "../execution/input-contract.js";
-import { compileWorkflowPlan } from "../workflows/ir/compile.js";
-import { compileResolveFreezeWorkflowV4 } from "../workflows/ir/freeze-v4.js";
-import { canonicalJson, computePlanHash } from "../workflows/ir/plan-hash.js";
-import { WorkflowSourceCollisionError, WorkflowSourceNameError, WorkflowSourceRejectionError, workflowNameForSourcePath, } from "../workflows/source-files.js";
-import { compileWorkflowSource } from "../workflows/source-ir/compile.js";
+import { checkWorkflowPlan, compileWorkflowSource } from "../workflows/compile.js";
+import { WorkflowSourceCollisionError, WorkflowSourceNameError, workflowNameForSourcePath, } from "../workflows/source-files.js";
 import { prepareTaskV3Execution } from "./prepare/prepare.js";
 import { parseSchedule } from "./schedule.js";
-import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeArtifactOwner, schedulerNativeBindingId, } from "./scheduler-binding.js";
+import { compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerNativeBindingId, } from "./scheduler-binding.js";
 import { parseTaskSource } from "./source/parse-task-source.js";
 import { projectTaskSourceV4 } from "./source/project-v4.js";
 import { taskSourceErrorDetail } from "./source-v3.js";
-export function computeSchedulerExecutionEvidenceDigest(planHash, sourceReadSet) {
-    const envelope = canonicalJson({
-        version: 1,
-        planHash,
-        sourceReadSet: sourceReadSet.map((snapshot) => ({
-            identity: snapshot.identity,
-            containmentPhysicalIdentity: snapshot.containmentPhysicalIdentity,
-            physicalIdentity: snapshot.physicalIdentity,
-            size: snapshot.size,
-        })),
-    });
-    return createHash("sha256").update("akm.scheduler.workflow-evidence\0v1\0").update(envelope).digest("hex");
-}
 const SCHEDULER_PROJECTION_CONFIG = Object.freeze({
     configVersion: "0.9.0",
     semanticSearchMode: "off",
 });
-export async function prepareSchedulerSyncSourceSet(input) {
-    const collector = new SchedulerSourceCollector(input);
-    const compiled = await compileDesiredSourceSet(input, collector);
-    const sourceSnapshot = collector.snapshot();
-    assertSchedulerSourceSnapshot(sourceSnapshot);
-    return Object.freeze({
-        desired: compiled.desired,
-        sourceSnapshot,
-        executableWorkflows: compiled.executableWorkflows,
-        failures: compiled.failures,
-    });
-}
-function schedulerActivationKey(kind, ref) {
-    return `${kind}\0${ref}`;
-}
-export function finalizeSchedulerSyncPlan(input, prepared) {
-    const inspection = inspectionForPlan(input);
-    const coherentInput = {
-        ...input,
-        installed: inspection.installed,
-        nativeArtifacts: inspection.artifacts,
-    };
-    const desired = prepared.desired;
-    assertUniqueDesiredIds(desired);
-    assertSchedulerBackendInspection(inspection, desired, input.inspection !== undefined);
-    assertNoForeignIds(desired, coherentInput);
-    const scopedInstalled = coherentInput.installed.filter((entry) => belongsToBundle(entry, coherentInput));
-    const present = new Map(scopedInstalled.map((entry) => [entry.id, entry]));
-    const installed = [];
-    const updated = [];
-    const unchanged = [];
-    const operations = [];
-    for (const binding of desired) {
-        const current = present.get(binding.id);
-        const options = installOptionsFor(coherentInput, current);
-        const resultFingerprint = coherentInput.expectedSignature?.(binding, options);
-        if (!current) {
-            installed.push(binding.id);
-            operations.push(freezeOperation({
-                kind: "install",
-                binding,
-                expected: freezeMutationExpectation(expectationForBinding(binding, "absent")),
-                ...(resultFingerprint !== undefined ? { resultFingerprint } : {}),
-                ...(options ? { options } : {}),
-            }));
-            continue;
-        }
-        if (current.signature !== undefined && resultFingerprint !== undefined && current.signature === resultFingerprint) {
-            unchanged.push(binding.id);
-            continue;
-        }
-        const artifact = exactInstalledArtifact(binding.id, current, inspection.artifacts);
-        const priorFingerprint = artifact?.fingerprint ?? current.signature;
-        if (artifact === undefined || priorFingerprint === undefined) {
-            throw new UsageError(`Installed scheduler binding ${JSON.stringify(binding.id)} has no exact native fingerprint; refusing update.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        updated.push(binding.id);
-        operations.push(freezeOperation({
-            kind: "update",
-            binding,
-            expected: freezeMutationExpectation(expectationForBinding(binding, "present", priorFingerprint)),
-            ...(resultFingerprint !== undefined ? { resultFingerprint } : {}),
-            ...(options ? { options } : {}),
-        }));
-    }
-    const desiredIds = new Set(desired.map(({ id }) => id));
-    const removed = scopedInstalled
-        .map(({ id }) => id)
-        .filter((id) => !desiredIds.has(id))
-        .sort(compareCodePoints);
-    for (const id of removed) {
-        const current = present.get(id);
-        operations.push(buildSchedulerRemoveOperation(id, current, inspection.artifacts, coherentInput));
-    }
-    return Object.freeze({
-        desired,
-        installed: Object.freeze(installed),
-        updated: Object.freeze(updated),
-        removed: Object.freeze(removed),
-        unchanged: Object.freeze(unchanged),
-        operations: Object.freeze(operations),
-        sourceSnapshot: prepared.sourceSnapshot,
-        failures: prepared.failures,
-    });
-}
-/** Validate one coherent whole-backend read before deriving any mutation plan. */
-export function assertSchedulerBackendInspection(inspection, desired = [], requireCompleteFingerprint = true) {
-    assertCoherentInspection(inspection, requireCompleteFingerprint);
-    assertUniqueInstalledIds(inspection.installed);
-    assertSchedulerNativeArtifactOwnership(desired, inspection.artifacts);
-}
-/**
- * Build the exact removal operation for one installed binding: same
- * exact-native-fingerprint / ordinal-attribution safety checks
- * `finalizeSchedulerSyncPlan`'s remove loop always applied, factored out so
- * `akm task prune` (#851) can build removal operations for entries
- * `belongsToBundle` structurally can't see (unresolvable ownership) without
- * re-deriving — or weakening — this logic. Throws the same `UsageError`s a
- * sync removal would on an inexact match; callers computing prune candidates
- * should only pass entries they've already independently confirmed are safe
- * to remove.
- */
-export function buildSchedulerRemoveOperation(id, current, artifacts, input) {
-    if (!current?.invocation) {
-        throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
-    }
-    const nativeId = exactInstalledNativeId(id, current, artifacts);
-    const artifact = artifacts.find((candidate) => candidate.nativeId === nativeId && candidate.bindingId === id);
-    const priorFingerprint = current.signature ?? artifact?.fingerprint;
-    if (!artifact || priorFingerprint === undefined) {
-        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} has no exact native fingerprint; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    const logicalSource = installedLogicalSource(current.invocation, input);
-    const ordinal = schedulerBindingOrdinal(id, logicalSource, current.invocation);
-    if (ordinal === undefined) {
-        throw new UsageError(`Installed scheduler binding ${JSON.stringify(id)} cannot be attributed to an exact schedule ordinal; refusing removal.`, "RESOURCE_ALREADY_EXISTS");
-    }
-    return Object.freeze({
-        kind: "remove",
-        id,
-        nativeId,
-        expected: freezeRemovalExpectation({
-            state: "present",
-            bindingId: id,
-            nativeId,
-            logicalSource,
-            ordinal,
-            invocation: current.invocation,
-            fingerprint: priorFingerprint,
-        }),
-        ...(current.ownerBundlePath !== undefined ? { ownerBundlePath: current.ownerBundlePath } : {}),
-    });
-}
-function exactInstalledNativeId(logicalId, current, artifacts) {
-    const exact = artifacts.find((artifact) => artifact.bindingId === logicalId);
-    return exact?.nativeId ?? current?.nativeId ?? schedulerNativeBindingId(logicalId);
-}
-function exactInstalledArtifact(bindingId, current, artifacts) {
-    const nativeId = current.nativeId ?? schedulerNativeBindingId(bindingId);
-    return artifacts.find((artifact) => artifact.nativeId === nativeId && (artifact.bindingId === bindingId || artifact.bindingId === undefined));
-}
-function nativeArtifactsForPlan(input) {
-    return (input.nativeArtifacts ??
-        input.installed.map((entry) => ({
-            nativeId: entry.nativeId ?? schedulerNativeBindingId(entry.id),
-            bindingId: entry.id,
-            ...(entry.invocation ? { invocation: Object.freeze([...entry.invocation]) } : {}),
-            ...(entry.signature !== undefined ? { fingerprint: entry.signature } : {}),
-        })));
-}
-function inspectionForPlan(input) {
-    return input.inspection ?? Object.freeze({ installed: input.installed, artifacts: nativeArtifactsForPlan(input) });
-}
-export function assertSchedulerNativeArtifactOwnership(desired, installed) {
-    const desiredByKey = new Map();
-    for (const binding of desired) {
-        const nativeId = schedulerBindingNativeId(binding);
-        const key = schedulerNativeArtifactKey(nativeId);
-        const prior = desiredByKey.get(key);
-        if (prior && !sameDesiredArtifact(prior, binding)) {
-            throw nativeArtifactCollision(desiredArtifact(prior), desiredArtifact(binding));
-        }
-        desiredByKey.set(key, binding);
-    }
-    const installedByKey = new Map();
-    for (const artifact of installed) {
-        const key = schedulerNativeArtifactKey(artifact.nativeId);
-        const prior = installedByKey.get(key);
-        if (prior) {
-            throw nativeArtifactCollision(prior, artifact);
-        }
-        installedByKey.set(key, artifact);
-        const wanted = desiredByKey.get(key);
-        if (!wanted)
-            continue;
-        // Re-derive ownership from the artifact's own invocation content (not the
-        // caller-supplied `bindingId` label) so a proven owner whose invocation
-        // no longer matches the desired shape is an UPDATE, not a refusal — that
-        // reconciliation happens below in finalizeSchedulerSyncPlan. An artifact
-        // whose invocation content does not actually prove it belongs to
-        // `wanted` (unproven, malformed, or a different logical owner) is still
-        // a genuine collision.
-        const provenBindingId = artifact.invocation !== undefined
-            ? schedulerNativeArtifactOwner(artifact.nativeId, artifact.invocation)?.logicalId
-            : undefined;
-        if (artifact.nativeId !== schedulerBindingNativeId(wanted) || provenBindingId !== wanted.id) {
-            throw nativeArtifactCollision(desiredArtifact(wanted), artifact);
-        }
-    }
-}
-function assertCoherentInspection(inspection, requireCompleteFingerprint = false) {
-    const seenNativeKeys = new Set();
-    for (const artifact of inspection.artifacts) {
-        const key = schedulerNativeArtifactKey(artifact.nativeId);
-        if (seenNativeKeys.has(key)) {
-            throw new UsageError(`Scheduler inspection has duplicate normalized native artifact ${JSON.stringify(artifact.nativeId)}; expected cardinality one.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        seenNativeKeys.add(key);
-    }
-    for (const installed of inspection.installed) {
-        const nativeId = installed.nativeId ?? schedulerNativeBindingId(installed.id);
-        const artifact = assertSchedulerNativeArtifactCardinality(inspection.artifacts, nativeId, 1);
-        if (!artifact ||
-            (installed.signature !== undefined &&
-                (artifact.fingerprint !== undefined
-                    ? installed.signature !== artifact.fingerprint
-                    : requireCompleteFingerprint)) ||
-            (artifact.bindingId !== undefined && artifact.bindingId !== installed.id)) {
-            throw new UsageError(`Scheduler inspection is not coherent for ${JSON.stringify(nativeId)}: installed and native fingerprints differ.`, "RESOURCE_ALREADY_EXISTS");
-        }
-        if (installed.invocation !== undefined &&
-            (artifact.invocation === undefined || !sameInvocation(installed.invocation, artifact.invocation))) {
-            throw new UsageError(`Scheduler inspection is not coherent for ${JSON.stringify(nativeId)}: installed and native owners differ.`, "RESOURCE_ALREADY_EXISTS");
-        }
-    }
-}
-function nativeArtifactCollision(left, right) {
-    const owner = (value) => value.bindingId === undefined || value.invocation === undefined
-        ? `${JSON.stringify(value.nativeId)} (unproven owner)`
-        : `binding ${JSON.stringify(value.bindingId)} invoking ${JSON.stringify(value.invocation)}`;
-    return new UsageError(`Native scheduler artifact collision between ${owner(left)} and ${owner(right)}; refusing to overwrite an existing or ambiguous native owner.`, "RESOURCE_ALREADY_EXISTS");
-}
-function desiredArtifact(binding) {
-    return {
-        nativeId: schedulerBindingNativeId(binding),
-        bindingId: binding.id,
-        invocation: binding.invocation,
-    };
-}
-function sameDesiredArtifact(left, right) {
-    return (schedulerBindingNativeId(left) === schedulerBindingNativeId(right) &&
-        left.id === right.id &&
-        left.logicalSource.kind === right.logicalSource.kind &&
-        left.logicalSource.ref === right.logicalSource.ref &&
-        left.ordinal === right.ordinal &&
-        left.executionEvidenceDigest === right.executionEvidenceDigest &&
-        sameInvocation(left.invocation, right.invocation));
-}
-async function compileDesiredSourceSet(input, collector) {
-    const bindings = [];
-    const executableWorkflows = [];
+export async function compileSchedulerSources(input) {
+    const sourceRoot = path.resolve(input.sourceRoot);
+    const desired = [];
     const failures = [];
-    await compileTaskSources(input, collector, bindings, failures);
-    await compileWorkflowSources(input, collector, bindings, executableWorkflows, failures);
-    // Degrade, don't reject (#867): one source that fails to parse/prepare no
-    // longer poisons the whole desired set — it is dropped from `desired` and
-    // reported here instead, so every OTHER task/workflow still reconciles.
-    // Genuinely cross-cutting integrity violations (duplicate ids, native
-    // artifact ownership conflicts, an incoherent backend inspection) are
-    // asserted separately in `finalizeSchedulerSyncPlan` and still hard-fail
-    // the whole sync — this only relaxes the per-source parse/prepare gate.
+    await compileTaskSources({ ...input, sourceRoot }, desired, failures);
+    compileWorkflowSources({ ...input, sourceRoot }, desired, failures);
     return Object.freeze({
-        desired: Object.freeze(bindings),
-        executableWorkflows: Object.freeze(executableWorkflows.sort((left, right) => compareCodePoints(left.ref, right.ref))),
+        desired: Object.freeze(desired),
         failures: Object.freeze(failures.sort((left, right) => compareCodePoints(left.path, right.path))),
     });
 }
-async function compileTaskSources(input, collector, out, failures) {
-    if (input.adapterId !== "akm" && input.adapterId !== "akm-task")
-        return;
-    const physicalOwners = new Map();
-    for (const guarded of collector.authoredTaskSources(input.adapterId)) {
-        const sourcePath = guarded.sourcePath;
-        const relative = guarded.relativePath;
-        const conceptId = relative.slice(0, -4);
-        const id = input.adapterId === "akm-task" ? conceptId : path.basename(sourcePath, ".yml");
-        const qualifiedRefForFailure = makeBundleRef(input.bundleName, conceptId);
-        if (input.enabledActivations &&
-            !input.enabledActivations.has(schedulerActivationKey("task", qualifiedRefForFailure))) {
+async function compileTaskSources(input, desired, failures) {
+    for (const file of taskSourceFiles(input.sourceRoot, input.adapterId)) {
+        const relative = toPosix(path.relative(input.sourceRoot, file));
+        const conceptId = relative.slice(0, -".yml".length);
+        const id = input.adapterId === "akm-task" ? conceptId : path.basename(file, ".yml");
+        const ref = sourceRef(input.bundleName, conceptId);
+        if (ref === undefined || (input.enabledRefs && !input.enabledRefs.has(ref)))
             continue;
-        }
         try {
-            const physicalIdentity = guarded.physicalIdentity;
-            const priorOwner = physicalOwners.get(physicalIdentity);
-            if (priorOwner !== undefined && priorOwner !== sourcePath) {
-                throw new UsageError(`Task sources ${JSON.stringify(priorOwner)} and ${JSON.stringify(sourcePath)} resolve to the same physical source identity; refusing canonical task identity collision.`, "RESOURCE_ALREADY_EXISTS");
-            }
-            physicalOwners.set(physicalIdentity, sourcePath);
-            // Project BEFORE prepareTaskV3Execution so projectability is checked —
-            // but build the scheduler bindings from the ORIGINAL task source v4
-            // document, not the projection, which deliberately drops
-            // `schedule[i].inputs` (project-v4.ts) —
-            // schedule-supplied inputs are delivered through the scheduler
-            // binding's own compiled invocation tail (P2b Lane B, spec §4.4,
-            // B-N3), not through the prepare-seam projection. A task source v4
             const parsed = parseTaskSource({
-                yaml: guarded.content,
-                filePath: sourcePath,
+                yaml: fs.readFileSync(file, "utf8"),
+                filePath: file,
                 workspaceRoot: input.sourceRoot,
             });
-            const document = projectTaskSourceV4(parsed.v4);
-            const qualifiedRef = makeBundleRef(input.bundleName, conceptId);
-            // See assertTaskScheduleInputsSatisfyContract's own docblock (below in
-            // this file) for why this second, defaults-applied gate exists.
-            assertTaskScheduleInputsSatisfyContract(parsed.v4, qualifiedRef);
-            await prepareTaskV3Execution(document, {
+            // A task with no `schedule:` is run by hand or by a workflow step; it
+            // contributes no binding and is not sync's to validate.
+            if (parsed.v4.schedule.length === 0)
+                continue;
+            assertTaskScheduleInputsSatisfyContract(parsed.v4, ref);
+            assertTaskScheduleCronValid(parsed.v4, input.backend);
+            // Project so a target that cannot resolve (a missing workflow, an
+            // unconfigured engine) is reported here rather than at fire time.
+            // Bindings compile from the original document: the projection drops
+            // `schedule[i].inputs`, which are delivered through the invocation tail.
+            await prepareTaskV3Execution(projectTaskSourceV4(parsed.v4), {
                 taskId: id,
-                taskRef: qualifiedRef,
+                taskRef: ref,
                 bundleName: input.bundleName,
                 bundleRoot: input.sourceRoot,
                 config: input.config ?? SCHEDULER_PROJECTION_CONFIG,
                 ...(input.resolveAsset ? { resolveAsset: input.resolveAsset } : {}),
-                readFile: (file, bundleRoot) => collector.readBytes(file, bundleRoot ?? input.sourceRoot),
-                commandSourceLoader: (ref, kind, options) => {
-                    const guardedOptions = {
-                        ...options,
-                        fileContext: (root, file) => collector.fileContext(root, file),
-                    };
-                    return kind === "command"
-                        ? loadAdapterExecutionSource(ref, "command", guardedOptions)
-                        : loadAdapterExecutionSource(ref, "persona", guardedOptions);
-                },
             });
-            const relSource = toPosix(path.relative(input.sourceRoot, sourcePath));
-            const sourceBindings = compileTaskSchedulerBindings({
+            desired.push(...compileTaskSchedulerBindings({
                 id,
-                qualifiedRef,
-                ...(input.bundleTarget ? { bundleTarget: input.bundleTarget } : {}),
+                qualifiedRef: ref,
                 schedules: parsed.v4.schedule.map((schedule) => ({
                     cron: schedule.cron,
                     ordinal: schedule.ordinal,
-                    source: `${relSource}:${schedule.source}`,
-                    // P2b Lane B (spec §4.4, B-N3): delivered through the compiled
-                    // binding's own invocation tail below — the F-B2 flip that closes
-                    // the P2a B-38 "validated but not yet delivered" gap this comment
-                    // used to describe.
+                    source: `${relative}:${schedule.source}`,
                     inputs: schedule.inputs,
                 })),
-            });
-            assertTaskScheduleCronValid(parsed.v4, input.backend);
-            out.push(...sourceBindings);
+            }));
         }
         catch (cause) {
-            failures.push(taskFailure(sourcePath, qualifiedRefForFailure, cause));
-        }
-    }
-}
-/**
- * P2b Lane B (spec §4.4, rows B-50/F-B2): validate every v4 `schedule:`
- * entry's `inputs` against the task's OWN declared contract WITH DEFAULTS
- * APPLIED — the same `applyInputDefaults` + `validateInputs` pair
- * `akm task run` uses (`src/tasks/run/load-task.ts`). `parseTaskSource`'s
- * own parse-time check (`task-source-v4.ts`'s `parseScheduleEntry`) already
- * rejects an unknown/malformed entry against the RAW supplied values; this
- * is a deliberate second, independent gate over the DEFAULTED view — the
- * exact set of values a compiled invocation actually delivers — so a
- * violation fails HERE, recorded as a task failure at sync, rather than
- * surfacing for the first time when the scheduler fires the invocation.
- *
- * Extracted so `akm task validate` can run the IDENTICAL gate
- * over a bare file path without a second, potentially-diverging copy of
- * this check. `refLabel` is only the text embedded in the thrown message —
- * `compileTaskSources` passes its bundle-qualified ref; `akm task validate`,
- * which never resolves a bundle for a bare file, passes the file path.
- */
-export function assertTaskScheduleInputsSatisfyContract(v4, refLabel) {
-    const contract = v4.inputs ?? {};
-    for (const scheduleEntry of v4.schedule) {
-        const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
-        const errors = validateInputs(contract, defaultedInputs);
-        if (errors.length > 0) {
-            throw new UsageError(`Task ${JSON.stringify(refLabel)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
-                `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
+            const detail = taskSourceErrorDetail(cause);
+            failures.push({ path: file, ref, reason: detail === errorMessage(cause) ? `${file}: ${detail}` : detail });
         }
     }
 }
-/**
- * Validate every v4 `schedule:` entry's `cron` against the active scheduler
- * backend's dialect (`parseSchedule`, `./schedule.ts`) — cron is the most
- * permissive of the three backends, so a task authored on Linux can carry a
- * cron expression launchd/schtasks cannot translate; `compileTaskSources`
- * re-checks against the LOCAL backend on every sync rather than trusting
- * whatever backend the file was authored against.
- *
- * Extracted alongside {@link assertTaskScheduleInputsSatisfyContract}
- * so `akm task validate` shares this exact gate instead of a second copy
- * that could silently drift from what `akm task sync` actually enforces.
- */
-export function assertTaskScheduleCronValid(v4, backend) {
-    for (const scheduleEntry of v4.schedule) {
-        parseSchedule(scheduleEntry.cron, backend);
+/** Task candidates: `tasks/*.yml` for the akm adapter, every `.yml` in the tree for `akm-task`. */
+function taskSourceFiles(sourceRoot, adapterId) {
+    if (adapterId === "akm") {
+        const dir = path.join(sourceRoot, "tasks");
+        const names = listDirectory(dir);
+        return names
+            .filter((name) => name.endsWith(".yml"))
+            .map((name) => path.join(dir, name))
+            .filter((file) => statOrUndefined(file)?.isFile() === true)
+            .sort(compareCodePoints);
     }
+    if (adapterId === "akm-task")
+        return walkFiles(sourceRoot).filter((file) => file.endsWith(".yml"));
+    return [];
 }
-async function compileWorkflowSources(input, collector, out, evidence, failures) {
+function compileWorkflowSources(input, desired, failures) {
     if (input.adapterId !== "akm" && input.adapterId !== "akm-workflow")
         return;
-    const lookups = enumerateWorkflowLookups(input, collector, failures);
-    for (const [canonicalName, sources] of lookups) {
-        const failurePath = sources[0]?.sourcePath ?? canonicalName;
-        const failureRef = makeBundleRef(input.bundleName, input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName);
-        if (input.enabledActivations && !input.enabledActivations.has(schedulerActivationKey("workflow", failureRef))) {
+    const root = input.adapterId === "akm" ? path.join(input.sourceRoot, "workflows") : input.sourceRoot;
+    const byName = new Map();
+    for (const file of walkFiles(root)) {
+        if (path.basename(file).toLowerCase() === "readme.md")
+            continue;
+        const authoredName = workflowNameForSourcePath(input.sourceRoot, input.adapterId, file);
+        if (authoredName === undefined)
+            continue;
+        const extension = path.posix.extname(authoredName).toLowerCase();
+        const stem = authoredName.slice(0, -extension.length).toLowerCase();
+        const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => stem.endsWith(suffix));
+        if (nestedSuffix) {
+            const relative = toPosix(path.relative(input.sourceRoot, file));
+            failures.push({ path: file, reason: new WorkflowSourceNameError(relative, nestedSuffix).message });
             continue;
         }
+        const canonicalName = canonicalizeWorkflowName(authoredName);
+        byName.set(canonicalName, [...(byName.get(canonicalName) ?? []), file]);
+    }
+    for (const [canonicalName, sources] of [...byName].sort(([left], [right]) => compareCodePoints(left, right))) {
+        const conceptId = input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
+        const ref = sourceRef(input.bundleName, conceptId);
+        if (ref === undefined || (input.enabledRefs && !input.enabledRefs.has(ref)))
+            continue;
+        const file = sources[0];
         try {
             if (sources.length > 1) {
-                throw new WorkflowSourceCollisionError(input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
+                throw new WorkflowSourceCollisionError(conceptId, sources.map((source) => toPosix(path.relative(input.sourceRoot, source))));
             }
-            const guarded = sources[0];
-            if (!guarded)
-                continue;
-            const compiled = compileWorkflowSource(guarded.content, {
-                path: guarded.relativePath,
+            const relative = toPosix(path.relative(input.sourceRoot, file));
+            const compiled = compileWorkflowSource(fs.readFileSync(file, "utf8"), {
+                path: relative,
                 workspaceRoot: input.sourceRoot,
             });
             if (!compiled.ok) {
@@ -448,336 +149,319 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
                     .map((error) => `${error.path}:${error.line ?? 1} [${error.code}] ${error.message}`)
                     .join("; "), "WORKFLOW_SOURCE_INVALID");
             }
-            const planDraft = compileWorkflowPlan(compiled.ir, canonicalName);
+            const planDraft = checkWorkflowPlan(compiled.plan);
             if (!planDraft.ok) {
-                throw new UsageError(planDraft.errors.map((error) => `${guarded.relativePath}:${error.line} ${error.message}`).join("; "), "WORKFLOW_SOURCE_INVALID");
+                throw new UsageError(planDraft.errors.map((error) => `${relative}:${error.line} ${error.message}`).join("; "), "WORKFLOW_SOURCE_INVALID");
             }
-            const conceptId = input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
-            const qualifiedRef = makeBundleRef(input.bundleName, conceptId);
-            const asset = {
-                ref: qualifiedRef,
-                path: guarded.sourcePath,
-                sourcePath: input.sourceRoot,
-                adapterId: input.adapterId,
-                title: canonicalName,
-                steps: [],
-                sourceIr: compiled.ir,
-            };
-            const frozen = await compileResolveFreezeWorkflowV4(asset, input.config ?? schedulerProjectionConfig(input), {
-                sourceCollector: collector.executionCollector(),
-            });
-            const planHash = computePlanHash(frozen.plan);
-            const executionEvidenceDigest = computeSchedulerExecutionEvidenceDigest(planHash, frozen.plan.sourceReadSet);
-            evidence.push(Object.freeze({
-                ref: qualifiedRef,
-                irVersion: 5,
-                planHash,
-                sourceReadSet: frozen.plan.sourceReadSet,
-                executionEvidenceDigest,
+            const schedules = (compiled.plan.schedules ?? []).map((schedule) => ({
+                cron: schedule.cron,
+                source: `${relative}:${schedule.line}`,
+                ordinal: schedule.ordinal,
             }));
-            const schedules = compiled.ir.triggers.flatMap((trigger) => trigger.kind === "schedule"
-                ? [
-                    {
-                        cron: trigger.cron,
-                        source: `${trigger.source.path}:${trigger.source.start}`,
-                        ordinal: trigger.ordinal,
-                    },
-                ]
-                : []);
-            for (const binding of compileWorkflowSchedulerBindings({
-                qualifiedRef,
-                schedules,
-                executionEvidenceDigest,
-            })) {
+            for (const binding of compileWorkflowSchedulerBindings({ qualifiedRef: ref, schedules })) {
                 parseSchedule(binding.cron, input.backend);
-                out.push(binding);
+                desired.push(binding);
             }
         }
         catch (cause) {
-            failures.push(workflowFailure(failurePath, failureRef, cause));
+            failures.push({ path: file, ref, reason: errorMessage(cause) });
         }
     }
 }
-function schedulerProjectionConfig(input) {
-    return Object.freeze({
-        ...SCHEDULER_PROJECTION_CONFIG,
-        defaultBundle: input.bundleName,
-        bundles: {
-            [input.bundleName]: {
-                path: input.sourceRoot,
-                components: { main: { root: ".", adapter: input.adapterId } },
-            },
-        },
-    });
-}
-function enumerateWorkflowLookups(input, collector, failures) {
-    const lookups = new Map();
-    for (const guarded of collector.authoredWorkflowSources(input.adapterId)) {
-        const sourcePath = guarded.sourcePath;
-        if (path.basename(sourcePath).toLowerCase() === "readme.md")
-            continue;
-        const authoredName = workflowNameForSourcePath(input.sourceRoot, input.adapterId, sourcePath);
-        if (authoredName === undefined)
-            continue;
-        const extension = path.posix.extname(authoredName).toLowerCase();
-        const stem = authoredName.slice(0, -extension.length).toLowerCase();
-        const nestedSuffix = WORKFLOW_EXTENSIONS.find((suffix) => stem.endsWith(suffix));
-        if (nestedSuffix) {
-            failures.push(workflowFailure(sourcePath, undefined, new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
-            continue;
-        }
-        const canonicalName = canonicalizeWorkflowName(authoredName);
-        const owners = lookups.get(canonicalName) ?? [];
-        owners.push(guarded);
-        lookups.set(canonicalName, owners);
+/** A file whose name cannot form a ref (a `#` in it) cannot be enabled, so it is not this sync's. */
+function sourceRef(bundleName, conceptId) {
+    try {
+        return makeBundleRef(bundleName, conceptId);
     }
-    return new Map([...lookups]
-        .sort(([left], [right]) => compareCodePoints(left, right))
-        .map(([name, sources]) => [name, Object.freeze(sources.sort(compareGuardedSources))]));
-}
-function installOptionsFor(input, current) {
-    if (current && !input.rebind) {
-        return Object.freeze({
-            ...(input.bundleTarget ? { target: input.bundleTarget } : {}),
-            binding: Object.freeze([...current.binding]),
-            contextPath: current.contextPath,
-        });
+    catch {
+        return undefined;
     }
-    return input.installOptions ? Object.freeze({ ...input.installOptions }) : undefined;
 }
-function belongsToBundle(entry, input) {
-    if (input.bundlePath !== undefined && entry.target === input.bundleName) {
-        // Path-scoped (#846), primary/unconfigured-bundle sync only: the name
-        // already matches, but a display name derived from a directory
-        // basename is not an identity — two unrelated bundles can legitimately
-        // share one. Require the entry's own scheduler-context descriptor to
-        // additionally confirm the resolved path. An entry whose owning path
-        // cannot be established is never assumed to be ours — that silent
-        // assumption is exactly what let an isolated/foreign bundle's sync
-        // reach for another bundle's real scheduler entries. (`bundlePath` is
-        // only set for a primary sync — a `--bundle <target>` entry's
-        // descriptor reflects the invoking process's OWN primary directory,
-        // not the targeted bundle's, so it is not a meaningful signal there;
-        // that case keeps relying on config-name uniqueness below.)
-        return entry.ownerBundlePath !== undefined && entry.ownerBundlePath === input.bundlePath;
+/** Directory entries, or none when the directory does not exist. Any other read error is the bundle's own failure. */
+function listDirectory(dir) {
+    try {
+        return fs.readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
     }
-    if (entry.target === input.bundleName || entry.target === input.bundleTarget)
-        return true;
-    return false;
-}
-function assertNoForeignIds(desired, input) {
-    const wanted = new Set(desired.map(({ id }) => id));
-    const foreign = input.installed.find((entry) => wanted.has(entry.id) && !belongsToBundle(entry, input));
-    if (!foreign)
-        return;
-    const where = foreign.ownerBundlePath
-        ? `the bundle at ${JSON.stringify(foreign.ownerBundlePath)}`
-        : foreign.target
-            ? `bundle ${JSON.stringify(foreign.target)}`
-            : "the default bundle";
-    const mine = input.bundlePath ? ` (this sync is scoped to ${JSON.stringify(input.bundlePath)})` : "";
-    throw new UsageError(`Scheduler id ${JSON.stringify(foreign.id)} is already scheduled from ${where}${mine}; desired source ids must not collide across bundles.`, "RESOURCE_ALREADY_EXISTS");
 }
-function assertUniqueDesiredIds(desired) {
-    const seen = new Set();
-    for (const binding of desired) {
-        if (seen.has(binding.id)) {
-            throw new UsageError(`Desired scheduler id collision for ${JSON.stringify(binding.id)}; no native definitions were changed.`, "RESOURCE_ALREADY_EXISTS");
+/** Every regular file under `dir` (symlinks followed), sorted. */
+function walkFiles(dir) {
+    const files = [];
+    const visit = (directory) => {
+        for (const name of listDirectory(directory)) {
+            const candidate = path.join(directory, name);
+            const stat = statOrUndefined(candidate);
+            if (stat?.isDirectory())
+                visit(candidate);
+            else if (stat?.isFile())
+                files.push(candidate);
         }
-        seen.add(binding.id);
+    };
+    visit(dir);
+    return files.sort(compareCodePoints);
+}
+/** A dangling or looping symlink is not a source file; it is skipped, never fatal. */
+function statOrUndefined(file) {
+    try {
+        return fs.statSync(file);
+    }
+    catch {
+        return undefined;
     }
 }
-function assertUniqueInstalledIds(installed) {
-    const seen = new Set();
-    for (const binding of installed) {
-        if (seen.has(binding.id)) {
-            throw new UsageError(`Installed scheduler id collision for ${JSON.stringify(binding.id)}; refusing whole-set reconciliation.`, "RESOURCE_ALREADY_EXISTS");
+/**
+ * Validate every v4 `schedule:` entry's `inputs` against the task's own
+ * declared contract with defaults applied — the exact set of values a
+ * compiled invocation delivers — so a violation is reported at sync rather
+ * than when the scheduler fires. Shared with `akm task validate`.
+ */
+export function assertTaskScheduleInputsSatisfyContract(v4, refLabel) {
+    const contract = v4.inputs ?? {};
+    for (const scheduleEntry of v4.schedule) {
+        const defaultedInputs = applyInputDefaults(contract, { ...scheduleEntry.inputs });
+        const errors = validateInputs(contract, defaultedInputs);
+        if (errors.length > 0) {
+            throw new UsageError(`Task ${JSON.stringify(refLabel)} schedule[${scheduleEntry.ordinal}].inputs does not satisfy ` +
+                `its declared inputs once defaults are applied: ${errors.join("; ")}`, "TASK_SOURCE_INVALID");
         }
-        seen.add(binding.id);
     }
 }
-function taskFailure(file, ref, cause) {
-    const detail = taskSourceErrorDetail(cause);
-    const reason = detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
-    return Object.freeze({ path: file, ref, reason });
-}
-function workflowFailure(file, ref, cause) {
-    return Object.freeze({ path: file, ...(ref ? { ref } : {}), reason: errorMessage(cause) });
-}
-function errorMessage(cause) {
-    return cause instanceof Error ? cause.message : String(cause);
+/**
+ * Validate every v4 `schedule:` entry's `cron` against the active backend's
+ * dialect: cron is the most permissive of the three, so a task authored on
+ * Linux can carry an expression launchd/schtasks cannot translate. Shared
+ * with `akm task validate`.
+ */
+export function assertTaskScheduleCronValid(v4, backend) {
+    for (const scheduleEntry of v4.schedule)
+        parseSchedule(scheduleEntry.cron, backend);
 }
-export function assertSchedulerSourceSnapshot(snapshot) {
-    try {
-        for (const source of snapshot.files) {
-            const current = captureGuardedExecutionSource(source.sourcePath, source.containmentRoot, {
-                authored: source.authored,
-                ...(source.identity ? { identity: source.identity } : {}),
-            });
-            if (JSON.stringify(current) !== JSON.stringify(source)) {
-                throw new Error(`source identity changed: ${source.sourcePath}`);
-            }
+export function installedRowNativeId(row) {
+    return row.nativeId ?? schedulerNativeBindingId(row.id);
+}
+/** The bundle an installed row's own invocation names: `--bundle <x>`, or a workflow ref's bundle. */
+export function scheduledInvocationBundle(invocation) {
+    if (!invocation)
+        return undefined;
+    const bundleIndex = invocation.indexOf("--bundle");
+    if (bundleIndex >= 0)
+        return invocation[bundleIndex + 1];
+    if (invocation[0] === "workflow" && invocation[1] === "run" && invocation[2]) {
+        try {
+            return parseBundleRef(invocation[2]).bundle;
         }
-        for (const manifest of snapshot.directoryManifests) {
-            const current = captureGuardedDirectoryManifest(manifest.directoryPath, manifest.containmentRoot);
-            if (JSON.stringify(current) !== JSON.stringify(manifest)) {
-                throw new Error(`directory manifest changed: ${manifest.directoryPath}`);
-            }
+        catch {
+            return undefined;
         }
     }
-    catch (cause) {
-        throw new UsageError(`Scheduler desired source read set changed after projection; refusing native mutation: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
-    }
+    return undefined;
 }
-class SchedulerSourceCollector {
-    #adapterId;
-    #sourceRoot;
-    #collector = new GuardedExecutionSourceCollector();
-    constructor(input) {
-        this.#adapterId = input.adapterId;
-        this.#sourceRoot = path.resolve(input.sourceRoot);
-        const root = this.#collector.trackDirectory(this.#sourceRoot, this.#sourceRoot);
-        const rootDirectories = new Set(root.entries.filter((entry) => entry.kind === "directory").map((entry) => entry.name));
-        const candidates = [];
-        if (input.adapterId === "akm") {
-            if (rootDirectories.has("tasks")) {
-                const taskRoot = path.join(this.#sourceRoot, "tasks");
-                const taskManifest = this.#collector.trackDirectory(taskRoot, this.#sourceRoot);
-                for (const entry of taskManifest.entries) {
-                    if (entry.kind === "file" && entry.name.endsWith(".yml")) {
-                        candidates.push(path.join(taskRoot, entry.name));
-                    }
-                }
-            }
-            if (rootDirectories.has("workflows")) {
-                candidates.push(...this.#collector.enumerateTree(path.join(this.#sourceRoot, "workflows"), this.#sourceRoot));
-            }
-        }
-        else if (input.adapterId === "akm-task") {
-            candidates.push(...this.#collector.enumerateTree(this.#sourceRoot, this.#sourceRoot).filter((file) => file.endsWith(".yml")));
-        }
-        else if (input.adapterId === "akm-workflow") {
-            candidates.push(...this.#collector.enumerateTree(this.#sourceRoot, this.#sourceRoot));
+/**
+ * The scope that owns an installed row, or none. A row written before
+ * `--bundle` existed names no bundle and belongs to the primary scope
+ * unless its descriptor says otherwise; a row that names a bundle belongs
+ * to the scope of that name — for the primary scope only when its
+ * descriptor also proves the path.
+ */
+export function installedRowScope(row, scopes) {
+    const bundle = row.target ?? scheduledInvocationBundle(row.invocation);
+    for (const scope of scopes) {
+        if (scope.bundlePath === undefined) {
+            if (bundle === scope.bundleName)
+                return scope;
+            continue;
         }
-        for (const file of candidates.sort(compareCodePoints)) {
-            this.#collector.capture(file, this.#sourceRoot, { authored: true });
+        if (bundle === undefined) {
+            if (row.ownerBundlePath === undefined || row.ownerBundlePath === scope.bundlePath)
+                return scope;
+            continue;
         }
+        if (bundle === scope.bundleName && row.ownerBundlePath === scope.bundlePath)
+            return scope;
     }
-    executionCollector() {
-        return this.#collector;
+    return undefined;
+}
+export function planSchedulerSync(input) {
+    const failures = [];
+    const installedByNative = new Map();
+    for (const row of input.installed)
+        installedByNative.set(installedRowNativeId(row), row);
+    // Two sources claiming one native row — compared case-insensitively, as
+    // Task Scheduler and a default macOS volume compare them: neither is
+    // installed and the row, if any, is left exactly as it is.
+    const desiredByNative = new Map();
+    for (const binding of input.desired) {
+        const key = schedulerBindingNativeId(binding).toLowerCase();
+        desiredByNative.set(key, [...(desiredByNative.get(key) ?? []), binding]);
     }
-    authoredTaskSources(adapterId) {
-        return this.#collector
-            .snapshot()
-            .sources.filter((file) => {
-            if (!file.authored || !file.relativePath.endsWith(".yml"))
-                return false;
-            if (adapterId === "akm-task")
-                return true;
-            return path.posix.dirname(file.relativePath) === "tasks";
-        })
-            .sort(compareGuardedSources);
+    const skipped = new Set();
+    for (const group of desiredByNative.values()) {
+        if (group.length < 2)
+            continue;
+        const refs = group.map((binding) => JSON.stringify(binding.logicalSource.ref)).join(" and ");
+        for (const binding of group) {
+            const nativeId = schedulerBindingNativeId(binding);
+            skipped.add(nativeId);
+            failures.push({
+                path: binding.source,
+                ref: binding.logicalSource.ref,
+                reason: `Scheduler id ${JSON.stringify(nativeId)} is claimed by ${refs}. Rename one task before enabling both.`,
+            });
+        }
     }
-    authoredWorkflowSources(adapterId) {
-        return this.#collector
-            .snapshot()
-            .sources.filter((file) => {
-            if (!file.authored)
-                return false;
-            if (adapterId === "akm-workflow")
-                return true;
-            return file.relativePath.startsWith("workflows/");
-        })
-            .sort(compareGuardedSources);
+    const installed = [];
+    const updated = [];
+    const unchanged = [];
+    const writes = [];
+    for (const binding of input.desired) {
+        const nativeId = schedulerBindingNativeId(binding);
+        if (skipped.has(nativeId))
+            continue;
+        const current = installedByNative.get(nativeId);
+        if (current &&
+            installedRowScope(current, input.scopes)?.bundleName !== parseBundleRef(binding.logicalSource.ref).bundle) {
+            skipped.add(nativeId);
+            failures.push({
+                path: binding.source,
+                ref: binding.logicalSource.ref,
+                reason: foreignRowMessage(nativeId, current),
+            });
+            continue;
+        }
+        const options = installOptionsFor(input, current);
+        const expected = input.expectedSignature?.(binding, options);
+        if (!current) {
+            installed.push(binding.id);
+            writes.push(Object.freeze({
+                kind: "install",
+                binding,
+                ...(options ? { options } : {}),
+                ...(expected !== undefined ? { expectedSignature: expected } : {}),
+            }));
+            continue;
+        }
+        if (expected === undefined || current.signature === expected) {
+            unchanged.push(binding.id);
+            continue;
+        }
+        updated.push(binding.id);
+        writes.push(Object.freeze({
+            kind: "update",
+            binding,
+            ...(options ? { options } : {}),
+            ...(current.signature !== undefined ? { installedSignature: current.signature } : {}),
+            expectedSignature: expected,
+        }));
     }
-    readBytes(file, containmentRoot) {
-        this.#trackAncestors(file, containmentRoot);
-        return this.#collector.readBytes(file, containmentRoot);
+    const desiredNative = new Set(input.desired.map(schedulerBindingNativeId));
+    const removals = new Map();
+    for (const row of input.installed) {
+        const nativeId = installedRowNativeId(row);
+        if (desiredNative.has(nativeId) || skipped.has(nativeId))
+            continue;
+        const scope = installedRowScope(row, input.scopes);
+        if (!scope)
+            continue;
+        const ref = installedRowRef(row, scope);
+        if (ref === undefined || !input.keepRefs?.has(ref))
+            removals.set(nativeId, row);
     }
-    fileContext(root, file) {
-        this.#trackAncestors(file, root);
-        return this.#collector.fileContext(root, file);
+    for (const row of input.extraRemovals ?? []) {
+        const nativeId = installedRowNativeId(row);
+        if (!desiredNative.has(nativeId) && !removals.has(nativeId))
+            removals.set(nativeId, row);
     }
-    snapshot() {
-        const guarded = this.#collector.snapshot();
-        const root = guarded.directoryManifests.find((manifest) => manifest.directoryPath === this.#sourceRoot && manifest.containmentRoot === this.#sourceRoot);
-        if (!root)
-            throw new Error("scheduler source collector lost its guarded root manifest");
+    const removeOperations = [...removals.values()]
+        .sort((left, right) => compareCodePoints(left.id, right.id))
+        .map((row) => Object.freeze({
+        kind: "remove",
+        id: row.id,
+        nativeId: installedRowNativeId(row),
+        ...(row.ownerBundlePath !== undefined ? { ownerBundlePath: row.ownerBundlePath } : {}),
+    }));
+    return Object.freeze({
+        desired: input.desired,
+        installed: Object.freeze(installed),
+        updated: Object.freeze(updated),
+        removed: Object.freeze(removeOperations.map((operation) => operation.id)),
+        unchanged: Object.freeze(unchanged),
+        operations: Object.freeze([...removeOperations, ...writes]),
+        failures: Object.freeze(failures),
+    });
+}
+/** An installed row keeps its own launcher unless `rebind`; the descriptor always follows the current policy. */
+function installOptionsFor(input, current) {
+    if (current && !input.rebind) {
         return Object.freeze({
-            adapterId: this.#adapterId,
-            sourceRoot: this.#sourceRoot,
-            sourceRealPath: root.realPath,
-            sourcePhysicalIdentity: root.physicalIdentity,
-            sourceDirectoryVersion: root.version,
-            files: Object.freeze([...guarded.sources].sort(compareGuardedSources)),
-            directoryManifests: guarded.directoryManifests,
+            binding: Object.freeze([...current.binding]),
+            contextPath: input.installOptions?.contextPath ?? current.contextPath,
         });
     }
-    #trackAncestors(file, containmentRoot) {
-        const root = path.resolve(containmentRoot);
-        const parent = path.dirname(path.resolve(file));
-        const relative = path.relative(root, parent);
-        if (relative.startsWith("..") || path.isAbsolute(relative))
-            return;
-        this.#collector.trackDirectory(root, root);
-        if (relative === "")
-            return;
-        let current = root;
-        for (const segment of relative.split(path.sep)) {
-            current = path.join(current, segment);
-            this.#collector.trackDirectory(current, root);
-        }
-    }
-}
-function compareGuardedSources(left, right) {
-    return compareCodePoints(left.sourcePath, right.sourcePath);
+    return input.installOptions ? Object.freeze({ ...input.installOptions }) : undefined;
 }
-function installedLogicalSource(invocation, input) {
-    if (invocation[0] === "workflow" && invocation[1] === "run" && invocation.length === 3) {
-        return Object.freeze({ kind: "workflow", ref: invocation[2] });
-    }
-    if (invocation[0] === "task" && invocation[1] === "run" && invocation[2]) {
-        const bundleIndex = invocation.indexOf("--bundle", 3);
-        const bundle = bundleIndex === -1 ? input.bundleName : invocation[bundleIndex + 1];
-        if (!bundle) {
-            throw new UsageError("Installed task invocation has no resolvable bundle owner.", "RESOURCE_ALREADY_EXISTS");
+/** The source ref an installed row runs, read from its own invocation. */
+function installedRowRef(row, scope) {
+    const [verb, action, subject] = row.invocation ?? [];
+    if (action !== "run" || !subject)
+        return undefined;
+    if (verb === "workflow")
+        return subject;
+    if (verb !== "task")
+        return undefined;
+    return `${scope.bundleName}//${scope.adapterId === "akm-task" ? subject : `tasks/${subject}`}`;
+}
+/** Where an installed row was scheduled from, for messages. */
+export function installedRowOwner(row) {
+    const bundle = row.target ?? scheduledInvocationBundle(row.invocation);
+    if (row.ownerBundlePath)
+        return `the bundle at ${JSON.stringify(row.ownerBundlePath)}`;
+    return bundle ? `bundle ${JSON.stringify(bundle)}` : "an installation this sync cannot attribute";
+}
+function foreignRowMessage(nativeId, row) {
+    return `Scheduler id ${JSON.stringify(nativeId)} is already scheduled from ${installedRowOwner(row)}; desired source ids must not collide across bundles. Leaving it out of this sync.`;
+}
+/** Project a set of operations into a preview report. Pure: no I/O, no backend calls. */
+export function renderSchedulerPlanPreview(backend, operations, unchanged = [], failures = []) {
+    const adds = [];
+    const updates = [];
+    const removes = [];
+    for (const operation of operations) {
+        if (operation.kind === "remove") {
+            removes.push({
+                id: operation.id,
+                kind: "remove",
+                nativeId: operation.nativeId,
+                ...(operation.ownerBundlePath !== undefined ? { ownerBundlePath: operation.ownerBundlePath } : {}),
+                ...(operation.reason !== undefined ? { reason: operation.reason } : {}),
+            });
+        }
+        else if (operation.kind === "install") {
+            adds.push({ id: operation.binding.id, kind: "install" });
+        }
+        else {
+            updates.push({
+                id: operation.binding.id,
+                kind: "update",
+                ...(operation.installedSignature !== undefined ? { installedFingerprint: operation.installedSignature } : {}),
+                ...(operation.expectedSignature !== undefined ? { expectedFingerprint: operation.expectedSignature } : {}),
+            });
         }
-        const conceptId = input.adapterId === "akm" ? `tasks/${invocation[2]}` : invocation[2];
-        return Object.freeze({ kind: "task", ref: makeBundleRef(bundle, conceptId) });
     }
-    throw new UsageError("Installed scheduler invocation has no exact canonical source owner.", "RESOURCE_ALREADY_EXISTS");
-}
-function freezeRemovalExpectation(expectation) {
-    return Object.freeze({
-        ...expectation,
-        logicalSource: Object.freeze({ ...expectation.logicalSource }),
-        invocation: Object.freeze([...expectation.invocation]),
-    });
-}
-function expectationForBinding(binding, state, fingerprint) {
     return {
-        state,
-        bindingId: binding.id,
-        nativeId: schedulerBindingNativeId(binding),
-        logicalSource: binding.logicalSource,
-        ordinal: binding.ordinal,
-        invocation: binding.invocation,
-        ...(fingerprint !== undefined ? { fingerprint } : {}),
+        backend,
+        dryRun: true,
+        adds,
+        updates,
+        removes,
+        unchanged: [...unchanged],
+        hasRemovals: removes.length > 0,
+        failures: [...failures],
     };
 }
-function freezeMutationExpectation(expectation) {
-    return Object.freeze({
-        ...expectation,
-        logicalSource: Object.freeze({ ...expectation.logicalSource }),
-        invocation: Object.freeze([...expectation.invocation]),
-    });
-}
-function freezeOperation(operation) {
-    return Object.freeze(operation);
-}
-function sameInvocation(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
 }
-// Retain the concrete error in this module's public dependency graph so callers
-// can continue to identify ownership failures without importing an adapter.
-export { WorkflowSourceRejectionError };