@fro.bot/systematic 3.31.6 → 3.32.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.
@@ -0,0 +1,399 @@
1
+ /**
2
+ * The deterministic core of the `ce:connect` helper: the rule index, the
3
+ * checks that decide which model-proposed candidates are published, the
4
+ * coverage check, the deterministic "already recorded" test and the digest.
5
+ *
6
+ * Import rule: node builtins, `frontmatter.ts` (js-yaml only), and the
7
+ * `connect-evidence.ts` and `connect-state.ts` modules. The `ce:connect` helper
8
+ * bundles this module, so it must never import zod, `config.ts` or
9
+ * `config-schema.ts`.
10
+ *
11
+ * Trust: the researcher is a model reading documents other people wrote, so a
12
+ * candidate is a proposal and nothing more. A candidate is published only when
13
+ * every path names a tracked, contained file of an allowed project, every
14
+ * fingerprint equals the hash taken when the run began, every excerpt appears
15
+ * verbatim in the file that is cited, every code citation still holds, and the
16
+ * rule id is one the index issued. Text in a candidate is never read as an
17
+ * instruction: it is length-capped, stripped of control characters and
18
+ * rendered as quoted evidence.
19
+ */
20
+ import { type ContainedRead, type InventoryFile, type InventoryRole } from './connect-evidence.js';
21
+ import type { CandidateRecord, CoverageRecord, Ledger } from './connect-state.js';
22
+ /**
23
+ * Where run state lives: `systematic/connect` under an absolute, non-empty
24
+ * `XDG_STATE_HOME`, else under `~/.local/state`. A relative `XDG_STATE_HOME`
25
+ * is ignored, as the XDG specification says.
26
+ */
27
+ export declare function resolveStateRoot(env: Readonly<Record<string, string | undefined>>, homeDir: string): string;
28
+ /** A short, stable key for a project, from its main-root identity. */
29
+ export declare function projectKey(mainRoot: string): string;
30
+ /** The directory name of a project, reduced to characters that survive a citation. */
31
+ export declare function projectName(mainRoot: string): string;
32
+ /**
33
+ * The id of a rule: one learning in one project. It depends on the project and
34
+ * the path only, never on the content, so a changed file keeps its id and
35
+ * reopens its ledger entry instead of making a new one.
36
+ */
37
+ export declare function ruleIdFor(mainRoot: string, relPath: string): string;
38
+ /** Characters kept from one section of a learning. */
39
+ export declare const SECTION_TEXT_CAP = 2000;
40
+ export interface RuleSection {
41
+ readonly text: string;
42
+ /** 1-based line of the heading in the file. */
43
+ readonly startLine: number;
44
+ readonly endLine: number;
45
+ readonly truncated: boolean;
46
+ }
47
+ export type RuleMissing = 'applies_when' | 'guidance' | 'prevention';
48
+ export interface RuleEntry {
49
+ readonly id: string;
50
+ /** The project's main root. */
51
+ readonly project: string;
52
+ readonly path: string;
53
+ readonly sha256: string;
54
+ readonly title?: string;
55
+ readonly appliesWhen: readonly string[];
56
+ readonly guidance?: RuleSection;
57
+ readonly prevention?: RuleSection;
58
+ readonly missing: readonly RuleMissing[];
59
+ /** The frontmatter did not parse. The sections are still read. */
60
+ readonly parseError: boolean;
61
+ }
62
+ export interface RuleSource {
63
+ readonly project: string;
64
+ readonly path: string;
65
+ readonly sha256: string;
66
+ }
67
+ /**
68
+ * Index one learning: its title, `applies_when`, and the Guidance and
69
+ * Prevention sections with their line bounds. What is missing and a
70
+ * frontmatter parse error are reported, never hidden.
71
+ */
72
+ export declare function extractRule(text: string, source: RuleSource): RuleEntry;
73
+ export interface ProvenanceCite {
74
+ /** The cited project's name, as `projectName` makes it. */
75
+ readonly project: string;
76
+ readonly path: string;
77
+ readonly fingerprint: string;
78
+ }
79
+ export interface ProvenanceIndexEntry {
80
+ /** The main root of the project whose learning this is. */
81
+ readonly project: string;
82
+ /** The learning's path in that project. */
83
+ readonly path: string;
84
+ readonly cites: readonly ProvenanceCite[];
85
+ readonly ruleIds: readonly string[];
86
+ }
87
+ /** `<project>:<path>@<fingerprint>`: how a learning cites text from another project. */
88
+ export declare function formatProvenanceCitation(project: string, relPath: string, fingerprint: string): string;
89
+ /** The provenance citations and rule ids a learning's text carries. */
90
+ export declare function scanProvenance(text: string): {
91
+ cites: ProvenanceCite[];
92
+ ruleIds: string[];
93
+ };
94
+ export declare const BATCH_VERSION = 1;
95
+ /** One rule family's report: what it covered and what it proposed. */
96
+ export interface Batch {
97
+ readonly version: 1;
98
+ readonly runId: string;
99
+ readonly family: string;
100
+ readonly ruleIds: readonly string[];
101
+ /** Main roots of the projects the family read. */
102
+ readonly projects: readonly string[];
103
+ readonly files: readonly string[];
104
+ readonly searches: readonly string[];
105
+ /** False when the family stopped before it covered its rules. */
106
+ readonly complete: boolean;
107
+ readonly candidates: readonly unknown[];
108
+ }
109
+ export type BatchParse = {
110
+ readonly ok: true;
111
+ readonly batch: Batch;
112
+ } | {
113
+ readonly ok: false;
114
+ readonly reason: 'malformed-batch' | 'batch-version';
115
+ };
116
+ /** Parse one batch file. The run id must be the run's own. */
117
+ export declare function parseBatch(text: string, runId: string): BatchParse;
118
+ export interface Coverage {
119
+ /** Indexed rules that no complete batch reported. */
120
+ readonly uncoveredRuleIds: readonly string[];
121
+ /** Allowed projects that no batch reported reading. */
122
+ readonly untouchedProjects: readonly string[];
123
+ /** Families that stopped before covering their rules. */
124
+ readonly incompleteFamilies: readonly string[];
125
+ }
126
+ export interface CoverageInput {
127
+ readonly ruleIds: readonly string[];
128
+ readonly projects: readonly string[];
129
+ readonly batches: readonly Batch[];
130
+ }
131
+ /**
132
+ * Whether the batches cover what the index issued. A model that is told to
133
+ * report nothing still has to name every rule id in a complete batch and every
134
+ * project it read, so silence cannot pass for a clean scan. A run with no
135
+ * rules has nothing to cover.
136
+ */
137
+ export declare function checkCoverage(input: CoverageInput): Coverage;
138
+ export interface OfferInput {
139
+ readonly rules: readonly RuleEntry[];
140
+ readonly coverage: readonly CoverageRecord[];
141
+ /** Rules one run is offered: families per run times rules per family. */
142
+ readonly size: number;
143
+ }
144
+ /** How a run was offered the index, and where the sweep stood when it began. */
145
+ export interface Offer {
146
+ /** Every indexed rule id, in the order they are offered. */
147
+ readonly order: readonly string[];
148
+ /** The head of `order`: the rules this run covers. */
149
+ readonly offered: readonly string[];
150
+ /** Offered rules that were never covered, or changed since they were. */
151
+ readonly fresh: readonly string[];
152
+ readonly total: number;
153
+ /** Indexed rules covered at their current hash when the run began. */
154
+ readonly coveredBefore: number;
155
+ readonly sliceSize: number;
156
+ }
157
+ /**
158
+ * Choose the rules a run covers. Every indexed rule is put in one order:
159
+ * first the rules never covered or changed since they were covered, then the
160
+ * covered rules from the least recently covered run to the most recent. Inside
161
+ * each of those groups the order is round-robin across projects, then by path,
162
+ * so a slice spans projects. The order depends on the index and the coverage
163
+ * records only, never on the model, so repeated runs sweep the whole index
164
+ * and then start over at the oldest.
165
+ */
166
+ export declare function planOffer(input: OfferInput): Offer;
167
+ /** Where the sweep over the index stands. */
168
+ export interface SweepProgress {
169
+ readonly total: number;
170
+ /** Rules covered at their current hash. */
171
+ readonly covered: number;
172
+ readonly coveredThisRun: number;
173
+ /** Runs of the slice size still needed to cover every rule, about. */
174
+ readonly runsLeft: number;
175
+ }
176
+ /** The sweep before a run covers anything. */
177
+ export declare function sweepBefore(offer: Pick<Offer, 'total' | 'coveredBefore' | 'sliceSize'>): SweepProgress;
178
+ /**
179
+ * The sweep after a committed run. A covered rule that was already covered at
180
+ * its current hash is covered this run but adds nothing to the total; an id
181
+ * the run was not offered counts for neither.
182
+ */
183
+ export declare function sweepProgress(offer: Pick<Offer, 'offered' | 'fresh' | 'total' | 'coveredBefore' | 'sliceSize'>, coveredRuleIds: readonly string[]): SweepProgress;
184
+ /** The one-line progress report of the digest header and the publish summary. */
185
+ export declare function renderSweepLine(progress: SweepProgress): string;
186
+ export declare const CANDIDATE_KINDS: readonly ['contradiction', 'transferable-lesson'];
187
+ export type CandidateKind = (typeof CANDIDATE_KINDS)[number];
188
+ export declare const NEXT_STEPS: readonly ['refresh-learning', 'compound-learning', 'investigate'];
189
+ export type NextStep = (typeof NEXT_STEPS)[number];
190
+ /** Limits on a candidate's fields. */
191
+ export declare const CANDIDATE_LIMITS: Readonly<{
192
+ title: 160;
193
+ summary: 800;
194
+ note: 400;
195
+ query: 200;
196
+ queries: 8;
197
+ excerptMin: 20;
198
+ excerptMax: 1500;
199
+ symbol: 200;
200
+ sources: 8;
201
+ targetEvidence: 8;
202
+ counterevidence: 8;
203
+ pathLength: 4096;
204
+ spanLines: 400;
205
+ }>;
206
+ export interface ProjectFacts {
207
+ /** The main root: the project's identity. */
208
+ readonly root: string;
209
+ readonly name: string;
210
+ readonly key: string;
211
+ /** The files the run's inventory hashed. */
212
+ readonly files: ReadonlyMap<string, {
213
+ readonly sha256: string;
214
+ readonly role: InventoryRole;
215
+ }>;
216
+ }
217
+ export declare function toProjectFacts(root: string, files: readonly InventoryFile[]): ProjectFacts;
218
+ export interface ValidationContext {
219
+ readonly projects: ReadonlyMap<string, ProjectFacts>;
220
+ readonly ruleIds: ReadonlySet<string>;
221
+ }
222
+ export interface ValidSource {
223
+ readonly project: string;
224
+ readonly projectName: string;
225
+ readonly path: string;
226
+ readonly fingerprint: string;
227
+ readonly excerpt: string;
228
+ /** How a learning cites this text: `<project>:<path>@<fingerprint>`. */
229
+ readonly cite: string;
230
+ }
231
+ export interface ValidTargetEvidence {
232
+ readonly path: string;
233
+ readonly start: number;
234
+ readonly end: number;
235
+ readonly symbol: string;
236
+ readonly fingerprint: string;
237
+ readonly excerpt: string;
238
+ }
239
+ export interface OverlapCheck {
240
+ readonly queries: readonly string[];
241
+ readonly result: 'none-found' | 'found';
242
+ readonly note?: string;
243
+ }
244
+ export interface ValidCandidate {
245
+ readonly kind: CandidateKind;
246
+ readonly ruleId: string;
247
+ /** The target project's main root. */
248
+ readonly target: string;
249
+ readonly targetName: string;
250
+ readonly title: string;
251
+ readonly summary: string;
252
+ readonly nextStep: NextStep;
253
+ readonly overlapCheck: OverlapCheck;
254
+ readonly sources: readonly ValidSource[];
255
+ readonly targetEvidence: readonly ValidTargetEvidence[];
256
+ readonly counterevidence: readonly ValidSource[];
257
+ }
258
+ export type DropReason = 'malformed-candidate' | 'unknown-kind' | 'unknown-rule-id' | 'rule-source-mismatch' | 'unknown-project' | 'absolute-path' | 'path-escape' | 'symlink-path' | 'untracked-path' | 'unsafe-path-character' | 'fingerprint-mismatch' | 'changed-since-begin' | 'excerpt-too-short' | 'excerpt-missing' | 'excerpt-lacks-symbol' | 'excerpt-outside-span' | 'citation-not-in-span' | 'citation-unchecked' | 'text-too-long' | 'invalid-text' | 'invalid-structure' | 'same-project-contradiction' | 'duplicate-candidate' | 'over-batch-cap';
259
+ export type CandidateCheck = {
260
+ readonly status: 'valid';
261
+ readonly candidate: ValidCandidate;
262
+ } | {
263
+ readonly status: 'dropped';
264
+ readonly reason: DropReason;
265
+ readonly detail?: string;
266
+ }
267
+ /** A cited file is gone since the run began. The candidate is held back and the run degrades. */
268
+ | {
269
+ readonly status: 'unresolved';
270
+ readonly missing: readonly string[];
271
+ };
272
+ /**
273
+ * Check one candidate the researcher proposed. Fields the contract does not
274
+ * name are never copied. The result is a validated candidate, a drop with its
275
+ * reason, or `unresolved` when a cited file vanished after the run began.
276
+ */
277
+ export declare function checkCandidate(raw: unknown, ctx: ValidationContext): CandidateCheck;
278
+ /**
279
+ * The record the ledger identifies a candidate by. A source's role carries the
280
+ * project key, so the same relative path in two projects stays two sources.
281
+ */
282
+ export declare function toCandidateRecord(candidate: ValidCandidate): CandidateRecord;
283
+ /**
284
+ * Ledger entries for the same kind and target whose source text reappears under
285
+ * another path. A rule id comes from the path, so a renamed learning is a new
286
+ * identity and the old entry is only pointed at. A person decides; nothing is
287
+ * matched or suppressed on this evidence.
288
+ */
289
+ export declare function findRenamedEntries(ledger: Ledger, record: CandidateRecord, id: string): string[];
290
+ /**
291
+ * Whether the target already records the connection: one of its learnings
292
+ * cites the same source path (by project name and path) or names the rule id.
293
+ * The test is lexical and deterministic. Such a candidate is listed as already
294
+ * recorded and is never proposed.
295
+ */
296
+ export declare function findRecorded(candidate: ValidCandidate, index: readonly ProvenanceIndexEntry[]): {
297
+ readonly pointer: string;
298
+ } | undefined;
299
+ export type Standing = 'new' | 'sources changed' | 'target changed';
300
+ export interface DigestCandidate {
301
+ readonly id: string;
302
+ readonly standing: Standing;
303
+ readonly refreshPointer?: string;
304
+ readonly possibleMatches: readonly string[];
305
+ readonly candidate: ValidCandidate;
306
+ }
307
+ export interface RecordedConnection {
308
+ readonly pointer: string;
309
+ readonly candidate: ValidCandidate;
310
+ }
311
+ export interface StaleCitation {
312
+ readonly project: string;
313
+ readonly document: string;
314
+ readonly line: number;
315
+ readonly path: string;
316
+ readonly start: number;
317
+ readonly end: number;
318
+ readonly result: 'not-in-span' | 'unchecked';
319
+ readonly foundElsewhere?: boolean;
320
+ readonly reason?: string;
321
+ }
322
+ export interface DigestProject {
323
+ readonly name: string;
324
+ readonly root: string;
325
+ readonly files: number;
326
+ /** No document holds a path-and-line citation, so none could be checked. */
327
+ readonly citationsUnsupported: boolean;
328
+ /** A bound stopped the inventory. */
329
+ readonly truncated: boolean;
330
+ }
331
+ export interface DigestModel {
332
+ readonly runId: string;
333
+ readonly outcome: 'complete' | 'degraded';
334
+ readonly generatedAt: string;
335
+ readonly mode: 'interactive' | 'headless';
336
+ readonly hostSupport: {
337
+ readonly supported: boolean;
338
+ readonly host?: string;
339
+ readonly version?: string;
340
+ readonly consented?: boolean;
341
+ };
342
+ readonly degradeReasons: readonly string[];
343
+ /** Where the sweep over the rule index stands after this run. */
344
+ readonly sweep?: SweepProgress;
345
+ readonly projects: readonly DigestProject[];
346
+ readonly unmatched: ReadonlyArray<{
347
+ readonly entry: string;
348
+ readonly reason: string;
349
+ }>;
350
+ readonly unread: readonly string[];
351
+ readonly dropped: Readonly<Record<string, number>>;
352
+ readonly discardedIncomplete: number;
353
+ readonly candidates: readonly DigestCandidate[];
354
+ readonly recorded: readonly RecordedConnection[];
355
+ readonly suppressed: number;
356
+ readonly staleCitations: readonly StaleCitation[];
357
+ readonly undecidedProvenance: ReadonlyArray<{
358
+ readonly project: string;
359
+ readonly path: string;
360
+ readonly cites: number;
361
+ }>;
362
+ }
363
+ /** Strip control and format characters. Line breaks stay; tabs become a space. */
364
+ export declare function sanitizeText(text: string): string;
365
+ /**
366
+ * Render the digest. All free text in it came from documents or from the
367
+ * researcher, so it appears only as block quotes and fenced excerpts with
368
+ * control characters removed. The digest is evidence for a person, and
369
+ * nothing in it is an instruction.
370
+ */
371
+ export declare function renderDigest(model: DigestModel): string;
372
+ /**
373
+ * The short chat summary of a run. Candidate titles are untrusted text, so they
374
+ * are quoted, one per line, and nothing in the summary reads as an instruction.
375
+ * Under each title the helper prints the promotion tokens for that candidate:
376
+ * `candidate:<run record path>` and `candidate-id:<id>` on one line, built from
377
+ * values the helper made and never from candidate text. A contradiction gets
378
+ * the `ce:compound-refresh` path scope of the target's learning instead, and a
379
+ * candidate whose next step is `investigate` gets a plain note.
380
+ */
381
+ export declare function renderSummary(model: DigestModel, digestPath: string, runRecordPath: string): string;
382
+ export declare function isWorkName(name: string): boolean;
383
+ /** `<state>/work/<runId>`: where one run keeps its snapshot and the researcher's batches. */
384
+ export declare function workDirPath(stateRoot: string, runId: string): string;
385
+ /** Remove every work directory. The lock is held, so any that exist are leftovers. */
386
+ export declare function cleanWorkRoot(stateRoot: string): void;
387
+ /** Create `work/<runId>` at 0700. Returns the directory, or undefined when it cannot be made safely. */
388
+ export declare function prepareWorkDir(stateRoot: string, runId: string): string | undefined;
389
+ export declare function removeWorkDir(stateRoot: string, runId: string): void;
390
+ /** Write a work file at 0600 by temporary file and rename. Throws on failure. */
391
+ export declare function writeWorkFile(dir: string, name: string, data: string): void;
392
+ /** Read a work file through the bounded reader: a regular file only, never a symlink. */
393
+ export declare function readWorkFile(dir: string, name: string, maxBytes: number): ContainedRead;
394
+ /** Bounds the helper enforces itself. */
395
+ export declare const BATCH_BOUNDS: Readonly<{
396
+ maxCandidatesPerBatch: 5;
397
+ maxRulesPerFamily: 8;
398
+ maxFamiliesPerRun: 6;
399
+ }>;