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

package/dist/core/config/schema/improve.js

@@ -0,0 +1,94 @@
+// 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/.
+/**
+ * Top-level `improve` config section (utility decay, salience, collapse
+ * detector, strategies). Extracted verbatim from the former `config-schema.ts`
+ * monolith — no behavior change.
+ */
+import { z } from "zod";
+import { ImproveProfileConfigSchema } from "./improve-processes.js";
+import { engineName, nonNegativeNumber } from "./primitives.js";
+// ── Improve top-level (utility decay, event retention) ─────────────────────
+const ImproveUtilityDecaySchema = z
+    .object({
+    halfLifeDays: z.number().finite().min(0.1).optional(),
+    feedbackStabilityBoost: z.number().finite().min(1).optional(),
+})
+    .passthrough();
+const ImproveSalienceSchema = z
+    .object({
+    /**
+     * WS-2 Part-V gate: enable the outcome-weight term in the salience projection.
+     * Default TRUE/absent (DEFAULT ON since the G2 saturation cap landed — see
+     * salience.ts): uses the WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60) so the
+     * prediction-error outcome signal shapes rankScore (the R1 loop-closure).
+     * Set to `false` to opt out and restore the WS-1 parity weights
+     * (w_e=0.30, w_r=0.70, w_o=0); the `outcome` sub-score is still computed
+     * and stored for observability in that mode.
+     */
+    outcomeWeightEnabled: z.boolean().optional(),
+    /**
+     * Minimum encoding salience score [0, 1] for a zero-feedback asset to be
+     * admitted to the high-salience improve lane (#608).
+     * Default 0.75. Set to 1.0 to disable the lane entirely.
+     */
+    salienceThreshold: z.number().min(0).max(1).optional(),
+    /**
+     * Per-run additive replay budget (#610). Up to this many top-salience refs are
+     * revisited even with no reactive signal and regardless of cooldown. Additive
+     * on top of --limit. Default 0 = no replay.
+     */
+    replayBudget: z.number().int().min(0).optional(),
+})
+    .passthrough();
+// R5 — longitudinal collapse detector (observe-only; deterministic,
+// fail-open, runs only on cycles where consolidate did work).
+// Default ON; opt out via `improve.collapseDetector.enabled: false`.
+// See docs/architecture/specs/improve-collapse-churn-detector-design.md.
+// The design's CHURN alert class was removed (never fired in production —
+// its accepted-change-volume input was always a hardcoded 0), so this schema
+// no longer carries `churnMinAcceptedActions`.
+const ImproveCollapseDetectorSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    // Canary set size minted on first run (owner-approved 30–50 range; default 40).
+    canaryCount: z.number().int().min(3).max(200).optional(),
+    // Top-K cutoff for canary recall/nDCG (default 10).
+    k: z.number().int().min(1).max(100).optional(),
+    // Trend window in qualifying cycles (default 5).
+    windowCycles: z.number().int().min(2).max(50).optional(),
+    // Absolute mean-recall drop vs window median that fires collapse (default 0.15).
+    recallDropThreshold: z.number().min(0).max(1).optional(),
+    // distinct-content-ratio decline over the window that fires collapse (default 0.05).
+    entropyDropThreshold: z.number().min(0).max(1).optional(),
+    // improve_cycle_metrics retention (default 365 days, owner-approved).
+    retentionDays: z.number().int().min(1).optional(),
+})
+    .passthrough();
+// #733 — orphan-GC pass (Workstream C, lean by design: one config gate).
+// The pass ALWAYS runs and ALWAYS reports counts (via the `asset_state_gc`
+// event); this gate controls ONLY whether it actually deletes rows whose
+// `missing_since` has been past the grace window (`STATE_GC_GRACE_MS`, 7
+// days — a named constant, not configurable) for longer than that window.
+const ImproveStateGcSchema = z
+    .object({
+    /**
+     * Actually DELETE `asset_salience` / `asset_outcome` rows once they have
+     * been unresolvable for longer than the grace window. Default false for
+     * 0.9.0: live data (the event's `pending` counts) proves the report
+     * clean before deletion is turned on.
+     */
+    collect: z.boolean().optional(),
+})
+    .passthrough();
+export const ImproveConfigSchema = z
+    .object({
+    strategies: z.record(engineName, ImproveProfileConfigSchema).optional(),
+    utilityDecay: ImproveUtilityDecaySchema.optional(),
+    eventRetentionDays: nonNegativeNumber.optional(),
+    salience: ImproveSalienceSchema.optional(),
+    collapseDetector: ImproveCollapseDetectorSchema.optional(),
+    stateGc: ImproveStateGcSchema.optional(),
+})
+    .passthrough();

