@holmes-lab/holmes-kit 0.35.24 → 0.36.0

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.
Files changed (136) hide show
  1. package/CHANGELOG.md +363 -0
  2. package/README.md +4 -2
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-status.js +4 -1
  5. package/dist/holmes/cli/approve-watch.js +3 -1
  6. package/dist/holmes/cli/approve.d.ts +10 -0
  7. package/dist/holmes/cli/approve.js +34 -4
  8. package/dist/holmes/cli/claude-switches.d.ts +7 -1
  9. package/dist/holmes/cli/claude-switches.js +11 -7
  10. package/dist/holmes/cli/codex-toml.d.ts +3 -0
  11. package/dist/holmes/cli/codex-toml.js +2 -1
  12. package/dist/holmes/cli/doctor.d.ts +31 -1
  13. package/dist/holmes/cli/doctor.js +204 -7
  14. package/dist/holmes/cli/index.js +115 -4
  15. package/dist/holmes/cli/init.js +4 -3
  16. package/dist/holmes/cli/os-notify.d.ts +3 -1
  17. package/dist/holmes/cli/os-notify.js +10 -4
  18. package/dist/holmes/cli/review.d.ts +25 -0
  19. package/dist/holmes/cli/review.js +111 -0
  20. package/dist/holmes/cli/roles-readme.d.ts +11 -0
  21. package/dist/holmes/cli/roles-readme.js +38 -16
  22. package/dist/holmes/cli/roles.d.ts +12 -0
  23. package/dist/holmes/cli/roles.js +86 -0
  24. package/dist/holmes/cli/run.d.ts +65 -0
  25. package/dist/holmes/cli/run.js +308 -0
  26. package/dist/holmes/cli/runtime-binding-approval.js +3 -2
  27. package/dist/holmes/cli/runtime-binding.d.ts +30 -0
  28. package/dist/holmes/cli/runtime-binding.js +116 -11
  29. package/dist/holmes/cli/scratch.d.ts +12 -0
  30. package/dist/holmes/cli/scratch.js +20 -0
  31. package/dist/holmes/cli/test-platform.d.ts +16 -0
  32. package/dist/holmes/cli/test-platform.js +31 -1
  33. package/dist/holmes/config/config.d.ts +49 -0
  34. package/dist/holmes/config/config.js +146 -3
  35. package/dist/holmes/config/project-caps.d.ts +21 -0
  36. package/dist/holmes/config/project-caps.js +114 -0
  37. package/dist/holmes/governance/approval-queue.d.ts +17 -3
  38. package/dist/holmes/governance/approval-queue.js +51 -8
  39. package/dist/holmes/governance/autonomy.d.ts +6 -0
  40. package/dist/holmes/governance/autonomy.js +21 -0
  41. package/dist/holmes/governance/push-gate-runner.d.ts +8 -0
  42. package/dist/holmes/governance/push-gate-runner.js +49 -1
  43. package/dist/holmes/governance/replica-id.d.ts +9 -0
  44. package/dist/holmes/governance/replica-id.js +44 -7
  45. package/dist/holmes/governance/role-policy.d.ts +41 -1
  46. package/dist/holmes/governance/role-policy.js +137 -20
  47. package/dist/holmes/governance/run-mode.d.ts +14 -0
  48. package/dist/holmes/governance/run-mode.js +120 -0
  49. package/dist/holmes/governance/tool-actions.d.ts +30 -0
  50. package/dist/holmes/governance/tool-actions.js +121 -0
  51. package/dist/holmes/guardrail/agent-launch-policy.d.ts +15 -0
  52. package/dist/holmes/guardrail/agent-launch-policy.js +177 -0
  53. package/dist/holmes/guardrail/classification-mode.d.ts +17 -0
  54. package/dist/holmes/guardrail/classification-mode.js +135 -0
  55. package/dist/holmes/guardrail/dynamic-write.d.ts +43 -0
  56. package/dist/holmes/guardrail/dynamic-write.js +304 -0
  57. package/dist/holmes/guardrail/impact-gate.d.ts +2 -0
  58. package/dist/holmes/guardrail/impact-gate.js +34 -11
  59. package/dist/holmes/guardrail/phase.d.ts +2 -1
  60. package/dist/holmes/guardrail/phase.js +22 -8
  61. package/dist/holmes/guardrail/powershell-shell.d.ts +21 -0
  62. package/dist/holmes/guardrail/powershell-shell.js +801 -0
  63. package/dist/holmes/guardrail/refusal-codes.d.ts +24 -0
  64. package/dist/holmes/guardrail/refusal-codes.js +140 -0
  65. package/dist/holmes/guardrail/risk-classifier.d.ts +17 -0
  66. package/dist/holmes/guardrail/risk-classifier.js +255 -27
  67. package/dist/holmes/guardrail/risk-types.d.ts +16 -0
  68. package/dist/holmes/guardrail/run-plan-scope.d.ts +23 -0
  69. package/dist/holmes/guardrail/run-plan-scope.js +155 -0
  70. package/dist/holmes/guardrail/run-refusals.d.ts +116 -0
  71. package/dist/holmes/guardrail/run-refusals.js +348 -0
  72. package/dist/holmes/guardrail/run-stages.d.ts +67 -0
  73. package/dist/holmes/guardrail/run-stages.js +188 -0
  74. package/dist/holmes/guardrail/scope-judgment.d.ts +5 -1
  75. package/dist/holmes/guardrail/scope-judgment.js +8 -10
  76. package/dist/holmes/guardrail/scope-refusal-memory.d.ts +3 -0
  77. package/dist/holmes/guardrail/scope-refusal-memory.js +85 -0
  78. package/dist/holmes/guardrail/shell-words.js +7 -7
  79. package/dist/holmes/guardrail/write-target.d.ts +31 -2
  80. package/dist/holmes/guardrail/write-target.js +118 -16
  81. package/dist/holmes/hooks/pre-tool-use.d.ts +36 -2
  82. package/dist/holmes/hooks/pre-tool-use.js +740 -81
  83. package/dist/holmes/hooks/session-start.js +5 -3
  84. package/dist/holmes/hooks/stop.d.ts +35 -1
  85. package/dist/holmes/hooks/stop.js +142 -7
  86. package/dist/holmes/mcp/elicit-approval.js +4 -4
  87. package/dist/holmes/mcp/handlers/graph-operations.js +5 -5
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +2 -2
  89. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -1
  90. package/dist/holmes/mcp/handlers/operator-inspection.js +3 -1
  91. package/dist/holmes/mcp/handlers/phase-queries.js +16 -1
  92. package/dist/holmes/mcp/handlers/requirement-triage.js +2 -2
  93. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -3
  94. package/dist/holmes/mcp/handlers/spec-approval.js +56 -9
  95. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +1 -0
  96. package/dist/holmes/mcp/handlers/spec-lifecycle.js +3 -3
  97. package/dist/holmes/mcp/handlers/spec-queries.d.ts +7 -0
  98. package/dist/holmes/mcp/handlers/spec-queries.js +5 -0
  99. package/dist/holmes/mcp/handlers/workspace-queries.js +2 -2
  100. package/dist/holmes/mcp/handlers.d.ts +2 -3
  101. package/dist/holmes/mcp/handlers.js +22 -2
  102. package/dist/holmes/mcp/harness-attestation.d.ts +2 -0
  103. package/dist/holmes/mcp/harness-attestation.js +3 -1
  104. package/dist/holmes/mcp/operator-recovery.d.ts +2 -0
  105. package/dist/holmes/mcp/operator-recovery.js +4 -3
  106. package/dist/holmes/mcp/server.js +9 -0
  107. package/dist/holmes/mcp/tool-schemas.js +6 -3
  108. package/dist/holmes/project/npx-bin.d.ts +26 -0
  109. package/dist/holmes/project/npx-bin.js +272 -2
  110. package/dist/holmes/project/root.js +6 -1
  111. package/dist/holmes/project/run-records.d.ts +17 -0
  112. package/dist/holmes/project/run-records.js +126 -0
  113. package/dist/holmes/project/scratch-root.d.ts +12 -0
  114. package/dist/holmes/project/scratch-root.js +132 -0
  115. package/dist/holmes/review/mrp.d.ts +35 -0
  116. package/dist/holmes/review/mrp.js +119 -0
  117. package/dist/holmes/review/verdicts.d.ts +117 -0
  118. package/dist/holmes/review/verdicts.js +345 -0
  119. package/dist/holmes/runtime/dispatch.js +6 -3
  120. package/dist/holmes/semantic/cloud-usage.d.ts +20 -0
  121. package/dist/holmes/semantic/cloud-usage.js +106 -0
  122. package/dist/holmes/semantic/embedder.d.ts +15 -6
  123. package/dist/holmes/semantic/embedder.js +84 -3
  124. package/dist/holmes/semantic/local-model.d.ts +21 -2
  125. package/dist/holmes/semantic/local-model.js +14 -3
  126. package/dist/holmes/semantic/tier.d.ts +25 -0
  127. package/dist/holmes/semantic/tier.js +86 -1
  128. package/dist/holmes/semantic/vector-cache.d.ts +1 -0
  129. package/dist/holmes/semantic/vector-cache.js +4 -1
  130. package/dist/holmes/spec/approval-blockers.d.ts +11 -1
  131. package/dist/holmes/spec/approval-blockers.js +70 -2
  132. package/dist/holmes/spec/renumber.d.ts +1 -1
  133. package/dist/holmes/spec/renumber.js +5 -2
  134. package/dist/holmes/spec/transition-policy.d.ts +5 -7
  135. package/dist/holmes/spec/transition-policy.js +17 -2
  136. package/package.json +1 -1
