akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/workflows/source-ir/semantics.js

@@ -0,0 +1,242 @@
+// 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/.
+/** Shared semantic validation for every workflow source-IR producer and decoder. */
+import fs from "node:fs";
+import path from "node:path";
+import { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
+import { validatePortableCommandTemplate } from "../../commands/command/portable-template.js";
+import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { parseSchedule } from "../../tasks/schedule.js";
+import { classifyWorkflowSourceUses } from "./uses.js";
+const TOKEN_SAFE_RUN = /^[A-Za-z0-9_./:@+=,-]+(?: [A-Za-z0-9_./:@+=,-]+)*$/;
+export class WorkflowSourceSemanticError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "WorkflowSourceSemanticError";
+    }
+}
+export function canonicalizeWorkflowCron(value) {
+    const canonical = value.trim().split(/\s+/).join(" ");
+    if (canonical.startsWith("@") || canonical.split(" ").length !== 5) {
+        throw new WorkflowSourceSemanticError("invalid-cron", "GitHub schedule cron must use exactly five fields.");
+    }
+    try {
+        parseSchedule(canonical, "cron");
+    }
+    catch (cause) {
+        throw new WorkflowSourceSemanticError("invalid-cron", cause instanceof Error ? cause.message : "Invalid cron schedule.");
+    }
+    return canonical;
+}
+export function canonicalizeWorkflowRun(value) {
+    if (value.includes("${{")) {
+        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions and contexts are not supported.");
+    }
+    if (value.includes("\n") || value.includes("\r")) {
+        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
+    }
+    const canonical = value
+        .trim()
+        .split(/[ \t]+/)
+        .join(" ");
+    if (!TOKEN_SAFE_RUN.test(canonical)) {
+        throw new WorkflowSourceSemanticError("unsafe-run-syntax", "Local run accepts only whitespace-separated safe tokens; shell expansion and operators are unsupported.");
+    }
+    return canonical;
+}
+export function canonicalizeWorkflowWorkingDirectory(value, workspaceRoot) {
+    if (hasControlCharacter(value)) {
+        throw new WorkflowSourceSemanticError("working-directory-control-character", "working-directory may not contain NUL or control characters.");
+    }
+    if (value === "" || value.trim() === "") {
+        throw new WorkflowSourceSemanticError("working-directory-escape", "working-directory must be a non-empty relative contained path.");
+    }
+    const portable = value.replaceAll("\\", "/");
+    const segments = portable.split("/");
+    if (path.posix.isAbsolute(portable) ||
+        path.win32.isAbsolute(value) ||
+        portable.startsWith("~") ||
+        segments.some((segment) => segment === "" || segment === "..")) {
+        throw new WorkflowSourceSemanticError("working-directory-escape", "working-directory must be relative and contained.");
+    }
+    const withoutDots = segments.filter((segment) => segment !== ".");
+    const canonical = withoutDots.length === 0 ? "." : withoutDots.join("/");
+    if (workspaceRoot !== undefined)
+        verifyPhysicalContainment(workspaceRoot, canonical);
+    return canonical;
+}
+function hasControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint <= 0x1f || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+export function classifyWorkflowStepUses(value, classifier = classifyWorkflowSourceUses) {
+    if (value.includes("${{")) {
+        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions are unsupported in uses.");
+    }
+    if (value.length === 0 || value.trim() !== value || /\s/.test(value)) {
+        throw new WorkflowSourceSemanticError("unsupported-uses-target", "uses must be one exact, non-empty executable ref");
+    }
+    const task = canonicalTaskTarget(value);
+    if (task)
+        return task;
+    let target;
+    try {
+        target = classifier(value);
+    }
+    catch (cause) {
+        throw usesFailure(value, cause);
+    }
+    if (target.kind === "github-action") {
+        throw new WorkflowSourceSemanticError("remote-action-acquisition-out-of-scope", `Remote action acquisition is out of scope for ${JSON.stringify(value)}.`);
+    }
+    if (target.kind === "workflow") {
+        throw new WorkflowSourceSemanticError("nested-workflow-unsupported", `Nested workflow target ${JSON.stringify(value)} is unsupported in a workflow step.`);
+    }
+    return target;
+}
+function canonicalTaskTarget(value) {
+    try {
+        const parsed = parseBundleRef(value);
+        if (parsed.fragment !== undefined || bundleRefToString(parsed) !== value)
+            return undefined;
+        const slash = parsed.conceptId.indexOf("/");
+        if (slash < 0 || parsed.conceptId.slice(0, slash) !== "tasks" || parsed.conceptId.length === slash + 1) {
+            return undefined;
+        }
+        return { kind: "task", ref: value };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Validate AKM's built-in command action at the shared source/decoder boundary.
+ *
+ * Inline YAML actions are portable templates and therefore use WP4's one
+ * authoritative template validator. Markdown prose is explicitly `literal`,
+ * while a stored ref remains resolution-owned because its template bytes are
+ * not available until the later resolver loads the command asset.
+ */
+export function validateWorkflowBuiltinCommand(value, mode) {
+    let action;
+    try {
+        action = parseBuiltinCommandAction(value);
+    }
+    catch (cause) {
+        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid akm/command inputs.");
+    }
+    const expectedMode = action.kind === "stored" ? "stored-ref" : "portable-template";
+    const effectiveMode = mode ?? expectedMode;
+    if (action.kind === "stored") {
+        if (effectiveMode !== "stored-ref") {
+            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Stored akm/command refs require commandMode stored-ref.");
+        }
+        return action;
+    }
+    if (effectiveMode === "stored-ref") {
+        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Inline akm/command content cannot use commandMode stored-ref.");
+    }
+    if (effectiveMode === "literal") {
+        if (action.arguments !== undefined) {
+            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
+        }
+        return action;
+    }
+    try {
+        validatePortableCommandTemplate(action.content, "inline workflow command");
+    }
+    catch (cause) {
+        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid portable command template.");
+    }
+    return action;
+}
+export function rejectNulInArgv(command) {
+    if (command.some((argument) => argument.includes("\0"))) {
+        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Direct exec argv may not contain NUL bytes.");
+    }
+}
+function usesFailure(value, cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const code = value.startsWith("docker://")
+        ? "docker-action-unsupported"
+        : value.startsWith("./") || value.startsWith("../") || value.startsWith("/")
+            ? "local-action-path-unsupported"
+            : /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/\/)?agents\//.test(value)
+                ? "non-executable-asset-ref"
+                : "unsupported-uses-target";
+    return new WorkflowSourceSemanticError(code, message);
+}
+function verifyPhysicalContainment(workspaceRoot, relative) {
+    let root;
+    try {
+        root = fs.realpathSync(workspaceRoot);
+    }
+    catch {
+        throw new WorkflowSourceSemanticError("working-directory-unverifiable", "Workspace root cannot be physically verified.");
+    }
+    const candidate = path.resolve(root, ...relative.split("/"));
+    if (!contained(root, candidate)) {
+        throw new WorkflowSourceSemanticError("working-directory-escape", "working-directory escapes the workspace.");
+    }
+    let current = root;
+    for (const segment of relative === "." ? [] : relative.split("/")) {
+        current = path.join(current, segment);
+        try {
+            const entry = fs.lstatSync(current);
+            if (entry.isSymbolicLink()) {
+                let physical;
+                try {
+                    physical = fs.realpathSync(current);
+                }
+                catch {
+                    throw new WorkflowSourceSemanticError("working-directory-unverifiable", "working-directory contains a dangling or unresolvable symlink.");
+                }
+                if (!contained(root, physical)) {
+                    throw new WorkflowSourceSemanticError("working-directory-escape", "working-directory resolves through a symlink outside the workspace.");
+                }
+                let target;
+                try {
+                    target = fs.statSync(current);
+                }
+                catch {
+                    throw new WorkflowSourceSemanticError("working-directory-unverifiable", "working-directory symlink target cannot be physically verified.");
+                }
+                if (!target.isDirectory()) {
+                    throw new WorkflowSourceSemanticError("working-directory-unverifiable", "working-directory must resolve through directories.");
+                }
+                continue;
+            }
+            if (!entry.isDirectory()) {
+                throw new WorkflowSourceSemanticError("working-directory-unverifiable", "working-directory must resolve through directories.");
+            }
+            const physical = fs.realpathSync(current);
+            if (!contained(root, physical)) {
+                throw new WorkflowSourceSemanticError("working-directory-escape", "working-directory resolves through a symlink outside the workspace.");
+            }
+        }
+        catch (cause) {
+            if (cause instanceof WorkflowSourceSemanticError)
+                throw cause;
+            const code = cause?.code;
+            if (code === "ENOENT") {
+                // A genuinely absent lexical component is allowed at source time; the
+                // runtime dispatch boundary revalidates containment when it appears.
+                // `lstat` distinguishes this from a dangling symlink, which fails
+                // closed above even before its target can appear.
+                return;
+            }
+            throw new WorkflowSourceSemanticError("working-directory-unverifiable", "working-directory cannot be physically verified.");
+        }
+    }
+}
+function contained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}

package/dist/workflows/source-ir/uses.js

@@ -0,0 +1,14 @@
+// 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/.
+/**
+ * Workflow source adapters deliberately do not own an executable-ref grammar.
+ * `tasks/...` is the one workflow-only target and is recognized by
+ * `classifyWorkflowStepUses`; every remaining target delegates here to WP6's
+ * canonical task-v3 classifier.
+ */
+import { classifyTaskV3Uses } from "../../tasks/source-v3.js";
+/** Canonical non-task classifier used by direct source-IR decoding. */
+export function classifyWorkflowSourceUses(value) {
+    return classifyTaskV3Uses(value);
+}

package/docs/README.md

@@ -30,6 +30,7 @@ the task needs, and capture what you learn along the way.
 - [Environment & Secrets](https://github.com/itlackey/akm/blob/main/docs/reference/env-and-secrets.md) -- `akm env` and `akm secret`: exact operations, file modes, and the security guarantee
 - [Run Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md) -- Start or continue a run, check on it, resume it, or abandon it
 - [Scheduling](https://github.com/itlackey/akm/blob/main/docs/guides/scheduling.md) -- Run akm tasks through the OS scheduler (cron / launchd / schtasks) safely
+- [Migrate to 0.9.2](migration/v0.9.1-to-v0.9.2.md) -- Convert task-v2 sources safely and understand workflow resume compatibility
 - [Improve the Library](https://github.com/itlackey/akm/blob/main/docs/guides/improve-the-library.md) -- Feedback, history, and proposals -- how evidence turns into reviewable changes
 - Recipes: [Turn a Website into a Searchable Bundle](https://github.com/itlackey/akm/blob/main/docs/guides/recipes/website-source.md), [Headless Install](https://github.com/itlackey/akm/blob/main/docs/guides/recipes/headless-install.md)
 
@@ -55,6 +56,7 @@ Working on akm itself, not just using it.
 - [CLI](reference/cli.md) -- All `akm` commands and flags
 - [Configuration](reference/configuration.md) -- Engines, strategies, bundles, and settings
 - [Supported Formats](reference/supported-formats.md) -- Every bundle format akm recognizes, its detection marker, and current read/write support
+- [Tasks](reference/tasks.md) -- Task-v3 files, targets, triggers, and fail-closed migration
 - [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) -- The capability taxonomy, directory conventions, and per-type examples
 - [Refs](https://github.com/itlackey/akm/blob/main/docs/reference/refs.md) -- The ref grammar `akm search` emits and `akm show` consumes
 - [Memory](https://github.com/itlackey/akm/blob/main/docs/reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories

package/docs/migration/README.md

@@ -2,7 +2,9 @@
 
 Upgrade guides and per-release migration notes.
 
-- [v0.8 -> v0.9 migration guide](v0.8-to-v0.9.md) -- Current-cycle breaking changes
+- [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2 to task-v3 conversion, the single durable-v4 workflow boundary, and release behavior changes
+- [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
+- [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
 - [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
 - [Release notes](release-notes/) -- The short per-release notes `akm help migrate <version>` prints (bundled with the npm package)

package/docs/migration/release-notes/0.9.2.md

@@ -0,0 +1,55 @@
+Migration notes for akm v0.9.2
+
+Exact-prefix additive `state.db` upgrades remain automatic. The released
+historical migration 018 is classified separately because it removes retired
+dead-lane state: ordinary commands stop before it. Run `akm upgrade --force`;
+after executable replacement AKM writes and verifies a sibling
+`state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak` snapshot, then
+applies the immutable migration. The exact ledger recheck, snapshot, and 018
+transaction share one SQLite writer-exclusion window. There is no general
+database migration command.
+
+A newly created `state.db` still bootstraps automatically, but only when this
+invocation atomically created and retained ownership of that exact inode. An
+already-existing file with no applied migration IDs is not fresh, whether its
+`schema_migrations` table is absent or empty: ordinary commands reject it
+without writing. `akm upgrade --force` first verifies a
+descriptor-bound `state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak`
+snapshot. The same writer-exclusion transaction then initializes the ledger and
+applies migrations 001–002, so an old-schema writer cannot commit data between
+the recovery snapshot and migration 002's rebuild. Snapshot readers and targets
+are bound to their held inodes, not swappable pathnames. A failed snapshot path
+is reported and never removed by cleanup code.
+
+Task sources now use Task v3. Normal execution rejects task-v2 files; preview
+the repository-wide conversion with `akm migrate apply --dry-run`, review every
+`changed`, `skipped`, or `blocked` result, then run `akm migrate apply`. The
+migrator validates the replacement before it backs up and replaces a source,
+and ambiguous argv arrays remain blocked for manual review.
+
+Workflows now accept peer Markdown (`.md`) and GitHub-shaped YAML (`.yml`)
+sources through source IR v1. Runs freeze durable plan v4, the only executable
+plan format. Pre-v4 stored plans are rejected; start a new run from current
+source. A v4 resume does not re-read the authored workflow, configuration, or
+asset index. Scheduled fires are new starts, so they read the current source
+and create a fresh v4 freeze. V4 also rejects `inherit_env`; use exact named
+environment bindings and `pass_env` names instead.
+
+`akm command run --dry-run` performs authorization and adapter lowering but
+does not dispatch or materialize credentials. It writes no authored source or
+durable state and records no usage, events, or accounting. Safe provenance and
+lowering notices omit resolved, prompt, command, environment, and credential
+values. `--verbose` writes those safe diagnostics to stderr without changing
+the command result on stdout. `akm health` adds offline
+`selected-model-aliases` and `configured-engines` advisories; their evidence
+does not disclose endpoint values, exact model IDs, credential values, or
+provider output.
+
+`improve.strategies.<name>.processes.triage.judgment` now accepts a boolean or
+an object. Set `judgment: false` to disable the tier explicitly. A newly
+authored object defaults to enabled, while unknown object keys are rejected.
+The standalone proposal command's `--judgment` option remains an explicit
+invocation override and does not rewrite strategy configuration.
+
+See the [long-form guide](../v0.9.1-to-v0.9.2.md) for complete task examples,
+workflow boundaries, compatibility details, and upgrade checks.

package/docs/migration/release-notes/README.md

@@ -5,6 +5,11 @@ focused migration note that `akm help migrate <version>` prints to the
 terminal. The longform cross-release guides (e.g. `v0.5-to-v0.6.md`)
 live one level up in `docs/migration/`.
 
+## Available notes
+
+- [0.9.2](0.9.2.md) — task v3, workflow source IR v1 and durable v4,
+  command diagnostics, and strategy judgment migration
+
 ## Adding notes for a new release
 
 1. Create `<version>.md` in this directory (e.g. `0.7.0.md`).