package/dist/core/config/schema/index-config.js

@@ -0,0 +1,176 @@
+// 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/.
+/**
+ * `index` config: reserved feature sections + arbitrary per-pass entries.
+ * Extracted verbatim from the former `config-schema.ts` monolith — no behavior
+ * change.
+ */
+import { z } from "zod";
+import { engineName, LlmInvocationOverridesSchema, nonEmptyString, positiveInt } from "./primitives.js";
+// ── Index / per-pass ────────────────────────────────────────────────────────
+//
+// WI-9.6c: `graphExtractionIncludeTypes` is no longer validated against a
+// hardcoded allowlist (the prior GRAPH_EXTRACTION_INCLUDE_TYPES_ALLOWED,
+// which included a stale `wiki` entry and was already missing `fact` from the
+// runtime consumer's own list — the schema-level allowlist had drifted from
+// reality). Accept-any until Chunk 2 sources a real type list from adapter
+// metadata: the field is now an array of arbitrary non-empty strings.
+// Runtime consumers already handle unknown/unsupported type strings
+// gracefully — src/indexer/graph/graph-extraction.ts's
+// `SUPPORTED_GRAPH_EXTRACTION_INCLUDE_TYPES` set (and `collectEligibleFiles`)
+// silently skips any type it doesn't recognize (no placement entry ⇒ zero
+// eligible files for that type; no crash). This is a permissive-direction
+// behavior change: configs with a previously-rejected type string now parse.
+const INDEX_PASS_RETIRED_KEYS = new Set([
+    "endpoint",
+    "provider",
+    "apiKey",
+    "baseUrl",
+    "temperature",
+    "maxTokens",
+    "capabilities",
+]);
+const INDEX_PASS_KNOWN_KEYS = new Set([
+    "engine",
+    "model",
+    "timeoutMs",
+    "enabled",
+    "llm",
+    "graphExtractionBatchSize",
+    "graphExtractionIncludeTypes",
+    "lazyGraphExtraction",
+]);
+/**
+ * Per-pass `index.<pass>` entry. Uses preprocess + manual validation so we can
+ * emit targeted error messages ("Retired or misplaced engine setting",
+ * "Unknown key `index.<pass>.<key>`")
+ * instead of Zod's generic `Unrecognized key` / `Expected boolean, received
+ * string` strings — keeps `akm` startup errors actionable.
+ */
+export const IndexPassConfigSchema = z.preprocess((raw, ctx) => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return raw; // let z.object below produce the type error
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (INDEX_PASS_RETIRED_KEYS.has(key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Retired or misplaced engine setting: \`${[...(ctx.path ?? []), key].join(".")}\` is not allowed. ` +
+                    "Select a named engine and use typed invocation fields instead.",
+            });
+            return raw;
+        }
+        if (!INDEX_PASS_KNOWN_KEYS.has(key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Unknown key \`${[...(ctx.path ?? []), key].join(".")}\`. Per-pass entries support ` +
+                    "`engine`, `model`, `timeoutMs`, `enabled`, `llm`, `graphExtractionBatchSize`, " +
+                    "`graphExtractionIncludeTypes`, and `lazyGraphExtraction`.",
+            });
+            return raw;
+        }
+    }
+    return raw;
+}, z
+    .object({
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    enabled: z.boolean().optional(),
+    llm: LlmInvocationOverridesSchema.optional(),
+    graphExtractionBatchSize: positiveInt.optional(),
+    // Accept-any until Chunk 2 (WI-9.6c) — no longer enum-restricted.
+    graphExtractionIncludeTypes: z.array(z.string().min(1)).nonempty().optional(),
+    lazyGraphExtraction: z.boolean().optional(),
+})
+    .passthrough());
+const MetadataEnhanceSchema = z.object({ enabled: z.boolean().optional() }).passthrough();
+const IndexDefaultsSchema = z
+    .object({
+    engine: engineName.optional(),
+    model: nonEmptyString.optional(),
+    timeoutMs: z.union([positiveInt, z.null()]).optional(),
+    llm: LlmInvocationOverridesSchema.optional(),
+})
+    .passthrough();
+/**
+ * Index config is a union of reserved feature sections and per-pass entries.
+ * Passthrough so per-pass entries (keyed by arbitrary pass names like `graph`,
+ * `enrichment`) can live next to the reserved keys.
+ *
+ * Reserved scalar key `indexBodyOpening` (stash-conventions SPEC-8, default
+ * false): when true, the metadata pass captures the first prose paragraph of
+ * each markdown asset body into `entry.bodyOpening`, which folds into the
+ * lowest-weight `content` FTS column and the embedding text. It is a boolean,
+ * not a per-pass object — the preprocess below exempts it from the
+ * object-shape check so it never routes into the per-pass catchall.
+ *
+ * The outer preprocess emits the legacy parser's actionable error messages
+ * for the two most common type-shape mistakes:
+ *   - An array at the `index` block.
+ *   - A non-object at `index.<passName>`.
+ * Inner field validation (graphExtractionIncludeTypes shape, invocation
+ * overrides, provider-key rejection) is delegated to {@link IndexPassConfigSchema}.
+ * `graphExtractionIncludeTypes` accepts arbitrary non-empty strings
+ * (WI-9.6c — no hardcoded type allowlist; accept-any until Chunk 2).
+ */
+const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
+    if (raw === undefined || raw === null)
+        return raw;
+    if (Array.isArray(raw)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Invalid `index` config: expected an object keyed by pass name (e.g. `{ "enrichment": { "enabled": false } }`).',
+        });
+        return raw;
+    }
+    if (typeof raw !== "object")
+        return raw;
+    for (const [passName, value] of Object.entries(raw)) {
+        if (passName === "stalenessDetection") {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Invalid `index.stalenessDetection`: the removed pass is not supported.",
+            });
+            return raw;
+        }
+        if (passName === "indexBodyOpening") {
+            if (typeof value !== "boolean") {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Invalid `index.indexBodyOpening`: expected a boolean (true to index the first body paragraph " +
+                        `of markdown assets into search). Got ${Array.isArray(value) ? "array" : typeof value}.`,
+                });
+                return raw;
+            }
+            continue;
+        }
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Invalid \`index.${passName}\` config: expected an object like \`{ "enabled": false }\`.`,
+            });
+            return raw;
+        }
+    }
+    return raw;
+}, z
+    .object({
+    defaults: IndexDefaultsSchema.optional(),
+    metadataEnhance: MetadataEnhanceSchema.optional(),
+    indexBodyOpening: z
+        .boolean()
+        .optional()
+        .describe("Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the " +
+        "lowest-weight `content` search column and the embedding text (default false). Secret/env files " +
+        "and session-kind memories are never captured. Toggling the flag changes indexed text: run " +
+        "`akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint " +
+        "collapse-detector canary baselines via `bun scripts/refresh-canary-set.ts --refresh`."),
+})
+    .catchall(IndexPassConfigSchema));
+// The runtime catchall correctly validates arbitrary pass objects, but its
+// inferred string index signature also covers reserved scalar keys. Publish a
+// precise output type while retaining the stricter runtime and JSON schemas.
+export const IndexConfigSchema = IndexConfigRuntimeSchema;

