akm-cli 0.10.261125-beta.1 → 0.10.261125

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.10.261125] - 2026-11-14
10
+
9
11
  ### Added
10
12
 
11
13
  - AKM Desktop's library map answers four questions about the whole library, one view each: Contents (what is in it, by topic, with the searches that found nothing), Use (what is read and what is dead weight), Problems (what is outdated, disliked or duplicated) and Relations (how its topics link to each other, in 3D or flat). It replaces the point cloud of every asset, which showed none of these. The figures of each view are also in words beside it.
@@ -26,6 +28,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
26
28
  - `akm setup --embedding-endpoint https://host/v1/models` stored `https://host/v1/models/v1`, and `…/V1` became `…/V1/v1`. An endpoint typed with `/models`, `/completions`, `/embeddings` or `/chat/completions` (any case) now names its base, and `/V1` counts as the `/v1` root.
27
29
  - The Desktop workspace API (`assets.show`, `assets.related`, `documents.readSource`, the graph) threw `no such table: entries` or `file is not a database` on a first-build, zero-filled or garbage `index.db`; they now treat an index that cannot serve as no index, so `assets.show` answers from the file with `durableRef: null`.
28
30
  - A garbage, zero-filled or truncated `state.db` now raises one error, exit 78 naming the file, from every verb except `health`: `feedback` and `index` no longer exit 70, `akm health` reports it as one failing finding (exit 1) for every kind of damage, `akm log` / `akm doctor log` no longer return zero events at exit 0, and workspace readers no longer throw a raw SQLite error.
31
+ - Concurrent akm commands dropped their usage records: `metrics.db` used SQLite's rollback journal, so each capture's commit waited on every other invocation's reads and gave up after 250 ms. On a disk-backed data directory, 8 concurrent commands lost a third of their records. The usage store now uses akm's standard journal mode (WAL), like the other databases, and the same burst records every command.
32
+ - Under Bun, closing an akm database left the SQLite connection open, with its file, WAL and shared memory, until garbage collection, whenever a prepared statement had not been finalized; `akm index` alone left about six such handles behind. Long-lived hosts such as Desktop accumulated them, and the collector's eventual close wrote the stale WAL into whatever file then sat at that path, including a restored `state.db`. Closing a database now finalizes its statements and closes the connection.
29
33
 
30
34
  ## [0.10.261124] - 2026-11-14
31
35
 
package/dist/cli/usage.js CHANGED
@@ -9,6 +9,7 @@ import { getDataDir } from "../core/paths.js";
9
9
  import { isKnownType } from "../core/recognition-util.js";
10
10
  import { hasSignalOwner, observeSignal } from "../core/signal-observers.js";
11
11
  import { openDatabase } from "../storage/database.js";
12
+ import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
12
13
  import { resolveAgentIdentity } from "../workflows/runtime/agent-identity.js";
13
14
  import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray } from "./invocation.js";
14
15
  // Enum-like string flags are not enums in citty. Keep this finite allowlist
