akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -6,7 +6,7 @@
  * `config-schema.ts` monolith — no behavior change.
  */
 import { z } from "zod";
-import { positiveInt } from "./primitives.js";
+import { engineName, positiveInt } from "./primitives.js";
 // ── Workflow engine ─────────────────────────────────────────────────────────
 /**
  * Workflow-engine settings (`workflow`).
@@ -19,11 +19,11 @@ import { positiveInt } from "./primitives.js";
  *     `[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(),
+    /** Named LLM or agent engine frozen into every criteria-bearing gate. */
+    judgeEngine: engineName.optional(),
 })
     .passthrough();

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

@@ -11,15 +11,18 @@
  * 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 { 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 { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath, resolveWriteTarget, } from "./write-source.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
@@ -31,25 +34,58 @@ 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 `secret:` (a single value).", "INVALID_FLAG_VALUE");
+        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) {
     // 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}`);
     }
@@ -58,19 +94,21 @@ export function findEnvSource(origin) {
 export function makeEnvRef(name, source) {
     // 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 });
+    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 = assetPathForName("env", envRoot, parsed.name);
     // Defense-in-depth: ensure the resolved path stays inside the env directory.
@@ -86,12 +124,20 @@ export function parseSecretRef(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) {
     // 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 });
+    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
@@ -99,14 +145,14 @@ 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 = assetPathForName("secret", typeRoot, parsed.name);
     // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
@@ -115,26 +161,6 @@ create) {
     }
     return { name: parsed.name, absPath, source };
 }
-// ── Write-target resolution (env/secret mutations) ───────────────────────────
-//
-// READS (`env run`/`show`/`list`/`path`, `secret run`/`path`/`list`) keep the
-// origin-aware, all-sources `findEnvSource` resolution above. WRITES route
-// through the canonical `resolveWriteTarget` selection every other write command
-// (remember/import/tasks/knowledge) shares: explicit `--target` wins, else
-// `defaultWriteTarget`, else the working stash, and the chosen source must be
-// writable (a non-writable `--target`/`defaultWriteTarget` fails fast with the
-// shared typed ConfigError). Env/secret VALUES are still never read or surfaced
-// here — these helpers only resolve the write target and the absolute path.
-/**
- * Spell an env/secret ref for a resolved write target. `target.selector` is the
- * config source name for a `--target`/`defaultWriteTarget` destination and
- * undefined for the working-stash fallback; `displayRef` suppresses the
- * `local`/`stash`/default sentinels, so the primary stash still spells the bare
- * `env/name` while a named bundle spells `bundle//env/name`.
- */
-export function writeTargetDisplaySource(target) {
-    return { path: target.source.path, ...(target.selector ? { registryId: target.selector } : {}) };
-}
 /**
  * Resolve the destination for an env mutation. Mirrors {@link resolveEnvPath}
  * but selects the source via {@link resolveWriteTarget} (writability-checked)
@@ -144,19 +170,20 @@ export function writeTargetDisplaySource(target) {
 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}".`);
+        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 target = resolveWriteTarget(loadConfig(), writeTarget);
+    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: parsed };
+    return { name: parsed.name, absPath, target, parsedRef: resolved.ref, ref: resolved.displayRef };
 }
 /**
  * Resolve the destination for a secret mutation. Mirrors
@@ -167,19 +194,20 @@ export function resolveEnvWriteTarget(ref, writeTarget, create) {
 export function resolveSecretWriteTarget(ref, writeTarget, 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);
     }
-    const target = resolveWriteTarget(loadConfig(), writeTarget);
+    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 };
+    return { name: parsed.name, absPath, target, ref: resolved.displayRef };
 }
 /**
  * Land an env/secret mutation on its write target's git boundary. Mirrors the
@@ -188,8 +216,10 @@ export function resolveSecretWriteTarget(ref, writeTarget, create) {
  * primary stash included) and for `env/` paths a stash `.gitignore` excludes, so
  * callers invoke it unconditionally after every create/ingest/set/remove.
  */
-export function commitEnvSecretWrite(target, ref, op, paths) {
-    for (const filePath of paths)
-        recordWriteTargetPath(target.source, filePath);
-    commitWriteTargetBoundary(target, `${op} ${formatRefForMessage({ type: ref.type, name: ref.name, ...(target.selector ? { origin: target.selector } : {}) })}`);
+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,33 +6,39 @@
  * 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 configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
-    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.",
+    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.",
 };
 /** 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_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.",
+    UNKNOWN_FLAG: "Run the command with `--help` to see its accepted flags.",
 };
 /** 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.",
+    // A proposal is addressed by id or ref, never by path — reusing
+    // FILE_NOT_FOUND here handed users "check the path exists and is readable"
+    // for a mistyped id, which points at the wrong thing entirely.
+    PROPOSAL_NOT_FOUND: "Run `akm proposal list` to see pending proposals and their ids.",
     FILE_NOT_FOUND: "Check the path exists and is readable.",
 };
 /**
@@ -97,7 +103,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.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/file-change.js

@@ -6,11 +6,12 @@
  *
  * 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. Falls back
- * to the payload for legacy in-memory objects that predate the envelope.
- * Typed structurally (not against `Proposal`) so this module stays
- * dependency-free.
+ * once multi-file proposals (consolidate ops) ride the envelope. Typed
+ * structurally (not against `Proposal`) so this module stays dependency-free.
  */
 export function proposalContent(p) {
-    return p.changes?.[0]?.after ?? p.payload.content;
+    const content = p.changes[0]?.after;
+    if (content === undefined)
+        throw new Error("Proposal primary change has no content.");
+    return content;
 }