akm-cli 0.9.16-alpha.1 → 0.9.16

package/dist/tasks/scheduler-sync-preview.js

@@ -25,7 +25,14 @@ export function renderSchedulerPlanPreview(backend, operations, unchanged = [],
             adds.push({ id: operation.binding.id, kind: "install" });
         }
         else {
-            updates.push({ id: operation.binding.id, kind: "update" });
+            updates.push({
+                id: operation.binding.id,
+                kind: "update",
+                ...(operation.expected.fingerprint !== undefined
+                    ? { installedFingerprint: operation.expected.fingerprint }
+                    : {}),
+                ...(operation.resultFingerprint !== undefined ? { expectedFingerprint: operation.resultFingerprint } : {}),
+            });
         }
     }
     return Object.freeze({

package/dist/tasks/scheduler-sync.js

@@ -51,6 +51,9 @@ export async function prepareSchedulerSyncSourceSet(input) {
         failures: compiled.failures,
     });
 }
+function schedulerActivationKey(kind, ref) {
+    return `${kind}\0${ref}`;
+}
 export function finalizeSchedulerSyncPlan(input, prepared) {
     const inspection = inspectionForPlan(input);
     const coherentInput = {
@@ -60,10 +63,8 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
     };
     const desired = prepared.desired;
     assertUniqueDesiredIds(desired);
-    assertCoherentInspection(inspection, input.inspection !== undefined);
-    assertUniqueInstalledIds(coherentInput.installed);
+    assertSchedulerBackendInspection(inspection, desired, input.inspection !== undefined);
     assertNoForeignIds(desired, coherentInput);
-    assertSchedulerNativeArtifactOwnership(desired, inspection.artifacts);
     const scopedInstalled = coherentInput.installed.filter((entry) => belongsToBundle(entry, coherentInput));
     const present = new Map(scopedInstalled.map((entry) => [entry.id, entry]));
     const installed = [];
@@ -123,6 +124,12 @@ export function finalizeSchedulerSyncPlan(input, prepared) {
         failures: prepared.failures,
     });
 }