@@ -0,0 +1,106 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.USAGE_RELPATH = void 0;
37
+ exports.recordCloudRequest = recordCloudRequest;
38
+ exports.cloudUsageSummary = cloudUsageSummary;
39
+ exports.cloudUsageLine = cloudUsageLine;
40
+ // @implements A-SPEC-476.5
41
+ const fs = __importStar(require("node:fs"));
42
+ const path = __importStar(require("node:path"));
43
+ /**
44
+ * Cloud embedding egress, counted where it leaves: one JSON line per HTTP request the cloud embedder sends (retries
45
+ * included), per project, by local calendar day. Supervisor 2026-10-19 00:20 (b): the jarvis ledger counts only its
46
+ * Python processes, so holmes-kit's own requests were invisible. The record is advisory — it never fails an embedding,
47
+ * and it holds neither the key nor any text.
48
+ */
49
+ exports.USAGE_RELPATH = path.join('.ax', 'state', 'semantic-usage.jsonl');
50
+ const READ_TAIL_BYTES = 4 * 1024 * 1024;
51
+ const localDay = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
52
+ function recordCloudRequest(root, texts, outcome, now = new Date()) {
53
+ try {
54
+ const file = path.join(root, exports.USAGE_RELPATH);
55
+ fs.mkdirSync(path.dirname(file), { recursive: true });
56
+ fs.appendFileSync(file, JSON.stringify({ day: localDay(now), texts, outcome }) + '\n');
57
+ }
58
+ catch { /* advisory: an unwritable state directory drops the record, never the embedding */ }
59
+ }
60
+ function cloudUsageSummary(root, now = new Date()) {
61
+ const zero = () => ({ requests: 0, texts: 0, failed: 0 });
62
+ const out = { today: zero(), last7: zero() };
63
+ let text;
64
+ try {
65
+ const file = path.join(root, exports.USAGE_RELPATH);
66
+ const size = fs.statSync(file).size;
67
+ const fd = fs.openSync(file, 'r');
68
+ try {
69
+ const len = Math.min(size, READ_TAIL_BYTES);
70
+ const buf = Buffer.alloc(len);
71
+ fs.readSync(fd, buf, 0, len, size - len);
72
+ text = buf.toString('utf8');
73
+ }
74
+ finally {
75
+ fs.closeSync(fd);
76
+ }
77
+ }
78
+ catch {
79
+ return out;
80
+ }
81
+ const today = localDay(now);
82
+ const window = new Set(Array.from({ length: 7 }, (_, i) => localDay(new Date(now.getFullYear(), now.getMonth(), now.getDate() - i))));
83
+ for (const line of text.split('\n')) {
84
+ let r;
85
+ try {
86
+ r = JSON.parse(line);
87
+ }
88
+ catch {
89
+ continue;
90
+ }
91
+ if (r === null || typeof r !== 'object' || typeof r.day !== 'string' || typeof r.texts !== 'number')
92
+ continue;
93
+ const add = (c) => { c.requests++; c.texts += r.texts; if (r.outcome !== 'ok')
94
+ c.failed++; };
95
+ if (window.has(r.day))
96
+ add(out.last7);
97
+ if (r.day === today)
98
+ add(out.today);
99
+ }
100
+ return out;
101
+ }
102
+ /** The doctor row text. */
103
+ function cloudUsageLine(s) {
104
+ const failed = s.last7.failed > 0 ? `, ${s.last7.failed} failed` : '';
105
+ return `today ${s.today.requests} requests (${s.today.texts} texts), last 7 days ${s.last7.requests} requests (${s.last7.texts} texts)${failed}`;
106
+ }
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import { type SemanticTier } from './tier';
19
19
  import { VectorCache } from './vector-cache';
