akm-cli 0.10.261126 → 0.10.261127-beta.1
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 +18 -0
- package/dist/commands/health/improve-metrics.js +23 -3
- package/dist/commands/health/md-report.js +4 -3
- package/dist/commands/improve/consolidate/pair-pass.js +52 -27
- package/dist/commands/improve/loop-stages.js +3 -2
- package/dist/commands/lint/base-linter.js +23 -20
- package/dist/commands/lint/index.js +26 -4
- package/dist/commands/sources/plugin-upgrade.js +23 -3
- package/dist/core/adapter/adapters/akm-lint.js +35 -12
- package/dist/core/adapter/adapters/shared.js +11 -22
- package/dist/core/asset/asset-ref.js +3 -2
- package/dist/core/asset/frontmatter-lint.js +17 -22
- package/dist/core/asset/lint-text.js +50 -0
- package/dist/indexer/indexer.js +5 -0
- package/dist/output/text/command-format.js +2 -1
- package/dist/scripts/akm-migrate-node.js +86 -37
- package/dist/scripts/akm-migrate.js +86 -37
- package/dist/storage/repositories/index-layout-repository.js +81 -0
- package/dist/storage/repositories/index-schema.js +18 -0
- package/dist/storage/repositories/task-history-repository.js +28 -0
- package/dist/storage/repositories/workflow-runs-repository.js +25 -0
- package/dist/tasks/run/attempt-lifecycle.js +8 -1
- package/dist/tasks/run/reconcile-abandoned.js +75 -0
- package/dist/tasks/run/run-task.js +9 -1
- package/dist/tasks/run/task-result.js +2 -0
- package/dist/workspace/graph-duplicates.js +124 -28
- package/dist/workspace/graph.js +39 -7
- package/docs/architecture/internals/health-advisories.md +1 -1
- package/docs/architecture/internals/improve-workflow.md +1 -1
- package/docs/architecture/internals/indexing.md +2 -2
- package/docs/architecture/internals/storage-locations.md +23 -4
- package/docs/reference/cli.md +7 -2
- package/docs/reference/workspace.md +11 -8
- package/package.json +1 -1
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
/**
|
|
5
|
+
* `index.db` layout repository: the library's shape by meaning, as `akm index` last computed it from the stored
|
|
6
|
+
* vectors (see `findSimilarity`). `entry_layout` holds each embedded entry's group and place in 3D; `duplicate_pairs`
|
|
7
|
+
* the near-duplicate pairs, most alike first. Both are derived and rewritten whole; `index_meta.layoutKey` is the hash
|
|
8
|
+
* of the vectors they were computed from, so a build whose vectors did not change skips the work.
|
|
9
|
+
*/
|
|
10
|
+
import { createHash } from "node:crypto";
|
|
11
|
+
import { findSimilarity } from "../../workspace/graph-duplicates.js";
|
|
12
|
+
import { getMeta, setMeta } from "./index-meta-repository.js";
|
|
13
|
+
import { listCurrentEmbeddings } from "./index-vec-repository.js";
|
|
14
|
+
/** The hash of the vectors and the entries they belong to, in id order. */
|
|
15
|
+
function vectorsKey(ids, vectors) {
|
|
16
|
+
const hash = createHash("sha1");
|
|
17
|
+
ids.forEach((id, k) => {
|
|
18
|
+
hash.update(String(id));
|
|
19
|
+
const v = vectors[k];
|
|
20
|
+
hash.update(new Uint8Array(v.buffer, v.byteOffset, v.byteLength));
|
|
21
|
+
});
|
|
22
|
+
return hash.digest("hex");
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Recompute and store the layout when the vectors changed since it was last stored; returns whether it ran. With too
|
|
26
|
+
* few embedded entries the tables are emptied.
|
|
27
|
+
*/
|
|
28
|
+
export async function storeLayout(db) {
|
|
29
|
+
const stored = listCurrentEmbeddings(db);
|
|
30
|
+
const ids = [...stored.keys()].sort((a, b) => a - b);
|
|
31
|
+
const vectors = ids.map((id) => stored.get(id));
|
|
32
|
+
const key = vectorsKey(ids, vectors);
|
|
33
|
+
if (getMeta(db, "layoutKey") === key)
|
|
34
|
+
return false;
|
|
35
|
+
const found = await findSimilarity(vectors);
|
|
36
|
+
const own = !db.inTransaction;
|
|
37
|
+
if (own)
|
|
38
|
+
db.exec("BEGIN IMMEDIATE");
|
|
39
|
+
try {
|
|
40
|
+
db.exec("DELETE FROM entry_layout; DELETE FROM duplicate_pairs;");
|
|
41
|
+
if (found) {
|
|
42
|
+
const place = db.prepare("INSERT INTO entry_layout (entry_id, grp, x, y, z) VALUES (?, ?, ?, ?, ?)");
|
|
43
|
+
const g = found.groups;
|
|
44
|
+
ids.forEach((id, k) => {
|
|
45
|
+
if (g.group[k] >= 0)
|
|
46
|
+
place.run(id, g.group[k], g.x[k], g.y[k], g.z[k]);
|
|
47
|
+
});
|
|
48
|
+
const pair = db.prepare("INSERT INTO duplicate_pairs (rank, a, b, cosine) VALUES (?, ?, ?, ?)");
|
|
49
|
+
const d = found.duplicates;
|
|
50
|
+
for (let k = 0; k < d.a.length; k++)
|
|
51
|
+
pair.run(k, ids[d.a[k]], ids[d.b[k]], d.cosine[k]);
|
|
52
|
+
}
|
|
53
|
+
setMeta(db, "layoutGroups", String(found?.groups.count ?? 0));
|
|
54
|
+
setMeta(db, "duplicateThreshold", String(found?.duplicates.threshold ?? 0));
|
|
55
|
+
setMeta(db, "duplicatesTruncated", found?.duplicates.truncated ? "1" : "0");
|
|
56
|
+
setMeta(db, "layoutKey", key);
|
|
57
|
+
if (own)
|
|
58
|
+
db.exec("COMMIT");
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
if (own && db.inTransaction)
|
|
62
|
+
db.exec("ROLLBACK");
|
|
63
|
+
throw error;
|
|
64
|
+
}
|
|
65
|
+
return true;
|
|
66
|
+
}
|
|
67
|
+
/** The stored layout: each placed entry's group and place, and the near-duplicate pairs, by entry id. */
|
|
68
|
+
export function readLayout(db) {
|
|
69
|
+
const tables = db
|
|
70
|
+
.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('entry_layout', 'duplicate_pairs')")
|
|
71
|
+
.all();
|
|
72
|
+
if (tables.length < 2)
|
|
73
|
+
return null;
|
|
74
|
+
return {
|
|
75
|
+
groups: Number(getMeta(db, "layoutGroups") ?? 0),
|
|
76
|
+
threshold: Number(getMeta(db, "duplicateThreshold") ?? 0),
|
|
77
|
+
truncated: getMeta(db, "duplicatesTruncated") === "1",
|
|
78
|
+
places: db.prepare("SELECT entry_id AS id, grp, x, y, z FROM entry_layout").all(),
|
|
79
|
+
pairs: db.prepare("SELECT a, b, cosine FROM duplicate_pairs ORDER BY rank").all(),
|
|
80
|
+
};
|
|
81
|
+
}
|
|
@@ -295,6 +295,24 @@ function applySchema(db) {
|
|
|
295
295
|
if (fingerprint)
|
|
296
296
|
db.prepare("UPDATE embeddings SET model = ? WHERE model IS NULL").run(fingerprint);
|
|
297
297
|
}
|
|
298
|
+
// The library's layout by meaning and its near-duplicate pairs, rewritten whole at the end of a build whose vectors
|
|
299
|
+
// changed (index-layout-repository.ts).
|
|
300
|
+
db.exec(`
|
|
301
|
+
CREATE TABLE IF NOT EXISTS entry_layout (
|
|
302
|
+
entry_id INTEGER PRIMARY KEY,
|
|
303
|
+
grp INTEGER NOT NULL,
|
|
304
|
+
x REAL NOT NULL,
|
|
305
|
+
y REAL NOT NULL,
|
|
306
|
+
z REAL NOT NULL,
|
|
307
|
+
FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
|
|
308
|
+
);
|
|
309
|
+
CREATE TABLE IF NOT EXISTS duplicate_pairs (
|
|
310
|
+
rank INTEGER PRIMARY KEY,
|
|
311
|
+
a INTEGER NOT NULL,
|
|
312
|
+
b INTEGER NOT NULL,
|
|
313
|
+
cosine REAL NOT NULL
|
|
314
|
+
);
|
|
315
|
+
`);
|
|
298
316
|
// Utility scores (aggregated per-entry utility metrics) — a regenerable
|
|
299
317
|
// cache recomputed from state.db's usage_events on every index run.
|
|
300
318
|
db.exec(`
|
|
@@ -69,6 +69,7 @@ export function decodeTaskHistoryMetadata(input) {
|
|
|
69
69
|
const trigger = parsed.trigger === "schedule" || parsed.trigger === "manual" ? parsed.trigger : undefined;
|
|
70
70
|
validateDetail(detail);
|
|
71
71
|
const steps = decodeSteps(parsed.steps);
|
|
72
|
+
const owner = decodeOwner(parsed.owner);
|
|
72
73
|
const cleanDetail = detail
|
|
73
74
|
? {
|
|
74
75
|
...(detail.runId !== undefined ? { runId: detail.runId } : {}),
|
|
@@ -84,6 +85,18 @@ export function decodeTaskHistoryMetadata(input) {
|
|
|
84
85
|
...(engine !== undefined ? { engine } : {}),
|
|
85
86
|
...(steps !== undefined ? { steps } : {}),
|
|
86
87
|
...(trigger !== undefined ? { trigger } : {}),
|
|
88
|
+
...(owner !== undefined ? { owner } : {}),
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
/** Tolerant: a malformed `owner` is dropped, never a reason to reject the row. */
|
|
92
|
+
function decodeOwner(value) {
|
|
93
|
+
if (!isRecord(value) || typeof value.pid !== "number" || typeof value.host !== "string")
|
|
94
|
+
return undefined;
|
|
95
|
+
return {
|
|
96
|
+
pid: value.pid,
|
|
97
|
+
host: value.host,
|
|
98
|
+
...(typeof value.bootId === "string" ? { bootId: value.bootId } : {}),
|
|
99
|
+
...(typeof value.startTime === "string" ? { startTime: value.startTime } : {}),
|
|
87
100
|
};
|
|
88
101
|
}
|
|
89
102
|
const STEP_STATUSES = new Set(["completed", "failed", "skipped", "reused"]);
|
|
@@ -139,6 +152,21 @@ export function finalizeTaskHistoryAttempt(db, row) {
|
|
|
139
152
|
.run(row.status, row.completed_at ?? null, row.failed_at ?? null, row.log_path ?? null, row.target_kind ?? null, row.target_ref ?? null, row.metadata_json, row.task_id, row.started_at);
|
|
140
153
|
return Number(result.changes) === 1;
|
|
141
154
|
}
|
|
155
|
+
/** Mark a still-`active` attempt `interrupted`: its owner is provably gone and it never recorded a finish. */
|
|
156
|
+
export function markTaskHistoryAttemptInterrupted(db, id) {
|
|
157
|
+
const result = db
|
|
158
|
+
.prepare("UPDATE task_history SET status = 'interrupted' WHERE id = ? AND status = 'active' AND completed_at IS NULL")
|
|
159
|
+
.run(id);
|
|
160
|
+
return Number(result.changes) === 1;
|
|
161
|
+
}
|
|
162
|
+
/** Every attempt still `active` and unfinished, oldest first. */
|
|
163
|
+
export function listActiveTaskHistoryAttempts(db) {
|
|
164
|
+
return db
|
|
165
|
+
.prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
|
|
166
|
+
target_kind, target_ref, metadata_json
|
|
167
|
+
FROM task_history WHERE status = 'active' AND completed_at IS NULL ORDER BY started_at ASC, id ASC`)
|
|
168
|
+
.all();
|
|
169
|
+
}
|
|
142
170
|
/**
|
|
143
171
|
* Upsert a task history row.
|
|
144
172
|
*/
|
|
@@ -149,6 +149,31 @@ export class WorkflowRunsRepository {
|
|
|
149
149
|
WHERE id = ?`)
|
|
150
150
|
.run(input.status, input.currentStepId, input.updatedAt, input.completedAt, input.runId);
|
|
151
151
|
}
|
|
152
|
+
/** Runs that are `completed` or `failed` yet still hold a `running` unit or unit attempt. */
|
|
153
|
+
listTerminalRunsWithRunningUnits() {
|
|
154
|
+
const rows = this.db
|
|
155
|
+
.prepare(`SELECT id FROM workflow_runs
|
|
156
|
+
WHERE status IN ('completed', 'failed')
|
|
157
|
+
AND (EXISTS (SELECT 1 FROM workflow_run_units u WHERE u.run_id = workflow_runs.id AND u.status = 'running')
|
|
158
|
+
OR EXISTS (SELECT 1 FROM workflow_run_unit_attempts a WHERE a.run_id = workflow_runs.id AND a.status = 'running'))`)
|
|
159
|
+
.all();
|
|
160
|
+
return rows.map((row) => row.id);
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Settle the units and unit attempts still `running` under a terminal run as `failed` with failure_reason
|
|
164
|
+
* `interrupted`: their own outcome is unknown, not a recorded success. Their rows are kept. The caller makes sure
|
|
165
|
+
* no driver still holds the run, since a live driver journals a unit's result after the run turns terminal.
|
|
166
|
+
*/
|
|
167
|
+
settleRunningUnitsOfTerminalRun(runId, finishedAt) {
|
|
168
|
+
for (const table of ["workflow_run_unit_attempts", "workflow_run_units"]) {
|
|
169
|
+
this.db
|
|
170
|
+
.prepare(`UPDATE ${table}
|
|
171
|
+
SET status = 'failed', failure_reason = 'interrupted', finished_at = ?
|
|
172
|
+
WHERE status = 'running'
|
|
173
|
+
AND run_id IN (SELECT id FROM workflow_runs WHERE id = ? AND status IN ('completed', 'failed'))`)
|
|
174
|
+
.run(finishedAt, runId);
|
|
175
|
+
}
|
|
176
|
+
}
|
|
152
177
|
markRunAbandoned(runId, updatedAt) {
|
|
153
178
|
const result = this.db
|
|
154
179
|
.prepare(`UPDATE workflow_runs
|
|
@@ -17,7 +17,9 @@
|
|
|
17
17
|
* `recordTaskAttemptFailure`'s one externally-visible effect (the stored
|
|
18
18
|
* `detail.error` code). The comment on the set says why each code is reachable.
|
|
19
19
|
*/
|
|
20
|
+
import os from "node:os";
|
|
20
21
|
import { AkmError, rethrowIfTestIsolationError } from "../../core/errors.js";
|
|
22
|
+
import { processIdentity } from "../../core/file-lock.js";
|
|
21
23
|
import { withStateDb } from "../../core/state-db.js";
|
|
22
24
|
import { reserveTaskHistoryAttempt } from "../../storage/repositories/task-history-repository.js";
|
|
23
25
|
import { validateTaskId } from "../task-id.js";
|
|
@@ -39,7 +41,12 @@ export function reserveTaskAttempt(taskId, requestedStartedAt) {
|
|
|
39
41
|
log_path: null,
|
|
40
42
|
target_kind: null,
|
|
41
43
|
target_ref: null,
|
|
42
|
-
metadata_json: JSON.stringify({
|
|
44
|
+
metadata_json: JSON.stringify({
|
|
45
|
+
metadataVersion: 2,
|
|
46
|
+
durationMs: 0,
|
|
47
|
+
detail: null,
|
|
48
|
+
owner: { pid: process.pid, host: os.hostname(), ...processIdentity(process.pid) },
|
|
49
|
+
}),
|
|
43
50
|
});
|
|
44
51
|
if (reserved)
|
|
45
52
|
return { startedAt, historyReserved: true };
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
2
|
+
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
|
+
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
|
+
/**
|
|
5
|
+
* Settle execution state whose owner is provably gone. An `active` task
|
|
6
|
+
* attempt is classified from the owner it recorded at reservation:
|
|
7
|
+
*
|
|
8
|
+
* - running: the owner process is alive (same host, same boot, same start time).
|
|
9
|
+
* - interrupted: the owner is provably gone — a different boot, a dead pid, or
|
|
10
|
+
* a reused pid. Marked `interrupted`; its finish time and outcome stay unknown.
|
|
11
|
+
* - indeterminate: it cannot be told (another host, no liveness evidence). Left `active`.
|
|
12
|
+
*
|
|
13
|
+
* Elapsed time never decides: a long-running attempt with a live owner stays `active`.
|
|
14
|
+
* An attempt reserved before owners were recorded is interrupted only when it
|
|
15
|
+
* started before the current boot.
|
|
16
|
+
*/
|
|
17
|
+
import os from "node:os";
|
|
18
|
+
import { isProcessAlive } from "../../core/common.js";
|
|
19
|
+
import { probeLock, processIdentity } from "../../core/file-lock.js";
|
|
20
|
+
import { withStateDb } from "../../core/state-db.js";
|
|
21
|
+
import { decodeTaskHistoryMetadata, listActiveTaskHistoryAttempts, markTaskHistoryAttemptInterrupted, } from "../../storage/repositories/task-history-repository.js";
|
|
22
|
+
import { WorkflowRunsRepository } from "../../storage/repositories/workflow-runs-repository.js";
|
|
23
|
+
import { workflowRunLockPath } from "../../workflows/exec/run-workflow.js";
|
|
24
|
+
function classifyOwner(owner, here) {
|
|
25
|
+
if (owner.host !== here.host)
|
|
26
|
+
return "indeterminate";
|
|
27
|
+
if (owner.bootId !== undefined && here.self !== undefined && owner.bootId !== here.self.bootId)
|
|
28
|
+
return "interrupted";
|
|
29
|
+
if (owner.startTime !== undefined && here.self !== undefined) {
|
|
30
|
+
const current = processIdentity(owner.pid);
|
|
31
|
+
if (current !== undefined)
|
|
32
|
+
return current.startTime === owner.startTime ? "running" : "interrupted";
|
|
33
|
+
}
|
|
34
|
+
return isProcessAlive(owner.pid) ? "indeterminate" : "interrupted";
|
|
35
|
+
}
|
|
36
|
+
function classifyAttempt(row, here) {
|
|
37
|
+
let owner;
|
|
38
|
+
try {
|
|
39
|
+
owner = decodeTaskHistoryMetadata(row.metadata_json).owner;
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
owner = undefined;
|
|
43
|
+
}
|
|
44
|
+
if (owner)
|
|
45
|
+
return classifyOwner(owner, here);
|
|
46
|
+
return new Date(row.started_at).getTime() < here.bootedAtMs ? "interrupted" : "indeterminate";
|
|
47
|
+
}
|
|
48
|
+
/** Mark every `active` attempt whose owner is provably gone `interrupted`. */
|
|
49
|
+
function reconcileAbandonedTaskAttempts(db) {
|
|
50
|
+
const here = {
|
|
51
|
+
host: os.hostname(),
|
|
52
|
+
self: processIdentity(process.pid),
|
|
53
|
+
bootedAtMs: Date.now() - os.uptime() * 1000,
|
|
54
|
+
};
|
|
55
|
+
for (const row of listActiveTaskHistoryAttempts(db)) {
|
|
56
|
+
if (row.id !== undefined && classifyAttempt(row, here) === "interrupted")
|
|
57
|
+
markTaskHistoryAttemptInterrupted(db, row.id);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Settle abandoned task attempts, and workflow units left running under a terminal run that no live process drives
|
|
62
|
+
* (its lock is absent or stale; a held or unreadable lock leaves the run alone).
|
|
63
|
+
*/
|
|
64
|
+
export function reconcileAbandonedExecutionState() {
|
|
65
|
+
withStateDb((db) => {
|
|
66
|
+
reconcileAbandonedTaskAttempts(db);
|
|
67
|
+
const repo = new WorkflowRunsRepository(db);
|
|
68
|
+
const now = new Date().toISOString();
|
|
69
|
+
for (const runId of repo.listTerminalRunsWithRunningUnits()) {
|
|
70
|
+
const lock = probeLock(workflowRunLockPath(runId)).state;
|
|
71
|
+
if (lock === "absent" || lock === "stale")
|
|
72
|
+
repo.settleRunningUnitsOfTerminalRun(runId, now);
|
|
73
|
+
}
|
|
74
|
+
});
|
|
75
|
+
}
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
* ONCE per call, and threads the result into every dispatch arm.
|
|
24
24
|
*/
|
|
25
25
|
import path from "node:path";
|
|
26
|
-
import { TransientError } from "../../core/errors.js";
|
|
26
|
+
import { rethrowIfTestIsolationError, TransientError } from "../../core/errors.js";
|
|
27
27
|
import { releaseLock } from "../../core/file-lock.js";
|
|
28
28
|
import { getStateDir } from "../../core/paths.js";
|
|
29
29
|
import { formatLockHolderPid, tryAcquireRunLock } from "../../core/run-lock.js";
|
|
@@ -33,6 +33,7 @@ import { nameStepError } from "../prepare/prepare-steps.js";
|
|
|
33
33
|
import { recordTaskAttemptFailure, reserveTaskAttempt } from "./attempt-lifecycle.js";
|
|
34
34
|
import { loadPreparedTask } from "./load-task.js";
|
|
35
35
|
import { resolveProvenanceContext } from "./provenance.js";
|
|
36
|
+
import { reconcileAbandonedExecutionState } from "./reconcile-abandoned.js";
|
|
36
37
|
import { runPreparedCommandTask } from "./run-command-task.js";
|
|
37
38
|
import { runNativeTask } from "./run-native-task.js";
|
|
38
39
|
import { resolveResume, runStepsTask } from "./run-steps-task.js";
|
|
@@ -44,6 +45,13 @@ export async function runTask(id, options) {
|
|
|
44
45
|
const requestedStartedAt = now();
|
|
45
46
|
const provenance = resolveProvenanceContext(options.provenance, options.scheduled === true);
|
|
46
47
|
const task = await loadPreparedTask(id, options);
|
|
48
|
+
try {
|
|
49
|
+
reconcileAbandonedExecutionState();
|
|
50
|
+
}
|
|
51
|
+
catch (error) {
|
|
52
|
+
rethrowIfTestIsolationError(error);
|
|
53
|
+
// Settling abandoned state is housekeeping; it never prevents a run.
|
|
54
|
+
}
|
|
47
55
|
// Experimental steps task: a run does not start while the previous one is alive, and `task:`
|
|
48
56
|
// steps and `--resume` are settled before any attempt is reserved.
|
|
49
57
|
let resume;
|
|
@@ -2,13 +2,14 @@
|
|
|
2
2
|
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
3
3
|
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
|
|
4
4
|
/**
|
|
5
|
-
* The library's
|
|
6
|
-
* that say the same thing.
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* the
|
|
5
|
+
* The library's shape by meaning, from the stored embeddings: what `assets.graph` reports so a host can show which assets
|
|
6
|
+
* are alike and list the ones that say the same thing. The assets are grouped by meaning (spherical k-means on the unit
|
|
7
|
+
* vectors); each group is placed in 3D by its centre, so alike groups sit near each other, and each asset around its
|
|
8
|
+
* group's centre by how its vector differs from it. Near-duplicate pairs are looked for only inside a group, to avoid
|
|
9
|
+
* comparing every pair. `akm index` runs it at the end of a build whose vectors changed and stores the result
|
|
10
|
+
* (index-layout-repository.ts); the graph read only reads it back. Nothing is embedded; the work yields to the event loop
|
|
11
|
+
* as it goes.
|
|
10
12
|
*/
|
|
11
|
-
import { createHash } from "node:crypto";
|
|
12
13
|
/** Fewest embedded assets duplicates are looked for in. */
|
|
13
14
|
const MIN_ASSETS = 8;
|
|
14
15
|
/** Most buckets, however large the library. */
|
|
@@ -25,25 +26,13 @@ const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve));
|
|
|
25
26
|
export function bucketCount(n) {
|
|
26
27
|
return Math.max(2, Math.min(MAX_BUCKETS, Math.round(Math.sqrt(n / 2))));
|
|
27
28
|
}
|
|
28
|
-
let cache;
|
|
29
|
-
/** The vectors' content, in order: an index build that changed no embedding gives the same key. */
|
|
30
|
-
function contentKey(vectors) {
|
|
31
|
-
const hash = createHash("sha1");
|
|
32
|
-
for (const v of vectors)
|
|
33
|
-
hash.update(v ? new Uint8Array(v.buffer, v.byteOffset, v.byteLength) : NO_VECTOR);
|
|
34
|
-
return hash.digest("hex");
|
|
35
|
-
}
|
|
36
|
-
const NO_VECTOR = new Uint8Array(1);
|
|
37
29
|
/**
|
|
38
|
-
*
|
|
30
|
+
* Groups by meaning and near-duplicate pairs among the assets: spherical k-means puts the assets into buckets (centres from an evenly spaced
|
|
39
31
|
* sample of at most 4,000, seeded deterministically, so the same vectors give the same pairs), and every pair inside a
|
|
40
|
-
* bucket whose cosine is at least {@link DUPLICATE_COSINE} is reported
|
|
41
|
-
*
|
|
32
|
+
* bucket whose cosine is at least {@link DUPLICATE_COSINE} is reported; the buckets are the groups, placed by
|
|
33
|
+
* {@link place}. `null` without at least eight embedded assets.
|
|
42
34
|
*/
|
|
43
|
-
export async function
|
|
44
|
-
const key = contentKey(vectors);
|
|
45
|
-
if (cache?.key === key)
|
|
46
|
-
return cache.result;
|
|
35
|
+
export async function findSimilarity(vectors) {
|
|
47
36
|
const dims = vectors.find((v) => v)?.length ?? 0;
|
|
48
37
|
const usable = [];
|
|
49
38
|
for (let i = 0; i < vectors.length; i++)
|
|
@@ -193,12 +182,119 @@ export async function findDuplicates(vectors) {
|
|
|
193
182
|
}
|
|
194
183
|
const kept = pairs.sort(byAlike).slice(0, MAX_PAIRS);
|
|
195
184
|
const result = {
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
185
|
+
duplicates: {
|
|
186
|
+
threshold: DUPLICATE_COSINE,
|
|
187
|
+
a: kept.map((p) => p[0]),
|
|
188
|
+
b: kept.map((p) => p[1]),
|
|
189
|
+
cosine: kept.map((p) => Math.round(p[2] * 10000) / 10000),
|
|
190
|
+
truncated: pairCount > MAX_PAIRS,
|
|
191
|
+
},
|
|
192
|
+
groups: place(unit, dims, usable, members, centres, vectors.length),
|
|
201
193
|
};
|
|
202
|
-
cache = { key, result };
|
|
203
194
|
return result;
|
|
204
195
|
}
|
|
196
|
+
/**
|
|
197
|
+
* Where each asset sits in 3D. A group's centre is placed along the three directions its centres differ most in (found
|
|
198
|
+
* by power iteration from fixed starts), scaled so the groups spread about 100 units from the middle, then groups that
|
|
199
|
+
* overlap are pushed apart. An asset sits around its centre along three fixed directions, by how its vector differs
|
|
200
|
+
* from the centre, so a group's most typical assets are near its middle; a group's radius grows with the cube root of
|
|
201
|
+
* its size.
|
|
202
|
+
*/
|
|
203
|
+
function place(unit, dims, usable, members, centres, n) {
|
|
204
|
+
const k = members.length;
|
|
205
|
+
const groups = {
|
|
206
|
+
count: k,
|
|
207
|
+
group: new Array(n).fill(-1),
|
|
208
|
+
x: new Array(n).fill(0),
|
|
209
|
+
y: new Array(n).fill(0),
|
|
210
|
+
z: new Array(n).fill(0),
|
|
211
|
+
};
|
|
212
|
+
const live = members.flatMap((rows, c) => (rows.length ? [c] : []));
|
|
213
|
+
const mean = new Float64Array(dims);
|
|
214
|
+
for (const c of live)
|
|
215
|
+
for (let d = 0; d < dims; d++)
|
|
216
|
+
mean[d] += centres[c * dims + d] / live.length;
|
|
217
|
+
const centred = (c, d) => centres[c * dims + d] - mean[d];
|
|
218
|
+
const axes = [];
|
|
219
|
+
for (let a = 0; a < 3; a++) {
|
|
220
|
+
let axis = Float64Array.from({ length: dims }, (_, d) => Math.sin(d * (a + 1) + 1));
|
|
221
|
+
for (let round = 0; round < 60; round++) {
|
|
222
|
+
const next = new Float64Array(dims);
|
|
223
|
+
for (const c of live) {
|
|
224
|
+
let along = 0;
|
|
225
|
+
for (let d = 0; d < dims; d++)
|
|
226
|
+
along += centred(c, d) * axis[d];
|
|
227
|
+
for (let d = 0; d < dims; d++)
|
|
228
|
+
next[d] += along * centred(c, d);
|
|
229
|
+
}
|
|
230
|
+
for (const done of axes) {
|
|
231
|
+
let along = 0;
|
|
232
|
+
for (let d = 0; d < dims; d++)
|
|
233
|
+
along += next[d] * done[d];
|
|
234
|
+
for (let d = 0; d < dims; d++)
|
|
235
|
+
next[d] -= along * done[d];
|
|
236
|
+
}
|
|
237
|
+
const norm = Math.hypot(...next) || 1;
|
|
238
|
+
axis = next.map((v) => v / norm);
|
|
239
|
+
}
|
|
240
|
+
axes.push(axis);
|
|
241
|
+
}
|
|
242
|
+
// Group centres in 3D, spread to a root mean square of 100 from the middle.
|
|
243
|
+
const at = members.map(() => [0, 0, 0]);
|
|
244
|
+
for (const c of live)
|
|
245
|
+
at[c] = axes.map((axis) => {
|
|
246
|
+
let along = 0;
|
|
247
|
+
for (let d = 0; d < dims; d++)
|
|
248
|
+
along += centred(c, d) * axis[d];
|
|
249
|
+
return along;
|
|
250
|
+
});
|
|
251
|
+
const spread = Math.sqrt(live.reduce((sum, c) => sum + at[c].reduce((s, v) => s + v * v, 0), 0) / live.length) || 1;
|
|
252
|
+
for (const c of live)
|
|
253
|
+
at[c] = at[c].map((v) => (100 * v) / spread);
|
|
254
|
+
const radius = members.map((rows) => 2.6 * Math.cbrt(rows.length));
|
|
255
|
+
for (let round = 0; round < 80; round++)
|
|
256
|
+
for (const a of live)
|
|
257
|
+
for (const b of live) {
|
|
258
|
+
if (b <= a)
|
|
259
|
+
continue;
|
|
260
|
+
const gap = at[b].map((v, i) => v - at[a][i]);
|
|
261
|
+
const apart = Math.hypot(...gap) || 1e-6;
|
|
262
|
+
const need = 1.15 * (radius[a] + radius[b]);
|
|
263
|
+
if (apart >= need)
|
|
264
|
+
continue;
|
|
265
|
+
const push = (need - apart) / 2 / apart;
|
|
266
|
+
at[a] = at[a].map((v, i) => v - gap[i] * push);
|
|
267
|
+
at[b] = at[b].map((v, i) => v + gap[i] * push);
|
|
268
|
+
}
|
|
269
|
+
// Three fixed directions for the spread inside a group.
|
|
270
|
+
let seed = 11;
|
|
271
|
+
const random = () => {
|
|
272
|
+
seed = (seed * 1664525 + 1013904223) >>> 0;
|
|
273
|
+
return seed / 2 ** 32 - 0.5;
|
|
274
|
+
};
|
|
275
|
+
const inner = [0, 1, 2].map(() => {
|
|
276
|
+
const v = Float64Array.from({ length: dims }, random);
|
|
277
|
+
const norm = Math.hypot(...v) || 1;
|
|
278
|
+
return v.map((x) => x / norm);
|
|
279
|
+
});
|
|
280
|
+
members.forEach((rows, c) => {
|
|
281
|
+
if (!rows.length)
|
|
282
|
+
return;
|
|
283
|
+
const offsets = rows.map((row) => inner.map((dir) => {
|
|
284
|
+
let along = 0;
|
|
285
|
+
for (let d = 0; d < dims; d++)
|
|
286
|
+
along += (unit[row * dims + d] - centres[c * dims + d]) * dir[d];
|
|
287
|
+
return along;
|
|
288
|
+
}));
|
|
289
|
+
const rms = Math.sqrt(offsets.reduce((sum, o) => sum + o[0] ** 2 + o[1] ** 2 + o[2] ** 2, 0) / rows.length) || 1;
|
|
290
|
+
const scale = radius[c] / rms;
|
|
291
|
+
rows.forEach((row, r) => {
|
|
292
|
+
const i = usable[row];
|
|
293
|
+
groups.group[i] = c;
|
|
294
|
+
groups.x[i] = Math.round((at[c][0] + offsets[r][0] * scale) * 10) / 10;
|
|
295
|
+
groups.y[i] = Math.round((at[c][1] + offsets[r][1] * scale) * 10) / 10;
|
|
296
|
+
groups.z[i] = Math.round((at[c][2] + offsets[r][2] * scale) * 10) / 10;
|
|
297
|
+
});
|
|
298
|
+
});
|
|
299
|
+
return groups;
|
|
300
|
+
}
|
package/dist/workspace/graph.js
CHANGED
|
@@ -10,9 +10,8 @@ import { resolveSourceEntries } from "../indexer/search/search-source.js";
|
|
|
10
10
|
import { countFeedbackSignalsByRef, countUseByRef, usageRetentionSince } from "../indexer/usage/usage-events.js";
|
|
11
11
|
import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
|
|
12
12
|
import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
|
|
13
|
+
import { readLayout } from "../storage/repositories/index-layout-repository.js";
|
|
13
14
|
import { listDeclaredLinks } from "../storage/repositories/index-links-repository.js";
|
|
14
|
-
import { listCurrentEmbeddings } from "../storage/repositories/index-vec-repository.js";
|
|
15
|
-
import { findDuplicates } from "./graph-duplicates.js";
|
|
16
15
|
import { withReadonlyStateDb } from "./readers.js";
|
|
17
16
|
/** Types never drawn: protected files and session logs, as `assets.related` leaves them out. */
|
|
18
17
|
const HIDDEN_TYPES = ["secret", "env", "session"];
|
|
@@ -22,9 +21,10 @@ const HIDDEN_TYPES = ["secret", "env", "session"];
|
|
|
22
21
|
* recorded). `shows`, `lastShownAt` and the feedback counts `positive` and `negative` are read live from the
|
|
23
22
|
* user-attributed usage events within retention (`use`); `modifiedAt` is the file's modification time. A link joins two
|
|
24
23
|
* nodes by index and names its kind by index into `kinds`. `nodes.tags[i]` indexes `tags`, the asset's own frontmatter
|
|
25
|
-
* tags. `duplicates` pairs assets whose stored embeddings are nearly the same
|
|
26
|
-
*
|
|
27
|
-
*
|
|
24
|
+
* tags. `duplicates` pairs assets whose stored embeddings are nearly the same, and `groups` gives each asset its group by
|
|
25
|
+
* meaning and a place in 3D where alike assets sit close, as the last `akm index` stored them (index-layout-repository.ts);
|
|
26
|
+
* both are `null` when too few assets are embedded. An asset embedded since then has no group (-1) until the next
|
|
27
|
+
* build. Nothing is written.
|
|
28
28
|
*/
|
|
29
29
|
export async function graph() {
|
|
30
30
|
try {
|
|
@@ -65,6 +65,7 @@ function emptyGraph() {
|
|
|
65
65
|
},
|
|
66
66
|
links: { from: [], to: [], kind: [] },
|
|
67
67
|
duplicates: null,
|
|
68
|
+
groups: null,
|
|
68
69
|
};
|
|
69
70
|
}
|
|
70
71
|
async function readGraph() {
|
|
@@ -137,10 +138,41 @@ async function readGraph() {
|
|
|
137
138
|
result.links.to.push(to);
|
|
138
139
|
result.links.kind.push(kindCode(link.kind));
|
|
139
140
|
}
|
|
140
|
-
const
|
|
141
|
+
const layout = readLayout(db);
|
|
141
142
|
closeDatabase(db);
|
|
142
143
|
closed = true;
|
|
143
|
-
|
|
144
|
+
if (layout?.groups) {
|
|
145
|
+
const n = rows.length;
|
|
146
|
+
const groups = {
|
|
147
|
+
count: layout.groups,
|
|
148
|
+
group: new Array(n).fill(-1),
|
|
149
|
+
x: new Array(n).fill(0),
|
|
150
|
+
y: new Array(n).fill(0),
|
|
151
|
+
z: new Array(n).fill(0),
|
|
152
|
+
};
|
|
153
|
+
for (const p of layout.places) {
|
|
154
|
+
const i = index.get(p.id);
|
|
155
|
+
if (i === undefined)
|
|
156
|
+
continue;
|
|
157
|
+
groups.group[i] = p.grp;
|
|
158
|
+
groups.x[i] = p.x;
|
|
159
|
+
groups.y[i] = p.y;
|
|
160
|
+
groups.z[i] = p.z;
|
|
161
|
+
}
|
|
162
|
+
const pairs = layout.pairs.flatMap((p) => {
|
|
163
|
+
const a = index.get(p.a);
|
|
164
|
+
const b = index.get(p.b);
|
|
165
|
+
return a === undefined || b === undefined ? [] : [[a, b, p.cosine]];
|
|
166
|
+
});
|
|
167
|
+
result.groups = groups;
|
|
168
|
+
result.duplicates = {
|
|
169
|
+
threshold: layout.threshold,
|
|
170
|
+
a: pairs.map((p) => p[0]),
|
|
171
|
+
b: pairs.map((p) => p[1]),
|
|
172
|
+
cosine: pairs.map((p) => p[2]),
|
|
173
|
+
truncated: layout.truncated,
|
|
174
|
+
};
|
|
175
|
+
}
|
|
144
176
|
const noted = [`${rows.length} assets and ${result.links.from.length} links of the enabled bundles.`];
|
|
145
177
|
if (!use)
|
|
146
178
|
noted.push("Use counts are zero: no usage history is available.");
|
|
@@ -69,7 +69,7 @@ says so in the message (`remoteUnavailable` in the evidence) and is `unknown`, n
|
|
|
69
69
|
| `state-db-migrations` | Always `pass` in a normal run; the message lists the migrations this open applied and the pre-migration copy (`evidence.applied`, `evidence.backupPath`). `fail` when the open could not apply a pending migration, or a read-only run (`--read-only` or AKM Desktop) finds one pending, which it must not apply; this row is then the whole report. | Run `akm migrate apply`. |
|
|
70
70
|
| `task-history-read` | Always `pass`; reports the number of `task_history` rows read in the window. | None. |
|
|
71
71
|
| `active-runs` | `warn`: a task run has been active for more than 15 minutes, regardless of `--since`. The message names the tasks and their age. | Inspect with `akm doctor log --task <id>`. |
|
|
72
|
-
| `improve-failures` | `warn`: a recorded run failed, ended with an exception or exhausted its budget, or contains processing failures (reflection, distillation LLM, generic action, consolidation chunk or memory-inference failure), even when its outer result is `ok: true`. Includes manual runs; excludes dry runs and runs outside the selected window. Signal-only interruptions (`SIGINT`, `SIGTERM`, `SIGHUP`) are `unknown`, not assumed cancellation or processing failure. Successful no-work runs, no-change decisions and quality rejections are not failures. | Inspect `akm doctor --since <same window> --group-by run` and the recorded result/log. |
|
|
72
|
+
| `improve-failures` | `warn`: a recorded run failed, ended with an exception or exhausted its budget, or contains processing failures (reflection, distillation LLM, generic action, consolidation chunk, consolidation pair judgment or memory-inference failure), even when its outer result is `ok: true`. Includes manual runs; excludes dry runs and runs outside the selected window. Signal-only interruptions (`SIGINT`, `SIGTERM`, `SIGHUP`) are `unknown`, not assumed cancellation or processing failure. Successful no-work runs, no-change decisions and quality rejections are not failures. | Inspect `akm doctor --since <same window> --group-by run` and the recorded result/log. |
|
|
73
73
|
| `connections-and-harnesses` | One table of every configured connection (endpoint, whether its key is held — a `$VAR` set in this shell, a `credentials.json` entry, or none — and whether the endpoint answers) and harness (platform, whether its binary is on `PATH`, and with a probe its `--version`), then the work that runs on them: improve, judges, agents, extract, enrich, index, and embedding, each naming the connection or harness and the model it resolves to through the same resolver the calls use (`evidence.rows`, typed `connection`, `harness` or `process`). `warn` when a key variable is unset, an endpoint does not answer, a harness is not installed, several connections (or harnesses) are configured and none is called `default` (said once, with the fix: name one `default`), or a work row cannot resolve because of the config; `unknown` when neither a connection nor a harness is configured; otherwise `pass`. Endpoint reachability is one bounded `GET /models` and the version is the harness's own `--version`; with `--no-probe` neither runs and the message says so. | Correct the named connection, key or harness; run `akm setup` when nothing is configured. A work row whose parts run somewhere other than the row's own target lists them in `overrides`, each with the kind (connection or harness), name and model it runs on: that is a per-process pin, working as set. |
|
|
74
74
|
| `semantic-search` | What the last `akm index` recorded about semantic search, with the index's entry and vector counts read now; no model load, no request. An unreadable index is always `fail`, even with semantic search off, because keyword search needs it too. Otherwise `pass` when every entry has a vector (local: on `onnxruntime-node`) or `semanticSearchMode` is `off`; `warn` when vectors lag entries, local embeddings ran on another runtime, or akm offers no local embeddings on this platform (`unavailable: platform`, where keyword search or an endpoint is the default); `fail` when the last index found it `blocked` (endpoint or model download failed) or `unavailable: load` (the runtime could not be downloaded or did not load), with the reason; `unknown` before the first index. | Fix the reason named; for an unreadable index, repair access or move the damaged index aside, then run `akm index`. `warn` for the platform: `akm setup --embedding off` for keyword search, or `akm setup --embedding <model> --embedding-endpoint <url>` for a remote endpoint. |
|
|
75
75
|
| `task-fail-rate` | `warn`: at least 5% of task runs in the window failed, or one task with at least 5 runs fails at that rate. The message names the dominant `detail.reason` (`timeout`, `non_zero_exit`, `spawn_failed`, ...) when one reason is at least half of the command-task failures. | Inspect failed runs with `akm doctor log --task <id>` and `akm task doctor`. `evidence.agentFailureReasonCounts` breaks command-task failures down by reason. |
|
|
@@ -188,4 +188,4 @@ Process selection is resolved once by `resolveImprovePlan`. The plan holds every
|
|
|
188
188
|
|
|
189
189
|
The result is `AkmImproveResult` (`src/core/improve-types.ts`), `schemaVersion: 2`. Besides `strategy`, `scope`, `dryRun`, and `ok` it carries: `plannedRefs`, `plan` (the resolved process routing and gates), `actions`, `distillSkipped` (the folded `distill-skipped` actions), `validationFailures`, `schemaRepairs`, `consolidation`, `extract`, `memoryCleanup`, `memoryInference`, `skippedProcesses`, `triage`, `proactiveMaintenance`, `deadUrls`, `writtenPaths`, `preRunSync`, and `sync`. A run that found the lock held returns `skipped: { reason: "lock-held" }`.
|
|
190
190
|
|
|
191
|
-
`actions` entries are `{ ref, mode, result }` where `mode` is one of `reflect`, `reflect-skipped`, `reflect-guard-rejected`, `reflect-failed`, `distill`, `memory-prune`, `memory-inference`, or `error` (`ImproveActionMode`). `distill-skipped` is emitted per ref but folded into `distillSkipped` before the result is built. `reflect-cooldown` stays in the type for older rows; nothing emits it.
|
|
191
|
+
`actions` entries are `{ ref, mode, result }` where `mode` is one of `reflect`, `reflect-skipped`, `reflect-guard-rejected`, `reflect-failed`, `distill`, `memory-prune`, `memory-inference`, or `error` (`ImproveActionMode`). `distill-skipped` is emitted per ref but folded into `distillSkipped` before the result is built. `reflect-cooldown` stays in the type for older rows; nothing emits it. A reflect candidate the quality judge or a guard refuses is `reflect-guard-rejected`, a verdict on the content, not an execution failure; health counts it as `reflect.rejected` (and reads an older `reflect-failed` row whose `result.reason` is `quality_rejected` the same way). The consolidate pair pass reports pairs that did not settle in `pairPass.failedJudgments`, with `failureKinds` (`transport`, `parse`, `cancelled`, `other`) and up to 20 `failures`, each with a clipped one-line reason and never the prompt or reply; their initiators get no ledger row, so the pairs are retried next run.
|
|
@@ -16,7 +16,7 @@ ignored. Per-call tuning lives on a named connection under
|
|
|
16
16
|
2. **Walk.** `scanSourceDirs` walks each source (`walkStashFlat`, `src/indexer/walk/walker.ts`), groups files by directory, and decides per directory whether it can be skipped. A directory that is drained has each file recognized by its bundle's adapter (`adapter.recognize`, see [Classification](classification.md)).
|
|
17
17
|
3. **Persist.** `persistDirRecords` writes every drained directory in one transaction: the `entries` row, its `entries_fts` row, its `entry_fragments` row, and its `asset_links` rows. A changed embedding input deletes the entry's vector. Rows for files that left a directory are deleted in the same transaction. The same transaction records which library the rows are for (`index_meta.stashDir` and `stashDirs`): that is what makes the index usable (see [Usable index](#usable-index)). It takes the write lock up front (`BEGIN IMMEDIATE`), so a writer that overlaps it waits out the busy timeout instead of failing at once.
|
|
18
18
|
4. **Reconcile.** When every source was scanned completely, rows belonging to removed sources are dropped. With `--clean`, rows whose file is gone are deleted (`--dry-run` previews them; unreadable files keep their rows).
|
|
19
|
-
5. **Embed.** `runEmbeddingPass` generates vectors for entries without one under the configured model, then verifies semantic search state.
|
|
19
|
+
5. **Embed.** `runEmbeddingPass` generates vectors for entries without one under the configured model, then verifies semantic search state. When the stored vectors changed, `storeLayout` groups the embedded entries by meaning, places them in 3D and finds the near-duplicate pairs, and stores them in `entry_layout` and `duplicate_pairs` for `assets.graph`; on 20,000 entries this takes a few seconds, and an unchanged set of vectors skips it.
|
|
20
20
|
6. **Finalize.** Rebuild `entries_fts` if its totals are stale, re-link `state.db` usage events to the new entry ids, recompute `utility_scores` in one `index.db` transaction (improve and `akm doctor metrics` read utility; search ranking does not), clear orphaned `llm_enrichment_cache` rows, and (after a complete scan) record `builtAt` and `sourceOwners` in `index_meta`. Then `VACUUM` if due, and append an `index_completed` event with the phase timings.
|
|
21
21
|
|
|
22
22
|
The command returns the entry count, per-phase timings, warnings, the `--clean` result, and a `verification` block with `semanticStatus` (`disabled`, `pending`, `ready-js`, or `blocked`). The run computes it (`verifyIndexState`) and records it in `index_meta` under `semanticSearch` (`unavailable` when the local runtime could not be downloaded or loaded), which `akm doctor`'s `semantic-search` check reads.
|
|
@@ -120,7 +120,7 @@ Text mode shows a spinner. `--verbose` prints every phase message to stderr. In
|
|
|
120
120
|
|
|
121
121
|
## Tables and layout
|
|
122
122
|
|
|
123
|
-
`ensureSchema` creates
|
|
123
|
+
`ensureSchema` creates twelve tables (`index_meta`, `entries`, `entries_fts`, `entry_fragments`, `asset_links`, `embeddings`, `entry_layout`, `duplicate_pairs`, `utility_scores`, `index_dir_state`, `llm_enrichment_cache`, `registry_index_cache`); columns are in [Storage Locations](storage-locations.md). `usage_events` and workflow run state live in `state.db`.
|
|
124
124
|
|
|
125
125
|
`index_meta.version` is the layout number, currently 26. It is a marker, not a gate:
|
|
126
126
|
|