@@ -203,6 +204,9 @@ function openUsage(filename) {
203
204
  fs.mkdirSync(path.dirname(filename), { recursive: true });
204
205
  const db = openDatabase(filename);
205
206
  try {
207
+ // akm's journal mode (WAL), so concurrent invocations' commits do not wait on each other's reads; then
208
+ // capture's own short wait, so a contended store never stalls a command.
209
+ applyStandardPragmas(db, { dataDir: path.dirname(filename) });
206
210
  db.exec("PRAGMA busy_timeout=250;");
207
211
  db.exec(`
208
212
  CREATE TABLE IF NOT EXISTS cli_usage_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
@@ -11,13 +11,13 @@
11
11
  * else is a plain miss.
12
12
  */
13
13
  import { sha256Hex } from "../runtime.js";
14
- import { openDatabaseFinalizing } from "../storage/database.js";
14
+ import { openDatabase } from "../storage/database.js";
15
15
  export function vectorTextHash(embeddingInput) {
16
16
  return sha256Hex(embeddingInput);
17
17
  }
18
18
  /** Create a vector file at `file` holding `rows`, all stamped with `model`. */
19
19
  export function writeVectorFile(file, model, rows) {
20
- const db = openDatabaseFinalizing(file, { create: true });
20
+ const db = openDatabase(file, { create: true });
21
21
  try {
22
22
  db.exec("CREATE TABLE vectors (model TEXT NOT NULL, text_hash TEXT NOT NULL, embedding BLOB NOT NULL, PRIMARY KEY (model, text_hash))");
23
23
  const insert = db.prepare("INSERT OR REPLACE INTO vectors (model, text_hash, embedding) VALUES (?, ?, ?)");
@@ -38,7 +38,7 @@ export function writeVectorFile(file, model, rows) {
38
38
  export function openVectorLookup(file, model, warn) {
39
39
  let db;
40
40
  try {
41
- db = openDatabaseFinalizing(file, { readonly: true, create: false });
41
+ db = openDatabase(file, { readonly: true, create: false });
42
42
  const widths = db
43
43
  .prepare("SELECT length(embedding) AS bytes, COUNT(*) AS n FROM vectors WHERE model = ? AND length(embedding) % 4 = 0 AND length(embedding) > 0 GROUP BY bytes ORDER BY n DESC LIMIT 1")
44
44
  .all(model);
@@ -30749,26 +30749,28 @@ var init_agent_builder = __esm(() => {
30749
30749
  // src/storage/database.ts
30750
30750
  import { createRequire as createRequire3 } from "node:module";
30751
30751
  function openDatabase(path13, opts) {
30752
- return isBun2 ? openBunDatabase(path13, opts) : openNodeDatabase(path13, opts);
30753
- }
30754
- function openDatabaseFinalizing(path13, opts) {
30755
- const db = openDatabase(path13, opts);
30756
- const tracked = new Set;
30757
- const origPrepare = db.prepare.bind(db);
30758
- const origClose = db.close.bind(db);
30759
- db.prepare = (sql, ...rest) => {
30760
- const stmt = origPrepare(sql, ...rest);
30761
- tracked.add(stmt);
30752
+ return isBun2 ? finalizeOnClose(openBunDatabase(path13, opts)) : openNodeDatabase(path13, opts);
30753
+ }
30754
+ function finalizeOnClose(db) {
30755
+ const live = new Set;
30756
+ const forget = new FinalizationRegistry((ref) => live.delete(ref));
30757
+ const prepare = db.prepare.bind(db);
30758
+ const close = db.close.bind(db);
30759
+ db.prepare = (sql) => {
30760
+ const stmt = prepare(sql);
30761
+ const ref = new WeakRef(stmt);
30762
+ live.add(ref);
30763
+ forget.register(stmt, ref);
30762
30764
  return stmt;
30763
30765
  };
30764
- db.close = (...args) => {
30765
- for (const stmt of tracked) {
30766
+ db.close = () => {
30767
+ for (const ref of live) {
30766
30768
  try {
30767
- stmt.finalize?.();
30769
+ ref.deref()?.finalize?.();
30768
30770
  } catch {}
30769
30771
  }
30770
- tracked.clear();
30771
- return origClose(...args);
30772
+ live.clear();
30773
+ close();
30772
30774
  };
30773
30775
  return db;
30774
30776
  }
@@ -30937,7 +30939,7 @@ function openSqliteReadSnapshot(dbPath) {
30937
30939
  let db;
30938
30940
  try {
30939
30941
  copySqliteSnapshot(dbPath, snapshotPath);
30940
- db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
30942
+ db = openDatabase(snapshotPath, { readonly: true, create: false });
30941
30943
  const closeSnapshot = db.close.bind(db);
30942
30944
  let closed = false;
30943
30945
  const cleanup = (bestEffort) => {
@@ -30748,26 +30748,28 @@ var init_agent_builder = __esm(() => {
30748
30748
  // src/storage/database.ts
30749
30749
  import { createRequire as createRequire2 } from "module";
30750
30750
  function openDatabase(path13, opts) {
30751
- return isBun2 ? openBunDatabase(path13, opts) : openNodeDatabase(path13, opts);
30752
- }
30753
- function openDatabaseFinalizing(path13, opts) {
30754
- const db = openDatabase(path13, opts);
30755
- const tracked = new Set;
30756
- const origPrepare = db.prepare.bind(db);
30757
- const origClose = db.close.bind(db);
30758
- db.prepare = (sql, ...rest) => {
30759
- const stmt = origPrepare(sql, ...rest);
30760
- tracked.add(stmt);
30751
+ return isBun2 ? finalizeOnClose(openBunDatabase(path13, opts)) : openNodeDatabase(path13, opts);
30752
+ }
30753
+ function finalizeOnClose(db) {
30754
+ const live = new Set;
30755
+ const forget = new FinalizationRegistry((ref) => live.delete(ref));
30756
+ const prepare = db.prepare.bind(db);
30757
+ const close = db.close.bind(db);
30758
+ db.prepare = (sql) => {
30759
+ const stmt = prepare(sql);
30760
+ const ref = new WeakRef(stmt);
30761
+ live.add(ref);
30762
+ forget.register(stmt, ref);
30761
30763
  return stmt;
30762
30764
  };
30763
- db.close = (...args) => {
30764
- for (const stmt of tracked) {
30765
+ db.close = () => {
30766
+ for (const ref of live) {
30765
30767
  try {
30766
- stmt.finalize?.();
30768
+ ref.deref()?.finalize?.();
30767
30769
  } catch {}
30768
30770
  }
30769
- tracked.clear();
30770
- return origClose(...args);
30771
+ live.clear();
30772
+ close();
30771
30773
  };
30772
30774
  return db;
30773
30775
  }
@@ -30936,7 +30938,7 @@ function openSqliteReadSnapshot(dbPath) {
30936
30938
  let db;
30937
30939
  try {
30938
30940
  copySqliteSnapshot(dbPath, snapshotPath);
30939
- db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
30941
+ db = openDatabase(snapshotPath, { readonly: true, create: false });
30940
30942
  const closeSnapshot = db.close.bind(db);
30941
30943
  let closed = false;
30942
30944
  const cleanup = (bestEffort) => {
@@ -40,52 +40,45 @@ const nodeRequire = createRequire(import.meta.url);
40
40
  * Open a SQLite database handle at `path` on the current runtime's driver
41
41
  * (`bun:sqlite` on Bun, `better-sqlite3` on Node). Returns a handle conforming
42
42
  * to the structural {@link Database} type.
43
+ *
44
+ * On Bun, `close()` means CLOSED. bun:sqlite's own `close()` is a
45
+ * `sqlite3_close_v2`: while any `prepare()` statement is unfinalized the
46
+ * connection survives as a zombie, holding the file, its WAL and its
47
+ * shared memory, until GC finalizes the statements. When GC finally closes it,
48
+ * the last-connection checkpoint writes that WAL into whatever file now sits at
49
+ * the path, a restored or replaced copy included. It also kept a later
50
+ * connection from leaving WAL mode (issue #720). So the handle finalizes every
51
+ * statement it prepared that is still alive before the real close. Statements
52
+ * are held weakly, so a per-row `prepare()` is not kept alive until close.
53
+ * better-sqlite3's `close()` already closes the connection outright.
43
54
  */
44
55
  export function openDatabase(path, opts) {
45
- return isBun ? openBunDatabase(path, opts) : openNodeDatabase(path, opts);
56
+ return isBun ? finalizeOnClose(openBunDatabase(path, opts)) : openNodeDatabase(path, opts);
46
57
  }
47
- /**
48
- * {@link openDatabase} with a finalize-on-close guard (issue #720).
49
- *
50
- * bun:sqlite's `Database.close()` is a `sqlite3_close_v2`: with any UNFINALIZED
51
- * `prepare()` statement outstanding, the underlying connection — and its WAL
52
- * shared-memory mapping — survives as a zombie until GC finalizes the
53
- * statements. A later connection in the same process then cannot leave WAL
54
- * mode (`PRAGMA journal_mode = DELETE` → "database is locked"), which is
55
- * exactly what silently defeated the migrate-apply single-file conversion.
56
- * (`db.query()` statements are Database-cached and immune; `prepare()` is the
57
- * dominant idiom in the migration helpers.)
58
- *
59
- * This variant tracks `prepare()` results and finalizes them (idempotently)
60
- * before the real `close()`, so close always means CLOSED. It is deliberately
61
- * OPT-IN for the migrate-apply flow's short-lived helper connections and the
62
- * migration test fixtures — NOT the global default: long-lived/hot paths cache
63
- * prepared statements per connection (e.g. the entries upsert WeakMap) and
64
- * worker flows may still be stepping a statement when a sibling close lands;
65
- * force-finalizing under them changes behavior they were built on.
66
- */
67
- export function openDatabaseFinalizing(path, opts) {
68
- const db = openDatabase(path, opts);
69
- const tracked = new Set();
70
- const origPrepare = db.prepare.bind(db);
71
- const origClose = db.close.bind(db);
72
- db.prepare = ((sql, ...rest) => {
73
- const stmt = origPrepare(sql, ...rest);
74
- tracked.add(stmt);
58
+ function finalizeOnClose(db) {
59
+ const live = new Set();
60
+ const forget = new FinalizationRegistry((ref) => live.delete(ref));
61
+ const prepare = db.prepare.bind(db);
62
+ const close = db.close.bind(db);
63
+ db.prepare = ((sql) => {
64
+ const stmt = prepare(sql);
65
+ const ref = new WeakRef(stmt);
66
+ live.add(ref);
67
+ forget.register(stmt, ref);
75
68
  return stmt;
76
69
  });
77
- db.close = ((...args) => {
78
- for (const stmt of tracked) {
70
+ db.close = () => {
71
+ for (const ref of live) {
79
72
  try {
80
- stmt.finalize?.();
73
+ ref.deref()?.finalize?.();
81
74
  }
82
75
  catch {
83
- // Already finalized (double-finalize is the idempotent no-op case).
76
+ // Already finalized by its owner.
84
77
  }
85
78
  }
86
- tracked.clear();
87
- return origClose(...args);
88
- });
79
+ live.clear();
80
+ close();
81
+ };
89
82
  return db;
90
83
  }
91
84
  function openBunDatabase(path, opts) {
@@ -19,7 +19,7 @@ import fs from "node:fs";
19
19
  import os from "node:os";
20
20
  import path from "node:path";
21
21
  import { sleepSync } from "../runtime.js";
22
- import { openDatabaseFinalizing } from "./database.js";
22
+ import { openDatabase } from "./database.js";
23
23
  const SNAPSHOT_MAX_ATTEMPTS = 8;
24
24
  const SNAPSHOT_BACKOFF_MS = 25;
25
25
  export class SqliteReadSnapshotUnavailableError extends Error {
@@ -151,7 +151,7 @@ export function openSqliteReadSnapshot(dbPath) {
151
151
  let db;
152
152
  try {
153
153
  copySqliteSnapshot(dbPath, snapshotPath);
154
- db = openDatabaseFinalizing(snapshotPath, { readonly: true, create: false });
154
+ db = openDatabase(snapshotPath, { readonly: true, create: false });
155
155
  const closeSnapshot = db.close.bind(db);
156
156
  let closed = false;
157
157
  const cleanup = (bestEffort) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261125-beta.1",
3
+ "version": "0.10.261125",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [