akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/workflow-cli.js

@@ -7,37 +7,37 @@
  * args/output shape are byte-identical. Handlers whose body is a plain
  * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
  * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
- * form. `workflow template` keeps a plain `defineCommand` because it writes the
- * template straight to stdout with no JSON envelope. The private helpers
- * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
+ * form.
+ *
+ * 0.9.0 CLI overhaul (S5): `workflow template` is dropped — `workflow create
+ * --print` prints the same content without writing. `workflow validate` is
+ * dropped — `akm lint --type workflows` covers structural validation.
+ * `workflow watch` is dropped — poll `akm log --since '@offset:<id>' --run
+ * <run-id>` instead. Workflows are markdown-only (workflow-format-
+ * unification) — `workflow create <name>.yaml` is a usage error.
  */
-import { defineCommand } from "citty";
+import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
 import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
-import { resolveSourceEntries } from "../indexer/search/search-source.js";
-import { hasBooleanFlag } from "../output/context.js";
-import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
-import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowProgramTemplate, getWorkflowTemplate, validateWorkflowProgramSource, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
-import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
-import { isWorkflowProgramPath } from "../workflows/program/project.js";
-import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
+import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
+import { parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES } from "../workflows/cli.js";
+import { requireWorkflowEngineEnabled } from "../workflows/exec/workflow-engine-gate.js";
+import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStartCommand = defineJsonCommand({
     meta: {
         name: "start",
         description: "Start a new workflow run in the current working scope",
     },
     args: {
-        ref: { type: "positional", description: "Workflow ref (workflow:<name>)", required: true },
+        ref: { type: "positional", description: "Workflow ref (workflows/<name>)", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object" },
         force: {
             type: "boolean",
-            description: "Allow a parallel run when an active run already exists in this scope (#485)",
+            description: "Allow a parallel run when an active run already exists in this scope",
             default: false,
         },
     },
@@ -59,45 +59,17 @@ const workflowNextCommand = defineJsonCommand({
     },
     async run({ args }) {
         // `--dry-run` is intentionally NOT a declared arg (so it stays out of
-        // --help). The guard reads it straight from process.argv so existing
-        // callers still get a clear, actionable error instead of a generic
-        // "unknown flag" from citty.
-        if (hasBooleanFlag(process.argv, "--dry-run")) {
+        // --help). The guard reads it straight from the invocation singleton so
+        // existing callers still get a clear, actionable error instead of a
+        // generic "unknown flag" from citty.
+        if (getParsedInvocation().hasFlag("--dry-run")) {
             throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
         }
         const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
-        // If the target looks like a UUID-style run id (no `:` and matches the
-        // run-id shape), short-circuit with a structured WORKFLOW_NOT_FOUND
-        // error before parseAssetRef gets to throw an unhelpful ref-parse error.
-        if (looksLikeWorkflowRunId(args.target)) {
-            const { hasWorkflowRun } = await import("../workflows/runtime/runs.js");
-            if (!(await hasWorkflowRun(args.target))) {
-                throw new NotFoundError(`Workflow run "${args.target}" not found.`, "WORKFLOW_NOT_FOUND", "Run `akm workflow list --active` to see runs.");
-            }
-        }
         const result = await getNextWorkflowStep(args.target, parsedParams);
         output("workflow-next", result);
     },
 });
-/**
- * Heuristic: a workflow run id is a UUID-shaped or hex-id-shaped string with
- * no `:` separator (refs always contain a colon: `workflow:<name>` or
- * `<origin>//workflow:<name>`). When this matches we can give a much better
- * error than parseAssetRef's "Invalid asset type" failure.
- */
-function looksLikeWorkflowRunId(target) {
-    if (target.includes(":"))
-        return false;
-    if (target.includes("/"))
-        return false;
-    // UUID v4-ish: 8-4-4-4-12 hex digits separated by dashes.
-    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(target))
-        return true;
-    // Bare hex/alphanumeric run ids of >=8 chars (covers shortened ids).
-    if (/^[0-9a-z][0-9a-z_-]{7,}$/i.test(target) && /[0-9]/.test(target))
-        return true;
-    return false;
-}
 const workflowCompleteCommand = defineJsonCommand({
     meta: {
         name: "complete",
@@ -141,42 +113,37 @@ const workflowStatusCommand = defineJsonCommand({
         description: "Show full workflow run state for review or resume; workflow refs resolve within the current scope",
     },
     args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+        target: { type: "positional", description: "Workflow run id or workflow ref (workflows/<name>)", required: true },
         units: {
             type: "boolean",
             description: "Also list per-unit rows from the run journal (unit id, status, failure_reason, and any result/error " +
-                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected (#22).",
+                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
-        // Check if target looks like a workflow ref
-        const parsed = (() => {
-            try {
-                return parseAssetRef(target);
-            }
-            catch {
-                return null;
-            }
-        })();
-        if (parsed?.type === "workflow") {
-            const ref = `${parsed.origin ? `${parsed.origin}//` : ""}workflow:${parsed.name}`;
-            const { runs } = await listWorkflowRuns({ workflowRef: ref });
-            if (runs.length === 0) {
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            }
-            const mostRecent = runs[0];
-            if (!mostRecent)
-                throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
-            output("workflow-status", result);
-        }
-        else {
+        if (await hasWorkflowRun(target)) {
             const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
+            return;
         }
+        let runs;
+        try {
+            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
+        }
+        catch (error) {
+            if (!target.includes(":") && !target.includes("/")) {
+                throw new NotFoundError(`Workflow run "${target}" not found.`, "WORKFLOW_NOT_FOUND");
+            }
+            throw error;
+        }
+        const mostRecent = runs[0];
+        if (!mostRecent)
+            throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
+        const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
+        output("workflow-status", result);
     },
 });
 const workflowListCommand = defineJsonCommand({
@@ -196,12 +163,12 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow in the working stash (markdown document by default; a .yaml/.yml name writes a YAML program)",
+        description: "Create a workflow (markdown document) in the working bundle",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory). A .yaml/.yml suffix creates a YAML program.",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory).",
             required: true,
         },
         path: {
@@ -210,7 +177,7 @@ const workflowCreateCommand = defineJsonCommand({
         },
         from: {
             type: "string",
-            description: "Import and validate content from an existing file (parsed per the destination extension)",
+            description: "Import and validate content from an existing file",
         },
         force: {
             type: "boolean",
@@ -222,6 +189,11 @@ const workflowCreateCommand = defineJsonCommand({
             description: "Explicitly replace an existing workflow with a fresh template (use with --force)",
             default: false,
         },
+        print: {
+            type: "boolean",
+            description: "Print the RAW template that would be written to stdout without creating anything — pipe it to a file as a starter document",
+            default: false,
+        },
     },
     async run({ args }) {
         // `name` is flat; subdirectory placement is `--path`'s job.
@@ -231,6 +203,14 @@ const workflowCreateCommand = defineJsonCommand({
         if (!namePattern.test(effectiveName)) {
             throw new UsageError("Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, hyphens, dots, underscores, and slashes.");
         }
+        assertWorkflowMarkdownName(effectiveName);
+        if (args.print) {
+            // Raw document, not an envelope — the retired `workflow template` was
+            // format-exempt for the same reason: `--print > starter.md` must yield
+            // a usable starter file, not `{ok,template,kind}` JSON.
+            process.stdout.write(getWorkflowTemplate());
+            return;
+        }
         if (args.force && !args.from && !args.reset) {
             throw new UsageError("Refusing to overwrite with template: pass --from <file> to replace content, or --reset to explicitly replace with a fresh template.");
         }
@@ -246,117 +226,20 @@ const workflowCreateCommand = defineJsonCommand({
         output("workflow-create", { ok: true, ...result });
     },
 });
-const workflowTemplateCommand = defineCommand({
-    meta: {
-        name: "template",
-        description: "Print a valid workflow template (markdown by default, --yaml for a YAML program)",
-    },
-    args: {
-        yaml: {
-            type: "boolean",
-            description: "Print a minimal valid YAML workflow program instead of the markdown template",
-            default: false,
-        },
-    },
-    run({ args }) {
-        process.stdout.write(args.yaml ? getWorkflowProgramTemplate() : getWorkflowTemplate());
-    },
-});
-const workflowValidateCommand = defineJsonCommand({
-    meta: {
-        name: "validate",
-        description: "Validate a workflow file or ref (markdown document or YAML program) and print any errors",
-    },
-    args: {
-        target: {
-            type: "positional",
-            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md/.yaml",
-            required: true,
-        },
-    },
-    async run({ args }) {
-        const filePath = await resolveWorkflowFilePath(args.target);
-        // YAML programs (redesign addendum, R1) validate through the program
-        // parser AND compiler so expression/reference errors surface at lint
-        // time; both error lists carry line numbers. Markdown is unchanged.
-        if (isWorkflowProgramPath(filePath)) {
-            const { result } = validateWorkflowProgramSource(filePath);
-            if (!result.ok) {
-                throw new UsageError(formatWorkflowErrors(filePath, result.errors));
-            }
-            // Non-fatal WARNINGS ride the envelope additively — `ok` stays true. The
-            // text formatter renders them clearly marked for humans; the JSON key is
-            // the machine channel. Empty array when the program is fully typed/declared.
-            output("workflow-validate", {
-                ok: true,
-                path: filePath,
-                format: "program",
-                title: result.program.name,
-                stepCount: result.program.steps.length,
-                warnings: result.warnings.map((w) => ({ line: w.line, message: w.message })),
-            });
-            return;
-        }
-        const { parse } = validateWorkflowSource(filePath);
-        if (parse.ok) {
-            output("workflow-validate", {
-                ok: true,
-                path: filePath,
-                title: parse.document.title,
-                stepCount: parse.document.steps.length,
-            });
-            return;
-        }
-        throw new UsageError(formatWorkflowErrors(filePath, parse.errors));
-    },
-});
-async function resolveWorkflowFilePath(target) {
-    // A bare (`workflow:<name>`) OR origin-qualified (`<origin>//workflow:<name>`)
-    // ref resolves through the source search, exactly like `workflow start` /
-    // `status` / `next`. Anything else is treated as a filesystem path. Detecting
-    // the origin-qualified form here (not just the bare prefix) keeps `validate`'s
-    // ref contract in lockstep with the rest of the workflow command family — an
-    // `extra//workflow:foo` ref validates the file that `extra//workflow:foo`
-    // starts, rather than being mistaken for a relative path that does not exist.
-    const looksLikeWorkflowRef = target.startsWith("workflow:") || target.includes("//workflow:");
-    if (!looksLikeWorkflowRef)
-        return target;
-    const parsed = parseAssetRef(target);
-    if (parsed.type !== "workflow") {
-        throw new UsageError(`Expected a workflow ref (workflow:<name>), got "${target}".`);
-    }
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const searchSources = resolveSourcesForOrigin(parsed.origin, allSources);
-    for (const source of searchSources) {
-        try {
-            return await resolveAssetPath(source.path, "workflow", parsed.name);
-        }
-        catch {
-            /* try next source */
-        }
-    }
-    throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
-}
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "EXPERIMENTAL: execute a workflow's steps with the native engine — akm dispatches each step's units " +
-            "(fan-out, schema output) to the configured runner and advances the run through the normal completion gates",
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: execute a workflow's steps with the native " +
+            "engine — akm dispatches each step's units (fan-out, schema output) to the configured runner and advances " +
+            "the run through the normal completion gates",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
         params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
         "max-steps": { type: "string", description: "Stop after executing this many steps" },
-        "require-gates": {
-            type: "boolean",
-            description: "Treat every criteria-bearing completion gate as required: if no LLM judge is available, BLOCK the step " +
-                "(for a human to resolve via `akm workflow resume`) instead of failing open. A per-step `gate.required: true` " +
-                "in the workflow does the same on every surface; this is the run-wide override (#18).",
-            default: false,
-        },
     },
     async run({ args }) {
+        requireWorkflowEngineEnabled(loadConfig(), "run");
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
         const rawMaxSteps = getStringArg(args, "max-steps");
         let maxSteps;
@@ -370,7 +253,6 @@ const workflowRunCommand = defineJsonCommand({
             target: args.target,
             ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
             ...(maxSteps !== undefined ? { maxSteps } : {}),
-            ...(args["require-gates"] === true ? { requireGates: true } : {}),
         });
         output("workflow-run", result);
     },
@@ -378,9 +260,10 @@ const workflowRunCommand = defineJsonCommand({
 const workflowBriefCommand = defineJsonCommand({
     meta: {
         name: "brief",
-        description: "EXPERIMENTAL: describe a run's active step as an executable work-list for ANY agent session (the " +
-            "harness-neutral driver protocol) — read-only, takes no engine lease, mutates nothing; prints per-unit " +
-            "instructions, output schema, env binding names, and the exact `akm workflow report` command lines",
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: describe a run's active step as an executable " +
+            "work-list for ANY agent session (the harness-neutral driver protocol) — read-only, takes no engine lease, " +
+            "mutates nothing; prints per-unit instructions, output schema, env binding names, and the exact " +
+            "`akm workflow report` command lines",
     },
     args: {
         target: {
@@ -390,6 +273,7 @@ const workflowBriefCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
+        requireWorkflowEngineEnabled(loadConfig(), "brief");
         const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
         const result = await buildWorkflowBrief(args.target);
         output("workflow-brief", result);
@@ -399,8 +283,9 @@ const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
 const workflowReportCommand = defineJsonCommand({
     meta: {
         name: "report",
-        description: "EXPERIMENTAL: report a unit's result back into a run (the mutating half of the harness-neutral driver " +
-            "protocol) — ingested through the SAME shared step semantics the engine uses. --status running claims/" +
+        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: report a unit's result back into a run (the " +
+            "mutating half of the harness-neutral driver protocol) — ingested through the SAME shared step semantics " +
+            "the engine uses. --status running claims/" +
             "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
             "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
             "parked on a route-only/empty step. Refused while a live engine lease exists",
@@ -438,6 +323,7 @@ const workflowReportCommand = defineJsonCommand({
         },
     },
     async run({ args }) {
+        requireWorkflowEngineEnabled(loadConfig(), "report");
         // --settle: the unit-less verb that advances a run parked on a
         // non-dispatching step. Mutually exclusive with the per-unit report flags.
         if (args.settle === true) {
@@ -515,41 +401,6 @@ async function readStdin() {
         chunks.push(chunk);
     return Buffer.concat(chunks).toString("utf8");
 }
-const workflowWatchCommand = defineJsonCommand({
-    meta: {
-        name: "watch",
-        description: "Print a run's workflow_* events (state.db events table) as NDJSON and exit; --stream polls in the " +
-            "foreground until the run reaches a terminal status (no daemon)",
-    },
-    args: {
-        runId: { type: "positional", description: "Workflow run id", required: true },
-        stream: {
-            type: "boolean",
-            description: "Keep polling for new events until the run leaves 'active' (completed/failed/blocked)",
-            default: false,
-        },
-        "interval-ms": { type: "string", description: "Poll interval in milliseconds for --stream (default: 1000)" },
-    },
-    async run({ args }) {
-        const rawInterval = getStringArg(args, "interval-ms");
-        let intervalMs;
-        if (rawInterval !== undefined) {
-            intervalMs = Number.parseInt(rawInterval, 10);
-            if (!/^\d+$/.test(rawInterval) || intervalMs <= 0) {
-                throw new UsageError(`--interval-ms must be a positive integer, got "${rawInterval}".`, "INVALID_FLAG_VALUE");
-            }
-        }
-        const { watchWorkflowRun } = await import("../workflows/exec/watch.js");
-        const result = await watchWorkflowRun({
-            runId: args.runId,
-            stream: args.stream === true,
-            ...(intervalMs !== undefined ? { intervalMs } : {}),
-        });
-        // The event lines above are raw NDJSON on stdout; this trailing envelope
-        // is the machine-readable command result (counts + terminal status).
-        output("workflow-watch", { ok: true, ...result });
-    },
-});
 const workflowAbandonCommand = defineJsonCommand({
     meta: {
         name: "abandon",
@@ -576,7 +427,7 @@ const workflowResumeCommand = defineJsonCommand({
         output("workflow-resume", result);
     },
 });
-export const workflowCommand = defineCommand({
+export const workflowCommand = defineGroupCommand({
     meta: {
         name: "workflow",
         description: "Author, inspect, and execute step-by-step workflow assets",
@@ -588,20 +439,16 @@ export const workflowCommand = defineCommand({
         status: workflowStatusCommand,
         list: workflowListCommand,
         create: workflowCreateCommand,
-        template: workflowTemplateCommand,
         resume: workflowResumeCommand,
         abandon: workflowAbandonCommand,
-        validate: workflowValidateCommand,
         run: workflowRunCommand,
         brief: workflowBriefCommand,
         report: workflowReportCommand,
-        watch: workflowWatchCommand,
-    },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasWorkflowSubcommand(args))
-                return;
-            output("workflow-list", await listWorkflowRuns({ activeOnly: true }));
-        });
     },
+    // No `defaultRun`: bare `akm workflow` is a usage error (exit 2), the
+    // canonical bare-group behavior — owner ruling 12. Run `akm workflow list
+    // --active` for what the bare form used to print. This group was previously
+    // hand-rolled on `defineCommand` with its own `hasWorkflowSubcommand` guard,
+    // which duplicated the subcommand names in a second hand-maintained set;
+    // `defineGroupCommand` derives the guard from `subCommands` directly.
 });

package/dist/core/action-contributors.js

@@ -1,7 +1,7 @@
 // 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/.
-import { defaultRendererRegistry } from "./asset/asset-registry.js";
+import { defaultRendererRegistry } from "./type-presentation.js";
 function registryActionContributor(registry) {
     return {
         name: "registry-action-contributor",

package/dist/core/activation-policy.js

@@ -0,0 +1,49 @@
+// 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/.
+/**
+ * Decide whether injecting an env with the given dangerous keys is allowed,
+ * warned, or blocked. Third-party (registry-installed) stashes hard-block;
+ * first-party stashes warn. See rule 1 above.
+ *
+ * @param dangerousKeys The subset of injected keys flagged as process-hijacking
+ *   (already filtered by the caller via `isDangerousEnvKey`).
+ * @param thirdParty `true` when the env's source is a third-party stash — i.e.
+ *   its origin carries a `registryId`.
+ */
+export function decideDangerousEnvInjection(input) {
+    if (input.dangerousKeys.length === 0)
+        return "allow";
+    return input.thirdParty ? "block" : "warn";
+}
+/**
+ * Decide the baseline install stance for a freshly-installed stash's
+ * dangerous-key scan. The interactive confirm / rollback UX is applied by the
+ * caller on top of the `"gate"` stance — this predicate only fixes the policy.
+ * See rule 2 above.
+ */
+export function decideDangerousKeyInstall(input) {
+    if (!input.findingsPresent)
+        return "allow";
+    return input.allowInsecure ? "warn-allow" : "gate";
+}
+// ── Rule 3: task activation (tasks/runner.ts) ────────────────────────────────
+/**
+ * Whether a scheduler-generated task invocation must be skipped because the
+ * task is not activated (its `enabled:` is false). Manual (non-scheduled) runs
+ * are always dispatched — installing a task grants nothing until enabled, but
+ * the operator may still run it by hand for catch-up / testing. See rule 3.
+ */
+export function shouldSkipUnactivatedTask(input) {
+    return !input.enabled && input.scheduled;
+}
+// ── Rule 4: write activation (search-source.ts, installations.ts) ────────────
+/**
+ * Whether a resolved source is write-activated. Only the primary stash and
+ * sources explicitly marked `writable: true` are writable; registry-cached
+ * (installed, read-only) sources are never written in place because
+ * `akm update` overwrites them. See rule 4 above.
+ */
+export function isSourceWriteActivated(source) {
+    return source.writable === true;
+}