+/** Validate one coherent whole-backend read before deriving any mutation plan. */
+export function assertSchedulerBackendInspection(inspection, desired = [], requireCompleteFingerprint = true) {
+    assertCoherentInspection(inspection, requireCompleteFingerprint);
+    assertUniqueInstalledIds(inspection.installed);
+    assertSchedulerNativeArtifactOwnership(desired, inspection.artifacts);
+}
 /**
  * Build the exact removal operation for one installed binding: same
  * exact-native-fingerprint / ordinal-attribution safety checks
@@ -299,6 +306,10 @@ async function compileTaskSources(input, collector, out, failures) {
         const conceptId = relative.slice(0, -4);
         const id = input.adapterId === "akm-task" ? conceptId : path.basename(sourcePath, ".yml");
         const qualifiedRefForFailure = makeBundleRef(input.bundleName, conceptId);
+        if (input.enabledActivations &&
+            !input.enabledActivations.has(schedulerActivationKey("task", qualifiedRefForFailure))) {
+            continue;
+        }
         try {
             const physicalIdentity = guarded.physicalIdentity;
             const priorOwner = physicalOwners.get(physicalIdentity);
@@ -308,14 +319,11 @@ async function compileTaskSources(input, collector, out, failures) {
             physicalOwners.set(physicalIdentity, sourcePath);
             // Project BEFORE prepareTaskV3Execution so projectability is checked —
             // but build the scheduler bindings from the ORIGINAL task source v4
-            // document, not the projection, which deliberately drops per-entry
-            // `enabled` and `schedule[i].inputs` (D2-N5, project-v4.ts) —
+            // document, not the projection, which deliberately drops
+            // `schedule[i].inputs` (project-v4.ts) —
             // schedule-supplied inputs are delivered through the scheduler
             // binding's own compiled invocation tail (P2b Lane B, spec §4.4,
             // B-N3), not through the prepare-seam projection. A task source v4
-            // document has no document-level `akm.enabled`, so `enabled: true` is
-            // passed at the document level and every entry's own `enabled`
-            // (always present, defaulted at parse time) decides.
             const parsed = parseTaskSource({
                 yaml: guarded.content,
                 filePath: sourcePath,
@@ -349,11 +357,9 @@ async function compileTaskSources(input, collector, out, failures) {
                 id,
                 qualifiedRef,
                 ...(input.bundleTarget ? { bundleTarget: input.bundleTarget } : {}),
-                enabled: true,
                 schedules: parsed.v4.schedule.map((schedule) => ({
                     cron: schedule.cron,
                     ordinal: schedule.ordinal,
-                    enabled: schedule.enabled,
                     source: `${relSource}:${schedule.source}`,
                     // P2b Lane B (spec §4.4, B-N3): delivered through the compiled
                     // binding's own invocation tail below — the F-B2 flip that closes
@@ -423,6 +429,9 @@ async function compileWorkflowSources(input, collector, out, evidence, failures)
     for (const [canonicalName, sources] of lookups) {
         const failurePath = sources[0]?.sourcePath ?? canonicalName;
         const failureRef = makeBundleRef(input.bundleName, input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName);
+        if (input.enabledActivations && !input.enabledActivations.has(schedulerActivationKey("workflow", failureRef))) {
+            continue;
+        }
         try {
             if (sources.length > 1) {
                 throw new WorkflowSourceCollisionError(input.adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName, sources.map((source) => source.relativePath));

package/dist/tasks/source/parse-task-source.js

@@ -2,138 +2,35 @@
 // 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/.
 /**
- * The task source version router (spec docs/plans/specs/p4-deletions-closeout.md
- * §3.2.2).
+ * Current task-source router.
  *
- * Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
- * `root.version`, and either dispatches into `parseTaskSourceV4Document` or
- * routes through the in-memory read shim below — no second parse of the v4
- * grammar itself, no re-serialization back to disk, no synthetic document
- * (the P1b §4.3 invariant this phase carries forward: the shim adds a pure
- * bytes-in/bytes-out detour, never a disk write).
- *
- * The terminal routing table:
- *
- *   | root `version`        | outcome                                                        |
- *   |------------------------|-----------------------------------------------------------------|
- *   | `4`                    | `parseTaskSourceV4Document` — the new grammar (row B-13)        |
- *   | `2` or `3`             | in-memory read shim (below): the SAME pure planners `akm migrate apply` uses (`./task-to-v3.ts`, `./task-to-v4.ts`) convert the bytes already in hand to v4 in memory; the result is parsed and returned with a one-line stderr deprecation warning. If the deterministic conversion itself fails (an unmigratable shape — the file needs a human decision, not a re-run), falls back to `TASK_SCHEMA_VERSION_UNSUPPORTED` naming the specific blocked reason (issue #869) — the shim removes friction for the deterministic case, it never hides a real problem |
- *   | any other number       | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (B-14/B-15) |
- *   | absent / not a number  | `parseTaskSourceV4Document` — its own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
- *
- * A missing or non-numeric `version:` is a MALFORMED v4 document, not a
- * legacy one — it routes into the v4 parser so the field error names the
- * one grammar `src` still accepts, rather than a generic "unsupported"
- * message that would send the user to the migrator for a document that was
- * never task v2 or v3 in the first place.
- *
- * task v2 and task v3 sources are no longer read as their own standing
- * grammar anywhere else in `src` — the only readers of that grammar are the
- * pure, byte-producing planners (`./task-to-v3.ts`, `./task-to-v4.ts`, and
- * the frozen v3 reader `./task-source-v3-frozen.ts`), reached either through
- * this shim (bytes in, bytes out, never touches disk) or through
- * `akm migrate apply` / `akm-migrate` (`scripts/akm-migrate`, which
- * additionally rewrites the file on disk once the user asks for that).
- * Policy: a deterministic byte transform is the tool's job, not the user's —
- * upgrading past a schema bump must not silently break a scheduled task, so
- * v2/v3 files keep reading successfully at the cost of a one-line
- * deprecation warning, and `akm migrate apply` remains available to rewrite
- * the file and silence it. The front end's own pre-version failures (source
- * not a string, source too large, YAML parse/warning/expansion) render with
- * the label `task source` (row B-17, closing the "task v3 source" label
- * wart P2a's §3.4 recorded).
+ * Runtime code accepts only the current v4 grammar. Historical v2/v3 files
+ * and the former source-owned `schedule[].enabled` field are handled only by
+ * the explicit `akm migrate` executable; execution never translates legacy
+ * bytes in memory.
  */
 import { UsageError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
 import { readBoundedTaskSourceYaml } from "./bounded-document.js";
-import { parseTaskSourceV4, parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION, } from "./task-source-v4.js";
-import { planTaskToV3File } from "./task-to-v3.js";
-import { planTaskToV4File } from "./task-to-v4.js";
-/** Read the root `version` field without over-accepting non-number values (e.g. the string `"4"`). */
+import { parseTaskSourceV4Document, TASK_SOURCE_V4_VERSION } from "./task-source-v4.js";
 export function peekTaskSourceVersion(root) {
     if (root === null || typeof root !== "object" || Array.isArray(root))
         return undefined;
     const value = root.version;
     return typeof value === "number" ? value : undefined;
 }
-const TASK_MIGRATE_HINT = "Run `akm migrate apply --dry-run` to preview the task-v3 to task-source-v4 conversion, then run `akm migrate apply`.";
-/**
- * Thrown only when the deterministic conversion itself could not produce a
- * task source v4 document — a case where a person must decide the intended
- * behavior (e.g. an ambiguous shell command), not one the migrator can just
- * be re-run to fix. `reason`/`detail` are the SAME blocked outcome
- * `akm migrate status`/`apply` reports for this file, so the message names
- * the actual decision instead of pointing at a command that will report the
- * identical block.
- */
-function unmigratableVersionError(filePath, version, reason, detail) {
-    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version} and needs a human decision before it can run — the deterministic migrator cannot convert it automatically (${reason}${detail ? `: ${detail}` : ""}).`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Review the file and resolve the ambiguity by hand, then it will convert normally; `akm migrate status` reports the same reason.");
-}
 function unsupportedVersionError(filePath, version) {
-    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", TASK_MIGRATE_HINT);
-}
-/**
- * Plan the SAME bytes already in hand through the pure v3->v4 (and, for v2,
- * chained v2->v3->v4) migration planner(s) — never touches disk, never
- * writes the file, never re-reads it from disk. Returns the produced v4
- * YAML text, or the blocked reason/detail when the deterministic conversion
- * cannot proceed (an unmigratable v2/v3 shape) — the caller falls back to
- * the same hard error this gate threw before the shim existed, now naming
- * that reason.
- */
-function planInMemoryV4Bytes(version, yaml, filePath, workspaceRoot) {
-    const bytes = Buffer.from(yaml, "utf8");
-    // `writable`/`onDiskWritable` gate the DISK apply path's "don't touch a
-    // read-only file" check inside the planners; this shim never writes
-    // anything to disk, so that check does not apply here and must not block
-    // an otherwise-legal read of a task file that happens to be read-only.
-    const baseInput = {
-        filePath,
-        bytes,
-        mode: 0o644,
-        writable: true,
-        onDiskWritable: true,
-        ...(workspaceRoot ? { containmentRoot: workspaceRoot } : {}),
-    };
-    let v3Bytes;
-    if (version === 3) {
-        v3Bytes = bytes;
-    }
-    else {
-        const v3Outcome = planTaskToV3File(baseInput);
-        if (v3Outcome.status !== "changed")
-            return { reason: v3Outcome.reason, detail: v3Outcome.detail };
-        v3Bytes = v3Outcome.after;
-    }
-    const v4Outcome = planTaskToV4File({ ...baseInput, bytes: v3Bytes });
-    if (v4Outcome.status !== "changed")
-        return { reason: v4Outcome.reason, detail: v4Outcome.detail };
-    return v4Outcome.after.toString("utf8");
+    return new UsageError(`TASK_SCHEMA_VERSION_UNSUPPORTED: Task at ${filePath} uses task schema version ${version}, which this release does not accept.`, "TASK_SCHEMA_VERSION_UNSUPPORTED", "Run `akm migrate apply --dry-run`, review the plan, then run `akm migrate apply`.");
 }
-/** Parse task source YAML, routing per the terminal table above. */
 export function parseTaskSource(input) {
     const { root, lineAt } = readBoundedTaskSourceYaml(input, { sourceLabel: "task source" });
     const version = peekTaskSourceVersion(root);
     if (version !== undefined && version !== TASK_SOURCE_V4_VERSION) {
-        if (version === 2 || version === 3) {
-            const shimmed = planInMemoryV4Bytes(version, input.yaml, input.filePath, input.workspaceRoot);
-            if (typeof shimmed === "string") {
-                const v4 = parseTaskSourceV4({
-                    yaml: shimmed,
-                    filePath: input.filePath,
-                    ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
-                });
-                warn(`akm: task ${input.filePath} uses schema v${version} — auto-read as v4; run \`akm migrate apply\` to rewrite it and silence this`);
-                return Object.freeze({ version: 4, v4 });
-            }
-            throw unmigratableVersionError(input.filePath, version, shimmed.reason, shimmed.detail);
-        }
         throw unsupportedVersionError(input.filePath, version);
     }
