akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/tasks/scheduler-sync.js

@@ -0,0 +1,654 @@
+// 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";
+import path from "node:path";
+import { loadAdapterExecutionSource } from "../commands/command/execution-source-loader.js";
+import { makeBundleRef } from "../core/asset/asset-ref.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 { 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 { prepareTaskV3Execution } from "./runtime-v3.js";
+import { parseSchedule } from "./schedule.js";
+import { assertSchedulerNativeArtifactCardinality, compileTaskSchedulerBindings, compileWorkflowSchedulerBindings, schedulerBindingNativeId, schedulerBindingOrdinal, schedulerNativeArtifactKey, schedulerNativeBindingId, } from "./scheduler-binding.js";
+import { parseTaskV3Yaml, taskV3SourceErrorDetail } 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,
+    });
+}
+export function finalizeSchedulerSyncPlan(input, prepared) {
+    const inspection = inspectionForPlan(input);
+    const coherentInput = {
+        ...input,
+        installed: inspection.installed,
+        nativeArtifacts: inspection.artifacts,
+    };
+    const desired = prepared.desired;
+    assertUniqueDesiredIds(desired);
+    assertCoherentInspection(inspection, input.inspection !== undefined);
+    assertUniqueInstalledIds(coherentInput.installed);
+    assertNoForeignIds(desired, coherentInput);
+    assertSchedulerNativeArtifactOwnership(desired, inspection.artifacts);
+    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);
+        if (!current?.invocation) {
+            throw nativeArtifactCollision({ nativeId: current?.nativeId ?? schedulerNativeBindingId(id), bindingId: id }, { nativeId: current?.nativeId ?? schedulerNativeBindingId(id) });
+        }
+        const nativeId = exactInstalledNativeId(id, current, inspection.artifacts);
+        const artifact = inspection.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, coherentInput);
+        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");
+        }
+        operations.push(Object.freeze({
+            kind: "remove",
+            id,
+            nativeId,
+            expected: freezeRemovalExpectation({
+                state: "present",
+                bindingId: id,
+                nativeId,
+                logicalSource,
+                ordinal,
+                invocation: current.invocation,
+                fingerprint: priorFingerprint,
+            }),
+        }));
+    }
+    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,
+    });
+}
+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;
+        if (artifact.nativeId !== schedulerBindingNativeId(wanted) ||
+            artifact.bindingId !== wanted.id ||
+            artifact.invocation === undefined ||
+            !sameInvocation(artifact.invocation, wanted.invocation)) {
+            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 = [];
+    const failures = [];
+    await compileTaskSources(input, collector, bindings, failures);
+    await compileWorkflowSources(input, collector, bindings, executableWorkflows, failures);
+    if (failures.length > 0) {
+        throw new UsageError(`Scheduler sync rejected the desired source set before mutation:\n${failures.map((failure) => `- ${failure}`).join("\n")}`, "INVALID_FLAG_VALUE");
+    }
+    return Object.freeze({
+        desired: Object.freeze(bindings),
+        executableWorkflows: Object.freeze(executableWorkflows.sort((left, right) => compareCodePoints(left.ref, right.ref))),
+    });
+}
+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");
+        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);
+            const document = parseTaskV3Yaml({
+                yaml: guarded.content,
+                filePath: sourcePath,
+                workspaceRoot: input.sourceRoot,
+            });
+            const qualifiedRef = makeBundleRef(input.bundleName, conceptId);
+            await prepareTaskV3Execution(document, {
+                taskId: id,
+                taskRef: qualifiedRef,
+                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 sourceBindings = compileTaskSchedulerBindings({
+                id,
+                qualifiedRef,
+                ...(input.bundleTarget ? { bundleTarget: input.bundleTarget } : {}),
+                enabled: document.akm?.enabled !== false,
+                schedules: document.triggers.schedules.map((schedule) => ({
+                    ...schedule,
+                    source: `${toPosix(path.relative(input.sourceRoot, sourcePath))}:${schedule.source}`,
+                })),
+            });
+            for (const binding of sourceBindings) {
+                parseSchedule(binding.cron, input.backend);
+                out.push(binding);
+            }
+        }
+        catch (cause) {
+            failures.push(taskFailure(sourcePath, cause));
+        }
+    }
+}
+async function compileWorkflowSources(input, collector, out, evidence, failures) {
+    if (input.adapterId !== "akm" && input.adapterId !== "akm-workflow")
+        return;
+    const lookups = enumerateWorkflowLookups(input, collector, failures);
+    for (const [canonicalName, sources] of lookups) {
+        try {
+            if (sources.length > 1) {
+                throw new WorkflowSourceCollisionError(input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));
+            }
+            const guarded = sources[0];
+            if (!guarded)
+                continue;
+            const compiled = compileWorkflowSource(guarded.content, {
+                path: guarded.relativePath,
+                workspaceRoot: input.sourceRoot,
+            });
+            if (!compiled.ok) {
+                throw new UsageError(compiled.errors
+                    .map((error) => `${error.path}:${error.line ?? 1} [${error.code}] ${error.message}`)
+                    .join("; "), "INVALID_FLAG_VALUE");
+            }
+            const planDraft = compileWorkflowPlan(compiled.ir, canonicalName);
+            if (!planDraft.ok) {
+                throw new UsageError(planDraft.errors.map((error) => `${guarded.relativePath}:${error.line} ${error.message}`).join("; "), "INVALID_FLAG_VALUE");
+            }
+            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: 4,
+                planHash,
+                sourceReadSet: frozen.plan.sourceReadSet,
+                executionEvidenceDigest,
+            }));
+            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,
+            })) {
+                parseSchedule(binding.cron, input.backend);
+                out.push(binding);
+            }
+        }
+        catch (cause) {
+            failures.push(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(errorMessage(new WorkflowSourceNameError(guarded.relativePath, nestedSuffix)));
+            continue;
+        }
+        const canonicalName = canonicalizeWorkflowName(authoredName);
+        const owners = lookups.get(canonicalName) ?? [];
+        owners.push(guarded);
+        lookups.set(canonicalName, owners);
+    }
+    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,
+        });
+    }
+    return input.installOptions ? Object.freeze({ ...input.installOptions }) : undefined;
+}
+function belongsToBundle(entry, input) {
+    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.target ? `bundle ${JSON.stringify(foreign.target)}` : "the default bundle";
+    throw new UsageError(`Scheduler id ${JSON.stringify(foreign.id)} is already scheduled from ${where}; 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");
+        }
+        seen.add(binding.id);
+    }
+}
+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");
+        }
+        seen.add(binding.id);
+    }
+}
+function taskFailure(file, cause) {
+    const detail = taskV3SourceErrorDetail(cause);
+    return detail === errorMessage(cause) ? `${file}: ${detail}` : detail;
+}
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+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}`);
+            }
+        }
+        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 (cause) {
+        throw new UsageError(`Scheduler desired source read set changed after projection; refusing native mutation: ${errorMessage(cause)}`, "RESOURCE_ALREADY_EXISTS");
+    }
+}
+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));
+        }
+        for (const file of candidates.sort(compareCodePoints)) {
+            this.#collector.capture(file, this.#sourceRoot, { authored: true });
+        }
+    }
+    executionCollector() {
+        return this.#collector;
+    }
+    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);
+    }
+    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);
+    }
+    readBytes(file, containmentRoot) {
+        this.#trackAncestors(file, containmentRoot);
+        return this.#collector.readBytes(file, containmentRoot);
+    }
+    fileContext(root, file) {
+        this.#trackAncestors(file, root);
+        return this.#collector.fileContext(root, file);
+    }
+    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");
+        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,
+        });
+    }
+    #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);
+}
+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");
+        }
+        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 } : {}),
+    };
+}
+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 compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function toPosix(value) {
+    return value.replaceAll("\\", "/");
+}
+// 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 };