package/dist/core/config/schema/output.js

@@ -0,0 +1,18 @@
+// 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/.
+/**
+ * `output` config section. Extracted verbatim from the former `config-schema.ts`
+ * monolith — no behavior change.
+ */
+import { z } from "zod";
+// ── Output ──────────────────────────────────────────────────────────────────
+export const OutputConfigSchema = z
+    .object({
+    // D7 — every `--format` value is a valid default, not just the three that
+    // predated universal md/html rendering. Kept in step with OUTPUT_FORMATS
+    // (`src/output/context.ts`).
+    format: z.enum(["json", "yaml", "text", "jsonl", "md", "html"]).optional(),
+    detail: z.enum(["brief", "normal", "full"]).optional(),
+})
+    .passthrough();

package/dist/core/config/schema/primitives.js

@@ -0,0 +1,94 @@
+// 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 atomic Zod schemas and small helpers used across the config-schema
+ * modules. Extracted verbatim from the former `config-schema.ts` monolith — no
+ * behavior change (see `./index` re-export barrel at `../config-schema.ts`).
+ */
+import { z } from "zod";
+import { validateExtraParams } from "../../extra-params.js";
+import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
+/** Persisted config schema version. Package prerelease/patch versions do not change this value. */
+export const CURRENT_CONFIG_VERSION = "0.9.0";
+// ── Reusable atomic schemas ─────────────────────────────────────────────────
+/** Positive integer (used for tokens, timeouts, batch sizes). */
+export const positiveInt = z.number().int().positive();
+/** Non-negative finite number (used for scores, weights, days). */
+export const nonNegativeNumber = z.number().finite().min(0);
+/** Non-empty string (rejects "" and whitespace-only). */
+export const nonEmptyString = z
+    .string()
+    .min(1)
+    .refine((v) => v.trim().length > 0, { message: "expected a non-empty string" });
+/** HTTP(S) URL string. */
+export const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.startsWith("https://"), {
+    message: "endpoint must start with http:// or https://",
+});
+const ENGINE_NAME_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
+export const ENV_REFERENCE_PATTERN = /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+export const engineName = z
+    .string()
+    .max(63)
+    .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
+export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must use http:// or https://" });
+        }
+        if (url.username || url.password || url.search || url.hash || !url.pathname.endsWith("/chat/completions")) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "endpoint must be a credential-free OpenAI chat-completions URL without query or fragment",
+            });
+        }
+    }
+    catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "endpoint must be a complete URL" });
+    }
+});
+export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx) => {
+    for (const issue of validateExtraParams(value)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: issue.path, message: issue.message });
+    }
+});
+function normalizeAliasKeys(raw, ctx) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return raw;
+    const normalized = {};
+    const originalByKey = new Map();
+    for (const [key, value] of Object.entries(raw)) {
+        const lower = key.toLowerCase();
+        const previous = originalByKey.get(lower);
+        if (previous !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [key],
+                message: `alias collides case-insensitively with ${previous}`,
+            });
+            continue;
+        }
+        originalByKey.set(lower, key);
+        normalized[lower] = value;
+    }
+    return normalized;
+}
+export const ModelAliasMapSchema = z.preprocess((raw, ctx) => normalizeAliasKeys(raw, ctx), z.record(z.string().min(1), z.string().min(1)));
+export const GlobalModelAliasesSchema = z.preprocess((raw, ctx) => normalizeAliasKeys(raw, ctx), z.record(z.string().min(1), z.record(z.string().min(1), z.string().min(1))));
+// ── Shared connection/invocation building blocks ────────────────────────────
+export const LlmCapabilitiesSchema = z
+    .object({
+    structuredOutput: z.boolean().optional(),
+})
+    .passthrough();
+export const LlmInvocationOverridesSchema = z
+    .object({
+    temperature: z.number().finite().optional(),
+    maxTokens: positiveInt.optional(),
+    supportsJsonSchema: z.boolean().optional(),
+    extraParams: ExtraParamsSchema.optional(),
+    contextLength: positiveInt.optional(),
+    enableThinking: z.boolean().optional(),
+})
+    .passthrough();

