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

package/dist/core/env-secret-ref.js

@@ -11,46 +11,106 @@
  * helpers only resolve refs to absolute paths and guard against directory
  * traversal.
  */
+import fs from "node:fs";
 import path from "node:path";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
-import { parseAssetRef } from "./asset/asset-ref.js";
-import { resolveAssetPathFromName } from "./asset/asset-spec.js";
+import { assetPathForName } from "./asset/asset-placement.js";
+import { displayRef, isFullRefInput, parseRefInput } from "./asset/resolve-ref.js";
 import { isWithin } from "./common.js";
 import { loadConfig } from "./config/config.js";
 import { NotFoundError, UsageError } from "./errors.js";
+import { resolveMutationTarget } from "./mutation-target.js";
+import { formatRefForMessage, withWriteTargetMutation } from "./write-source.js";
+/**
+ * The `vault` asset type was removed in 0.9.0. The env/secret input path no
+ * longer routes through the legacy stored-ref parser (which carries the removal
+ * signpost), so a `vault:`/`vault/` leading token would otherwise be silently
+ * qualified into an `env/vault:…` not-found. Detect it here and re-emit the
+ * migration signpost so 0.8→0.9 muscle memory still gets pointed at env/secret.
+ */
+function assertNotRemovedVaultRef(ref) {
+    const boundary = ref.indexOf("//");
+    const bare = boundary >= 0 ? ref.slice(boundary + 2) : ref;
+    if (/^vault[:/]/.test(bare.trim())) {
+        throw new UsageError("The `vault` asset type was removed in 0.9.0 — use `env/` (whole .env config) or `secrets/` (a single value).", "INVALID_FLAG_VALUE");
+    }
+}
+/**
+ * Q-08 ruling: the pre-0.9.0 `type:name` ref grammar taught `env:<name>` /
+ * `secret:<name>` (help text and docs also implied `environment:`/`secrets:`
+ * variants) as the way to address a single env/secret. That grammar is GONE —
+ * NO alias, no re-acceptance (same rule as the retired `vault:` prefix above).
+ * Left unchecked, a colon-prefixed ref does not error here at all: it falls
+ * through to the "bare name" convenience below and gets silently qualified
+ * into a literal `env/env:name` (or `secrets/secret:name`) file that can never
+ * exist — a confusing not-found that hides the real mistake instead of naming
+ * it. Reject it here, loudly, before that happens.
+ */
+function assertNotColonRef(ref, aliases, replacement) {
+    const boundary = ref.indexOf("//");
+    const bare = (boundary >= 0 ? ref.slice(boundary + 2) : ref).trim();
+    const colon = bare.indexOf(":");
+    if (colon <= 0)
+        return;
+    const head = bare.slice(0, colon).toLowerCase();
+    if (!aliases.includes(head))
+        return;
+    const name = bare.slice(colon + 1);
+    throw new UsageError(`The \`${head}:\` ref spelling was removed in 0.9.0 — use the slash form instead: \`${replacement}${name}\`.`, "INVALID_FLAG_VALUE");
+}
 export function parseEnvRef(ref) {
-    return parseAssetRef(ref.includes(":") ? ref : `env:${ref}`);
+    // Accept a bare env name (`prod`, `sub/prod`) or the new-grammar
+    // `[bundle//]env/name` conceptId. A bare name's leading segment maps to no
+    // asset type, so it is qualified with the `env/` conceptId prefix; anything
+    // already a full new-grammar ref is parsed as-is.
+    assertNotRemovedVaultRef(ref);
+    assertNotColonRef(ref, ["env", "environment"], "env/");
+    return parseRefInput(isFullRefInput(ref) ? ref : `env/${ref}`);
 }