-    const documentOptions = {
+    const v4 = parseTaskSourceV4Document(root, {
         filePath: input.filePath,
         ...(input.workspaceRoot ? { workspaceRoot: input.workspaceRoot } : {}),
         lineAt,
-    };
-    return Object.freeze({ version: 4, v4: parseTaskSourceV4Document(root, documentOptions) });
+    });
+    return Object.freeze({ version: 4, v4 });
 }

package/dist/tasks/source/project-v4.js

@@ -4,8 +4,8 @@
 /**
  * Map every top-level task source v4 execution control and D2-N7 survivor
  * into v3's `akm.*` shape, one field at a time (never a whole-object copy,
- * so a field task source v4 does not represent — `inputs`, per-binding
- * `enabled` — can never leak in by accident). Returns `undefined` when
+ * so a field task source v4 does not represent — such as `inputs` — can
+ * never leak in by accident). Returns `undefined` when
  * nothing maps, matching v3's own
  * convention of omitting the `akm` key entirely rather than emitting an
  * always-present empty object (`source-v3.ts:789`).

package/dist/tasks/source/task-source-v4.js

@@ -75,7 +75,7 @@ export const TASK_SOURCE_V4_TOP_LEVEL_KEYS = [
     "maxRetries",
 ];
 /** Closes one `schedule:` list entry (D2-N5). */