package/dist/core/config/schema/search.js

@@ -0,0 +1,30 @@
+// 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/.
+/**
+ * `search` config section (graph-boost tuning). Extracted verbatim from the
+ * former `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+import { nonEmptyString, nonNegativeNumber, positiveInt } from "./primitives.js";
+// ── Search ──────────────────────────────────────────────────────────────────
+const SearchGraphBoostSchema = z
+    .object({
+    directBoostPerEntity: nonNegativeNumber.optional(),
+    directBoostCap: nonNegativeNumber.optional(),
+    hopBoostPerEntity: nonNegativeNumber.optional(),
+    hopBoostCap: nonNegativeNumber.optional(),
+    /** Hard-capped at 3; values > 3 hard-error so users see the typo. */
+    maxHops: positiveInt.max(3).optional(),
+    confidenceMode: z.enum(["off", "blend", "multiply"]).default("blend").optional(),
+    /** Range [0, 1]; values > 1 hard-error (no silent clamp). */
+    confidenceWeight: z.number().finite().min(0).max(1).default(0.2).optional(),
+})
+    .passthrough();
+export const SearchConfigSchema = z
+    .object({
+    minScore: nonNegativeNumber.optional(),
+    defaultExcludeTypes: z.array(nonEmptyString).optional(),
+    graphBoost: SearchGraphBoostSchema.optional(),
+})
+    .passthrough();

package/dist/core/config/schema/setup.js

