@fro.bot/systematic 3.32.3 → 3.33.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.
@@ -137,7 +137,10 @@ export interface CoverageInput {
137
137
  export declare function checkCoverage(input: CoverageInput): Coverage;
138
138
  export interface OfferInput {
139
139
  readonly rules: readonly RuleEntry[];
140
+ /** The ledger's coverage, of every selection. Only the records of `selection` count. */
140
141
  readonly coverage: readonly CoverageRecord[];
142
+ /** The run's selection id; left out, the run has no selection. */
143
+ readonly selection?: string;
141
144
  /** Rules one run is offered: families per run times rules per family. */
142
145
  readonly size: number;
143
146
  }
@@ -161,7 +164,8 @@ export interface Offer {
161
164
  * each of those groups the order is round-robin across projects, then by path,
162
165
  * so a slice spans projects. The order depends on the index and the coverage
163
166
  * records only, never on the model, so repeated runs sweep the whole index
164
- * and then start over at the oldest.
167
+ * and then start over at the oldest. Coverage belongs to a selection: a rule
168
+ * that only another selection covered is not covered here.
165
169
  */
166
170
  export declare function planOffer(input: OfferInput): Offer;
167
171
  /** Where the sweep over the index stands. */
@@ -269,6 +273,7 @@ export type CandidateCheck = {
269
273
  readonly status: 'unresolved';
270
274
  readonly missing: readonly string[];
271
275
  };
276
+ export declare function pathProblem(rel: unknown): DropReason | undefined;
272
277
  /**
273
278
  * Check one candidate the researcher proposed. Fields the contract does not
274
279
  * name are never copied. The result is a validated candidate, a drop with its
@@ -340,6 +345,8 @@ export interface DigestModel {
340
345
  readonly consented?: boolean;
341
346
  };
342
347
  readonly degradeReasons: readonly string[];
348
+ /** What the run was narrowed to. */
349
+ readonly selection?: Selection;
343
350
  /** Where the sweep over the rule index stands after this run. */
344
351
  readonly sweep?: SweepProgress;
345
352
  readonly projects: readonly DigestProject[];
@@ -379,6 +386,10 @@ export interface DroppedCandidate {
379
386
  export declare const NO_TITLE = "(no title)";
380
387
  /** Name a dropped candidate from its raw form, which may be anything. */
381
388
  export declare function nameDropped(family: string, raw: unknown, reason: string): DroppedCandidate;
389
+ /** Render untrusted prose as a block quote, so it cannot become a heading or a list. */
390
+ export declare function quote(text: string): string;
391
+ export declare function inline(text: string): string;
392
+ export declare function renderCandidate(item: DigestCandidate, index: number): string[];
382
393
  /**
383
394
  * Render the digest. All free text in it came from documents or from the
384
395
  * researcher, so it appears only as block quotes and fenced excerpts with
@@ -386,6 +397,16 @@ export declare function nameDropped(family: string, raw: unknown, reason: string
386
397
  * nothing in it is an instruction.
387
398
  */
388
399
  export declare function renderDigest(model: DigestModel): string;
400
+ /** A run record path that can be pasted as one `candidate:` token: no whitespace, no control character. */
401
+ export declare function isPasteablePath(file: string): boolean;
402
+ /**
403
+ * The next step for one candidate, built from values the helper made and never
404
+ * from candidate text. A lesson is promoted by `ce:compound` from its tokens. A
405
+ * contradiction is promoted by `ce:compound-refresh` with the exact path of the
406
+ * target's own learning, which `ce:compound` refuses. A candidate to
407
+ * investigate has nothing to promote yet.
408
+ */
409
+ export declare function handoffLine(item: DigestModel['candidates'][number], runRecordPath: string, pasteable: boolean): string;
389
410
  /**
390
411
  * The short chat summary of a run. Candidate titles are untrusted text, so they
391
412
  * are quoted, one per line, and nothing in the summary reads as an instruction.
@@ -414,3 +435,91 @@ export declare const BATCH_BOUNDS: Readonly<{
414
435
  maxRulesPerFamily: 8;
415
436
  maxFamiliesPerRun: 6;
416
437
  }>;
438
+ /** The most words one request may carry. */
439
+ export declare const MAX_SELECTION_WORDS = 32;
440
+ /** The most characters in one word. */
441
+ export declare const MAX_SELECTION_WORD_LENGTH = 2048;
442
+ /** What a run reads: the whole allow list, a named group, or picked projects. */
443
+ export type Selection = {
444
+ readonly kind: 'all';
445
+ } | {
446
+ readonly kind: 'group';
447
+ readonly name: string;
448
+ readonly id: string;
449
+ } | {
450
+ readonly kind: 'projects';
451
+ readonly picks: readonly string[];
452
+ readonly id: string;
453
+ };
454
+ /** An allow-list entry that resolved to a project. */
455
+ export interface SelectionProject {
456
+ readonly entry: string;
457
+ readonly mainRoot: string;
458
+ }
459
+ export type MemberResolution = {
460
+ readonly status: 'resolved';
461
+ readonly mainRoot: string;
462
+ } | {
463
+ readonly status: 'unmatched';
464
+ readonly reason: string;
465
+ };
466
+ export interface SelectionRequest {
467
+ /** The `group:` and `projects:` words, as the skill collected them. */
468
+ readonly words: readonly string[];
469
+ /** The merged `connect.groups` of the user config, by name. */
470
+ readonly groups: Readonly<Record<string, readonly string[]>>;
471
+ /** The resolved allow list, in its own order. */
472
+ readonly allowed: readonly SelectionProject[];
473
+ /** Resolve one group member the way an allow-list entry resolves. */
474
+ readonly resolveMember: (entry: string) => MemberResolution;
475
+ }
476
+ export type SelectionRefusal = {
477
+ readonly reason: 'conflicting-selection';
478
+ readonly detail: string;
479
+ } | {
480
+ readonly reason: 'unknown-group';
481
+ readonly group: string;
482
+ } | {
483
+ readonly reason: 'unknown-project';
484
+ readonly project: string;
485
+ } | {
486
+ readonly reason: 'ambiguous-project';
487
+ readonly project: string;
488
+ readonly keys: readonly string[];
489
+ } | {
490
+ readonly reason: 'group-member-not-allowed';
491
+ readonly group: string;
492
+ readonly member: string;
493
+ readonly memberReason?: string;
494
+ };
495
+ export type SelectionResult = {
496
+ readonly status: 'ok';
497
+ readonly selection: Selection;
498
+ /** The selected projects, in allow-list order. */
499
+ readonly projects: readonly SelectionProject[];
500
+ }
501
+ /** The words are not a well-formed request. */
502
+ | {
503
+ readonly status: 'invalid';
504
+ } | {
505
+ readonly status: 'refused';
506
+ readonly refusal: SelectionRefusal;
507
+ };
508
+ /**
509
+ * The coverage namespace of a selection: its id, or nothing for a run with no
510
+ * selection, whose coverage carries no selection field.
511
+ */
512
+ export declare function selectionNamespace(selection: Selection): string | undefined;
513
+ /** The id of a selection: a hash of the sorted project keys, so only membership counts. */
514
+ export declare function selectionIdFor(keys: readonly string[]): string;
515
+ /**
516
+ * Turn the selection words of a request into the projects a run reads. Pure:
517
+ * the caller supplies the groups, the resolved allow list and the member
518
+ * resolver. A selection only narrows the allow list; a project that is not on
519
+ * it is refused, never added.
520
+ *
521
+ * Order of checks: a malformed word, then a conflict, then the lookups. Words
522
+ * that repeat identically count once; `projects:a,b` and `projects:b,a` are
523
+ * different words and conflict.
524
+ */
525
+ export declare function resolveSelection(request: SelectionRequest): SelectionResult;
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Import for `ce:connect`: take the run record of a scheduled run, which names
3
+ * projects by the paths of a runner that no longer exists, and re-check every
4
+ * candidate in it against the operator's own checkouts.
5
+ *
6
+ * Trust: the record is untrusted input, downloaded by the skill and handed over
7
+ * as a directory. This module opens `run.json` in it and nothing else. Nothing
8
+ * the record says is believed. A project is matched by its recorded `owner/repo`
9
+ * to exactly one allowed local checkout. The rule id, the roles, the target
10
+ * root and the candidate id are computed again from local roots, and every
11
+ * fingerprint, excerpt and cited span is checked against the local files by the
12
+ * same `checkCandidate` a local run uses. The recorded id is checked only to
13
+ * detect a record that was edited, and is never used.
14
+ *
15
+ * Import rule: node builtins and the `connect-*` modules. The `ce:connect`
16
+ * helper bundles this module, so it must never import zod, `config.ts` or
17
+ * `config-schema.ts`.
18
+ */
19
+ import { type DigestCandidate, type ProjectFacts, type ValidCandidate } from './connect-helper-core.js';
20
+ import { type CandidateRecord } from './connect-state.js';
21
+ /** The record's fixed place in the downloaded directory. */
22
+ export declare const IMPORT_RECORD_FILE = "run.json";
23
+ export declare const MAX_IMPORT_RECORD_BYTES: number;
24
+ /** Why a downloaded record cannot be used at all. */
25
+ export type RecordFailure = 'directory-unreadable' | 'record-missing' | 'record-symlink' | 'record-not-regular' | 'record-too-large' | 'record-unreadable' | 'record-malformed' | 'record-schema-version';
26
+ /** A project of the run as the record names it. */
27
+ export interface ImportProject {
28
+ readonly root: string;
29
+ readonly key: string;
30
+ readonly name: string;
31
+ readonly repo?: string;
32
+ readonly commit?: string;
33
+ }
34
+ export interface ImportRecord {
35
+ /** The run's own id, from the record. */
36
+ readonly runId: string;
37
+ readonly projects: readonly ImportProject[];
38
+ /** Each candidate as recorded. Checked one by one, never trusted. */
39
+ readonly candidates: readonly unknown[];
40
+ }
41
+ export type RecordRead = {
42
+ readonly status: 'ok';
43
+ readonly record: ImportRecord;
44
+ } | {
45
+ readonly status: 'failed';
46
+ readonly reason: RecordFailure;
47
+ };
48
+ /** Check the parts of a record that every candidate depends on. */
49
+ export declare function parseImportRecord(value: unknown): RecordRead;
50
+ /**
51
+ * Read `run.json` from a downloaded directory. The directory is resolved to a
52
+ * real path once; the record is then read through the contained reader, which
53
+ * refuses a symlink, a non-regular file and a record over the size bound. No
54
+ * other entry of the directory is listed, opened or followed.
55
+ */
56
+ export declare function readImportRecord(directory: string): RecordRead;
57
+ /** An allowed local checkout. */
58
+ export interface LocalCheckout {
59
+ readonly root: string;
60
+ readonly key: string;
61
+ readonly name: string;
62
+ readonly repo?: string;
63
+ readonly commit?: string;
64
+ }
65
+ export type MappingRefusal = 'project-without-repo' | 'repo-not-allowed' | 'repo-ambiguous';
66
+ export type ProjectMapping = {
67
+ readonly status: 'mapped';
68
+ readonly local: LocalCheckout;
69
+ } | {
70
+ readonly status: 'unmapped';
71
+ readonly reason: MappingRefusal;
72
+ /** The keys of the local checkouts that share the repository. */
73
+ readonly keys?: readonly string[];
74
+ };
75
+ /** Match a recorded project to exactly one allowed local checkout by `owner/repo`. */
76
+ export declare function mapProject(project: ImportProject, locals: readonly LocalCheckout[]): ProjectMapping;
77
+ /** One recorded project and where it landed, for the answer. */
78
+ export interface ProjectReport {
79
+ readonly name: string;
80
+ readonly repo?: string;
81
+ readonly ciCommit?: string;
82
+ readonly status: 'mapped' | MappingRefusal;
83
+ readonly localRoot?: string;
84
+ readonly localKey?: string;
85
+ readonly localName?: string;
86
+ readonly localCommit?: string;
87
+ }
88
+ export type RefusalReason = 'candidate-malformed' | 'duplicate-candidate' | 'candidate-id-mismatch' | 'project-not-in-record' | MappingRefusal | 'project-unreadable' | 'path-rejected' | 'rule-id-mismatch' | 'file-not-tracked' | 'file-symlink' | 'file-changed' | 'file-vanished' | 'check-failed';
89
+ /** The fixed text for each refusal. */
90
+ export declare const REFUSAL_TEXT: Readonly<Record<RefusalReason, string>>;
91
+ export interface ImportRefusal {
92
+ /** The recorded id, when it is well formed. */
93
+ readonly id: string | null;
94
+ /** A display-safe line: capped, with control characters removed. */
95
+ readonly title: string;
96
+ readonly reason: RefusalReason;
97
+ readonly reasonText: string;
98
+ /** The sub-reason of a path or a check, from a fixed list. */
99
+ readonly detail?: string;
100
+ /** `<local project>:<path>` of the file the refusal is about. */
101
+ readonly file?: string;
102
+ readonly keys?: readonly string[];
103
+ readonly repo?: string;
104
+ }
105
+ export interface ImportAccepted {
106
+ readonly recordedId: string;
107
+ /** The candidate with local roots, checked against local files. */
108
+ readonly candidate: ValidCandidate;
109
+ readonly record: CandidateRecord;
110
+ /** The id computed from local roots. */
111
+ readonly id: string;
112
+ }
113
+ export interface Verification {
114
+ readonly projects: readonly ProjectReport[];
115
+ readonly accepted: readonly ImportAccepted[];
116
+ readonly refused: readonly ImportRefusal[];
117
+ }
118
+ export interface VerifyInput {
119
+ readonly record: ImportRecord;
120
+ readonly locals: readonly LocalCheckout[];
121
+ /** The inventory of a local checkout, or nothing when it cannot be read. */
122
+ readonly factsFor: (root: string) => ProjectFacts | undefined;
123
+ }
124
+ /**
125
+ * Check every candidate of the record against the local checkouts. A candidate
126
+ * is accepted only when it maps, its paths and ids hold, and `checkCandidate`
127
+ * passes on local files. Everything else is refused with a fixed reason; one
128
+ * refusal never stops the others.
129
+ */
130
+ export declare function verifyRecord(input: VerifyInput): Verification;
131
+ export interface ImportProvenance {
132
+ readonly repo: string;
133
+ readonly runId: string;
134
+ readonly commit?: string;
135
+ }
136
+ /** What was done with one candidate that passed local checks. */
137
+ export interface ImportedCandidate {
138
+ readonly item: DigestCandidate;
139
+ /** The run record that holds it. */
140
+ readonly runRecordPath: string;
141
+ }
142
+ export interface SkippedCandidate {
143
+ readonly id: string;
144
+ readonly title: string;
145
+ readonly reason: 'rejected-locally' | 'promoted-locally';
146
+ readonly refreshPointer?: string;
147
+ }
148
+ export interface ImportModel {
149
+ readonly runId: string | undefined;
150
+ readonly outcome: 'complete' | 'degraded';
151
+ /** Why the import is degraded; empty when it is complete. */
152
+ readonly degradeReasons: readonly string[];
153
+ readonly provenance: ImportProvenance;
154
+ /** The run's own id, from the record. */
155
+ readonly sourceRunId: string;
156
+ readonly projects: readonly ProjectReport[];
157
+ readonly imported: number;
158
+ readonly candidates: readonly ImportedCandidate[];
159
+ readonly skipped: readonly SkippedCandidate[];
160
+ readonly refused: readonly ImportRefusal[];
161
+ }
162
+ /**
163
+ * The chat summary of an import. Every value in it is either made by the
164
+ * helper or passed a validator; titles are quoted. The promotion lines are the
165
+ * ones a local run prints, so `ce:compound` takes them unchanged.
166
+ */
167
+ export declare function renderImportSummary(model: ImportModel, digestPath: string | undefined): string;
168
+ /** The digest of an import run, with the same quoting a local digest uses. */
169
+ export declare function renderImportDigest(model: ImportModel, written: readonly DigestCandidate[], generatedAt: string): string;
@@ -0,0 +1,33 @@
1
+ /**
2
+ * The portable identity of a checkout for `ce:connect`: `owner/repo` of its
3
+ * GitHub `origin` remote and the commit its HEAD names. A run record that
4
+ * carries both can be matched to another machine's checkout of the same
5
+ * project after the run's own paths are gone.
6
+ *
7
+ * Reads files under `.git/` only, through the contained reader (no symlink is
8
+ * followed, every read is bounded). No git process and no network is used, and
9
+ * nothing in a remote URL except the validated `owner/repo` is ever returned,
10
+ * so credentials in a URL cannot reach a record. Import rule: node builtins
11
+ * and `connect-evidence.ts` only, because the `ce:connect` helper bundles it.
12
+ * Never throws: anything unreadable, unexpected or not GitHub is absent.
13
+ */
14
+ export interface RepoIdentity {
15
+ /** Lowercase `owner/repo` of the GitHub `origin` remote. */
16
+ readonly repo?: string;
17
+ /** The full hash HEAD names. */
18
+ readonly commit?: string;
19
+ }
20
+ /**
21
+ * `owner/repo` of a GitHub remote URL, lowercase, or nothing. Three forms are
22
+ * read: an https URL, `git@github.com:o/r` and an `ssh://` URL, each with or
23
+ * without `.git` and a trailing slash. Another host, a port, a query, a
24
+ * fragment or a local path is not GitHub here. Userinfo is dropped and never
25
+ * returned.
26
+ */
27
+ export declare function normalizeGithubRemote(url: string): string | undefined;
28
+ /**
29
+ * The repository identity of the checkout whose main root is `mainRoot`. A
30
+ * root whose `.git` is not a real directory (a linked worktree, a submodule, a
31
+ * symlink) has neither field.
32
+ */
33
+ export declare function readRepoIdentity(mainRoot: string): RepoIdentity;
@@ -13,6 +13,8 @@
13
13
  * runs/<id>/ a published run
14
14
  * runs/<id>.tmp/ a run being staged
15
15
  * ledger.json the ledger
16
+ * ci-run.json written by a CI workflow before the run: its marker
17
+ * invocation.json written by the helper on a CI run: marker, phase, outcome
16
18
  *
17
19
  * Staging and publishing: a run is built in `runs/<id>.tmp/` and the rename to
18
20
  * `runs/<id>/` is the commit. The ledger is rewritten after it, with a
@@ -235,9 +237,20 @@ export interface CoverageRecord {
235
237
  * rule a record is. Absent on a record written before it was kept.
236
238
  */
237
239
  readonly project?: string;
240
+ /**
241
+ * The id of the selection (a group or picked projects) whose run covered the
242
+ * rule. Absent for a run with no selection, which is the namespace every
243
+ * version 1 record belongs to. A rule is covered once per namespace.
244
+ */
245
+ readonly selection?: string;
238
246
  }
247
+ /**
248
+ * The ledger as it is held in memory. Version 2 adds the `selection` of a
249
+ * coverage record. A version 1 file is read as version 2 with the same records,
250
+ * and is replaced by a version 2 file the next time the ledger is written.
251
+ */
239
252
  export interface Ledger {
240
- readonly version: 1;
253
+ readonly version: 2;
241
254
  readonly entries: readonly LedgerEntry[];
242
255
  /** Absent when no committed run has covered a rule. */
243
256
  readonly coverage?: readonly CoverageRecord[];
@@ -296,6 +309,12 @@ export declare function classifyCandidate(ledger: Ledger, candidate: CandidateRe
296
309
  */
297
310
  export interface CoverageUpdate {
298
311
  readonly runId: string;
312
+ /**
313
+ * The id of the run's selection. The update reads and changes only the
314
+ * records of that selection; the records of every other selection stay as
315
+ * they are. Left out, the update is for the no-selection namespace.
316
+ */
317
+ readonly selection?: string;
299
318
  /** Every rule the run indexed, with the hash of its learning and its project's key. */
300
319
  readonly indexed: ReadonlyArray<{
301
320
  readonly ruleId: string;
@@ -369,6 +388,115 @@ export type RewriteResult = 'rewritten' | 'failed';
369
388
  * run already, or is not a plain file name, is refused.
370
389
  */
371
390
  export declare function rewriteRunFiles(root: string, lock: LockHandle, runId: string, files: Readonly<Record<string, string>>): RewriteResult;
391
+ /**
392
+ * The parsed `run.json` of a published run, or nothing when the run is gone,
393
+ * pruned, not a plain run id, or not readable as one bounded regular file. The
394
+ * content is whatever the file holds: a caller checks the fields it uses.
395
+ */
396
+ export declare function readRunRecord(root: string, runId: string): unknown;
397
+ /** The name every import run directory starts with. */
398
+ export declare const IMPORT_RUN_PREFIX = "import-";
399
+ /** A sortable, unique id for an import run. */
400
+ export declare function newImportRunId(now?: number): string;
401
+ /** What an import sees once it holds the lock. */
402
+ export interface ImportView {
403
+ readonly ledger: Ledger;
404
+ /** The import runs that are kept, newest first. */
405
+ readonly importRuns: readonly string[];
406
+ }
407
+ /** What an import decides to write. */
408
+ export type ImportPlan = {
409
+ readonly publish: false;
410
+ } | {
411
+ readonly publish: true;
412
+ readonly runId: string;
413
+ readonly files: Readonly<Record<string, string>>;
414
+ readonly candidates: readonly CandidateRecord[];
415
+ /**
416
+ * The files that replace the committed ones when the ledger could not be
417
+ * written after the commit, so the run says what happened to it.
418
+ */
419
+ readonly onLedgerWriteFailed?: () => Readonly<Record<string, string>>;
420
+ };
421
+ export type ImportInsertResult = {
422
+ readonly status: 'busy';
423
+ readonly reason: LockBusyReason;
424
+ } | {
425
+ readonly status: 'failed';
426
+ readonly reason: 'lock-failed' | 'ledger-unreadable' | PublishFailure;
427
+ }
428
+ /** The plan wrote nothing. */
429
+ | {
430
+ readonly status: 'unchanged';
431
+ } | {
432
+ readonly status: 'published';
433
+ readonly runDir: string;
434
+ readonly ledger: {
435
+ readonly written: true;
436
+ } | {
437
+ readonly written: false;
438
+ readonly error: string;
439
+ };
440
+ /** False when the replacement files for a failed ledger write could not be written. */
441
+ readonly runRecordCurrent?: false;
442
+ };
443
+ /**
444
+ * Insert an import run under the lock. `plan` sees the ledger and the kept
445
+ * import runs, and returns the run to write or nothing. A plan that returns
446
+ * nothing leaves the state root as it was. The run is published the way a
447
+ * local run is (staged, renamed, then the ledger is rewritten), with no
448
+ * coverage, so an import never changes what a sweep has covered. When the
449
+ * ledger cannot be written after the commit, the plan's replacement files are
450
+ * written over the committed ones before the lock is released. A busy lock
451
+ * writes nothing, and the lock is always released.
452
+ */
453
+ export declare function insertImportRun(root: string, plan: (view: ImportView) => ImportPlan, options?: LockOptions & PublishOptions): ImportInsertResult;
454
+ /** Written by a CI workflow into the state root before the run; its marker tags the invocation record. */
455
+ export declare const CI_RUN_FILE = "ci-run.json";
456
+ /** Written by the helper on every path of a CI run from `begin` onward. */
457
+ export declare const INVOCATION_FILE = "invocation.json";
458
+ export interface InvocationProject {
459
+ readonly key: string;
460
+ readonly name: string;
461
+ readonly repo?: string;
462
+ readonly commit?: string;
463
+ }
464
+ export type InvocationRecord = {
465
+ readonly version: 1;
466
+ readonly marker: string;
467
+ readonly phase: 'begun';
468
+ readonly runId: string;
469
+ readonly projects: readonly InvocationProject[];
470
+ } | {
471
+ readonly version: 1;
472
+ readonly marker: string;
473
+ readonly phase: 'terminal';
474
+ readonly outcome: 'complete' | 'degraded' | 'busy' | 'failed';
475
+ readonly finalLine: string;
476
+ readonly reason?: string;
477
+ readonly runId?: string;
478
+ readonly projects?: readonly InvocationProject[];
479
+ };
480
+ export interface InvocationWriteOptions {
481
+ /** Runs before the write. A test seam: throwing here is a failed write that leaves the previous file. */
482
+ readonly beforeWrite?: (record: InvocationRecord) => void;
483
+ }
484
+ /**
485
+ * The marker a CI workflow wrote to `ci-run.json` in the state root, or
486
+ * nothing. The file must be exactly `{"version":1,"marker":"<name>"}` and small;
487
+ * a root or file that is a symlink, a missing root or file, and every other
488
+ * shape or read failure mean no CI run. Creates nothing and never throws.
489
+ */
490
+ export declare function readCiRunMarker(root: string): string | undefined;
491
+ /**
492
+ * Replace `invocation.json` with a temporary file and a rename, owner-only.
493
+ * Only named fields are written, so a field outside the record never reaches
494
+ * the file. A record out of shape, a root that is not a real directory and any
495
+ * write failure are `failed`, and the previous file is left as it was.
496
+ */
497
+ export declare function writeInvocationRecord(root: string, record: InvocationRecord, options?: InvocationWriteOptions): 'written' | 'failed';
498
+ /** The invocation record, or nothing when it is missing, oversize, not a regular file or out of shape. */
499
+ export declare function readInvocationRecord(root: string): InvocationRecord | undefined;
372
500
  export type PruneResult = {
373
501
  readonly status: 'pruned';
374
502
  readonly removedRuns: readonly string[];
@@ -396,6 +524,12 @@ export interface DecideInput {
396
524
  readonly reason: string;
397
525
  /** Where a promoted learning was written. Ignored for `rejected`. */
398
526
  readonly destination?: string;
527
+ /**
528
+ * Apply the decision only if the entry is still a `candidate` when the lock
529
+ * is held. A caller that read the ledger earlier uses this so a decision
530
+ * made in between is not overwritten.
531
+ */
532
+ readonly onlyIfOpen?: boolean;
399
533
  }
400
534
  export type DecideResult = {
401
535
  readonly status: 'decided';
@@ -405,12 +539,13 @@ export type DecideResult = {
405
539
  readonly reason: LockBusyReason;
406
540
  } | {
407
541
  readonly status: 'failed';
408
- readonly reason: 'invalid-input' | 'unknown-candidate' | 'lock-failed' | 'ledger-unreadable' | 'write-failed';
542
+ readonly reason: 'invalid-input' | 'unknown-candidate' | 'not-open' | 'lock-failed' | 'ledger-unreadable' | 'write-failed';
409
543
  };
410
544
  /**
411
545
  * Record a decision on a ledger entry. It takes the lock, so a busy lock makes
412
546
  * it fail without writing, and rewrites the ledger by temp-and-rename. Both
413
- * statuses need a reason.
547
+ * statuses need a reason. With `onlyIfOpen`, an entry that is no longer a
548
+ * candidate is left as it is and the answer is `not-open`.
414
549
  */
415
550
  export declare function decideLedgerEntry(root: string, input: DecideInput, options?: LockOptions): DecideResult;
416
551
  export type ClearResult = {
package/dist/pi.js CHANGED
@@ -12748,6 +12748,8 @@ import {
12748
12748
  var MAX_ALLOW_PROJECTS = 64;
12749
12749
  var MAX_ALLOW_PROJECT_LENGTH = 4096;
12750
12750
  var MAX_CONNECT_CONFIG_BYTES = 1024 * 1024;
12751
+ var MAX_CONNECT_GROUPS = 32;
12752
+ var CONNECT_GROUP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
12751
12753
 
12752
12754
  // src/lib/removed-names.ts
12753
12755
  var REMOVED_BUNDLED_SKILL_NAMES = [
@@ -13052,11 +13054,30 @@ var ConnectSettingsSchema = trustProtected(object({
13052
13054
  allow_projects: array(string2().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).max(MAX_ALLOW_PROJECTS).optional().meta({
13053
13055
  description: `Main repository roots that \`ce:connect\` may read for contradictions and transferable lessons. Each entry is an absolute or \`~\`-prefixed path to the root of a repository checkout, not a subdirectory and not a linked worktree. At most ${MAX_ALLOW_PROJECTS} entries; an entry that matches no repository is reported by the run and does not widen the list. The lists in user, user.local, custom and custom.local config are merged as a union. Omitted or empty, it allows no project.`,
13054
13056
  examples: [["~/src/github.com/me/app", "/srv/checkouts/shared-lib"]]
13057
+ }),
13058
+ groups: record(string2().regex(CONNECT_GROUP_NAME_PATTERN), array(string2().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).min(1).max(MAX_ALLOW_PROJECTS)).refine((groups) => Object.keys(groups).length <= MAX_CONNECT_GROUPS).optional().meta({
13059
+ description: `Named subsets of the allow list that \`ce:connect\` can be narrowed to with \`group:<name>\`. A group name is 1 to 64 characters of lowercase letters, digits and hyphens, led by a letter or digit (\`${CONNECT_GROUP_NAME_PATTERN.source}\`). Each group lists at least one and at most ${MAX_ALLOW_PROJECTS} members in the same form as an \`allow_projects\` entry. At most ${MAX_CONNECT_GROUPS} groups per file. A group never adds a project: a member that is not on the allow list stops the run that selects the group. Groups merge by name across user, user.local, custom and custom.local config, and a later file replaces a same-named group whole.`,
13060
+ examples: [
13061
+ {
13062
+ "harness-tools": [
13063
+ "~/src/github.com/me/app",
13064
+ "/srv/checkouts/shared-lib"
13065
+ ]
13066
+ }
13067
+ ],
13068
+ maxProperties: MAX_CONNECT_GROUPS
13055
13069
  })
13056
13070
  }).strict().meta({
13057
- description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list.",
13071
+ description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list and no groups.",
13058
13072
  examples: [
13059
13073
  { allow_projects: ["~/src/github.com/me/app"] },
13074
+ {
13075
+ allow_projects: [
13076
+ "~/src/github.com/me/app",
13077
+ "~/src/github.com/me/lib"
13078
+ ],
13079
+ groups: { "harness-tools": ["~/src/github.com/me/app"] }
13080
+ },
13060
13081
  { allow_projects: [] }
13061
13082
  ]
13062
13083
  }));
@@ -14209,9 +14230,20 @@ function mergeConnect(sources) {
14209
14230
  const blocks = sources.flatMap((source) => source.config.connect === undefined ? [] : [source.config.connect]);
14210
14231
  if (blocks.length === 0)
14211
14232
  return {};
14233
+ const groups = {};
14234
+ let hasGroups = false;
14235
+ for (const block of blocks) {
14236
+ if (block.groups === undefined)
14237
+ continue;
14238
+ hasGroups = true;
14239
+ for (const [name, members] of Object.entries(block.groups)) {
14240
+ groups[name] = [...members];
14241
+ }
14242
+ }
14212
14243
  return {
14213
14244
  connect: {
14214
- allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), [])
14245
+ allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), []),
14246
+ ...hasGroups && { groups }
14215
14247
  }
14216
14248
  };
14217
14249
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.32.3",
3
+ "version": "3.33.1",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -118,13 +118,13 @@
118
118
  }
119
119
  },
120
120
  "devDependencies": {
121
- "@biomejs/biome": "2.6.5",
122
- "@earendil-works/pi-coding-agent": "1.5.0",
121
+ "@biomejs/biome": "2.6.6",
122
+ "@earendil-works/pi-coding-agent": "1.5.2",
123
123
  "@opencode-ai/plugin": "1.19.5",
124
124
  "@opencode-ai/sdk": "1.19.5",
125
- "@opencode/client": "2.2.6",
126
- "@opencode/plugin": "2.2.6",
127
- "@opencode/sdk": "2.2.6",
125
+ "@opencode/client": "2.2.7",
126
+ "@opencode/plugin": "2.2.7",
127
+ "@opencode/sdk": "2.2.7",
128
128
  "@semantic-release/exec": "7.1.0",
129
129
  "@tintinweb/pi-subagents": "0.22.1",
130
130
  "@types/bun": "latest",
@@ -138,7 +138,7 @@
138
138
  "rimraf": "6.1.4",
139
139
  "semantic-release": "25.0.9",
140
140
  "semantic-release-export-data": "1.2.0",
141
- "typebox": "1.4.4",
141
+ "typebox": "1.4.6",
142
142
  "typescript": "7.0.2"
143
143
  },
144
144
  "dependencies": {
@@ -147,7 +147,7 @@
147
147
  "zod": "4.6.7"
148
148
  },
149
149
  "overrides": {
150
- "@earendil-works/pi-ai": "1.5.0",
150
+ "@earendil-works/pi-ai": "1.5.2",
151
151
  "brace-expansion": "^5.0.8",
152
152
  "conventional-changelog-writer": ">=9",
153
153
  "devalue": "^5.9.3",