-export const TASK_SOURCE_V4_SCHEDULE_KEYS = ["cron", "enabled", "inputs"];
+export const TASK_SOURCE_V4_SCHEDULE_KEYS = ["cron", "inputs"];
 /**
  * The closed key set for one `inputs.<name>` declaration root (D2-N3). The
  * JSON-Schema-subset portion is DERIVED from
@@ -479,12 +479,6 @@ function parseScheduleEntry(entryRaw, index, contract, ctx) {
         sourceError(ctx, [...entryPath, "cron"], "is required.");
     const cron = stringField(entry.cron, ctx, [...entryPath, "cron"], { nonempty: true });
     noGithubExpression(cron, ctx, [...entryPath, "cron"]);
-    let enabled = true;
-    if (own(entry, "enabled")) {
-        if (typeof entry.enabled !== "boolean")
-            sourceError(ctx, [...entryPath, "enabled"], "must be a boolean.");
-        enabled = entry.enabled;
-    }
     let inputsLiteral = Object.freeze({});
     if (own(entry, "inputs")) {
         const inputsValue = asRecord(presentJsonValue(entry.inputs, ctx, [...entryPath, "inputs"]), ctx, [
@@ -516,7 +510,7 @@ function parseScheduleEntry(entryRaw, index, contract, ctx) {
         inputsLiteral = Object.freeze({ ...inputsValue });
     }
     checkScheduleEntryRunnable(inputsLiteral, contract, ctx, entryPath);
-    return Object.freeze({ cron, enabled, inputs: inputsLiteral, source: `schedule[${index}].cron`, ordinal: index });
+    return Object.freeze({ cron, inputs: inputsLiteral, source: `schedule[${index}].cron`, ordinal: index });
 }
 function parseSchedule(input, contract, ctx) {
     if (!own(input, "schedule"))
@@ -530,12 +524,10 @@ function parseSchedule(input, contract, ctx) {
         // runnability contract, at the `schedule` key's own field path (it has
         // neither an ordinal nor an `inputs:` sub-path to point at).
         checkScheduleEntryRunnable(Object.freeze({}), contract, ctx, ["schedule"]);
-        return Object.freeze([
-            Object.freeze({ cron, enabled: true, inputs: Object.freeze({}), source: "schedule", ordinal: 0 }),
-        ]);
+        return Object.freeze([Object.freeze({ cron, inputs: Object.freeze({}), source: "schedule", ordinal: 0 })]);
     }
     if (!Array.isArray(raw) || raw.length === 0) {
-        sourceError(ctx, ["schedule"], "must be a non-empty string or a non-empty list of {cron, enabled?, inputs?} records.");
+        sourceError(ctx, ["schedule"], "must be a non-empty string or a non-empty list of {cron, inputs?} records.");
     }
     if (raw.length > TASK_V3_MAX_SCHEDULES) {
         sourceError(ctx, ["schedule"], `accepts at most ${TASK_V3_MAX_SCHEDULES} entries.`);

package/dist/tasks/source/task-to-v3.js

@@ -11,7 +11,6 @@ import { WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_TIMEOUT_MS } from "../../wo
 import { validateTaskId } from "../task-id.js";
 import { assertBoundedTaskYamlDocument, TASK_V3_MAX_REDACT_NAMES } from "./bounded-document.js";
 import { classifyTaskV3Uses, parseTaskV3Yaml } from "./task-source-v3-frozen.js";
-import { parseTaskSourceV4 } from "./task-source-v4.js";
 const V2_KEYS = new Set([
     "version",
     "name",
@@ -442,17 +441,10 @@ export function planTaskToV3File(input) {
         }
     }
     if (data.version === 4) {
-        try {
-            parseTaskSourceV4({
-                yaml: source,
-                filePath: input.filePath,
-                ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
-            });
-            return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
-        }
-        catch (cause) {
-            return blocked(input, "invalid-v4-task", cause instanceof Error ? cause.message : String(cause));
-        }
+        // Generation 1 owns v2 only. Do not validate v4 here: generation 2 must
+        // be allowed to recognize and remove the retired schedule[].enabled field
+        // before the current runtime parser sees those bytes.
+        return Object.freeze({ status: "skipped", ...base(input), reason: "already-v4" });
     }
     if (data.version !== 2) {
         return blocked(input, "unsupported-task-version", `expected version 2, 3, or 4, got ${String(data.version)}`);

package/dist/tasks/source/task-to-v4.js

@@ -17,7 +17,7 @@
  */
 import crypto from "node:crypto";
 import path from "node:path";
