akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/tasks/runtime-v3.js

@@ -0,0 +1,281 @@
+// 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 task-v3 runtime projection.
+ *
+ * This is the only bridge from authored task-v3 source into executable work.
+ * It performs all source/config/asset reads before the task runner reserves a
+ * durable attempt and returns immutable snapshots. In particular, script work
+ * contains frozen bytes and their digest, never a path that can be reread when
+ * a delayed or resumed dispatch begins.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { prepareCommandInvocation, } from "../commands/command/command-execution.js";
+import { makeBundleRef, parseBundleRef } from "../core/asset/asset-ref.js";
+import { ConfigError, NotFoundError, UsageError } from "../core/errors.js";
+import { DURATION_UNITS, parseDuration } from "../core/time.js";
+import { captureFrozenDirectoryIdentity } from "../execution/directory-identity.js";
+import { isPortableExecutionAgentSelector } from "../execution/source.js";
+import { requireAuthorizedExecutionPlan } from "../integrations/agent/execution-cascade.js";
+import { lowerResolvedExecutionRequest } from "../integrations/agent/execution-lowering.js";
+import { resolveAssetPath } from "../sources/resolve.js";
+import { detectSecretShapedParams } from "../workflows/exec/param-secrets.js";
+import { compileWorkflowPlan } from "../workflows/ir/compile.js";
+import { compileWorkflowSource } from "../workflows/source-ir/compile.js";
+import { isInferredSecretName } from "./log-redaction.js";
+import { isBunStandaloneMain } from "./resolve-akm-bin.js";
+import { SCHEDULED_TASK_CONTEXT_KEYS } from "./scheduler-invocation.js";
+const SCRIPT_INTERPRETERS = Object.freeze({
+    ".sh": "sh",
+    ".ts": "bun",
+    ".js": "bun",
+    ".ps1": "powershell",
+    ".cmd": "cmd",
+    ".bat": "cmd",
+    ".py": "python",
+    ".rb": "ruby",
+    ".go": "go",
+    ".pl": "perl",
+    ".php": "php",
+    ".lua": "lua",
+    ".r": "rscript",
+    ".swift": "swift",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+});
+function own(value, key) {
+    return value !== undefined && Object.hasOwn(value, key);
+}
+function environmentSnapshot(environment) {
+    const out = Object.create(null);
+    for (const key of Object.keys(environment ?? {}).sort()) {
+        const raw = environment?.[key];
+        if (raw === undefined)
+            continue;
+        const value = String(raw);
+        if (isInferredSecretName(key) || detectSecretShapedParams({ [key]: value }).length > 0) {
+            throw new UsageError(`Task v3 env.${key} is a secret-shaped literal env value. Store credentials in a secret/env binding rather than durable task source.`, "INVALID_FLAG_VALUE");
+        }
+        Object.defineProperty(out, key, { value, enumerable: true, configurable: false, writable: false });
+    }
+    return Object.freeze(out);
+}
+/** Merge source env with the authoritative, closed scheduler directory context. */
+function commandEnvironmentSnapshot(environment, schedulerContext) {
+    const out = Object.create(null);
+    for (const key of Object.keys(environment)) {
+        Object.defineProperty(out, key, { value: environment[key], enumerable: true, configurable: true, writable: true });
+    }
+    for (const key of SCHEDULED_TASK_CONTEXT_KEYS) {
+        const value = schedulerContext?.[key];
+        if (!value)
+            continue;
+        Object.defineProperty(out, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+    return Object.freeze(out);
+}
+function normalizeTimeout(value) {
+    if (value === undefined || value === null || typeof value === "number")
+        return value;
+    const parsed = parseDuration(value, DURATION_UNITS);
+    if (parsed === null)
+        throw new UsageError(`Invalid task timeout ${JSON.stringify(value)}.`, "INVALID_FLAG_VALUE");
+    return parsed;
+}
+function qualifyOwnedRef(ref, context) {
+    const parsed = parseBundleRef(ref);
+    const bundle = parsed.bundle ?? context.bundleName;
+    return { parsed, qualified: makeBundleRef(bundle, parsed.conceptId) };
+}
+function currentExecutionValues(document, context, environment) {
+    const akm = document.akm;
+    const agent = akm?.agent;
+    return Object.freeze({
+        ...(own(akm, "agent")
+            ? {
+                agent: typeof agent === "string" && isPortableExecutionAgentSelector(agent)
+                    ? qualifyOwnedRef(agent, context).qualified
+                    : agent,
+            }
+            : {}),
+        ...(own(akm, "engine") ? { engine: akm?.engine } : {}),
+        ...(own(akm, "model") ? { model: akm?.model } : {}),
+        ...(own(akm, "inference") ? { inference: akm?.inference } : {}),
+        ...(own(akm, "outputSchema") ? { outputSchema: akm?.outputSchema } : {}),
+        ...(own(akm, "tools") ? { tools: akm?.tools } : {}),
+        ...(own(akm, "timeout") ? { timeout: akm?.timeout } : {}),
+        workspace: context.bundleRoot,
+        environment,
+    });
+}
+function base(document, context, environment) {
+    const timeoutMs = normalizeTimeout(document.akm?.timeout);
+    return Object.freeze({
+        taskId: context.taskId,
+        taskRef: context.taskRef,
+        enabled: document.akm?.enabled !== false,
+        environment,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        redact: Object.freeze([...(document.akm?.redact ?? [])]),
+    });
+}
+async function resolvedOwnedAsset(qualified, type, context) {
+    const parsed = parseBundleRef(qualified);
+    const prefix = `${type}s/`;
+    const name = parsed.conceptId.slice(prefix.length);
+    if (context.resolveAsset) {
+        const resolved = await context.resolveAsset({ bundle: parsed.bundle, type, name, ref: qualified });
+        return typeof resolved === "string"
+            ? Object.freeze({ file: resolved, bundleRoot: context.bundleRoot })
+            : Object.freeze({ file: resolved.file, bundleRoot: resolved.bundleRoot });
+    }
+    if (parsed.bundle !== context.bundleName) {
+        throw new NotFoundError(`Task target ${JSON.stringify(qualified)} names bundle ${JSON.stringify(parsed.bundle)}, but no bundle resolver was provided.`, "ASSET_NOT_FOUND");
+    }
+    return Object.freeze({
+        file: await resolveAssetPath(context.bundleRoot, type, name),
+        bundleRoot: context.bundleRoot,
+    });
+}
+function scriptInterpreter(extension, ref) {
+    const interpreter = SCRIPT_INTERPRETERS[extension];
+    if (!interpreter) {
+        throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} has no closed runtime interpreter for extension ${JSON.stringify(extension)}.`, "INVALID_FLAG_VALUE");
+    }
+    if (interpreter !== "bun")
+        return interpreter;
+    if (!process.versions.bun) {
+        throw new UsageError(`Task v3 script target ${JSON.stringify(ref)} requires Bun for ${extension} execution, but this runtime cannot provide it.`, "INVALID_FLAG_VALUE");
+    }
+    return isBunStandaloneMain() ? "bun-standalone" : "bun";
+}
+function captureDirectoryIdentity(bundleRoot, workingDirectory) {
+    try {
+        return captureFrozenDirectoryIdentity(bundleRoot, workingDirectory);
+    }
+    catch (cause) {
+        if (cause instanceof UsageError)
+            throw cause;
+        throw new UsageError(`Task working directory ${JSON.stringify(workingDirectory ?? ".")} cannot be physically verified: ${cause instanceof Error ? cause.message : String(cause)}`, "INVALID_FLAG_VALUE");
+    }
+}
+function defaultTaskShell(platform) {
+    return platform === "win32" ? "powershell" : "sh";
+}
+function validatePreparedCommand(invocation, context) {
+    const request = requireAuthorizedExecutionPlan(invocation.plan);
+    if (!request.engine.name) {
+        throw new ConfigError(`Task ${JSON.stringify(context.taskRef)} has no resolved execution engine. Configure defaults.engine or akm.engine before running it.`, "INVALID_CONFIG_FILE");
+    }
+    // Lowering is pure. Running it before the durable-attempt boundary proves
+    // the selected target is transport-projectable; dispatch repeats the same
+    // deterministic projection from this frozen request/config snapshot.
+    lowerResolvedExecutionRequest(request, invocation.config);
+    return invocation;
+}
+function validateWorkflowRuntimeSource(file, workspaceRoot, readFile) {
+    const source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(readFile(file, workspaceRoot));
+    const compiled = compileWorkflowSource(source, { path: file, workspaceRoot });
+    if (!compiled.ok) {
+        const detail = compiled.errors.map((error) => `${error.path}:${error.line}: ${error.message}`).join("; ");
+        throw new UsageError(`Task workflow target is not projectable: ${detail}`, "INVALID_FLAG_VALUE");
+    }
+    const planned = compileWorkflowPlan(compiled.ir, path.basename(file, path.extname(file)));
+    if (!planned.ok) {
+        const detail = planned.errors.map((error) => `${file}:${error.line}: ${error.message}`).join("; ");
+        throw new UsageError(`Task workflow target is not projectable: ${detail}`, "INVALID_FLAG_VALUE");
+    }
+}
+/** Project one canonical task-v3 source into immutable executable work. */
+export async function prepareTaskV3Execution(document, context) {
+    const environment = environmentSnapshot(document.env);
+    const commandEnvironment = commandEnvironmentSnapshot(environment, context.schedulerContext);
+    const common = base(document, context, environment);
+    if (document.target.kind === "run") {
+        const cwdIdentity = captureDirectoryIdentity(context.bundleRoot, document.target.workingDirectory);
+        return Object.freeze({
+            ...common,
+            kind: "shell",
+            command: document.target.run,
+            shell: document.target.shell ?? defaultTaskShell(context.platform ?? process.platform),
+            cwd: cwdIdentity.realCwd,
+            cwdIdentity,
+        });
+    }
+    const target = document.target.uses;
+    if (target.kind === "github-action") {
+        throw new UsageError(`GitHub action ${JSON.stringify(target.ref)} is recognized but remote action acquisition is unsupported in 0.9.2.`, "INVALID_FLAG_VALUE");
+    }
+    if (target.kind === "builtin-command") {
+        const command = document.target.command;
+        if (!command)
+            throw new Error("invariant: parsed built-in command target has no command action");
+        const action = command.kind === "stored"
+            ? {
+                ref: qualifyOwnedRef(command.ref, context).qualified,
+                ...(command.arguments !== undefined ? { arguments: command.arguments } : {}),
+            }
+            : { content: command.content, ...(command.arguments !== undefined ? { arguments: command.arguments } : {}) };
+        const invocation = validatePreparedCommand(await (context.prepareCommand ?? prepareCommandInvocation)({
+            action,
+            config: context.config,
+            invocationKind: "task",
+            current: currentExecutionValues(document, context, commandEnvironment),
+            ...(context.commandSourceLoader ? { sourceLoader: context.commandSourceLoader } : {}),
+        }), context);
+        return Object.freeze({ ...common, kind: "command", invocation });
+    }
+    const { qualified } = qualifyOwnedRef(target.ref, context);
+    if (target.kind === "command") {
+        if (document.target.with !== undefined) {
+            throw new UsageError("Task v3 command refs do not accept with; use akm/command with {ref, arguments} for portable arguments.", "INVALID_FLAG_VALUE");
+        }
+        const invocation = validatePreparedCommand(await (context.prepareCommand ?? prepareCommandInvocation)({
+            action: { ref: qualified },
+            config: context.config,
+            invocationKind: "task",
+            current: currentExecutionValues(document, context, commandEnvironment),
+            ...(context.commandSourceLoader ? { sourceLoader: context.commandSourceLoader } : {}),
+        }), context);
+        return Object.freeze({ ...common, kind: "command", invocation });
+    }
+    if (target.kind === "workflow") {
+        if (Object.keys(environment).length > 0) {
+            throw new UsageError("Task v3 workflow env cannot be consumed by the durable workflow runtime in 0.9.2; remove env or use a command target.", "INVALID_FLAG_VALUE");
+        }
+        const resolved = await resolvedOwnedAsset(qualified, "workflow", context);
+        validateWorkflowRuntimeSource(resolved.file, resolved.bundleRoot, context.readFile ?? ((targetPath) => fs.readFileSync(targetPath)));
+        return Object.freeze({
+            ...common,
+            kind: "workflow",
+            ref: qualified,
+            params: Object.freeze({ ...(document.target.with ?? {}) }),
+            ...(document.akm?.maxSteps !== undefined ? { maxSteps: document.akm.maxSteps } : {}),
+            ...(document.akm?.maxRetries !== undefined ? { maxRetries: document.akm.maxRetries } : {}),
+        });
+    }
+    if (document.target.with !== undefined) {
+        throw new UsageError("Task v3 script refs do not accept with.", "INVALID_FLAG_VALUE");
+    }
+    const resolved = await resolvedOwnedAsset(qualified, "script", context);
+    const file = resolved.file;
+    const extension = path.extname(file).toLowerCase();
+    const raw = (context.readFile ?? ((targetPath) => fs.readFileSync(targetPath)))(file, resolved.bundleRoot);
+    const bytes = Uint8Array.from(raw);
+    const cwdIdentity = captureDirectoryIdentity(resolved.bundleRoot);
+    return Object.freeze({
+        ...common,
+        kind: "script",
+        sourceRef: qualified,
+        interpreter: scriptInterpreter(extension, qualified),
+        extension,
+        bytesBase64: Buffer.from(bytes).toString("base64"),
+        byteLength: bytes.byteLength,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+        cwd: cwdIdentity.realCwd,
+        cwdIdentity,
+    });
+}

package/dist/tasks/scheduler-binding.js

@@ -0,0 +1,272 @@
+// 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/.
+/**
+ * Secret-free input to every native scheduler backend.
+ *
+ * The binding deliberately contains only stable source identity, trigger
+ * identity, and the public CLI tail. Source content, action inputs,
+ * environment values, resolved requests, and credentials must never cross
+ * this boundary or be persisted by an OS scheduler.
+ */
+import { createHash } from "node:crypto";
+import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
+import { UsageError } from "../core/errors.js";
+import { normaliseTaskConceptId } from "./task-id.js";
+export function compileTaskSchedulerBindings(input) {
+    const id = normaliseTaskConceptId(input.id);
+    const ref = assertQualifiedRef(input.qualifiedRef, "task");
+    const bundle = parseBundleRef(ref).bundle;
+    if (!bundle)
+        throw new Error("invariant: qualified scheduler task ref lost its bundle");
+    const invocation = Object.freeze(["task", "run", id, "--bundle", bundle, "--scheduled"]);
+    return Object.freeze(input.schedules.map((schedule) => {
+        const bindingId = schedule.ordinal === 0 ? id : digestBindingId("task", ref, schedule.ordinal);
+        return freezeBinding({
+            id: bindingId,
+            nativeId: schedulerNativeBindingId(bindingId),
+            logicalSource: { kind: "task", ref },
+            cron: schedule.cron,
+            source: schedule.source,
+            ordinal: schedule.ordinal,
+            enabled: input.enabled,
+            invocation,
+        });
+    }));
+}
+export function compileWorkflowSchedulerBindings(input) {
+    const ref = assertQualifiedRef(input.qualifiedRef, "workflow");
+    const invocation = Object.freeze(["workflow", "run", ref]);
+    return Object.freeze(input.schedules.map((schedule) => {
+        const bindingId = digestBindingId("workflow", ref, schedule.ordinal);
+        return freezeBinding({
+            id: bindingId,
+            nativeId: bindingId,
+            logicalSource: { kind: "workflow", ref },
+            cron: schedule.cron,
+            source: schedule.source,
+            ordinal: schedule.ordinal,
+            enabled: true,
+            invocation,
+            ...(input.executionEvidenceDigest !== undefined
+                ? { executionEvidenceDigest: assertSchedulerExecutionEvidenceDigest(input.executionEvidenceDigest) }
+                : {}),
+        });
+    }));
+}
+export function assertSchedulerExecutionEvidenceDigest(value) {
+    if (!/^[a-f0-9]{64}$/u.test(value)) {
+        throw new UsageError("Scheduler workflow execution evidence must be a lowercase SHA-256 digest.", "INVALID_FLAG_VALUE");
+    }
+    return value;
+}
+/**
+ * Map a logical binding id to the flat portable token persisted by native
+ * schedulers. Existing flat ids are byte-for-byte stable; only standalone
+ * component-relative ids need an encoded native spelling.
+ */
+export function schedulerNativeBindingId(id) {
+    if (!id.includes("/"))
+        return id;
+    const digest = createHash("sha256")
+        .update(JSON.stringify(["nested-task", id]))
+        .digest("hex")
+        .slice(0, 32);
+    return `task-${digest}`;
+}
+/** Portable collision key for scheduler namespaces with Windows semantics. */
+export function schedulerNativeArtifactKey(nativeId) {
+    return nativeId.toLowerCase().replace(/\.+$/u, "");
+}
+export function schedulerNativeArtifactsForKey(artifacts, nativeId) {
+    const key = schedulerNativeArtifactKey(nativeId);
+    return artifacts.filter((artifact) => schedulerNativeArtifactKey(artifact.nativeId) === key);
+}
+export function assertSchedulerNativeArtifactCardinality(artifacts, nativeId, expectedCount) {
+    const matches = schedulerNativeArtifactsForKey(artifacts, nativeId);
+    if (matches.length !== expectedCount) {
+        const expectedState = expectedCount === 0 ? "absence" : "one present owner";
+        throw new UsageError(`Native scheduler artifact ${JSON.stringify(nativeId)} changed: normalized cardinality ${matches.length} violates the expected ${expectedState} before mutation.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    return matches[0];
+}
+/** Return a logical owner only when the public invocation proves the mapping. */
+export function schedulerLogicalBindingOwner(nativeId, invocation) {
+    return schedulerNativeArtifactOwner(nativeId, invocation)?.logicalId;
+}
+export function schedulerNativeArtifactOwner(nativeId, invocation) {
+    if (invocation[0] === "workflow" && invocation[1] === "run") {
+        return { logicalId: nativeId, logicalKind: "workflow" };
+    }
+    const taskId = invocation[0] === "task" && invocation[1] === "run" ? invocation[2] : undefined;
+    const bundleIndex = invocation.indexOf("--bundle", 3);
+    if (!taskId || bundleIndex === -1 || !invocation[bundleIndex + 1])
+        return undefined;
+    return {
+        logicalId: schedulerNativeBindingId(taskId) === nativeId ? taskId : nativeId,
+        logicalKind: "task",
+    };
+}
+export function assertSchedulerNativeArtifactOwner(nativeId, intended, invocation) {
+    const intendedNativeId = intended.nativeId ?? schedulerNativeBindingId(intended.id);
+    if (nativeId === intendedNativeId && invocation && sameInvocation(invocation, intended.invocation))
+        return;
+    const description = invocation ? JSON.stringify(invocation) : "an unproven or malformed invocation";
+    throw new UsageError(`Native scheduler artifact ${JSON.stringify(nativeId)} belongs to ${description}, not the exact ${intended.logicalSource.kind} owner ${JSON.stringify(intended.logicalSource.ref)} with binding ${JSON.stringify(intended.id)}.`, "RESOURCE_ALREADY_EXISTS");
+}
+/** Recover binding identity without treating the native hash as source ownership. */
+export function schedulerLogicalBindingId(nativeId, invocation) {
+    return schedulerLogicalBindingOwner(nativeId, invocation) ?? nativeId;
+}
+export function schedulerBindingNativeId(binding) {
+    return binding.nativeId ?? schedulerNativeBindingId(binding.id);
+}
+export function assertSchedulerRemovalArtifact(nativeId, expected, invocation, fingerprint) {
+    const normalized = normalizeRemovalExpectation(expected);
+    assertSchedulerExpectationIdentity(normalized);
+    const fingerprintMatches = normalized.fingerprint === undefined || normalized.fingerprint === fingerprint;
+    if (nativeId === normalized.nativeId &&
+        invocation !== undefined &&
+        sameInvocation(invocation, normalized.invocation) &&
+        fingerprintMatches) {
+        return;
+    }
+    throw new UsageError(`Native scheduler artifact ${JSON.stringify(nativeId)} changed owner or fingerprint; refusing to remove an unverified ${normalized.logicalSource.kind} owner ${JSON.stringify(normalized.logicalSource.ref)}.`, "RESOURCE_ALREADY_EXISTS");
+}
+export function assertSchedulerExpectationIdentity(expected, binding) {
+    const identity = canonicalSchedulerIdentity(expected.logicalSource, expected.ordinal, expected.invocation);
+    if (identity.bindingId !== expected.bindingId ||
+        identity.nativeId !== expected.nativeId ||
+        !sameInvocation(identity.invocation, expected.invocation) ||
+        (binding !== undefined &&
+            (binding.id !== expected.bindingId ||
+                schedulerBindingNativeId(binding) !== expected.nativeId ||
+                binding.ordinal !== expected.ordinal ||
+                binding.logicalSource.kind !== expected.logicalSource.kind ||
+                binding.logicalSource.ref !== expected.logicalSource.ref ||
+                !sameInvocation(binding.invocation, expected.invocation)))) {
+        throw new UsageError("Scheduler mutation expectation has a forged or inconsistent binding identity.", "INVALID_FLAG_VALUE");
+    }
+    if (expected.state === "absent" && expected.fingerprint !== undefined) {
+        throw new UsageError("An absent scheduler expectation cannot carry prior artifact state.", "INVALID_FLAG_VALUE");
+    }
+}
+export function assertSchedulerMutationArtifact(artifact, expected) {
+    assertSchedulerExpectationIdentity(expected);
+    if (expected.state === "absent") {
+        if (artifact === undefined)
+            return;
+    }
+    else if (artifact !== undefined &&
+        artifact.nativeId === expected.nativeId &&
+        artifact.bindingId === expected.bindingId &&
+        artifact.invocation !== undefined &&
+        sameInvocation(artifact.invocation, expected.invocation) &&
+        expected.fingerprint !== undefined &&
+        artifact.fingerprint === expected.fingerprint) {
+        return;
+    }
+    throw new UsageError(`Native scheduler artifact ${JSON.stringify(expected.nativeId)} changed from its frozen ${expected.state} state; refusing mutation.`, "RESOURCE_ALREADY_EXISTS");
+}
+export function assertSchedulerRollbackArtifact(artifact, expected) {
+    const matches = expected.allowed.some((state) => {
+        if (state.state === "absent")
+            return artifact === undefined;
+        if (!artifact || artifact.nativeId !== expected.nativeId)
+            return false;
+        if (artifact.fingerprint !== state.fingerprint || artifact.bindingId !== state.bindingId)
+            return false;
+        return state.invocation === undefined
+            ? artifact.invocation === undefined
+            : artifact.invocation !== undefined && sameInvocation(artifact.invocation, state.invocation);
+    });
+    if (matches)
+        return;
+    throw new UsageError(`Native scheduler artifact ${JSON.stringify(expected.nativeId)} changed after the transaction began; refusing rollback over a concurrent owner or fingerprint.`, "RESOURCE_ALREADY_EXISTS");
+}
+/**
+ * Validate a rollback target from one complete native inventory. Rollback
+ * guards may allow either the transaction-written state or the prior state,
+ * but neither state permits two portable-key-equivalent artifacts.
+ */
+export function assertSchedulerRollbackArtifactCardinality(artifacts, expected) {
+    const matches = schedulerNativeArtifactsForKey(artifacts, expected.nativeId);
+    if (matches.length > 1) {
+        throw new UsageError(`Native scheduler artifact ${JSON.stringify(expected.nativeId)} changed after the transaction began: normalized rollback cardinality ${matches.length} exceeds one.`, "RESOURCE_ALREADY_EXISTS");
+    }
+    const artifact = matches[0];
+    assertSchedulerRollbackArtifact(artifact, expected);
+    return artifact;
+}
+export function canonicalSchedulerIdentity(logicalSource, ordinal, invocation) {
+    const parsed = parseBundleRef(logicalSource.ref);
+    if (!parsed.bundle || parsed.fragment !== undefined || bundleRefToString(parsed) !== logicalSource.ref) {
+        throw new UsageError("Scheduler expectation requires one canonical fully-qualified source.", "INVALID_FLAG_VALUE");
+    }
+    if (!Number.isSafeInteger(ordinal) || ordinal < 0) {
+        throw new UsageError("Scheduler expectation ordinal must be a non-negative integer.", "INVALID_FLAG_VALUE");
+    }
+    if (logicalSource.kind === "workflow") {
+        const canonicalInvocation = ["workflow", "run", logicalSource.ref];
+        if (!sameInvocation(invocation, canonicalInvocation)) {
+            throw new UsageError("Workflow scheduler expectation invocation does not match its qualified source.", "INVALID_FLAG_VALUE");
+        }
+        const bindingId = digestBindingId("workflow", logicalSource.ref, ordinal);
+        return Object.freeze({ bindingId, nativeId: bindingId, invocation: Object.freeze(canonicalInvocation) });
+    }
+    const taskId = invocation[0] === "task" && invocation[1] === "run" ? invocation[2] : undefined;
+    if (!taskId || normaliseTaskConceptId(taskId) !== taskId) {
+        throw new UsageError("Task scheduler expectation has an invalid public task id.", "INVALID_FLAG_VALUE");
+    }
+    const canonicalInvocation = ["task", "run", taskId, "--bundle", parsed.bundle, "--scheduled"];
+    if (!sameInvocation(invocation, canonicalInvocation)) {
+        throw new UsageError("Task scheduler expectation invocation does not match its qualified source.", "INVALID_FLAG_VALUE");
+    }
+    if (parsed.conceptId !== taskId && parsed.conceptId !== `tasks/${taskId}`) {
+        throw new UsageError("Task scheduler expectation id does not match its qualified source.", "INVALID_FLAG_VALUE");
+    }
+    const bindingId = ordinal === 0 ? taskId : digestBindingId("task", logicalSource.ref, ordinal);
+    return Object.freeze({
+        bindingId,
+        nativeId: schedulerNativeBindingId(bindingId),
+        invocation: Object.freeze(canonicalInvocation),
+    });
+}
+/** Recover the authored schedule ordinal from the exact source/binding identity. */
+export function schedulerBindingOrdinal(bindingId, logicalSource, invocation) {
+    if (logicalSource.kind === "task" && bindingId === invocation[2])
+        return 0;
+    for (let ordinal = 0; ordinal < 4096; ordinal += 1) {
+        if (digestBindingId(logicalSource.kind, logicalSource.ref, ordinal) === bindingId)
+            return ordinal;
+    }
+    return undefined;
+}
+function digestBindingId(kind, ref, ordinal) {
+    const prefix = kind === "workflow" ? "wf" : "task";
+    const digest = createHash("sha256")
+        .update(JSON.stringify([kind, ref, ordinal]))
+        .digest("hex")
+        .slice(0, 32);
+    return `${prefix}-${digest}`;
+}
+function assertQualifiedRef(value, kind) {
+    const parsed = parseBundleRef(value);
+    if (!parsed.bundle || parsed.fragment !== undefined || bundleRefToString(parsed) !== value) {
+        throw new UsageError(`${kind} scheduler bindings require one canonical fully-qualified ref.`, "INVALID_FLAG_VALUE");
+    }
+    return value;
+}
+function freezeBinding(binding) {
+    return Object.freeze({
+        ...binding,
+        logicalSource: Object.freeze({ ...binding.logicalSource }),
+        invocation: Object.freeze([...binding.invocation]),
+    });
+}
+function sameInvocation(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function normalizeRemovalExpectation(expected) {
+    return { ...expected, state: "present" };
+}