20
+ import { type Pipeline } from './local-model';
20
21
  export interface SemanticRuntime {
21
22
  label: string;
22
23
  /** One text, awaited by the handler BEFORE the sync ranking; null on any failure. */
@@ -30,16 +31,15 @@ export interface SemanticRuntime {
30
31
  }>;
31
32
  }
32
33
  export interface EmbedderOpts {
33
- pipelineLoader?: (model: string) => Promise<(text: string, o: {
34
- pooling: string;
35
- normalize: boolean;
36
- }) => Promise<{
37
- data: Float32Array;
38
- }>>;
34
+ pipelineLoader?: (model: string) => Promise<Pipeline>;
35
+ /** The most tokens one local inference is given (A-SPEC-719.15); injectable so tests use a small one. */
36
+ tokenBudget?: number;
39
37
  fetchImpl?: typeof fetch;
40
38
  key?: string;
41
39
  sleep?: (ms: number) => Promise<void>;
42
40
  log?: (line: string) => void;
41
+ /** @implements A-SPEC-476.5 — replaces the per-request usage record (default: the cache's project). */
42
+ usage?: (texts: number, outcome: string) => void;
43
43
  }
44
44
  /**
45
45
  * @implements A-SPEC-719.3 — the local warm publishes a segment after this many new vectors, as the cloud warm does
@@ -47,4 +47,13 @@ export interface EmbedderOpts {
47
47
  * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
48
48
  */
49
49
  export declare const LOCAL_WARM_CHECKPOINT = 25;
50
+ /**
51
+ * The chunks a text is embedded as, each at most `budget` tokens where a separator allows it.
52
+ *
53
+ * @implements A-SPEC-719.15
54
+ * A blank line first, then a line break, then a space: adjacent segments are joined greedily while the joined text stays
55
+ * within the budget, and a segment that does not fit is split by the next separator. A segment with no separator left
56
+ * is kept whole — the tokenizer's cap (local-model.ts) bounds what the model is given. Pure.
57
+ */
58
+ export declare function chunkByTokens(text: string, budget: number, count: (t: string) => number): string[];
50
59
  export declare function makeTierEmbedder(tier: SemanticTier, cache: VectorCache, opts?: EmbedderOpts): SemanticRuntime | null;
@@ -1,8 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.LOCAL_WARM_CHECKPOINT = void 0;
4
+ exports.chunkByTokens = chunkByTokens;
4
5
  exports.makeTierEmbedder = makeTierEmbedder;
5
- // @implements A-SPEC-591
6
+ // @implements A-SPEC-591, A-SPEC-719.14, A-SPEC-719.15, A-SPEC-476.5
6
7
  // @implements A-SPEC-719.3
7
8
  // @implements A-SPEC-478
8
9
  /**
@@ -24,6 +25,7 @@ exports.makeTierEmbedder = makeTierEmbedder;
24
25
  */
25
26
  const tier_1 = require("./tier");
26
27
  const credentials_1 = require("./credentials");
28
+ const cloud_usage_1 = require("./cloud-usage");
27
29
  const local_model_1 = require("./local-model");
28
30
  const CLOUD_BATCH = 25;
29
31
  /**
@@ -32,6 +34,52 @@ const CLOUD_BATCH = 25;
32
34
  * documents for up to 1 h 53 min, and any worker ended before its last text landed nothing.
33
35
  */
34
36
  exports.LOCAL_WARM_CHECKPOINT = 25;
37
+ /**
38
+ * @implements A-SPEC-719.14 — one macrotask turn. The local runtime's inference settles without the event loop ever
39
+ * reaching its timer phase, so a warm that only awaits it is one uninterrupted job: measured 2026-10-18 on Windows, a
40
+ * 20 s timer had not fired after 100 s of BGE-M3 warm, and six refresh children outlived their deadline and their
41
+ * supersede watch (A-SPEC-719.1, 719.2). With this turn after each inference the same timer fired at 20.1 s.
42
+ */
43
+ const yieldToEventLoop = () => new Promise((resolve) => setImmediate(resolve));
44
+ /**
45
+ * The chunks a text is embedded as, each at most `budget` tokens where a separator allows it.
46
+ *
47
+ * @implements A-SPEC-719.15
48
+ * A blank line first, then a line break, then a space: adjacent segments are joined greedily while the joined text stays
49
+ * within the budget, and a segment that does not fit is split by the next separator. A segment with no separator left
50
+ * is kept whole — the tokenizer's cap (local-model.ts) bounds what the model is given. Pure.
51
+ */
52
+ function chunkByTokens(text, budget, count) {
53
+ const split = (t, separators) => {
54
+ if (count(t) <= budget || separators.length === 0)
55
+ return [t];
56
+ const [sep, ...rest] = separators;
57
+ const parts = t.split(sep);
58
+ if (parts.length === 1)
59
+ return split(t, rest);
60
+ const out = [];
61
+ let current = '';
62
+ for (const part of parts) {
63
+ const joined = current === '' ? part : current + sep + part;
64
+ if (count(joined) <= budget) {
65
+ current = joined;
66
+ continue;
67
+ }
68
+ if (current !== '')
69
+ out.push(current);
70
+ if (count(part) <= budget)
71
+ current = part;
72
+ else {
73
+ out.push(...split(part, rest));
74
+ current = '';
75
+ }
76
+ }
77
+ if (current !== '')
78
+ out.push(current);
79
+ return out;
80
+ };
81
+ return split(text, ['\n\n', '\n', ' ']);
82
+ }
35
83
  const CLOUD_BACKOFF_MS = 30_000;