@@ -0,0 +1,18 @@
+// 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/.
+/**
+ * Setup-derived recommendations (`setup`). Extracted verbatim from the former
+ * `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+// ── Setup-derived recommendations ──────────────────────────────────────────
+//
+// R-063 #11: this object previously carried a `taskSchedules` sub-key (cron
+// hints nominally derived by `akm setup --reset-recommended`), but nothing in
+// the tasks subsystem or setup flow ever read or wrote it — confirmed dead at
+// HEAD (deriveRecommendedConfig's return type never included it either; see
+// tests/integration/setup/detect-environment.test.ts's regression guard).
+// Removed. The `setup` namespace itself is kept (passthrough) for future
+// setup-derived config.
+export const SetupConfigSchema = z.object({}).passthrough();

package/dist/core/config/schema/sources-bundles.js

@@ -0,0 +1,169 @@
+// 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/.
+/**
+ * Sources / registries / installed entries + the 0.9.0 `bundles` shape.
+ * Extracted verbatim from the former `config-schema.ts` monolith — no behavior
+ * change.
+ */
+import { z } from "zod";
+import { isBundleSlug } from "../../asset/asset-ref.js";
+import { httpUrl, nonEmptyString, positiveInt } from "./primitives.js";
+// ── Sources / registries / installed ────────────────────────────────────────
+const SourceConfigEntryOptionsSchema = z.record(z.unknown());
+export const SourceConfigEntrySchema = z
+    .object({
+    type: nonEmptyString,
+    path: z.string().min(1).optional(),
+    url: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    enabled: z.boolean().optional(),
+    writable: z.boolean().optional(),
+    primary: z.boolean().optional(),
+    options: SourceConfigEntryOptionsSchema.optional(),
+})
+    .passthrough()
+    .superRefine((entry, ctx) => {
+    if (entry.options && "pushOnCommit" in entry.options) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["options", "pushOnCommit"],
+            message: "options.pushOnCommit is not supported",
+        });
+    }
+    if (!["filesystem", "git", "website", "npm"].includes(entry.type)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["type"],
+            message: `unsupported source type "${entry.type}"; expected filesystem, git, website, or npm`,
+        });
+    }
+    if (entry.writable === true && (entry.type === "website" || entry.type === "npm")) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `writable: true is only supported on filesystem and git sources (got "${entry.type}"` +
+                (entry.name ? ` on source "${entry.name}"` : "") +
+                ").",
+        });
+    }
+});
+export const RegistryConfigEntrySchema = z
+    .object({
+    url: httpUrl,
+    name: z.string().min(1).optional(),
+    enabled: z.boolean().optional(),
+    provider: z.string().min(1).optional(),
+    options: z.record(z.unknown()).optional(),
+})
+    .passthrough();
+// ── Bundles (0.9.0 config-shape cutover, spec §10.1 / D-R5) ─────────────────
+//
+// `bundles` + `defaultBundle` are the 0.9.0 desired-configuration shape that
+// supersedes the pre-cutover `stashDir` / `sources[]` / `installed[]` trio. Each
+// bundle entry carries ONE source descriptor (`path` | `git` | `website` | `npm`
+// — mirroring today's source types), an optional `writable`, an optional
+// `registryId` locator (the original registry install id, preserved verbatim so
+// a non-slug-legal id like `github:owner/repo` is not lost when its slug-legal
+// bundle KEY is derived), and an optional single-entry `components` map (spec
+// §10.1; the transitional one-component-per-bundle coupling — NOT multi-component
+// machinery). The map KEY is the workspace bundle slug (spec §11.1 charset: no
+// `/`, `:`, `.`, `#`, whitespace), validated with {@link isBundleSlug}.
+//
+// The config migrator ({@link migrateConfigSourcesToBundles}) emits these keyed
+// by exactly what `deriveInstallations` derives today (D-R5). `bindings` (spec
+// §10.1) is Tier B and is NEVER accepted here (the top-level superRefine rejects
+// it) — it is not part of the 0.9.0 config-shape cutover.
+/** Website source descriptor for a bundle entry (spec §10.1). */
+const BundleWebsiteDescriptorSchema = z
+    .object({
+    url: httpUrl,
+    refresh: z.string().min(1).optional(),
+    maxPages: positiveInt.optional(),
+    maxDepth: positiveInt.optional(),
+})
+    .passthrough();
+/** One component of a bundle (spec §10.1). Single-entry, transitional. */
+const BundleComponentConfigSchema = z
+    .object({
+    root: z.string().min(1).optional(),
+    adapter: nonEmptyString.optional(),
+    writable: z.boolean().optional(),
+})
+    .passthrough();
+export const BundleConfigEntrySchema = z
+    .object({
+    // Exactly one source descriptor (enforced in superRefine below):
+    path: z.string().min(1).optional(),
+    git: z.string().min(1).optional(),
+    website: BundleWebsiteDescriptorSchema.optional(),
+    npm: z.string().min(1).optional(),
+    writable: z.boolean().optional(),
+    // Opt a bundle out of indexing, search, refresh, and write targeting
+    // without deleting it. Carried over from the pre-cutover `sources[].enabled`
+    // flag, which the runtime still honors on the derived source entry
+    // (`write-source.ts`, `search-source.ts`); without it here, migrating a
+    // disabled source would silently reactivate it.
+    enabled: z.boolean().optional(),
+    // The original registry install id when the bundle KEY was slug-derived from
+    // it (e.g. registryId `github:owner/repo` → key `repo`). Preserved so the
+    // source locator survives the config-shape migration (D-R5). Absent when the
+    // bundle key already equals the source's stable id.
+    registryId: z.string().min(1).optional(),
+    components: z.record(z.string().min(1), BundleComponentConfigSchema).optional(),
+})
+    .passthrough()
+    .superRefine((entry, ctx) => {
+    const options = entry.options;
+    if (options && typeof options === "object" && "pushOnCommit" in options) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["options", "pushOnCommit"],
+            message: "options.pushOnCommit is not supported",
+        });
+    }
+    const descriptors = ["path", "git", "website", "npm"].filter((k) => entry[k] !== undefined);
+    if (descriptors.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "a bundle entry must carry exactly one source descriptor (path, git, website, or npm)",
+        });
+    }
+    else if (descriptors.length > 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `a bundle entry must carry exactly one source descriptor; got ${descriptors.join(", ")}`,
+        });
+    }
+    if (entry.writable === true && (entry.website !== undefined || entry.npm !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["writable"],
+            message: "writable: true is only supported on path and git bundle sources",
+        });
+    }
+    const componentEntries = entry.components ? Object.entries(entry.components) : [];
+    if (entry.components !== undefined && componentEntries.length !== 1) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["components"],
+            message: "a bundle components map must contain exactly one component",
+        });
+    }
+    const componentEntry = componentEntries[0];
+    if (componentEntry?.[1].writable === true && (entry.website !== undefined || entry.npm !== undefined)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["components", componentEntry[0], "writable"],
+            message: "writable: true is only supported on path and git bundle sources",
+        });
+    }
+});
+/**
+ * `bundles` map. Keys are workspace bundle slugs (spec §11.1 / D-R5 charset).
+ * The key charset is validated with {@link isBundleSlug} so a key can never carry
+ * `/`, `:`, `.`, `#`, or whitespace (which would break the `bundle//conceptId`
+ * ref grammar).
+ */
+export const BundlesConfigSchema = z.record(z.string().min(1).refine(isBundleSlug, {
+    message: "bundle key must be a legal slug (no '/', ':', '.', '#', or whitespace)",
+}), BundleConfigEntrySchema);