-import { LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
+import { isMap, isSeq, LineCounter, parseDocument, stringify as stringifyYaml } from "yaml";
 import { assertBoundedTaskYamlDocument } from "./bounded-document.js";
 import { classifyTaskV3Uses } from "./task-source-v3-frozen.js";
 import { parseTaskSourceV4 } from "./task-source-v4.js";
@@ -244,7 +244,6 @@ function planV3DataToV4(input, data) {
     if (!input.writable || input.onDiskWritable === false) {
         return blocked(input, "read-only-source", !input.writable ? "the owning source is not writable" : "the source file or publication directory is read-only");
     }
-    const enabledFalse = akm !== undefined && akm.enabled === false;
     let scheduleField;
     // Several independent translation facts can need reporting on the SAME
     // file (a manual-only trigger AND a dropped output schema, say), so
@@ -253,7 +252,7 @@ function planV3DataToV4(input, data) {
     const notices = [];
     if (hasAkmSchedule) {
         const cron = akm.schedule;
-        scheduleField = enabledFalse ? [{ cron, enabled: false }] : cron;
+        scheduleField = cron;
     }
     else {
         const rawSchedule = onRecord !== undefined && Object.hasOwn(onRecord, "schedule") ? onRecord.schedule : undefined;
@@ -276,10 +275,7 @@ function planV3DataToV4(input, data) {
                 }
                 crons.push(record.cron);
             }
-            scheduleField = crons.map((cron) => (enabledFalse ? { cron, enabled: false } : { cron }));
-        }
-        else if (enabledFalse) {
-            return blocked(input, "enabled-false-has-no-schedule-entry", "akm.enabled: false has no schedule entry to attach to (the only trigger is on.workflow_dispatch); task source v4 has no top-level enabled flag.");
+            scheduleField = crons.map((cron) => ({ cron }));
         }
         else {
             notices.push("schedule: is absent from the migrated document — the source's only trigger was on.workflow_dispatch (manual dispatch); task source v4 tasks are always runnable manually via `akm task run`, so no schedule: entry was emitted.");
@@ -368,6 +364,43 @@ export function planTaskToV4File(input) {
         return blocked(input, "invalid-task-yaml", causeMessage(cause));
     }
     if (data.version === 4) {
+        const document = parseDocument(source, { uniqueKeys: true });
+        const schedule = document.get("schedule", true);
+        let removed = false;
+        if (isSeq(schedule)) {
+            for (const entry of schedule.items) {
+                if (!isMap(entry) || !entry.has("enabled"))
+                    continue;
+                entry.delete("enabled");
+                removed = true;
+            }
+        }
+        if (removed) {
+            if (!input.writable || input.onDiskWritable === false) {
+                return blocked(input, "read-only-source", !input.writable
+                    ? "the owning source is not writable"
+                    : "the source file or publication directory is read-only");
+            }
+            const after = Buffer.from(document.toString(), "utf8");
+            try {
+                parseTaskSourceV4({
+                    yaml: after.toString("utf8"),
+                    filePath: input.filePath,
+                    ...(input.containmentRoot ? { workspaceRoot: input.containmentRoot } : {}),
+                });
+            }
+            catch (cause) {
+                return blocked(input, "generated-v4-validation-failed", causeMessage(cause));
+            }
+            return Object.freeze({
+                status: "changed",
+                ...base(input),
+                reason: "source-enablement-removed",
+                after,
+                afterHash: hash(after),
+                notice: "Removed source-owned schedule enablement; scheduler activation is now host-local config.",
+            });
+        }
         try {
             parseTaskSourceV4({
                 yaml: source,

package/docs/migration/README.md

@@ -4,6 +4,7 @@ Upgrade guides and per-release migration notes.
 
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, 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.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
 - [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

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

@@ -85,33 +85,27 @@ scheduled or opportunistic run step aside instead of contending with a rebuild
 already in progress; the shipped `index-refresh` scheduled task already passes
 it.
 
-`akm index` now packs embedding requests against the provider's own probed
-context window and slot count (llama.cpp's `GET /props`, Ollama's
-`POST /api/show`) instead of a flat configured token budget: an 8192-token
-llama.cpp embedder, for example, is packed against its real 8192 rather
-than a generic guess. An endpoint that answers neither probe (an
-OpenAI-compatible server, a gateway) gets a conservative built-in default,
-with the same run-scoped recovery as before — on the first request rejected
-for exceeding the endpoint's context window, `akm index` lowers its
-effective budget for the rest of that run (reported with one line) rather
-than continuing to hit the same wall on every following batch; a window akm
-actually probed from the endpoint is treated as authoritative and is never
-second-guessed this way. `embedding.maxTokens` and `embedding.batchSize`
-(the previous per-request token-budget and document-count config keys) are
-retired — see [Retired Configuration](../../reference/configuration.md#retired-configuration)
-— since the provider's own limits are now the source of truth.
+`embedding.maxTokens`'s default (the per-request token budget) is now 6000,
+down from 8000: a field report on an 8192-token llama.cpp embedder showed the
+4-chars-per-token estimator undercounts dense technical text by 7-55%, so the
+old default regularly overshot the endpoint's real context window. If you
+already set `embedding.maxTokens` explicitly, this default change does not
+affect you — your configured value is unchanged. `akm index` also now
+recovers automatically within a run: on the first request rejected for
+exceeding the endpoint's context window, it lowers its effective budget for
+the rest of that run (reported with one line) rather than continuing to hit
+the same wall on every following batch.
 
 `embedding.concurrency` (positive integer, 1-16) overrides the number of
 embedding requests kept in flight at once, which otherwise defaults to 1 for
-a loopback endpoint and 2 for a remote one, or the provider's own probed
-slot count (llama.cpp's `total_slots`) when the probe reports one. Set an
-explicit override only for an endpoint that genuinely serves parallel
-requests — a local model server started with a multi-slot flag (llama.cpp's
-`--parallel N`, vLLM) — since the default already protects an ordinary
-single-slot server from reload-thrash. Embedding throughput is still tuned
-first by request SIZE — the probed token budget and document-count cap
-above; the concurrency override is a second lever for a server that can
-actually use it.
+a loopback endpoint and 2 for a remote one. Set it only for an endpoint that
+genuinely serves parallel requests — a local model server started with a
+multi-slot flag (llama.cpp's `--parallel N`, vLLM) — since the default
+already protects an ordinary single-slot server from reload-thrash.
+Embedding throughput is still tuned first by `embedding.batchSize`
+(documents per request) and `embedding.maxTokens` (token
+budget per request); the concurrency override is a second lever for a
+server that can actually use it.
 
 `embedding.timeoutMs` bounds each embedding request (default 120s, up from a
 prior fixed 30s that cut off a slow local model server mid-response). It is
@@ -148,16 +142,24 @@ this is a drop-in fix for anyone running `akm` under a scheduler,
 supervisor, or hook that can time out or kill the launcher process
 directly.
 
-A large document is no longer truncated for embedding — `akm index` splits
-it into multiple content-addressed units instead (one vector per section,
-sized against the embedding provider's own probed context window), so a
-long document's later sections are searchable too, not silently dropped
-past a head cap. `embedding.maxInputTokens`, the earlier per-document
-truncation cap this superseded within the same 0.9.15 cycle, is retired —
-see [Retired Configuration](../../reference/configuration.md#retired-configuration).
-`embedding.contextLength` is retired too: Ollama's `num_ctx` is now sent
-automatically from the same probe, or set explicitly via
-`embedding.ollamaOptions.num_ctx`.
+`embedding.maxInputTokens` (default 512) now caps how much of a single
+document's text is sent to the embedding provider, truncating to the head
+instead of ever failing a whole batch over one oversized document.
+
+- An existing install's already-stored vectors are untouched and stay
+  valid — this only changes what happens for entries embedded *after*
+  upgrading.
+- New embeddings (any entry indexed for the first time, or re-indexed after
+  a content change) go through the new 512-token cap by default. If you
+  were relying on documents longer than ~2000 characters being embedded in
+  full, set `embedding.maxInputTokens` higher in `config.json`.
+- `akm index --reembed` re-embeds every entry under the new cap — run it if
+  you want your entire existing index rebuilt against the new default (or a
+  custom `embedding.maxInputTokens` you've set).
+- `embedding.contextLength` is Ollama's `num_ctx` only now; it no longer
+  also sets the per-request token budget (`embedding.maxTokens`). If you had
+  set `contextLength` specifically to control request batching (not your
+  Ollama server's context window), set `embedding.maxTokens` instead.
 
 **Which token knob fixed the original 8k-context overflow.** A 0.9.15-beta
 field report described documents estimated under the request budget that