@dzhechkov/harness-core 0.3.50 → 0.3.54
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/dist/brain.d.ts +146 -4
- package/dist/brain.d.ts.map +1 -1
- package/dist/brain.js +437 -78
- package/dist/brain.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/src/brain.ts +500 -86
- package/src/index.ts +8 -0
package/dist/brain.d.ts
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
*
|
|
15
15
|
* @packageDocumentation
|
|
16
16
|
*/
|
|
17
|
-
import { type BookKUHit } from './book-kb.js';
|
|
17
|
+
import { type BookKU, type BookKUHit } from './book-kb.js';
|
|
18
18
|
/** The durable, cross-project brain home. `DZ_BRAIN_HOME` overrides `~/.dz/brain`. */
|
|
19
19
|
export declare function brainHome(): string;
|
|
20
20
|
/** Lexical (FTS5) store for the whole brain — all sources, source-tagged. */
|
|
@@ -31,6 +31,10 @@ export interface BrainSource {
|
|
|
31
31
|
readonly corpusVersion?: string;
|
|
32
32
|
readonly lang?: string;
|
|
33
33
|
readonly isbn?: string;
|
|
34
|
+
/** SPDX-ish license id — carried for repo sources (§8: refuse promoting unknown-license repos). */
|
|
35
|
+
readonly license?: string;
|
|
36
|
+
/** Relative path (from the brain home) to this source's capability card, e.g. `primers/<slug>.md`. */
|
|
37
|
+
readonly primer?: string;
|
|
34
38
|
readonly addedTs: string;
|
|
35
39
|
}
|
|
36
40
|
/** The brain registry — the durable list of everything ingested. */
|
|
@@ -47,11 +51,48 @@ export declare function readRegistry(home: string): BrainRegistry;
|
|
|
47
51
|
export declare function writeRegistry(home: string, reg: BrainRegistry): void;
|
|
48
52
|
/** List every registered source. `home` defaults to {@link brainHome}. */
|
|
49
53
|
export declare function listBrain(home?: string): BrainSource[];
|
|
54
|
+
/**
|
|
55
|
+
* Read reconstructed KUs from ANY `books.sqlite`-format lexical store (a project store, the brain
|
|
56
|
+
* store, or a per-source slice) — the single shared reader behind {@link promoteProjectToBrain},
|
|
57
|
+
* {@link buildPrimer}, {@link exportBrainSlice}, and {@link importBrainSlice}. `source` narrows to
|
|
58
|
+
* one book; default reads all. Synchronous (native `better-sqlite3` via `createRequire`) and
|
|
59
|
+
* best-effort: an absent store or unresolved dependency returns an honest `error`, never throws.
|
|
60
|
+
*/
|
|
61
|
+
export declare function readBookKus(opts: {
|
|
62
|
+
storePath: string;
|
|
63
|
+
depsRoot?: string;
|
|
64
|
+
source?: string;
|
|
65
|
+
}): {
|
|
66
|
+
kus: BookKU[];
|
|
67
|
+
error?: string;
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* Build a source's capability card (ADR-001 §5.4) by reading its KUs from the brain lexical store
|
|
71
|
+
* ({@link readBookKus}) + its registry entry, then rendering {@link buildPrimerMarkdown}. Best-effort:
|
|
72
|
+
* a missing store/source returns an honest `error` with empty `markdown`, never throws.
|
|
73
|
+
*/
|
|
74
|
+
export declare function buildPrimer(opts: {
|
|
75
|
+
brainHome?: string;
|
|
76
|
+
depsRoot?: string;
|
|
77
|
+
slug: string;
|
|
78
|
+
}): Promise<{
|
|
79
|
+
markdown: string;
|
|
80
|
+
error?: string;
|
|
81
|
+
}>;
|
|
82
|
+
/** Write a source's primer to `<brainHome>/primers/<slug>.md` (mkdir). Best-effort; honest error. */
|
|
83
|
+
export declare function writePrimer(opts: {
|
|
84
|
+
brainHome?: string;
|
|
85
|
+
depsRoot?: string;
|
|
86
|
+
slug: string;
|
|
87
|
+
}): Promise<{
|
|
88
|
+
path: string;
|
|
89
|
+
error?: string;
|
|
90
|
+
}>;
|
|
50
91
|
/**
|
|
51
92
|
* Promote a PROJECT's digitized book KB into the durable cross-project brain (ADR-001 P0
|
|
52
|
-
* `book-brain-register`). Reads the project's lexical `books.sqlite
|
|
53
|
-
*
|
|
54
|
-
*
|
|
93
|
+
* `book-brain-register`). Reads the project's lexical `books.sqlite` ({@link readBookKus}) and mirrors
|
|
94
|
+
* every KU into the brain via the shared {@link mirrorKusToBrain} path (lexical + vector + registry +
|
|
95
|
+
* primer). `kind: 'book'`.
|
|
55
96
|
*
|
|
56
97
|
* **Non-clobbering:** promoting the same book twice does not duplicate — the lexical upsert keys on
|
|
57
98
|
* `(book, ku_id, corpus_version)` and the vector rows are pre-deleted before re-index.
|
|
@@ -67,9 +108,109 @@ export declare function promoteProjectToBrain(opts: {
|
|
|
67
108
|
kus: number;
|
|
68
109
|
error?: string;
|
|
69
110
|
}>;
|
|
111
|
+
/**
|
|
112
|
+
* `dz brain update <slug>` backend (ADR-001 §11 P3 — non-destructive refresh). The project has
|
|
113
|
+
* re-ingested a source's book at a NEW `corpus_version`; this re-reads that source's CURRENT KUs
|
|
114
|
+
* from the PROJECT lexical store ({@link readBookKus} at the project `bookKbPath`, `source=slug`)
|
|
115
|
+
* and re-mirrors them into the brain via the shared {@link mirrorKusToBrain} path.
|
|
116
|
+
*
|
|
117
|
+
* **Non-clobbering + non-destructive:** the per-source stale-corpus eviction inside the reused
|
|
118
|
+
* `putBookKnowledge` upsert evicts THIS source's old-corpus rows and upserts the new ones, while
|
|
119
|
+
* OTHER sources are untouched. The primer is refreshed as part of the mirror. Reports the
|
|
120
|
+
* before/after KU counts (read directly from the brain, so `after` reflects the post-eviction set)
|
|
121
|
+
* and the new `corpusVersion`.
|
|
122
|
+
*
|
|
123
|
+
* Honest failure, no partial state: an unregistered source, or a project with no KUs for it, returns
|
|
124
|
+
* an `error` before any write happens.
|
|
125
|
+
*/
|
|
126
|
+
export declare function updateBrainSource(opts: {
|
|
127
|
+
brainHome?: string;
|
|
128
|
+
depsRoot?: string;
|
|
129
|
+
slug: string;
|
|
130
|
+
projectRoot: string;
|
|
131
|
+
addedTs: string;
|
|
132
|
+
}): Promise<{
|
|
133
|
+
before: number;
|
|
134
|
+
after: number;
|
|
135
|
+
corpusVersion?: string;
|
|
136
|
+
error?: string;
|
|
137
|
+
}>;
|
|
138
|
+
/**
|
|
139
|
+
* Export ONE source's KUs from the brain as a STANDALONE lexical-only `books.sqlite` slice at
|
|
140
|
+
* `outPath` (ADR-001 §8.1). Reads via {@link readBookKus} and writes via {@link putBookKnowledge} —
|
|
141
|
+
* lexical only; vectors re-embed on import. This is the portable, per-book shareable unit.
|
|
142
|
+
*/
|
|
143
|
+
export declare function exportBrainSlice(opts: {
|
|
144
|
+
brainHome?: string;
|
|
145
|
+
depsRoot?: string;
|
|
146
|
+
slug: string;
|
|
147
|
+
outPath: string;
|
|
148
|
+
}): Promise<{
|
|
149
|
+
kuCount: number;
|
|
150
|
+
error?: string;
|
|
151
|
+
}>;
|
|
152
|
+
/**
|
|
153
|
+
* Import a per-book slice ({@link exportBrainSlice} output, or a pack's `brain/<slug>.sqlite`) into
|
|
154
|
+
* the brain (ADR-001 §8.1). Reads the slice's KUs ({@link readBookKus}) and mirrors them via the same
|
|
155
|
+
* non-clobbering {@link mirrorKusToBrain} path as promote (upsert + re-embed + registry + primer).
|
|
156
|
+
*/
|
|
157
|
+
export declare function importBrainSlice(opts: {
|
|
158
|
+
brainHome?: string;
|
|
159
|
+
depsRoot?: string;
|
|
160
|
+
slicePath: string;
|
|
161
|
+
addedTs: string;
|
|
162
|
+
}): Promise<{
|
|
163
|
+
sources: string[];
|
|
164
|
+
kus: number;
|
|
165
|
+
error?: string;
|
|
166
|
+
}>;
|
|
167
|
+
/**
|
|
168
|
+
* Register an array of already-shaped KUs (from a repo deep-walk, §6, or raw JSON) into the brain via
|
|
169
|
+
* the shared {@link mirrorKusToBrain} path — the CLI `--from-kus` backend. `slug` is authoritative:
|
|
170
|
+
* every KU is registered under it (so a repo's `book` field is normalized to the source slug). The
|
|
171
|
+
* registry entry carries `kind` and, for `repo`, `license`.
|
|
172
|
+
*/
|
|
173
|
+
/**
|
|
174
|
+
* SPDX ids the license gate treats as clearly-permissive (auto-pass for repo ingest). Anything else
|
|
175
|
+
* — including an absent license — is refused unless `override:true`. Kept deliberately small and
|
|
176
|
+
* conservative (ADR §8: repos carry their own licenses; the brain must not silently ingest
|
|
177
|
+
* unknown/incompatible source into a redistributable slice).
|
|
178
|
+
*/
|
|
179
|
+
export declare const PERMISSIVE_LICENSES: readonly string[];
|
|
180
|
+
export declare function registerKusToBrain(opts: {
|
|
181
|
+
brainHome?: string;
|
|
182
|
+
depsRoot?: string;
|
|
183
|
+
kus: readonly BookKU[];
|
|
184
|
+
slug: string;
|
|
185
|
+
kind: 'repo' | 'book' | 'paper';
|
|
186
|
+
addedTs: string;
|
|
187
|
+
lang?: string;
|
|
188
|
+
license?: string;
|
|
189
|
+
override?: boolean;
|
|
190
|
+
}): Promise<{
|
|
191
|
+
kus: number;
|
|
192
|
+
error?: string;
|
|
193
|
+
}>;
|
|
194
|
+
/**
|
|
195
|
+
* A DETERMINISTIC lexical reranker (ADR-001 §11 P3 / G3) — lifts precision on the top-K without a
|
|
196
|
+
* model dependency, so the sync grounding path stays fast + offline. Scores each hit against the
|
|
197
|
+
* query's CONTENT TERMS (reusing {@link contentTerms}) by (a) term COVERAGE, (b) a FIELD WEIGHT
|
|
198
|
+
* (name > problem > content), and (c) a small type PRIOR, then returns the top-`limit` reordered.
|
|
199
|
+
* Fully deterministic: no clock, no random, stable tie-break by `kuId`.
|
|
200
|
+
*
|
|
201
|
+
* This is deliberately lexical: an ML cross-encoder reranker is OUT OF SCOPE for the sync path (it
|
|
202
|
+
* would make grounding slow + online + non-deterministic). A future model reranker is a drop-in
|
|
203
|
+
* swap BEHIND this same `(query, hits, opts) → hits` signature — callers never change.
|
|
204
|
+
*/
|
|
205
|
+
export declare function rerankHits(query: string, hits: BookKUHit[], opts?: {
|
|
206
|
+
limit?: number;
|
|
207
|
+
}): BookKUHit[];
|
|
70
208
|
/**
|
|
71
209
|
* Cross-source lexical recall over the whole brain — a thin, brain-home-scoped wrapper over
|
|
72
210
|
* {@link queryBookKnowledge}. `source` narrows to one source; default is cross-source. Never throws.
|
|
211
|
+
*
|
|
212
|
+
* `rerank` (default **false** — pure FTS order stays the default so nothing regresses): when true,
|
|
213
|
+
* over-fetch (`limit*3`, capped) then {@link rerankHits} down to `limit` for on-point top-K.
|
|
73
214
|
*/
|
|
74
215
|
export declare function queryBrain(opts: {
|
|
75
216
|
query: string;
|
|
@@ -78,6 +219,7 @@ export declare function queryBrain(opts: {
|
|
|
78
219
|
source?: string;
|
|
79
220
|
limit?: number;
|
|
80
221
|
match?: 'all' | 'any';
|
|
222
|
+
rerank?: boolean;
|
|
81
223
|
}): Promise<{
|
|
82
224
|
hits: BookKUHit[];
|
|
83
225
|
error?: string;
|
package/dist/brain.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../src/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,
|
|
1
|
+
{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../src/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,EAAoD,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAK7G,sFAAsF;AACtF,wBAAgB,SAAS,IAAI,MAAM,CAGlC;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAID,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mGAAmG;IACnG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CAC/C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAgBxD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAGpE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAEtD;AAmDD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAwBpC;AAsID;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAQhD;AAED,qGAAqG;AACrG,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5C;AAyGD;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAW9D;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+CrF;AAID;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAS/C;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAO9D;AAED;;;;;GAKG;AACH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAEhD,CAAC;AAEF,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA4B3C;AA2BD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EAAE,CAoBnG;AAID;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBjD;AAmDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDjF"}
|