package/dist/core/config/schema/workflow.js

@@ -0,0 +1,29 @@
+// 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` engine settings. Extracted verbatim from the former
+ * `config-schema.ts` monolith — no behavior change.
+ */
+import { z } from "zod";
+import { positiveInt } from "./primitives.js";
+// ── Workflow engine ─────────────────────────────────────────────────────────
+/**
+ * Workflow-engine settings (`workflow`).
+ *
+ * `maxConcurrency` is the engine-wide ceiling on concurrent units for native
+ * fan-out (`akm workflow run`). It replaces the hard-coded `min(16, cores−2)`
+ * cap (which matched Claude Code) with a user knob:
+ *   - UNSET  → the CPU-derived default `min(16, max(1, cores−2))`.
+ *   - SET    → the explicit positive integer, CLAMPED at read time to
+ *     `[1, WORKFLOW_MAX_CONCURRENCY_CEILING]` (64). Values above the ceiling
+ *     are clamped, not rejected, so a config shared across machines with wildly
+ *     different core counts never hard-fails validation.
+ * The R3 brief/report driver surface does NOT consult this — drivers own their
+ * own parallelism (the engine only caps native dispatch).
+ */
+export const WorkflowConfigSchema = z
+    .object({
+    maxConcurrency: positiveInt.optional(),
+})
+    .passthrough();