akm-cli 0.6.0 → 0.7.0-rc1

package/dist/src/core/proposals.js

@@ -0,0 +1,406 @@
+/**
+ * Proposal substrate (#225).
+ *
+ * One durable proposal store for every future reflection / generation flow
+ * (`akm reflect`, `akm propose`, `akm distill`, lesson distillation, …).
+ * Proposals are *queue state*, not source-of-truth assets — they sit on disk
+ * waiting for human (or automated) review and only become assets after
+ * `akm proposal accept` validates and promotes them via
+ * {@link writeAssetToSource}.
+ *
+ * # Storage layout
+ *
+ *   <stashRoot>/.akm/proposals/<id>/proposal.json
+ *   <stashRoot>/.akm/proposals/archive/<id>/proposal.json
+ *
+ * One directory per proposal id (a stable `crypto.randomUUID()`), so multiple
+ * proposals can target the same `ref` without filesystem collisions.
+ *
+ * # Why direct fs (and not `writeAssetToSource`)
+ *
+ * The architectural rule "all writes go through `writeAssetToSource`" applies
+ * to *assets*. Proposals are **not** assets — they live outside the asset tree
+ * (under `.akm/proposals/`, parallel to how `events.jsonl` lives outside the
+ * asset tree). Routing them through `writeAssetToSource` would force them into
+ * a `TYPE_DIRS` slot, would commit them to git, and would leak unaccepted
+ * drafts through the normal indexer. None of that is what we want for queue
+ * state. The {@link promoteProposal} step is the bridge: it routes the
+ * accepted payload through `writeAssetToSource` so the actual asset write
+ * still funnels through the single dispatch point in
+ * `src/core/write-source.ts`.
+ *
+ * Direct `fs` IO here is deliberate and the only place in the v1 codebase
+ * that bypasses `writeAssetToSource` for "stash-adjacent" durable state. See
+ * CLAUDE.md ("Writes" section) for the contract.
+ */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { makeAssetRef, parseAssetRef } from "./asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { NotFoundError, UsageError } from "./errors";
+import { parseFrontmatter } from "./frontmatter";
+import { lintLessonContent } from "./lesson-lint";
+import { resolveWriteTarget, writeAssetToSource } from "./write-source";
+// ── Path helpers ────────────────────────────────────────────────────────────
+/**
+ * Resolve `<stashRoot>/.akm/proposals` (or its archive subdirectory). Direct
+ * fs paths because proposal storage is queue state, not asset state — see the
+ * module docblock for the architectural carve-out.
+ */
+export function getProposalsRoot(stashDir, archive = false) {
+    return archive ? path.join(stashDir, ".akm", "proposals", "archive") : path.join(stashDir, ".akm", "proposals");
+}
+function proposalDir(stashDir, id, archive) {
+    return path.join(getProposalsRoot(stashDir, archive), id);
+}
+function proposalFile(stashDir, id, archive) {
+    return path.join(proposalDir(stashDir, id, archive), "proposal.json");
+}
+function nowIso(ctx) {
+    const fn = ctx?.now ?? Date.now;
+    return new Date(fn()).toISOString();
+}
+function newId(ctx) {
+    const fn = ctx?.randomUUID ?? randomUUID;
+    return fn();
+}
+// ── Read / write primitives ─────────────────────────────────────────────────
+function readProposalFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        throw new NotFoundError(`Proposal not found at ${filePath}.`, "FILE_NOT_FOUND", `The proposal file is missing or unreadable: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new UsageError(`Proposal file at ${filePath} is not valid JSON: ${err.message}`, "INVALID_JSON_ARGUMENT", "Re-create the proposal or remove the corrupt file under .akm/proposals/<id>/.");
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new UsageError(`Proposal file at ${filePath} is not a JSON object.`, "INVALID_JSON_ARGUMENT");
+    }
+    return parsed;
+}
+function writeProposalFile(filePath, proposal) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(proposal, null, 2)}\n`, "utf8");
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Create a new pending proposal. The id is a stable random UUID, so two
+ * proposals with the same `ref` never collide on disk.
+ */
+export function createProposal(stashDir, input, ctx) {
+    // Validate the ref up front so callers get a clear error instead of a
+    // surprise during `accept`. This also normalises the ref string.
+    const parsedRef = parseAssetRef(input.ref);
+    const normalizedRef = makeAssetRef(parsedRef.type, parsedRef.name, parsedRef.origin);
+    const id = newId(ctx);
+    const created = nowIso(ctx);
+    const proposal = {
+        id,
+        ref: normalizedRef,
+        status: "pending",
+        source: input.source,
+        ...(input.sourceRun !== undefined ? { sourceRun: input.sourceRun } : {}),
+        createdAt: created,
+        updatedAt: created,
+        payload: {
+            content: input.payload.content,
+            ...(input.payload.frontmatter !== undefined ? { frontmatter: input.payload.frontmatter } : {}),
+        },
+    };
+    writeProposalFile(proposalFile(stashDir, id, false), proposal);
+    return proposal;
+}
+/**
+ * List every proposal under the stash. By default returns pending proposals
+ * from the live queue; pass `{ includeArchive: true }` to include rejected /
+ * accepted entries that have been moved aside.
+ */
+export function listProposals(stashDir, options = {}) {
+    const out = [];
+    const roots = [{ dir: getProposalsRoot(stashDir, false), archive: false }];
+    if (options.includeArchive) {
+        roots.push({ dir: getProposalsRoot(stashDir, true), archive: true });
+    }
+    for (const { dir } of roots) {
+        if (!fs.existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            // Skip the archive subdirectory when iterating the live queue.
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === "archive")
+                continue;
+            const filePath = path.join(dir, entry.name, "proposal.json");
+            if (!fs.existsSync(filePath))
+                continue;
+            try {
+                out.push(readProposalFile(filePath));
+            }
+            catch {
+                // Surface invalid proposal files via a synthetic stub so callers can
+                // see something in `akm proposal list` rather than the file
+                // disappearing silently.
+                out.push({
+                    id: entry.name,
+                    ref: "unknown:unknown",
+                    status: "pending",
+                    source: "invalid",
+                    createdAt: "",
+                    updatedAt: "",
+                    payload: { content: "" },
+                    review: {
+                        outcome: "rejected",
+                        reason: "Invalid proposal file (could not be parsed).",
+                        decidedAt: "",
+                    },
+                });
+            }
+        }
+    }
+    return out
+        .filter((p) => (options.status ? p.status === options.status : true))
+        .filter((p) => (options.ref ? p.ref === options.ref : true))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+/**
+ * Look up a proposal by id. Searches the live queue first, then the archive.
+ * Throws `NotFoundError` when no match exists.
+ */
+export function getProposal(stashDir, id) {
+    const livePath = proposalFile(stashDir, id, false);
+    if (fs.existsSync(livePath))
+        return readProposalFile(livePath);
+    const archivedPath = proposalFile(stashDir, id, true);
+    if (fs.existsSync(archivedPath))
+        return readProposalFile(archivedPath);
+    throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+}
+/**
+ * Whether a proposal currently lives in the archive (used by callers that
+ * need to know whether to look in the archive root for files / paths).
+ */
+export function isProposalArchived(stashDir, id) {
+    return !fs.existsSync(proposalFile(stashDir, id, false)) && fs.existsSync(proposalFile(stashDir, id, true));
+}
+/**
+ * Move a proposal directory into the archive subtree and update its status.
+ * Used by both accept (status `accepted`) and reject (status `rejected`)
+ * paths so the live queue only contains pending entries.
+ */
+export function archiveProposal(stashDir, id, status, reason, ctx) {
+    const sourceDir = proposalDir(stashDir, id, false);
+    if (!fs.existsSync(sourceDir)) {
+        // If it's already archived, just update the metadata in place.
+        const archived = proposalFile(stashDir, id, true);
+        if (fs.existsSync(archived)) {
+            const existing = readProposalFile(archived);
+            const updated = {
+                ...existing,
+                status,
+                updatedAt: nowIso(ctx),
+                review: {
+                    outcome: status,
+                    ...(reason !== undefined ? { reason } : {}),
+                    decidedAt: nowIso(ctx),
+                },
+            };
+            writeProposalFile(archived, updated);
+            return updated;
+        }
+        throw new NotFoundError(`Proposal "${id}" not found.`, "FILE_NOT_FOUND");
+    }
+    const targetDir = proposalDir(stashDir, id, true);
+    fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+    fs.renameSync(sourceDir, targetDir);
+    const updated = {
+        ...readProposalFile(proposalFile(stashDir, id, true)),
+        status,
+        updatedAt: nowIso(ctx),
+        review: {
+            outcome: status,
+            ...(reason !== undefined ? { reason } : {}),
+            decidedAt: nowIso(ctx),
+        },
+    };
+    writeProposalFile(proposalFile(stashDir, id, true), updated);
+    return updated;
+}
+/**
+ * Validate a proposal payload before promotion. Generic by default — any
+ * proposal must parse cleanly and carry a non-empty body. Lessons get the
+ * extra per-type lint from {@link lintLessonContent} so the contract documented
+ * in v1 spec §13 is enforced at promotion time. Other asset types can hook
+ * here in the future without changing call sites.
+ */
+export function validateProposal(proposal) {
+    const findings = [];
+    if (!proposal.payload || typeof proposal.payload.content !== "string" || proposal.payload.content.trim() === "") {
+        findings.push({ kind: "empty-content", message: `Proposal ${proposal.id} has empty content.` });
+    }
+    let ref;
+    try {
+        ref = parseAssetRef(proposal.ref);
+    }
+    catch (err) {
+        findings.push({
+            kind: "invalid-ref",
+            message: `Proposal ${proposal.id} has invalid ref "${proposal.ref}": ${err.message}`,
+        });
+        return { ok: false, findings };
+    }
+    // Generic frontmatter parse check for markdown-y types. If the content
+    // *looks* like it has frontmatter (`---\n…\n---`) we ensure it parses.
+    if (proposal.payload.content.startsWith("---")) {
+        try {
+            parseFrontmatter(proposal.payload.content);
+        }
+        catch (err) {
+            findings.push({
+                kind: "invalid-frontmatter",
+                message: `Proposal ${proposal.id} frontmatter could not be parsed: ${err.message}`,
+            });
+        }
+    }
+    // Type-specific validators.
+    if (ref.type === "lesson") {
+        const lessonReport = lintLessonContent(proposal.payload.content, `proposal:${proposal.id}`);
+        for (const finding of lessonReport.findings) {
+            findings.push({ kind: finding.kind, message: finding.message });
+        }
+    }
+    return { ok: findings.length === 0, findings };
+}
+/**
+ * Validate a proposal, then promote it through the canonical
+ * {@link writeAssetToSource} dispatch (the single place that branches on
+ * `source.kind`). On success the proposal directory is moved to the archive
+ * with status `accepted`. Validation failures throw a `UsageError` carrying
+ * every finding so the CLI can render a single clear error envelope.
+ */
+export async function promoteProposal(stashDir, config, id, options = {}, ctx) {
+    const proposal = getProposal(stashDir, id);
+    if (proposal.status !== "pending") {
+        throw new UsageError(`Proposal ${id} is not pending (current status: ${proposal.status}). Only pending proposals can be accepted.`, "INVALID_FLAG_VALUE");
+    }
+    const report = validateProposal(proposal);
+    if (!report.ok) {
+        const message = report.findings.map((f) => `[${f.kind}] ${f.message}`).join("\n");
+        throw new UsageError(`Proposal ${id} failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", "Fix the proposal payload (frontmatter / content) and try again, or reject the proposal with a reason.");
+    }
+    const ref = parseAssetRef(proposal.ref);
+    if (!TYPE_DIRS[ref.type]) {
+        throw new UsageError(`Proposal ${id} targets unknown asset type "${ref.type}".`, "INVALID_FLAG_VALUE");
+    }
+    const target = resolveWriteTarget(config, options.target);
+    const written = await writeAssetToSource(target.source, target.config, ref, proposal.payload.content);
+    const archived = archiveProposal(stashDir, id, "accepted", undefined, ctx);
+    return { proposal: archived, assetPath: written.path, ref: written.ref };
+}
+/**
+ * Compute a diff between a proposal payload and the existing on-disk asset.
+ * Uses {@link resolveWriteTarget} to find where the asset would land — so the
+ * diff matches exactly what `accept` will write. Falls back to "new asset"
+ * when no asset is currently materialised at the target ref.
+ */
+export function diffProposal(stashDir, config, id, options = {}) {
+    const proposal = getProposal(stashDir, id);
+    const ref = parseAssetRef(proposal.ref);
+    let targetPath;
+    let existing = null;
+    try {
+        const target = resolveWriteTarget(config, options.target);
+        targetPath = resolveAssetFilePathSafe(target.source, ref);
+        if (targetPath && fs.existsSync(targetPath)) {
+            existing = fs.readFileSync(targetPath, "utf8");
+        }
+    }
+    catch {
+        // No writable target configured — still return a "new asset" diff so
+        // callers can see the proposed payload without erroring out.
+    }
+    const proposed = proposal.payload.content;
+    if (existing === null) {
+        return {
+            existing: null,
+            proposed,
+            unified: formatNewAssetDiff(proposal.ref, proposed),
+            isNew: true,
+            ...(targetPath ? { targetPath } : {}),
+        };
+    }
+    return {
+        existing,
+        proposed,
+        unified: formatUnifiedDiff(existing, proposed, proposal.ref),
+        isNew: false,
+        ...(targetPath ? { targetPath } : {}),
+    };
+}
+function resolveAssetFilePathSafe(source, ref) {
+    const typeDir = TYPE_DIRS[ref.type];
+    if (!typeDir)
+        return undefined;
+    const typeRoot = path.join(source.path, typeDir);
+    try {
+        return resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Minimal unified-diff renderer. We deliberately avoid pulling a runtime
+ * dependency just for this — proposals diffs are usually small (a single
+ * lesson / skill file), so the LCS-free greedy renderer below is plenty for
+ * humans to review. The output mirrors `git diff --no-index` for the first
+ * `@@ … @@` hunk: enough to be familiar, not so detailed that we re-implement
+ * a full LCS table.
+ */
+export function formatUnifiedDiff(left, right, label) {
+    if (left === right)
+        return "";
+    const leftLines = left.split("\n");
+    const rightLines = right.split("\n");
+    const lines = [`--- ${label} (existing)`, `+++ ${label} (proposed)`];
+    // Pad to the longer side so alignment is one-to-one. Real diff tools use
+    // LCS to align matching runs; we don't need that fidelity for a review
+    // surface — both halves are visible regardless.
+    const max = Math.max(leftLines.length, rightLines.length);
+    lines.push(`@@ 1,${leftLines.length} 1,${rightLines.length} @@`);
+    for (let i = 0; i < max; i += 1) {
+        const l = leftLines[i];
+        const r = rightLines[i];
+        if (l === r && l !== undefined) {
+            lines.push(` ${l}`);
+            continue;
+        }
+        if (l !== undefined)
+            lines.push(`-${l}`);
+        if (r !== undefined)
+            lines.push(`+${r}`);
+    }
+    return lines.join("\n");
+}
+function formatNewAssetDiff(ref, content) {
+    const lines = [`--- /dev/null`, `+++ ${ref} (proposed, new asset)`];
+    lines.push(`@@ 0,0 1,${content.split("\n").length} @@`);
+    for (const line of content.split("\n")) {
+        lines.push(`+${line}`);
+    }
+    return lines.join("\n");
+}

package/dist/src/core/warn.js

@@ -0,0 +1,72 @@
+/**
+ * Module-level quiet/verbose flags for stderr warning gating.
+ *
+ * `quiet` is controlled by the CLI `--quiet`/`-q` flag.
+ * `verbose` is controlled by the CLI `--verbose` flag, with `AKM_VERBOSE`
+ * (env var) winning regardless: env > flag > default (false).
+ */
+let quiet = false;
+let verbose = false;
+export function setQuiet(value) {
+    quiet = value;
+}
+/**
+ * Reset the quiet flag to false.
+ * Intended for test teardown to prevent quiet state from leaking between tests.
+ */
+export function resetQuiet() {
+    quiet = false;
+}
+export function isQuiet() {
+    return quiet;
+}
+/**
+ * Set the verbose flag from a CLI flag. The `AKM_VERBOSE` env var, when set,
+ * always wins regardless of this flag (env > flag > default).
+ */
+export function setVerbose(value) {
+    verbose = value;
+}
+/**
+ * Reset the verbose flag to false. Intended for test teardown so verbose
+ * state does not leak between tests.
+ */
+export function resetVerbose() {
+    verbose = false;
+}
+/**
+ * Returns true when verbose output is requested.
+ *
+ * Precedence: `AKM_VERBOSE` env var (when truthy) > `setVerbose(true)` > false.
+ * Truthy matches `1`, `true`, `yes`, `on` (case-insensitive). The values
+ * `0`, `false`, `no`, `off` hard-disable verbose even if the flag is set,
+ * so operators can override per-invocation. Any other value (including
+ * empty string) is treated as "not set" and falls through to the flag.
+ */
+export function isVerbose() {
+    const env = process.env.AKM_VERBOSE?.trim().toLowerCase();
+    if (env === "1" || env === "true" || env === "yes" || env === "on")
+        return true;
+    if (env === "0" || env === "false" || env === "no" || env === "off")
+        return false;
+    return verbose;
+}
+/**
+ * Emit a warning to stderr unless --quiet is active.
+ * Drop-in replacement for console.warn() across the codebase.
+ */
+export function warn(...args) {
+    if (!quiet) {
+        console.warn(...args);
+    }
+}
+/**
+ * Emit a warning only when verbose output is requested. Use for noisy
+ * per-item diagnostics that should be replaced by a one-line summary at
+ * default verbosity (e.g. registry-content workflow validation errors).
+ */
+export function warnVerbose(...args) {
+    if (isVerbose()) {
+        warn(...args);
+    }
+}

package/dist/{core → src/core}/write-source.js

@@ -30,6 +30,50 @@ import { ConfigError, UsageError } from "./errors";
  * {@link assertWritableAllowedForKind}.
  */
 const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
+/**
+ * Maximum length of a sanitized git commit message. Git itself imposes no
+ * fixed limit, but message strings come from refs and `--message` flags that
+ * can be supplied by users or upstream config. A 4096-char clamp keeps audit
+ * trails readable and prevents pathological payloads from bloating the log
+ * stream a downstream consumer parses.
+ */
+const COMMIT_MESSAGE_MAX_LENGTH = 4096;
+/**
+ * Sanitize a string before passing it as `git commit -m <message>`.
+ *
+ * Defenses, in order:
+ *   1. Strip NUL bytes (`\0`) — git rejects them anyway, but we never want
+ *      them in argv.
+ *   2. Replace any CR/LF (`\r`, `\n`) and other ASCII control chars with a
+ *      single space. This collapses newline-injection attempts that would
+ *      otherwise turn a single-line commit subject into a forged trailer
+ *      block.
+ *   3. Collapse runs of whitespace into a single space and trim.
+ *   4. Clamp to {@link COMMIT_MESSAGE_MAX_LENGTH} characters.
+ *
+ * If the result is empty after sanitization the caller should substitute a
+ * default — this helper returns `""` rather than throwing because not every
+ * callsite has a sensible "invalid input" exit code, and "empty" is a
+ * recoverable signal.
+ */
+export function sanitizeCommitMessage(input) {
+    if (typeof input !== "string")
+        return "";
+    // 1. Strip NULs outright.
+    let out = input.replace(/\0/g, "");
+    // 2. Replace CR/LF + other C0 control characters (0x00-0x1F, 0x7F) with a
+    //    space. Tab (0x09) is included intentionally — commit subjects should
+    //    be a single visual line.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitization
+    out = out.replace(/[\x00-\x1F\x7F]/g, " ");
+    // 3. Collapse whitespace runs and trim.
+    out = out.replace(/\s+/g, " ").trim();
+    // 4. Clamp length.
+    if (out.length > COMMIT_MESSAGE_MAX_LENGTH) {
+        out = out.slice(0, COMMIT_MESSAGE_MAX_LENGTH).trimEnd();
+    }
+    return out;
+}
 // ── Public helpers ──────────────────────────────────────────────────────────
 /**
  * Resolve the effective `writable` flag for a source config entry, applying
@@ -135,8 +179,18 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
     // 2. config.defaultWriteTarget.
     if (akmConfig.defaultWriteTarget) {
         const match = configuredSources.find((s) => s.name === akmConfig.defaultWriteTarget);
-        if (match)
+        if (match) {
+            // BUG-H3: mirror the --target writability gate so a misconfigured
+            // defaultWriteTarget pointed at a non-writable kind (website/npm) or
+            // an explicit `writable: false` filesystem entry fails fast with a
+            // ConfigError, rather than surfacing as a generic UsageError after
+            // path-building has already begun.
+            const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
+            if (!effectiveWritable) {
+                throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${akmConfig.defaultWriteTarget}" source in your config, or change \`defaultWriteTarget\` to a writable source.`);
+            }
             return adaptConfiguredSource(match);
+        }
         // Fall through if the named target no longer exists — surface a clear error.
         throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm list` to see configured sources.");
     }
@@ -200,9 +254,14 @@ function runGitCommit(repoDir, filePath, message) {
     if (addResult.status !== 0) {
         throw new Error(`git add failed: ${addResult.stderr?.trim() || "unknown error"}`);
     }
+    // Defense in depth: sanitize the commit subject one more time at the spawn
+    // boundary. Callers should already pass sanitized strings (via
+    // formatRefForMessage / saveGitStash), but this guards against future
+    // refactors that forget. Empty after sanitize falls back to a safe stub.
+    const safeMessage = sanitizeCommitMessage(message) || "akm update";
     // Provide a fallback identity so fresh CI/test environments without
     // user.name/user.email configured can always commit.
-    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", message], { encoding: "utf8" });
+    const commitResult = spawnSync("git", ["-C", repoDir, "-c", "user.name=akm", "-c", "user.email=akm@local", "commit", "-m", safeMessage], { encoding: "utf8" });
     if (commitResult.status !== 0) {
         // `nothing to commit` is a no-op success — the file may have matched the
         // existing tree exactly. Surface other errors verbatim.
@@ -221,7 +280,16 @@ function runGitPush(repoDir) {
     }
 }
 function formatRefForMessage(ref) {
-    return ref.origin ? `${ref.origin}//${ref.type}:${ref.name}` : `${ref.type}:${ref.name}`;
+    // Sanitize each component independently. `ref.origin` originates from user
+    // config and could contain CR/LF that would otherwise be smuggled into the
+    // commit subject and forge trailers downstream. `ref.type` and `ref.name`
+    // are also sanitized defensively — the asset-spec validator should already
+    // reject control bytes there, but a single sanitizer at the boundary keeps
+    // the contract explicit and centralized.
+    const origin = ref.origin ? sanitizeCommitMessage(ref.origin) : "";
+    const type = sanitizeCommitMessage(ref.type);
+    const name = sanitizeCommitMessage(ref.name);
+    return origin ? `${origin}//${type}:${name}` : `${type}:${name}`;
 }
 /**
  * Derive a {@link WriteTargetSource} + persisted {@link SourceConfigEntry}
@@ -241,8 +309,15 @@ function adaptConfiguredSource(runtime) {
         throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
     }
     // Map the runtime kind to the write helper's `kind` discriminator. Only
-    // filesystem and git produce writable sources at v1.
-    const kind = runtime.type === "filesystem" || runtime.type === "git" ? runtime.type : runtime.type;
+    // filesystem and git produce writable sources at v1; any other kind
+    // reaching this point is a config-loader bug (assertWritableAllowedForKind
+    // should have rejected it). Throw a ConfigError rather than silently
+    // forwarding an unsupported kind.
+    if (runtime.type !== "filesystem" && runtime.type !== "git") {
+        throw new ConfigError(`write-source: source "${runtime.name}" has unsupported kind "${runtime.type}" for writes. ` +
+            "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
+    }
+    const kind = runtime.type;
     const config = {
         type: runtime.type,
         name: runtime.name,