36
84
  function makeTierEmbedder(tier, cache, opts = {}) {
37
85
  if (tier.tier === 'none' || tier.model === undefined)
@@ -40,6 +88,7 @@ function makeTierEmbedder(tier, cache, opts = {}) {
40
88
  if (tier.tier === 'local') {
41
89
  const tag = `${model}@${local_model_1.LOCAL_REVISION}-q8-${(0, tier_1.POOLING_OF)(model)}`;
42
90
  let pipe = null;
91
+ const budget = opts.tokenBudget ?? local_model_1.LOCAL_EMBED_TOKEN_BUDGET;
43
92
  const load = () => {
44
93
  if (pipe === null) {
45
94
  pipe = (opts.pipelineLoader ?? local_model_1.loadLocalPipeline)(model);
@@ -49,7 +98,27 @@ function makeTierEmbedder(tier, cache, opts = {}) {
49
98
  const embed = async (text) => {
50
99
  try {
51
100
  const p = await load();
52
- return Array.from((await p(text, { pooling: (0, tier_1.POOLING_OF)(model), normalize: true })).data);
101
+ const options = { pooling: (0, tier_1.POOLING_OF)(model), normalize: true };
102
+ const tokenizer = p.tokenizer;
103
+ // A text within the budget — and any text, for a pipeline that exposes no tokenizer — is one call, as before.
104
+ if (typeof tokenizer !== 'function')
105
+ return Array.from((await p(text, options)).data);
106
+ const count = (t) => tokenizer(t, { truncation: false }).input_ids.size;
107
+ if (count(text) <= budget)
108
+ return Array.from((await p(text, options)).data);
109
+ // @implements A-SPEC-719.15 — longer: chunks within the budget, pooled by the tokens each one gave the model.
110
+ let pooled = null;
111
+ for (const chunk of chunkByTokens(text, budget, count)) {
112
+ const v = (await p(chunk, options)).data;
113
+ const weight = Math.min(count(chunk), budget);
114
+ if (pooled === null)
115
+ pooled = new Array(v.length).fill(0);
116
+ for (let i = 0; i < v.length; i++)
117
+ pooled[i] += v[i] * weight;
118
+ await yieldToEventLoop(); // A-SPEC-719.14 — a long text cannot starve the child's timers either
119
+ }
120
+ const norm = Math.hypot(...pooled);
121
+ return pooled.map((x) => x / norm);
53
122
  }
54
123
  catch {
55
124
  pipe = null;
@@ -86,6 +155,7 @@ function makeTierEmbedder(tier, cache, opts = {}) {
86
155
  if (computed % exports.LOCAL_WARM_CHECKPOINT === 0)
87
156
  cache.flush(); // A-SPEC-719.3 — an ended worker keeps this much
88
157
  }
158
+ await yieldToEventLoop(); // A-SPEC-719.14 — after every attempted inference, failed ones included
89
159
  }
90
160
  cache.flush();
91
161
  return { computed, cached };
@@ -99,12 +169,23 @@ function makeTierEmbedder(tier, cache, opts = {}) {
99
169
  return null;
100
170
  const f = opts.fetchImpl ?? fetch;
101
171
  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
172
+ // @implements A-SPEC-476.5 — every HTTP request is counted (retries included); never the key, never a text.
173
+ const usage = opts.usage ?? ((n, outcome) => (0, cloud_usage_1.recordCloudRequest)(cache.root, n, outcome));
102
174
  const callBatch = async (texts, taskType) => {
103
175
  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:batchEmbedContents?key=${key}`;
104
176
  const body = JSON.stringify({ requests: texts.map((t) => ({ model: `models/${model}`, content: { parts: [{ text: t }] }, taskType })) });
105
177
  for (let attempt = 0; attempt < 5; attempt++) {
178
+ let res;
179
+ try {
180
+ res = await f(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
181
+ }
182
+ catch {
183
+ usage(texts.length, 'network');
184
+ opts.log?.('cloud embed network error');
185
+ return null;
186
+ }
187
+ usage(texts.length, res.ok ? 'ok' : `http-${res.status}`);
106
188
  try {
107
- const res = await f(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
108
189
  if (res.status === 429 || res.status >= 500) {
109
190
  opts.log?.(`cloud embed backoff (HTTP ${res.status})`);
110
191
  await sleep(CLOUD_BACKOFF_MS);
@@ -2,12 +2,31 @@ import { spawnSync } from 'node:child_process';
2
2
  import { LOCAL_REVISION, modelCacheDir, modelCacheReady, readLocalModelReadiness } from './model-cache';
3
3
  export { modelCacheDir, modelCacheReady, readLocalModelReadiness };
4
4
  export { LOCAL_REVISION };
5
- type Pipeline = (text: string, options: {
5
+ /** The runtime's tokenizer, as far as Holmes reads it: a token count, and the length it truncates at. */
6
+ export interface LocalTokenizer {
7
+ (text: string, options?: {
8
+ truncation?: boolean;
9
+ }): {
10
+ input_ids: {
11
+ size: number;
12
+ };
13
+ };
14
+ model_max_length?: number;
15
+ }
16
+ export type Pipeline = ((text: string, options: {
6
17
  pooling: string;
7
18
  normalize: boolean;
8
19
  }) => Promise<{
9
20
  data: Float32Array;
10
- }>;
21
+ }>) & {
22
+ tokenizer?: LocalTokenizer;
23
+ };
24
+ /**
25
+ * @implements A-SPEC-719.15 — the most tokens one local inference is given. BGE-M3's memory grows steeply with input
26
+ * length — measured 2026-10-18 on Windows (16 GB): 2.83 GB at 1,024 tokens, 3.75 GB at 2,048, past 9.19 GB at 4,096 —
27
+ * and requirement texts reach 28,946 tokens. A longer text is embedded in chunks of at most this many (embedder.ts).
28
+ */
29
+ export declare const LOCAL_EMBED_TOKEN_BUDGET = 2048;
11
30
  interface Runtime {
12
31
  pipeline(task: string, model: string, options: Record<string, unknown>): Promise<Pipeline>;
13
32
  }
@@ -1,10 +1,10 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.LOCAL_REVISION = exports.readLocalModelReadiness = exports.modelCacheReady = exports.modelCacheDir = void 0;
3
+ exports.LOCAL_EMBED_TOKEN_BUDGET = exports.LOCAL_REVISION = exports.readLocalModelReadiness = exports.modelCacheReady = exports.modelCacheDir = void 0;
4
4
  exports.loadLocalPipeline = loadLocalPipeline;
5
5
  exports.verifyLocalModel = verifyLocalModel;
6
6
  exports.runModelSetup = runModelSetup;
7
- // @implements A-SPEC-591, A-SPEC-712
7
+ // @implements A-SPEC-591, A-SPEC-712, A-SPEC-719.15
8
8
  const node_child_process_1 = require("node:child_process");
9
9
  const tier_1 = require("./tier");
10
10
  const model_cache_1 = require("./model-cache");
@@ -12,6 +12,12 @@ Object.defineProperty(exports, "LOCAL_REVISION", { enumerable: true, get: functi
12
12
  Object.defineProperty(exports, "modelCacheDir", { enumerable: true, get: function () { return model_cache_1.modelCacheDir; } });
13
13
  Object.defineProperty(exports, "modelCacheReady", { enumerable: true, get: function () { return model_cache_1.modelCacheReady; } });
14
14
  Object.defineProperty(exports, "readLocalModelReadiness", { enumerable: true, get: function () { return model_cache_1.readLocalModelReadiness; } });
15
+ /**
16
+ * @implements A-SPEC-719.15 — the most tokens one local inference is given. BGE-M3's memory grows steeply with input
17
+ * length — measured 2026-10-18 on Windows (16 GB): 2.83 GB at 1,024 tokens, 3.75 GB at 2,048, past 9.19 GB at 4,096 —
18
+ * and requirement texts reach 28,946 tokens. A longer text is embedded in chunks of at most this many (embedder.ts).
19
+ */
20
+ exports.LOCAL_EMBED_TOKEN_BUDGET = 2048;
15
21
  // TypeScript's CommonJS transform rewrites import() into require(), which cannot load this ESM
16
22
  // dependency on supported Node 20 versions. Preserve native dynamic import without shell code.
17
23
  const importRuntime = new Function('return import("@xenova/transformers")');
@@ -33,7 +39,12 @@ async function loadLocalPipeline(model = tier_1.LOCAL_MODEL, options = {}) {
33
39
  revision: model === tier_1.LOCAL_MODEL ? model_cache_1.LOCAL_REVISION : 'main',
34
40
  cache_dir: cacheDir,
35
41
  local_files_only: !options.download,
36
- })).catch(error => { cache.delete(key); throw error; });
42
+ })).then((pipe) => {
43
+ // @implements A-SPEC-719.15 — the tokenizer truncates at the budget: the bound for a piece no separator can split.
44
+ if (pipe.tokenizer)
45
+ pipe.tokenizer.model_max_length = exports.LOCAL_EMBED_TOKEN_BUDGET;
46
+ return pipe;
47
+ }).catch(error => { cache.delete(key); throw error; });
37
48
  cache.set(key, pending);
38
49
  return pending;
39
50
  }
@@ -31,7 +31,19 @@ export interface SemanticTier {
31
31
  localRuntimePresent?: boolean;
32
32
  /** Why local BGE-M3 was not activated, when readiness was observed. */
33
33
  localState?: LocalModelReadiness['state'];
34
+ /**
35
+ * @implements A-SPEC-476.1 — present when the project's `semantic.maxTier` lowered the tier or could not be read:
36
+ * the cap that applied, the source of a key it withheld (never the value), and the read problem if any.
37
+ */
38
+ cap?: {
39
+ maxTier: 'local' | 'none';
40
+ keyWithheld?: KeySource;
41
+ problem?: SemanticCapProblem;
42
+ };
34
43
  }
44
+ /** @implements A-SPEC-476.1 — the project cap: `cloud` is no cap. */
45
+ export type SemanticCap = 'cloud' | 'local' | 'none';
46
+ export type SemanticCapProblem = 'unreadable' | 'malformed';
35
47
  /**
36
48
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
37
49
  * S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
@@ -46,3 +58,16 @@ export declare function resolveSemanticTier(opts?: {
46
58
  localReadiness?: LocalModelReadiness;
47
59
  credentials?: CredentialOpts;
48
60
  }): SemanticTier;
61
+ /**
62
+ * @implements A-SPEC-476.1 — the project's cap, read on its own. `loadConfig` falls back to the default config on a broken
63
+ * file, and the default has no cap — cloud; a cap that cannot be read must fail toward none instead.
64
+ */
65
+ export declare function readSemanticCap(root: string): {
66
+ maxTier: SemanticCap;
67
+ problem?: SemanticCapProblem;
68
+ };
69
+ /**
70
+ * @implements A-SPEC-476.1 — the tier every semantic path uses: the machine's tier, lowered by the project's cap. The cap
71
+ * only lowers — no value of it produces cloud without a key in the chain — and a key it withholds is named by source.
72
+ */
73
+ export declare function resolveProjectSemanticTier(root: string, opts?: Parameters<typeof resolveSemanticTier>[0]): SemanticTier;
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-476, A-SPEC-712
2
+ // @implements A-SPEC-476, A-SPEC-712, A-SPEC-476.1
3
3
  /**
4
4
  * The semantic layer's tier structure — the owner's two-lever design made a contract:
5
5
  * maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
@@ -12,15 +12,53 @@
12
12
  * Consent model: setting GEMINI_API_KEY IS the opt-in. The tier resolver never probes the
13
13
  * network; presence signals only, so doctor can call it offline.
14
14
  */
15
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
16
+ if (k2 === undefined) k2 = k;
17
+ var desc = Object.getOwnPropertyDescriptor(m, k);
18
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
19
+ desc = { enumerable: true, get: function() { return m[k]; } };
20
+ }
21
+ Object.defineProperty(o, k2, desc);
22
+ }) : (function(o, m, k, k2) {
23
+ if (k2 === undefined) k2 = k;
24
+ o[k2] = m[k];
25
+ }));
26
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
27
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
28
+ }) : function(o, v) {
29
+ o["default"] = v;
30
+ });
31
+ var __importStar = (this && this.__importStar) || (function () {
32
+ var ownKeys = function(o) {
33
+ ownKeys = Object.getOwnPropertyNames || function (o) {
34
+ var ar = [];
35
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
36
+ return ar;
37
+ };
38
+ return ownKeys(o);
39
+ };
40
+ return function (mod) {
41
+ if (mod && mod.__esModule) return mod;
42
+ var result = {};
43
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
44
+ __setModuleDefault(result, mod);
45
+ return result;
46
+ };
47
+ })();
15
48
  Object.defineProperty(exports, "__esModule", { value: true });
16
49
  exports.CLOUD_MODEL = exports.LOCAL_MODEL = void 0;
17
50
  exports.POOLING_OF = POOLING_OF;
18
51
  exports.resolveSemanticTier = resolveSemanticTier;
52
+ exports.readSemanticCap = readSemanticCap;
53
+ exports.resolveProjectSemanticTier = resolveProjectSemanticTier;
54
+ const fs = __importStar(require("node:fs"));
55
+ const path = __importStar(require("node:path"));
19
56
  const credentials_1 = require("./credentials");
20
57
  const model_cache_1 = require("./model-cache");
21
58
  Object.defineProperty(exports, "LOCAL_MODEL", { enumerable: true, get: function () { return model_cache_1.LOCAL_MODEL; } });
22
59
  /** The opt-in cloud tier's model (S-491 four-arm winner). */
23
60
  exports.CLOUD_MODEL = 'gemini-embedding-001';
61
+ const CAPS = ['cloud', 'local', 'none'];
24
62
  /**
25
63
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
26
64
  * S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
@@ -47,6 +85,9 @@ function resolveSemanticTier(opts = {}) {
47
85
  if (found !== null) {
48
86
  return { tier: 'cloud', model: exports.CLOUD_MODEL, egress: true, keySource: found.source };
49
87
  }
88
+ return localOrNone(opts);
89
+ }
90
+ function localOrNone(opts) {
50
91
  // @implements A-SPEC-594 — availability is a CONJUNCTION. Once @xenova/transformers became a
51
92
  // required dependency, `localModulePresent()` answered true for every install and stopped
52
93
  // discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
@@ -59,3 +100,47 @@ function resolveSemanticTier(opts = {}) {
59
100
  return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}),
60
101
  ...(hasModule && observed && !observed.ready ? { localState: observed.state } : {}) };
61
102
  }
103
+ /**
104
+ * @implements A-SPEC-476.1 — the project's cap, read on its own. `loadConfig` falls back to the default config on a broken
105
+ * file, and the default has no cap — cloud; a cap that cannot be read must fail toward none instead.
106
+ */
107
+ function readSemanticCap(root) {
108
+ const f = path.join(root, 'ax.config.json');
109
+ let text;
110
+ try {
111
+ text = fs.readFileSync(f, 'utf8');
112
+ }
113
+ catch (e) {
114
+ return e.code === 'ENOENT' ? { maxTier: 'cloud' } : { maxTier: 'none', problem: 'unreadable' };
115
+ }
116
+ let parsed;
117
+ try {
118
+ parsed = JSON.parse(text);
119
+ }
120
+ catch {
121
+ return { maxTier: 'none', problem: 'unreadable' };
122
+ }
123
+ if (parsed === null || typeof parsed !== 'object' || !('semantic' in parsed))
124
+ return { maxTier: 'cloud' };
125
+ const semantic = parsed.semantic;
126
+ if (semantic === null || typeof semantic !== 'object' || Array.isArray(semantic))
127
+ return { maxTier: 'none', problem: 'malformed' };
128
+ if (!('maxTier' in semantic))
129
+ return { maxTier: 'cloud' };
130
+ const declared = semantic.maxTier;
131
+ return CAPS.includes(declared) ? { maxTier: declared } : { maxTier: 'none', problem: 'malformed' };
132
+ }
133
+ /**
134
+ * @implements A-SPEC-476.1 — the tier every semantic path uses: the machine's tier, lowered by the project's cap. The cap
135
+ * only lowers — no value of it produces cloud without a key in the chain — and a key it withholds is named by source.
136
+ */
137
+ function resolveProjectSemanticTier(root, opts = {}) {
138
+ const cap = readSemanticCap(root);
139
+ if (cap.maxTier === 'cloud')
140
+ return resolveSemanticTier(opts);
141
+ const found = (0, credentials_1.resolveSemanticKey)({ env: opts.env ?? process.env, ...opts.credentials });
142
+ const capInfo = { maxTier: cap.maxTier, ...(found !== null ? { keyWithheld: found.source } : {}), ...(cap.problem ? { problem: cap.problem } : {}) };
143
+ if (cap.maxTier === 'none')
144
+ return { tier: 'none', egress: false, cap: capInfo };
145
+ return { ...localOrNone(opts), cap: capInfo };
146
+ }
@@ -3,6 +3,7 @@ export declare const COMPACTION_THRESHOLD = 16;
3
3
  /** Age after which a compaction lock or an abandoned `.tmp` is considered orphaned by a dead writer. */
4
4
  export declare const STALE_MS: number;
5
5
  export declare class VectorCache {
6
+ readonly root: string;
6
7
  private readonly file;
7
8
  private readonly dir;
8
9
  private readonly lock;
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.VectorCache = exports.STALE_MS = exports.COMPACTION_THRESHOLD = void 0;
37
- // @implements A-SPEC-476
37
+ // @implements A-SPEC-476, A-SPEC-476.5
38
38
  // @implements A-SPEC-630
39
39
  /**
40
40
  * Content-addressed vector cache: never compute the same embedding twice, never serve a stale
@@ -126,12 +126,15 @@ function segmentName() {
126
126
  return `${String(lastStamp).padStart(15, '0')}-${String(process.pid).padStart(8, '0')}-${(0, node_crypto_1.randomBytes)(4).toString('hex')}.json`;
127
127
  }
128
128
  class VectorCache {
129
+ root;
129
130
  file;
130
131
  dir;
131
132
  lock;
132
133
  store = null;
133
134
  dirty = new Set();
135
+ // @implements A-SPEC-476.5 — the project the cache serves; the cloud embedder counts its requests against it.
134
136
  constructor(root) {
137
+ this.root = root;
135
138
  this.file = path.join(root, FILE);
136
139
  this.dir = path.join(root, SEGMENT_DIR);
137
140
  this.lock = path.join(this.dir, LOCK_DIR);
@@ -26,6 +26,7 @@ import { Spec } from './spec-parser';
26
26
  * ("남아 있는 TODO 주석을 제거한다"), and every one carries real content beside it.
27
27
  */
28
28
  export declare function placeholderSections(spec: Spec): string[];
29
+ export declare function scaffoldSections(spec: Spec): string[];
29
30
  /**
30
31
  * Codes that `validateSpec` reports but approval itself supplies, so they are not blockers.
31
32
  * Exported because `spec_approve` filters by the same set — two hand-maintained lists were how the
@@ -44,6 +45,13 @@ export declare const placeholderMessage: (sections: string[]) => string;
44
45
  /** The one wording for an unsealed parent. Shared so a second, degraded copy cannot appear. */
45
46
  export declare const unsealedParentMessage: (pid: string) => string;
46
47
  export declare function parentBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
48
+ /**
49
+ * @implements A-SPEC-182.3 — the chain above the direct parents (which `parentBlockers` judges): one message per
50
+ * ancestor that is not approved. A-SPEC-102.2–102.6 were sealed under the approved H-SPEC-102 while REQ-102 was draft.
51
+ * Cycles end; depth is bounded. A missing direct parent is validateSpec's finding; a missing ancestor above it is one
52
+ * here (@implements A-SPEC-182.4 — skipping it sealed a chain whose top no spec carries).
53
+ */
54
+ export declare function ancestorBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
47
55
  /**
48
56
  * Every reason `spec` cannot be approved right now. Empty means nothing is in the way.
49
57
  *
@@ -51,7 +59,9 @@ export declare function parentBlockers(spec: Spec, resolve: (id: string) => Spec
51
59
  * placeholders. Pure — it reads the spec objects it is handed and touches no filesystem, because
52
60
  * the gate calls it from a PreToolUse hook on every tool call.
53
61
  */
54
- export declare function approvalBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
62
+ export declare function approvalBlockers(spec: Spec, resolve: (id: string) => Spec | null, opts?: {
63
+ scaffold?: boolean;
64
+ }): string[];
55
65
  /** The separator between one spec's blockers. Shared so nothing re-splits on a guessed delimiter. */
56
66
  export declare const BLOCKER_SEP = "; ";
57
67
  /**