-export function findEnvSource(origin) {
+export function findEnvSource(origin, type, name) {
     const sources = resolveSourceEntries(undefined, loadConfig());
     if (sources.length === 0) {
-        throw new UsageError("No stashes configured. Run `akm init` to create your working stash.");
+        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
+    }
+    const candidates = origin ? resolveSourcesForOrigin(origin, sources) : sources;
+    const typeDir = type === "env" ? "env" : "secrets";
+    const member = candidates.find((source) => fs.existsSync(assetPathForName(type, path.join(source.path, typeDir), name)));
+    if (member)
+        return member;
+    if (!origin) {
+        const fallback = candidates[0];
+        if (fallback)
+            return fallback;
+        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
     }
-    if (!origin || origin === "local")
-        return sources[0];
-    const named = sources.find((source) => source.registryId === origin);
+    const named = candidates[0];
     if (!named) {
         throw new NotFoundError(`Source not found for origin: ${origin}`);
     }
     return named;
 }
 export function makeEnvRef(name, source) {
-    return source?.registryId ? `${source.registryId}//env:${name}` : `env:${name}`;
+    // F4b output-spelling flip: `env/name` in the primary stash, `bundle//env/name`
+    // for a slug-clean named source.
+    return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source));
 }
 /**
- * Resolve an env ref to an absolute `.env` path. Accepts `env:` and
- * `environment:` (alias) refs as well as bare names. The path is returned even
- * when the file does not yet exist (so `create` writes under `env/`).
+ * Resolve an env ref to an absolute `.env` path. Accepts the `env/<name>`
+ * conceptId (or a bare name, auto-qualified into it) — the retired
+ * `env:`/`environment:` colon spelling is rejected loudly (Q-08), never
+ * silently resolved. The path is returned even when the file does not yet
+ * exist (so `create` writes under `env/`).
  */
 export function resolveEnvPath(ref) {
     const parsed = parseEnvRef(ref);
     if (parsed.type !== "env") {
-        throw new UsageError(`Expected an env ref (env:<name>); got "${ref}".`);
+        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
     }
-    const source = findEnvSource(parsed.origin);
+    const source = findEnvSource(parsed.origin, "env", parsed.name);
     const envRoot = path.join(source.path, "env");
-    const envPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+    const envPath = assetPathForName("env", envRoot, parsed.name);
     // Defense-in-depth: ensure the resolved path stays inside the env directory.
     // validateName already rejects traversal patterns like "../../foo", but an
     // absolute-path override or symlink-based attack could still escape without
@@ -61,10 +121,23 @@ export function resolveEnvPath(ref) {
     return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
 }
 export function parseSecretRef(ref) {
-    return parseAssetRef(ref.includes(":") ? ref : `secret:${ref}`);
+    // Same bare-name-vs-full-ref rule as parseEnvRef; a bare name is qualified
+    // with the `secrets/` conceptId prefix (secret's stash subdir).
+    assertNotRemovedVaultRef(ref);
+    assertNotColonRef(ref, ["secret", "secrets"], "secrets/");
+    return parseRefInput(isFullRefInput(ref) ? ref : `secrets/${ref}`);
 }
 export function makeSecretRef(name, source) {
-    return source?.registryId ? `${source.registryId}//secret:${name}` : `secret:${name}`;
+    // F4b output-spelling flip: `secrets/name` in the primary stash,
+    // `bundle//secrets/name` for a slug-clean named source.
+    return displayRef({ type: "secret", name, bundleId: source?.registryId }, displayDefaultBundle(source));
+}
+function displayDefaultBundle(source) {
+    const config = loadConfig();
+    if (config.defaultBundle || !source)
+        return config.defaultBundle;
+    const primary = resolveSourceEntries(undefined, config)[0];
+    return primary && path.resolve(primary.path) === path.resolve(source.path) ? source.registryId : undefined;
 }
 export function resolveSecretPath(ref, 
 // Create-only (`secret set`): enforce a flat ref name and apply `--path` as
@@ -72,19 +145,81 @@ export function resolveSecretPath(ref,
 create) {
     const parsed = parseSecretRef(ref);
     if (parsed.type !== "secret") {
-        throw new UsageError(`Expected a secret ref (secret:<name>); got "${ref}".`);
+        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
     }
     if (create) {
         assertFlatAssetName(parsed.name);
         parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
     }
     // Source resolution is identical for every asset type; reuse the env helper.
-    const source = findEnvSource(parsed.origin);
+    const source = findEnvSource(parsed.origin, "secret", parsed.name);
     const typeRoot = path.join(source.path, "secrets");
-    const absPath = resolveAssetPathFromName("secret", typeRoot, parsed.name);
+    const absPath = assetPathForName("secret", typeRoot, parsed.name);
     // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
     if (!isWithin(absPath, typeRoot)) {
         throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
     }
     return { name: parsed.name, absPath, source };
 }
+/**
+ * Resolve the destination for an env mutation. Mirrors {@link resolveEnvPath}
+ * but selects the source via {@link resolveWriteTarget} (writability-checked)
+ * instead of the read-side {@link findEnvSource}. `create` enforces a flat ref
+ * name and applies `--path` as the subdirectory (matching `env create`).
+ */
+export function resolveEnvWriteTarget(ref, writeTarget, create) {
+    const parsed = parseEnvRef(ref);
+    if (parsed.type !== "env") {
+        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
+    }
+    if (create) {
+        assertFlatAssetName(parsed.name);
+        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
+    }
+    const resolved = resolveMutationTarget(loadConfig(), parsed, writeTarget, { allowedAdapters: ["akm", "dotenv"] });
+    const { target } = resolved;
+    const envRoot = path.join(target.source.path, "env");
+    const absPath = assetPathForName("env", envRoot, parsed.name);
+    if (!isWithin(absPath, envRoot)) {
+        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+    }
+    return { name: parsed.name, absPath, target, parsedRef: resolved.ref, ref: resolved.displayRef };
+}
+/**
+ * Resolve the destination for a secret mutation. Mirrors
+ * {@link resolveSecretPath} but selects the source via
+ * {@link resolveWriteTarget} (writability-checked) instead of the read-side
+ * {@link findEnvSource}.
+ */
+export function resolveSecretWriteTarget(ref, writeTarget, create) {
+    const parsed = parseSecretRef(ref);
+    if (parsed.type !== "secret") {
+        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
+    }
+    if (create) {
+        assertFlatAssetName(parsed.name);
+        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
+    }
+    const resolved = resolveMutationTarget(loadConfig(), parsed, writeTarget, { allowedAdapters: ["akm", "dotenv"] });
+    const { target } = resolved;
+    const typeRoot = path.join(target.source.path, "secrets");
+    const absPath = assetPathForName("secret", typeRoot, parsed.name);
+    if (!isWithin(absPath, typeRoot)) {
+        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
+    }
+    return { name: parsed.name, absPath, target, ref: resolved.displayRef };
+}
+/**
+ * Land an env/secret mutation on its write target's git boundary. Mirrors the
+ * tasks/knowledge write path: record each mutated path, then fire the single
+ * batch-at-boundary commit. Both steps are no-ops for filesystem targets (the
+ * primary stash included) and for `env/` paths a stash `.gitignore` excludes, so
+ * callers invoke it unconditionally after every create/ingest/set/remove.
+ */
+export function withEnvSecretWrite(target, ref, op, paths, mutate) {
+    return withWriteTargetMutation(target, paths, {
+        ignored: "local-only",
+        purpose: `${ref.type}-${op.toLowerCase()}`,
+        message: `${op} ${formatRefForMessage({ type: ref.type, name: ref.name, origin: target.source.name })}`,
+    }, mutate);
+}

package/dist/core/errors.js

@@ -6,32 +6,34 @@
  * imperative. Returning undefined means "no canned hint".
  */
 const CONFIG_HINTS = {
-    STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your stash, or set stashDir in your config.",
-    STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
-    STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
+    STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your bundle, or configure a defaultBundle path.",
+    STASH_DIR_NOT_A_DIRECTORY: "The configured default bundle path exists but isn't a directory. Update it to point at a folder.",
+    STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update the default bundle path.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
-    LLM_NOT_CONFIGURED: 'Run `akm setup` or `akm config set profiles.llm.default \'{"endpoint":"...","model":"..."}\' to configure an LLM profile.',
-    TEST_ISOLATION_MISSING: "Under bun test, when AKM_STASH_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
-    SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_STASH_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
-    UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The stash directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
-    UNKNOWN_IMPROVE_PROFILE: "Pass one of the listed profile names to `--profile`, or define it under `profiles.improve` in your config. Names are case-sensitive.",
+    LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
+    TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
+    SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_BUNDLE_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
+    UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
+    UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
+    WORKFLOW_ENGINE_NOT_ENABLED: "Run `akm config set experimental.workflowEngine true` to enable it.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {
     INVALID_FLAG_VALUE: "Run `akm <command> --help` to see accepted values.",
-    INVALID_SOURCE_VALUE: "Pick one of: stash, registry, both.",
-    INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, text, yaml.",
+    INVALID_SOURCE_VALUE: "Pick one of: local, registry, all, or a configured source name.",
+    INVALID_FORMAT_VALUE: "Pick one of: json, jsonl, yaml, text, md, html.",
     INVALID_DETAIL_VALUE: "Pick one of: brief, normal, full. For agent/summary projections use --shape.",
     INVALID_SHAPE_VALUE: "Pick one of: human, agent, summary (summary is only valid on `akm show`).",
     INVALID_JSON_CONFIG_VALUE: 'Quote JSON values in your shell, for example: akm config set embedding \'{"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}\'.',
-    MISSING_OR_AMBIGUOUS_TARGET: "Use `akm update --all` or pass a target like `akm update npm:@scope/pkg` (not both).",
-    TARGET_NOT_UPDATABLE: "Run `akm list` to view your sources, then retry with one of those values.",
-    MISSING_REQUIRED_ARGUMENT: "Refs use the form type:name, e.g. `akm show skill:deploy` or `akm show knowledge:guide.md`.",
+    MISSING_OR_AMBIGUOUS_TARGET: "Use `akm bundle update --all` or pass a target like `akm bundle update npm:@scope/pkg` (not both).",
+    TARGET_NOT_UPDATABLE: "Run `akm bundle list` to view your sources, then retry with one of those values.",
+    MISSING_REQUIRED_ARGUMENT: "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.",
+    UNKNOWN_COMMAND: "Run `akm --help` to see available commands.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
-    SOURCE_NOT_FOUND: "Run `akm list` to view your sources, then retry with one of those values.",
+    SOURCE_NOT_FOUND: "Run `akm bundle list` to view your sources, then retry with one of those values.",
     WORKFLOW_NOT_FOUND: "Run `akm workflow list --active` to see runs.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
@@ -97,7 +99,7 @@ export class NotFoundError extends AkmError {
  * Test-isolation guard helper.
  *
  * `src/core/paths.ts` throws `ConfigError("TEST_ISOLATION_MISSING")` under
- * `bun test` when `AKM_STASH_DIR` is set without a paired data-dir or
+ * `bun test` when `AKM_BUNDLE_DIR` is set without a paired data-dir or
  * state-dir override. That throw must never be swallowed by best-effort
  * catches around DB/data-dir operations — otherwise the guard's loud failure
  * silently degrades into a "no result" outcome (cold cache, missing snapshot,

package/dist/core/events-types.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/core/events.js

@@ -1,52 +1,19 @@
 // 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/.
-/**
- * Append-only events stream — backed by state.db (#204, Phase 3).
- *
- * Every mutating CLI verb funnels through `appendEvent` so external
- * observers (sync, replication, audit, dashboards) can react to stash
- * changes. Events are stored in the `events` table in `state.db`
- * (SQLite, WAL mode) instead of a flat `events.jsonl` file.
- *
- * The helper is the only thing in akm that writes to the events table. It
- * accepts an injectable `dbPath` (via `EventsContext`) so tests can pin a
- * tmpdir without any global mutation.
- *
- * Format (each EventEnvelope):
- *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
- *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
- *
- * - `id` is a monotonic SQLite AUTOINCREMENT rowid. Callers can persist it
- *   as a durable cursor for `--since` resumption (replaces the old byte-offset
- *   cursor). The public API still surfaces this as `nextOffset` (an opaque
- *   number) for backward compatibility with callers that stored byte-offset
- *   cursors.
- * - `ts` is ISO-8601 (UTC, millisecond precision).
- */
-import path from "node:path";
 import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
-import { getDataDir } from "./paths.js";
-import { openStateDatabase, withStateDb } from "./state-db.js";
+import { getStateDbPath, openStateDatabase, withStateDb } from "./state-db.js";
 import { error } from "./warn.js";
-/**
- * Legacy events.jsonl path — used only by the migration script
- * (`scripts/migrate-storage.ts`) to import existing event history into
- * state.db. No events are written here by akm v0.9+.
- */
-export function getEventsPath() {
-    return path.join(getDataDir(), "events.jsonl");
-}
 /**
  * Resolve the state.db path from context:
  *   1. `ctx.dbPath` — explicit override (test seam)
- *   2. default      — `<dataDir>/state.db`
+ *   2. default      — the canonical state.db path
  */
 function resolveDbPath(ctx) {
     if (ctx?.dbPath)
         return ctx.dbPath;
-    return path.join(getDataDir(), "state.db");
+    return getStateDbPath();
 }
 function resolveNow(ctx) {
     return ctx?.now ?? Date.now;
@@ -100,6 +67,17 @@ export function appendEvent(input, ctx) {
         error(`akm: appendEvent failed: ${String(err)}`);
     }
 }
+/**
+ * 0.9.0 breaking change (owner ruling 12): `akm sync` used to persist
+ * `eventType: "save"`; it now writes `"sync"` instead (matching the command
+ * name). Existing `state.db` rows — and any user script running
+ * `akm log --type save` — still carry the old spelling. Rather than
+ * rewriting historical rows (a migration users never asked for, on data we
+ * don't get to touch at rest), reads treat the two names as synonyms: asking
+ * for either "save" or "sync" returns rows written under both names. Only
+ * the WRITE path (sources-cli.ts's `runSyncBody`) changed.
+ */
+const SAVE_SYNC_EVENT_TYPE_ALIASES = new Set(["save", "sync"]);
 /**
  * Read all events matching the filter. Returns a `nextOffset` that callers
  * can persist between processes for monotonic resumption.
@@ -117,14 +95,37 @@ export function readEvents(options = {}, ctx) {
         return { events: [], nextOffset: 0 };
     }
     try {
+        // A "save"/"sync" query can't be expressed as a single SQL `event_type =
+        // ?` match (see SAVE_SYNC_EVENT_TYPE_ALIASES above), so widen the SQL
+        // filter to "no type filter" for that one case and apply the alias match
+        // client-side alongside the existing tag post-filter below.
+        const typeIsAliased = options.type !== undefined && SAVE_SYNC_EVENT_TYPE_ALIASES.has(options.type);
+        // D-38: a JS-side post-filter (the type alias above, or the tag filters
+        // below) runs AFTER the SQL read, so a SQL-level LIMIT applied before it
+        // could drop rows the post-filter would have kept out anyway, silently
+        // returning fewer than `limit` (or the wrong — oldest-in-the-SQL-window —
+        // events). Only push `limit` into SQL (readStateEvents) when nothing
+        // downstream can shrink the result further; otherwise read unbounded (the
+        // pre-existing behavior) and apply `limit` ourselves, below, AFTER the
+        // post-filter runs.
+        const needsPostFilter = typeIsAliased ||
+            (options.excludeTags?.length ?? 0) > 0 ||
+            (options.includeTags?.length ?? 0) > 0 ||
+            options.runId !== undefined;
+        const pushLimitToSql = options.limit !== undefined && !needsPostFilter;
         const { events: rawEvents, nextId } = readStateEvents(db, {
             sinceId: options.sinceOffset,
             since: options.since,
-            type: options.type,
+            type: typeIsAliased ? undefined : options.type,
             ref: options.ref,
+            ...(pushLimitToSql ? { limit: options.limit } : {}),
         });
-        // Apply tag filters in application code (same as the old JSONL implementation).
-        const events = rawEvents.filter((envelope) => {
+        const filtered = rawEvents.filter((envelope) => {
+            if (typeIsAliased && !SAVE_SYNC_EVENT_TYPE_ALIASES.has(envelope.eventType))
+                return false;
+            if (options.runId !== undefined && envelope.metadata?.runId !== options.runId)
+                return false;
+            // Apply tag filters after the indexed state.db read.
             const tags = envelope.metadata?.tags ?? [];
             if (options.excludeTags?.some((t) => tags.includes(t)))
                 return false;
@@ -132,98 +133,15 @@ export function readEvents(options = {}, ctx) {
                 return false;
             return true;
         });
+        // `filtered` is ascending by id; slicing off the end keeps the MOST
+        // RECENT `limit` events post-filter, matching the SQL-pushdown path's
+        // semantics exactly. `nextOffset` intentionally stays `nextId` — the
+        // durable resume cursor tracks the underlying SQL read, not this
+        // display-only truncation.
+        const events = options.limit !== undefined && !pushLimitToSql ? filtered.slice(-options.limit) : filtered;
         return { events, nextOffset: nextId };
     }
     finally {
         db.close();
     }
 }
-/**
- * Follow the events table in state.db. Polls at `intervalMs` (default 75ms)
- * and emits every new event to `onEvent`. Resolves when `signal` aborts, when
- * `maxEvents` events have been observed, or when `maxDurationMs` elapses.
- *
- * The polling cursor is a monotonic SQLite rowid so concurrent writers cannot
- * cause skips: between two reads we always pick up everything inserted since
- * the last `nextOffset`.
- */
-export async function tailEvents(options = {}, ctx) {
-    const intervalMs = options.intervalMs ?? 75;
-    const collected = [];
-    let cursor = options.sinceOffset ?? 0;
-    // Seed the cursor: if the caller passed --since (timestamp) but no
-    // sinceOffset, do an initial filtered read so they see history before
-    // we start polling. This matches the documented behaviour of `tail
-    // --since`: emit existing events that match, then follow.
-    if (options.sinceOffset === undefined) {
-        const initial = readEvents({
-            since: options.since,
-            type: options.type,
-            ref: options.ref,
-            excludeTags: options.excludeTags,
-            includeTags: options.includeTags,
-        }, ctx);
-        for (const event of initial.events) {
-            collected.push(event);
-            options.onEvent?.(event);
-            if (options.maxEvents !== undefined && collected.length >= options.maxEvents) {
-                return { events: collected, nextOffset: initial.nextOffset, reason: "maxEvents" };
-            }
-        }
-        cursor = initial.nextOffset;
-    }
-    const startedAt = Date.now();
-    return new Promise((resolve) => {
-        let resolved = false;
-        let timer;
-        function finish(reason) {
-            if (resolved)
-                return;
-            resolved = true;
-            if (timer)
-                clearInterval(timer);
-            resolve({ events: collected, nextOffset: cursor, reason });
-        }
-        function tick() {
-            try {
-                const result = readEvents({
-                    sinceOffset: cursor,
-                    type: options.type,
-                    ref: options.ref,
-                    excludeTags: options.excludeTags,
-                    includeTags: options.includeTags,
-                }, ctx);
-                cursor = result.nextOffset;
-                for (const event of result.events) {
-                    // Apply --since filter inside the polling loop too — the cursor is
-                    // rowid-based so it can hand us events the user filtered out.
-                    if (options.since && event.ts && event.ts < options.since)
-                        continue;
-                    collected.push(event);
-                    options.onEvent?.(event);
-                    if (options.maxEvents !== undefined && collected.length >= options.maxEvents) {
-                        finish("maxEvents");
-                        return;
-                    }
-                }
-            }
-            catch {
-                // Non-fatal: stay in the loop.
-            }
-            if (options.maxDurationMs !== undefined && Date.now() - startedAt >= options.maxDurationMs) {
-                finish("maxDuration");
-            }
-        }
-        if (options.signal) {
-            if (options.signal.aborted) {
-                finish("signal");
-                return;
-            }
-            options.signal.addEventListener("abort", () => finish("signal"), { once: true });
-        }
-        timer = setInterval(tick, intervalMs);
-        // Run one tick immediately so callers don't have to wait an interval
-        // for events written in the same tick as the tail starts.
-        tick();
-    });
-}

package/dist/core/extra-params.js

@@ -0,0 +1,62 @@
+// 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/.
+export const EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
+    "model",
+    "messages",
+    "temperature",
+    "maxtokens",
+    "responseformat",
+    "stream",
+    "streamoptions",
+    "enablethinking",
+    "chattemplatekwargs",
+];
+export const EXTRA_PARAMS_CREDENTIAL_KEYS = [
+    "authorization",
+    "headers",
+    "apikey",
+    "token",
+    "password",
+    "secret",
+    "cookie",
+    "setcookie",
+];
+const PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
+const CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+export function normalizeExtraParamKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/** Validate provider extras without allowing them to override AKM fields or carry credentials. */
+export function validateExtraParams(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [{ path: [], message: "must be an object" }];
+    }
+    const issues = [];
+    const visit = (entry, path) => {
+        if (Array.isArray(entry)) {
+            entry.forEach((child, index) => {
+                visit(child, [...path, index]);
+            });
+            return;
+        }
+        if (!entry || typeof entry !== "object")
+            return;
+        for (const [key, child] of Object.entries(entry)) {
+            const normalized = normalizeExtraParamKey(key);
+            if (path.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
+                issues.push({ path: [key], message: `${key} is protected by AKM` });
+            }
+            if (CREDENTIAL_KEYS.has(normalized)) {
+                issues.push({ path: [...path, key], message: `${key} cannot carry credentials` });
+            }
+            visit(child, [...path, key]);
+        }
+    };
+    visit(value, []);
+    return issues;
+}
+export function formatExtraParamsIssue(label, issue) {
+    const suffix = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${part}`)).join("");
+    return `${label}${suffix} ${issue.message}`;
+}

package/dist/core/file-change.js

@@ -0,0 +1,17 @@
+// 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/.
+/**
+ * The content of a proposal's PRIMARY change (WI-6.2 envelope read path).
+ *
+ * By construction `changes[0].after === payload.content`; consumers read
+ * through this accessor so the single-content assumption lives in ONE place
+ * once multi-file proposals (consolidate ops) ride the envelope. Typed
+ * structurally (not against `Proposal`) so this module stays dependency-free.
+ */
+export function proposalContent(p) {
+    const content = p.changes[0]?.after;
+    if (content === undefined)
+        throw new Error("Proposal primary change has no content.");
+    return content;
+}