@maycombhq/sdk 2.0.0-beta.28.1 → 2.0.0-beta.28.3

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/npm/core/api.d.ts CHANGED
@@ -600,8 +600,29 @@ import { z } from "zod";
600
600
  * lines naming each with the file to fix it in. Additive only. Apply to every repo (POST
601
601
  * /api/facts/apply-all) the same: a repo that wrote with facts left out is applied, and its
602
602
  * result carries `leftOut` (all repos) and `leftOutRepos` (how many repos left some out).
603
+ * 3.15.0 (beta.28.2, ADR 0197 "beta.28.1 and older reading version 2"): a refused build's
604
+ * `reasons` (BuildRefusalView: GET /api/build's `pending.refused` and `last.refused`, a scan's
605
+ * and an Apply's job result) may be `newer-atticus`: catalog/sources/build.json or a slot was
606
+ * written by a newer Atticus, at a version of its format this one doesn't read. Its `message`
607
+ * says so, its `command` is `npm i -g @maycombhq/atticus@beta`, and nothing was written; it is
608
+ * never `not-upgraded`. The Apply preview's `confirm.refused` may list it the same way. The
609
+ * upgrade job (POST /api/upgrade) refuses on such a catalog with the same words; GET
610
+ * /api/upgrade then lists no `pending` step and says why in `newerCatalog`, and GET
611
+ * /api/build/undo offers no `plan` (its `problem` says why). Every route
612
+ * that writes one of the build's inputs (the build, scan, Apply, undo, prune, the upgrade, the
613
+ * map's edits and deletes, corrections, call corrections, pairings, declared links and boxes,
614
+ * answers, triage, the AI's decisions, the baseline, initiatives, an owner question's send,
615
+ * starting a run, the org pack's files, patterns, sources, adapters and AI settings, a file
616
+ * promoted into inputs/, repos and owners) answers 409 on such a catalog before it writes
617
+ * anything: a problem whose `refused` is `{ reasons: ["newer-atticus"], message, newer }`,
618
+ * `newer` (BuildRefusalView's, optional) naming each file a newer Atticus wrote with its
619
+ * version and the newest one this Atticus reads. Additive only.
620
+ * Also in 3.15.0 (ADR 0197 review): a `hand-edits` refusal may carry `unreadableManifest: true`,
621
+ * when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
622
+ * `command` is the build again with `--discard-edits` of every record file, never the curate.
623
+ * Additive only.
603
624
  */
604
- export declare const API_VERSION = "3.14.0";
625
+ export declare const API_VERSION = "3.15.0";
605
626
  export declare const DEFAULT_PORT = 4321;
606
627
  /** RFC 9457 problem details, used for every error. */
607
628
  /**
@@ -3991,6 +4012,7 @@ export declare const BuildRefusalView: z.ZodObject<{
3991
4012
  "large-removals": "large-removals";
3992
4013
  "hand-edits": "hand-edits";
3993
4014
  "not-upgraded": "not-upgraded";
4015
+ "newer-atticus": "newer-atticus";
3994
4016
  }>>;
3995
4017
  message: z.ZodString;
3996
4018
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4067,6 +4089,14 @@ export declare const BuildRefusalView: z.ZodObject<{
4067
4089
  repo: z.ZodString;
4068
4090
  why: z.ZodString;
4069
4091
  }, z.core.$strip>>>;
4092
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4093
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4094
+ path: z.ZodString;
4095
+ name: z.ZodString;
4096
+ field: z.ZodString;
4097
+ version: z.ZodNumber;
4098
+ reads: z.ZodNumber;
4099
+ }, z.core.$strip>>>;
4070
4100
  command: z.ZodString;
4071
4101
  plan: z.ZodOptional<z.ZodString>;
4072
4102
  }, z.core.$strip>;
@@ -4102,6 +4132,7 @@ export declare const BuildReportView: z.ZodObject<{
4102
4132
  "large-removals": "large-removals";
4103
4133
  "hand-edits": "hand-edits";
4104
4134
  "not-upgraded": "not-upgraded";
4135
+ "newer-atticus": "newer-atticus";
4105
4136
  }>>;
4106
4137
  message: z.ZodString;
4107
4138
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4178,6 +4209,14 @@ export declare const BuildReportView: z.ZodObject<{
4178
4209
  repo: z.ZodString;
4179
4210
  why: z.ZodString;
4180
4211
  }, z.core.$strip>>>;
4212
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4213
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4214
+ path: z.ZodString;
4215
+ name: z.ZodString;
4216
+ field: z.ZodString;
4217
+ version: z.ZodNumber;
4218
+ reads: z.ZodNumber;
4219
+ }, z.core.$strip>>>;
4181
4220
  command: z.ZodString;
4182
4221
  plan: z.ZodOptional<z.ZodString>;
4183
4222
  }, z.core.$strip>>;
@@ -4316,6 +4355,7 @@ export declare const CatalogBuildView: z.ZodObject<{
4316
4355
  "large-removals": "large-removals";
4317
4356
  "hand-edits": "hand-edits";
4318
4357
  "not-upgraded": "not-upgraded";
4358
+ "newer-atticus": "newer-atticus";
4319
4359
  }>>;
4320
4360
  message: z.ZodString;
4321
4361
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4392,6 +4432,14 @@ export declare const CatalogBuildView: z.ZodObject<{
4392
4432
  repo: z.ZodString;
4393
4433
  why: z.ZodString;
4394
4434
  }, z.core.$strip>>>;
4435
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4436
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4437
+ path: z.ZodString;
4438
+ name: z.ZodString;
4439
+ field: z.ZodString;
4440
+ version: z.ZodNumber;
4441
+ reads: z.ZodNumber;
4442
+ }, z.core.$strip>>>;
4395
4443
  command: z.ZodString;
4396
4444
  plan: z.ZodOptional<z.ZodString>;
4397
4445
  }, z.core.$strip>>;
@@ -4415,6 +4463,7 @@ export declare const CatalogBuildView: z.ZodObject<{
4415
4463
  "large-removals": "large-removals";
4416
4464
  "hand-edits": "hand-edits";
4417
4465
  "not-upgraded": "not-upgraded";
4466
+ "newer-atticus": "newer-atticus";
4418
4467
  }>>;
4419
4468
  message: z.ZodString;
4420
4469
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4491,6 +4540,14 @@ export declare const CatalogBuildView: z.ZodObject<{
4491
4540
  repo: z.ZodString;
4492
4541
  why: z.ZodString;
4493
4542
  }, z.core.$strip>>>;
4543
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4544
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4545
+ path: z.ZodString;
4546
+ name: z.ZodString;
4547
+ field: z.ZodString;
4548
+ version: z.ZodNumber;
4549
+ reads: z.ZodNumber;
4550
+ }, z.core.$strip>>>;
4494
4551
  command: z.ZodString;
4495
4552
  plan: z.ZodOptional<z.ZodString>;
4496
4553
  }, z.core.$strip>>;
@@ -4923,6 +4980,7 @@ export declare const MapEditsResult: z.ZodObject<{
4923
4980
  "large-removals": "large-removals";
4924
4981
  "hand-edits": "hand-edits";
4925
4982
  "not-upgraded": "not-upgraded";
4983
+ "newer-atticus": "newer-atticus";
4926
4984
  }>>;
4927
4985
  message: z.ZodString;
4928
4986
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4999,6 +5057,14 @@ export declare const MapEditsResult: z.ZodObject<{
4999
5057
  repo: z.ZodString;
5000
5058
  why: z.ZodString;
5001
5059
  }, z.core.$strip>>>;
5060
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
5061
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
5062
+ path: z.ZodString;
5063
+ name: z.ZodString;
5064
+ field: z.ZodString;
5065
+ version: z.ZodNumber;
5066
+ reads: z.ZodNumber;
5067
+ }, z.core.$strip>>>;
5002
5068
  command: z.ZodString;
5003
5069
  plan: z.ZodOptional<z.ZodString>;
5004
5070
  }, z.core.$strip>>;
@@ -5021,6 +5087,7 @@ export declare const FactsApplyResult: z.ZodObject<{
5021
5087
  "large-removals": "large-removals";
5022
5088
  "hand-edits": "hand-edits";
5023
5089
  "not-upgraded": "not-upgraded";
5090
+ "newer-atticus": "newer-atticus";
5024
5091
  }>>;
5025
5092
  message: z.ZodString;
5026
5093
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -5097,6 +5164,14 @@ export declare const FactsApplyResult: z.ZodObject<{
5097
5164
  repo: z.ZodString;
5098
5165
  why: z.ZodString;
5099
5166
  }, z.core.$strip>>>;
5167
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
5168
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
5169
+ path: z.ZodString;
5170
+ name: z.ZodString;
5171
+ field: z.ZodString;
5172
+ version: z.ZodNumber;
5173
+ reads: z.ZodNumber;
5174
+ }, z.core.$strip>>>;
5100
5175
  command: z.ZodString;
5101
5176
  plan: z.ZodOptional<z.ZodString>;
5102
5177
  }, z.core.$strip>>;
@@ -6375,6 +6450,7 @@ export declare const VerifyPreviewView: z.ZodObject<{
6375
6450
  "nothing-read": "nothing-read";
6376
6451
  empty: "empty";
6377
6452
  "unexplained-removals": "unexplained-removals";
6453
+ "newer-atticus": "newer-atticus";
6378
6454
  }>>>;
6379
6455
  upgrade: z.ZodOptional<z.ZodLiteral<true>>;
6380
6456
  command: z.ZodOptional<z.ZodString>;
@@ -14233,6 +14309,7 @@ export declare const UpgradeView: z.ZodObject<{
14233
14309
  files: z.ZodArray<z.ZodString>;
14234
14310
  }, z.core.$strip>>;
14235
14311
  upgraded: z.ZodOptional<z.ZodArray<z.ZodString>>;
14312
+ newerCatalog: z.ZodOptional<z.ZodString>;
14236
14313
  }, z.core.$strip>;
14237
14314
  /**
14238
14315
  * 3.5.0: what a setup edit changed, or with `preview: true` would change: the file
@@ -12,5 +12,11 @@ export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>):
12
12
  export declare function commitCurrent(): boolean;
13
13
  /** The signal of the job this code runs in, if it runs in one. */
14
14
  export declare function currentSignal(): AbortSignal | undefined;
15
+ /**
16
+ * Beta.28.3: the signal a long read may stop on part way (the hash of every file of the
17
+ * catalog): the job's, until its work says it has started writing. From then there is none, so a
18
+ * read that is part of a write is never cut short and nothing is left half written.
19
+ */
20
+ export declare function stoppableSignal(): AbortSignal | undefined;
15
21
  /** Stop here when the job was cancelled. */
16
22
  export declare function throwIfCancelled(): void;
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Reading and hashing many small files (beta.28.2): a catalog's 100,000 record files took 10 to
3
+ * 13 s to hash through the promise API, four calls each (open, stat, read, close) handed to
4
+ * libuv's thread pool and back, and each text decoded, its line endings replaced and encoded again
5
+ * to be hashed. Here a few worker threads read them with the synchronous calls, one file at a
6
+ * time each (so no more than one open file a worker: no EMFILE, on Windows either), and hash the
7
+ * bytes; the main thread stays free (a progress line, Stop between steps) and gets the results in
8
+ * the order of the paths, whatever the order the workers finish in. Every byte of every file is
9
+ * read: nothing is taken from a file's size and time. A small folder, or a process where a worker
10
+ * can't start, is read in this thread instead, to the same results.
11
+ *
12
+ * Beta.28.3: a read given a `signal` (a job's Stop) ends when it is stopped, with CancelledError:
13
+ * the workers are ended where they are (no more than the file each has open is read on), this
14
+ * thread's read stops between two files, and the wait for workers that never start ends at once.
15
+ * It only reads, so a stopped read leaves nothing behind.
16
+ */
17
+ /** A file's size and time (ms, floored), as `stat` gives them. */
18
+ export interface FileStat {
19
+ size: number;
20
+ mtimeMs: number;
21
+ }
22
+ /** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
23
+ export interface FileHash extends FileStat {
24
+ sha: string;
25
+ }
26
+ /**
27
+ * How the files are read: tests force a number of workers (0: this thread) and the smallest
28
+ * folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
29
+ * folders of `MIN_FILES` files or more.
30
+ */
31
+ export declare const filePoolHooks: {
32
+ workers?: number;
33
+ minFiles?: number;
34
+ /** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
35
+ failStart?: boolean;
36
+ /** A test's workers that start and never say they are ready (nor fail, nor exit). */
37
+ neverReady?: boolean;
38
+ /** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
39
+ startTimeoutMs?: number;
40
+ /** A test hears how many files are read so far (in workers a batch at a time). */
41
+ onRead?: (files: number) => void;
42
+ };
43
+ /**
44
+ * How long the workers have to say they are ready before this thread reads instead (the final
45
+ * review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
46
+ * in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
47
+ */
48
+ export declare const START_TIMEOUT_MS = 10000;
49
+ /**
50
+ * The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
51
+ * Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
52
+ * any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
53
+ */
54
+ export declare function textShaOf(bytes: Buffer): string;
55
+ /**
56
+ * Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
57
+ * (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
58
+ * the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
59
+ * hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
60
+ * is of exactly those bytes (record-cache.ts). With `signal`, a stop ends the read part way and
61
+ * fails the call with CancelledError (beta.28.3).
62
+ */
63
+ export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
64
+ raw?: boolean;
65
+ signal?: AbortSignal;
66
+ }): Promise<FileHash[]>;
67
+ /**
68
+ * Every named file's size and time (ms, floored), in the order of `rels`; none for one not there.
69
+ * With `signal`, a stop ends the read part way and fails the call with CancelledError.
70
+ */
71
+ export declare function statFilesIn(dir: string, rels: readonly string[], o?: {
72
+ signal?: AbortSignal;
73
+ }): Promise<(FileStat | undefined)[]>;
package/npm/core/fs.d.ts CHANGED
@@ -5,7 +5,23 @@
5
5
  * Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
6
6
  * it is retried a few times before giving up.
7
7
  */
8
- export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
8
+ export declare function writeFileAtomic(path: string, data: string | Uint8Array, o?: {
9
+ /**
10
+ * Told the size and time (ms, floored) of the file as written (beta.28.2: a writer keeps its
11
+ * parse by them): the temporary file's, taken on its handle before the rename (which keeps
12
+ * them), when the file has the same once renamed; not told when they differ (the file was
13
+ * changed meanwhile, or the system set another time on close). With them, the sha256 of the
14
+ * bytes written and `writtenAt`, the clock (ms) as the write began: a parse kept by them is
15
+ * checked by that hash while the file's time is within the timestamp's grain of `writtenAt`
16
+ * (record-cache.ts, `RACY_MS`).
17
+ */
18
+ stat?: (s: {
19
+ size: number;
20
+ mtimeMs: number;
21
+ sha: string;
22
+ writtenAt: number;
23
+ }) => void;
24
+ }): Promise<void>;
9
25
  /**
10
26
  * Copy a file the way `writeFileAtomic` writes one: to a temporary file beside the target, then
11
27
  * renamed over it. The copy is made by the system (a copy-on-write clone where the file system
@@ -60,12 +60,14 @@ export * from "./fs.js";
60
60
  export * from "./glob.js";
61
61
  export * from "./repo-files.js";
62
62
  export * from "./record-cache.js";
63
+ export * from "./file-pool.js";
63
64
  export * from "./kept-files.js";
64
65
  export * from "./log.js";
65
66
  export * from "./run-log.js";
66
67
  export * from "./printer.js";
67
68
  export * from "./zip.js";
68
69
  export * from "./words.js";
70
+ export * from "./initialisms.js";
69
71
  export * from "./zip-read.js";
70
72
  export * from "./tar-read.js";
71
73
  export * from "./schema/question.js";
@@ -0,0 +1,62 @@
1
+ /**
2
+ * An acronym and the words it stands for (beta.28.3): "SSO" and "single sign-on", "EDW" and
3
+ * "enterprise data warehouse". One side of a search often writes the letters and the other the
4
+ * words, with no word in common, and a small embedding model rates the two far apart.
5
+ *
6
+ * The link is taken only from where the organisation's own pages define it: "Enterprise Data
7
+ * Warehouse (EDW)", "EDW (Enterprise Data Warehouse)", or a line of an abbreviations list
8
+ * ("EDW: Enterprise Data Warehouse", "| SSO | single sign-on |"), and only when the words' first
9
+ * letters spell the acronym. Letters alone are not enough: ordinary prose spells most
10
+ * three-letter acronyms by chance ("step still open" is no SSO), so a run of words is never
11
+ * taken for an acronym's meaning unless a page sets the two side by side. Deterministic, no
12
+ * model. A link only ranks and keeps what a search shows; it never makes a record or a fact.
13
+ */
14
+ export interface Initialism {
15
+ /** As written: capital letters and digits, three to six, starting with a letter. */
16
+ acronym: string;
17
+ /** The words it stands for: lower case, single spaces, hyphens as spaces. */
18
+ phrase: string;
19
+ }
20
+ /**
21
+ * How a phrase is looked for in a text: lower case, anything but letters and digits as one space,
22
+ * a space at each end. Where a sentence, a bracket or a paragraph ends there is a bar, so a phrase is
23
+ * never found across one ("the change. Request access" writes no "change request").
24
+ */
25
+ export declare const foldWords: (s: string) => string;
26
+ /**
27
+ * The acronyms a text defines, each with the words it sets beside it, in the order met:
28
+ *
29
+ * - `words (ACR)`: the words just before the bracket, as many as spell it;
30
+ * - `ACR (words)`: everything in the bracket;
31
+ * - `ACR: words`, `ACR - words`, `ACR = words`, `| ACR | words |` at a line's start (after a
32
+ * list mark or emphasis): the words up to the next punctuation, as many as spell it.
33
+ *
34
+ * The words' first letters must spell the acronym; a pair that doesn't is no definition.
35
+ */
36
+ export declare function definedInitialisms(text: string): Initialism[];
37
+ export interface InitialismUse extends Initialism {
38
+ /** Which form the text writes. */
39
+ wrote: "acronym" | "phrase";
40
+ }
41
+ export interface InitialismLink extends Initialism {
42
+ /** Which text writes the acronym; the other writes the words. */
43
+ acronymIn: "a" | "b";
44
+ }
45
+ /** The acronyms an estate's pages define, to link a text that writes one form to one that writes the other. */
46
+ export interface InitialismBook {
47
+ readonly size: number;
48
+ entries(): Initialism[];
49
+ /** The defined acronyms a text writes, and the defined phrases it writes, in the book's order. */
50
+ uses(text: string): InitialismUse[];
51
+ /**
52
+ * The names one text writes as an acronym and the other only as its words. A name both write
53
+ * as the acronym is a word in common, not a link, and is left out.
54
+ */
55
+ links(a: string, b: string): InitialismLink[];
56
+ }
57
+ /**
58
+ * A book of definitions, each acronym and phrase once, sorted: the same definitions give the same
59
+ * book. An acronym that is an ordinary word in capitals (POST, NOTE, AND) is left out, as is a
60
+ * phrase of one word.
61
+ */
62
+ export declare function initialismBook(defs: Iterable<Initialism>): InitialismBook;
@@ -7,11 +7,22 @@ import { type ChildProcess } from "node:child_process";
7
7
  * listener (onStopping: taskrun aborts its model call), and lets the signal end Atticus once nothing
8
8
  * holds on (or after TREE_SIGNAL_GRACE_MS). When Atticus exits, every tree still running is killed
9
9
  * outright. Shared by taskrun's builds and workspace's git (it was taskrun's own).
10
+ *
11
+ * Beta.28.3: three ways a tree outlived Atticus when the terminal closed at the wrong moment.
12
+ * The handlers were hooked only once the child was tracked, after it had started: a signal in
13
+ * between (seen in CI, a few milliseconds wide) ended Atticus as if nothing ran, and the child,
14
+ * in its own group, never heard it (startTree hooks first). A tree started after the signal was
15
+ * never stopped, and Atticus ending by the signal (no exit handlers run then) killed nothing of
16
+ * what still ran after the grace, nor what a stopped tree's leader left behind in its group.
10
17
  */
11
18
  /** How a tracked tree is stopped: its own way (git's tree, a build's group), by the signal. */
12
19
  export type StopTree = (signal: NodeJS.Signals) => void;
13
20
  /** However long the runs take to record themselves, Atticus ends by the signal within this. */
14
21
  export declare const TREE_SIGNAL_GRACE_MS = 10000;
22
+ /** A test's shorter grace (TREE_SIGNAL_GRACE_MS otherwise). */
23
+ export declare const processTreeHooks: {
24
+ signalGraceMs?: number;
25
+ };
15
26
  /**
16
27
  * Stop every tracked tree (SIGTERM, each its own way) and tell each listener: Atticus is
17
28
  * stopping (atticus ui on its way out, or a signal).
@@ -51,9 +62,21 @@ export declare const stopPending: () => boolean;
51
62
  /**
52
63
  * Keep a child in its own process group until it ends: stopped with Atticus (a signal,
53
64
  * stopTrackedTrees) by `stop`, killed by it with SIGKILL when Atticus exits. Gives back the way
54
- * to let go of it (when it has ended).
65
+ * to let go of it (when it has ended). One tracked after a signal that ends Atticus is stopped
66
+ * at once. A child started in its own group is started through `startTree`, never tracked after
67
+ * the fact: a signal between its start and this call would end Atticus and leave it running.
55
68
  */
56
69
  export declare function trackTree(child: ChildProcess, stop?: StopTree): () => void;
70
+ /**
71
+ * Start a child in its own process group and keep it (trackTree), with the signals' handlers in
72
+ * place before it starts: from its first moment a closed terminal, Ctrl+C or SIGTERM stops it
73
+ * with Atticus. `stop` is how it is stopped (its group by default). A start that throws keeps
74
+ * nothing.
75
+ */
76
+ export declare function startTree<C extends ChildProcess>(start: () => C, stop?: (child: C) => StopTree): {
77
+ child: C;
78
+ untrack: () => void;
79
+ };
57
80
  /**
58
81
  * Hold a stop for a task run, from its start until its record is saved: a signal meanwhile
59
82
  * stops its trees, and Atticus ends only once it is released.
@@ -1,3 +1,4 @@
1
+ import { type FileStat } from "./file-pool.js";
1
2
  /**
2
3
  * Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
3
4
  * 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
@@ -16,7 +17,31 @@
16
17
  *
17
18
  * Nothing here decides what a file means: the caller's `parse` does, and only its output (the
18
19
  * record, or the problem with the file) is kept.
20
+ *
21
+ * Racily clean files (the final review of beta.28.2, Git's rule of the same name). A file system
22
+ * keeps a file's time to a grain (FAT 2 s, HFS+ 1 s, some SMB and NFS mounts 1 s or more), so a
23
+ * same-size edit made within that grain of a read or a write can keep the time the parse was kept
24
+ * by, and size and time alone would serve the old text. So each parse is kept with the clock as
25
+ * it was taken (`at`: before the bytes parsed were read, or before a writer wrote them), and one
26
+ * whose file's time is no more than `RACY_MS` before `at` is "racy": it keeps the sha256 of the
27
+ * bytes parsed, and is reused only when the file still hashes to them (read in the file pool's
28
+ * workers; cheaper than a parse), then kept again as of the hash's read when by then it is no
29
+ * longer racy (the next command, seconds on: from then on its stat alone decides). A parse whose
30
+ * file's time is more than `RACY_MS` before `at` is trusted by size and time, as before: any edit
31
+ * after `at` has a time after `at` less the grain, so it can't keep that time. A parse kept with no `at` (an older cache) is racy, and with no hash it is
32
+ * parsed again. The rule takes this machine's clock and the file system's to agree to within the
33
+ * grain (a mount whose server runs more than `RACY_MS` behind can still serve a stale parse, as
34
+ * Git can).
35
+ */
36
+ /**
37
+ * The widest timestamp grain allowed for (FAT's 2 s): a parse kept of a file whose time was
38
+ * within this of the moment it was kept is checked by its hash before it is reused.
19
39
  */
40
+ export declare const RACY_MS = 2000;
41
+ /** Tests set the clock a parse is kept at (ms; default `Date.now`). */
42
+ export declare const recordCacheHooks: {
43
+ now?: () => number;
44
+ };
20
45
  /** One file's parse: the value, or why the file isn't valid. Never both. */
21
46
  export interface Parsed<T> {
22
47
  /** The file, relative to the folder, with forward slashes. */
@@ -35,8 +60,21 @@ export type ParseOutcome<T> = {
35
60
  ok: false;
36
61
  message: string;
37
62
  };
38
- /** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
39
- export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
63
+ interface Entry {
64
+ size: number;
65
+ mtimeMs: number;
66
+ /** The clock (ms) as the parse was kept: before its bytes were read, or written. None: racy. */
67
+ at?: number;
68
+ /** A racy entry's sha256 of the bytes parsed (none once it isn't racy). */
69
+ sha?: string;
70
+ value?: unknown;
71
+ problem?: string;
72
+ }
73
+ /**
74
+ * Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. With `signal`, a stop
75
+ * ends it between two lots with CancelledError (beta.28.3).
76
+ */
77
+ export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>, signal?: AbortSignal): Promise<O[]>;
40
78
  /**
41
79
  * Read and parse every named file of a folder, reusing the parses kept from an earlier run for
42
80
  * the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
@@ -59,4 +97,59 @@ export declare function readParsedFiles<T>(o: {
59
97
  keep?: boolean;
60
98
  /** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
61
99
  withStats?: boolean;
100
+ /**
101
+ * Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
102
+ * then writes some of the files adds their parses with `keepParses` (beta.28.2).
103
+ */
104
+ kept?: (k: KeptParses<T>) => void;
105
+ /**
106
+ * Beta.28.3: a job's Stop. A stop while the files' sizes and times are read, their bytes
107
+ * hashed, or the files read and parsed (a first read of a large catalog) ends the read with
108
+ * CancelledError; nothing is kept of a stopped read.
109
+ */
110
+ signal?: AbortSignal;
62
111
  }): Promise<Parsed<T>[]>;
112
+ /** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
113
+ export interface KeptParses<T> {
114
+ readonly memo: {
115
+ root: string;
116
+ file: string;
117
+ };
118
+ readonly version: string;
119
+ readonly dir: string;
120
+ /** The kept parses by path, as that read left them. */
121
+ readonly entries: ReadonlyMap<string, Entry>;
122
+ /** Only to tie the type to the parse's value. */
123
+ readonly _value?: T;
124
+ }
125
+ /**
126
+ * Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
127
+ * the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
128
+ * megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
129
+ * it had as it was written, with the parse of the text the writer wrote there, which is what a
130
+ * read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
131
+ * kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
132
+ * with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
133
+ * write began), so the next read reuses it only when the file still hashes to them; one with no
134
+ * hash is parsed again by the next read. A cache that can't be written costs the next read its
135
+ * parses.
136
+ */
137
+ export declare function keepParses<T>(k: KeptParses<T>, o: {
138
+ /**
139
+ * Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
140
+ * `stat`): it is kept only while it still has exactly those, so an edit made since (of the
141
+ * same size too: its time differs, or within the grain its hash does) is parsed by the next
142
+ * read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
143
+ */
144
+ files: readonly {
145
+ rel: string;
146
+ value?: T;
147
+ problem?: string;
148
+ at: FileStat & {
149
+ sha?: string;
150
+ writtenAt?: number;
151
+ };
152
+ }[];
153
+ removed: readonly string[];
154
+ }): Promise<void>;
155
+ export {};
package/npm/index.js CHANGED
@@ -6992,7 +6992,9 @@ var BuildRefusalView = z31.object({
6992
6992
  "unexplained-removals",
6993
6993
  "large-removals",
6994
6994
  "hand-edits",
6995
- "not-upgraded"
6995
+ "not-upgraded",
6996
+ // 3.15.0 (beta.28.2, ADR 0197): build.json or a slot a newer Atticus wrote.
6997
+ "newer-atticus"
6996
6998
  ])),
6997
6999
  message: z31.string(),
6998
7000
  removals: z31.array(BuildRemoval).optional(),
@@ -7002,6 +7004,28 @@ var BuildRefusalView = z31.object({
7002
7004
  discardEdits: z31.number().int().optional(),
7003
7005
  /** A scan that read nothing: each repo it couldn't read in full, and why. */
7004
7006
  unread: z31.array(z31.object({ repo: z31.string(), why: z31.string() })).optional(),
7007
+ /**
7008
+ * 3.15.0 (beta.28.2, ADR 0197): a `hand-edits` refusal because build.json is there but doesn't
7009
+ * read (edited or merged by hand). The only way on is to build again with `discardEdits` (every
7010
+ * record file); its edits are not to be made curated.
7011
+ */
7012
+ unreadableManifest: z31.literal(true).optional(),
7013
+ /**
7014
+ * 3.15.0 (beta.28.2, ADR 0197): a `newer-atticus` refusal's files a newer Atticus wrote
7015
+ * (build.json, a slot), each with its version field, the version it has and the newest one
7016
+ * this Atticus reads, as the 409 problem's `refused.newer` and the command line's --json say.
7017
+ */
7018
+ newer: z31.array(z31.object({
7019
+ /** Metarepo-relative, '/'-separated. */
7020
+ path: z31.string(),
7021
+ /** What the words call it: `build.json`, or its path. */
7022
+ name: z31.string(),
7023
+ /** The version field (`version`, `slotVersion`, `factsSchemaVersion`). */
7024
+ field: z31.string(),
7025
+ version: z31.number().int(),
7026
+ /** The newest version of it this Atticus reads. */
7027
+ reads: z31.number().int()
7028
+ })).optional(),
7005
7029
  /** What goes on in a terminal (the build, the hand edits' curate, or the upgrade). */
7006
7030
  command: z31.string(),
7007
7031
  /**
@@ -7637,7 +7661,7 @@ var VerifyPreviewView = z31.object({
7637
7661
  confirm: z31.object({
7638
7662
  removals: z31.number().int().optional(),
7639
7663
  edits: z31.number().int().optional(),
7640
- refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals"])).optional(),
7664
+ refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals", "newer-atticus"])).optional(),
7641
7665
  upgrade: z31.literal(true).optional(),
7642
7666
  command: z31.string().optional()
7643
7667
  }).optional(),
@@ -9887,7 +9911,12 @@ var UpgradeView = z31.object({
9887
9911
  * committed yet, besides the stamp. Final round: the panel reads them from the upgrade job's
9888
9912
  * result, and offers Propose for the stamp alone too.
9889
9913
  */
9890
- upgraded: z31.array(z31.string()).optional()
9914
+ upgraded: z31.array(z31.string()).optional(),
9915
+ /**
9916
+ * 3.15.0 (beta.28.2, ADR 0197): the catalog was built by a newer Atticus, in words that say to
9917
+ * upgrade Atticus (never `atticus upgrade`); `pending` is then empty, as the upgrade refuses.
9918
+ */
9919
+ newerCatalog: z31.string().optional()
9891
9920
  });
9892
9921
  var FileEditView = z31.object({
9893
9922
  path: z31.string(),
@@ -13618,6 +13647,11 @@ init_common();
13618
13647
  init_kinds();
13619
13648
  init_kept_files();
13620
13649
 
13650
+ // packages/core/dist/cancel.js
13651
+ import { AsyncLocalStorage } from "node:async_hooks";
13652
+ var store = new AsyncLocalStorage();
13653
+ var commits = new AsyncLocalStorage();
13654
+
13621
13655
  // packages/core/dist/gates-migrate.js
13622
13656
  init_orgpack();
13623
13657
  import { isMap as isMap6, isSeq as isSeq4, parseDocument as parseDocument6 } from "yaml";
@@ -13968,8 +14002,11 @@ var RETITLE_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
13968
14002
  var DAY = 24 * 60 * 60 * 1e3;
13969
14003
 
13970
14004
  // packages/core/dist/printer.js
13971
- import { AsyncLocalStorage } from "node:async_hooks";
13972
- var printer = new AsyncLocalStorage();
14005
+ import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
14006
+ var printer = new AsyncLocalStorage2();
14007
+
14008
+ // packages/core/dist/initialisms.js
14009
+ var ORDINARY = new Set("add all alter and any are ask asc bad begin but can case close closed column commit copy create data date day debug delete desc done drop each else end error fail false file fix fixme for from full get given good group had has having head help how inner insert int into its join key left like limit list max may min must new next none not note now null off old one only open option options order our out outer pass patch per post put read right row run see select set shall should show start status stop sum table tbd test that the then this tip todo top true two union update use user value values via warn warning was when where who why with yes you".split(" "));
13973
14010
 
13974
14011
  // packages/core/dist/zip-read.js
13975
14012
  var ZIP_LIMITS = {
@@ -14110,11 +14147,6 @@ init_kinds();
14110
14147
  init_spec();
14111
14148
  var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSION}`;
14112
14149
 
14113
- // packages/core/dist/cancel.js
14114
- import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
14115
- var store = new AsyncLocalStorage2();
14116
- var commits = new AsyncLocalStorage2();
14117
-
14118
14150
  // packages/core/dist/assistant-actor.js
14119
14151
  init_ai();
14120
14152
  init_orgpack();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maycombhq/sdk",
3
- "version": "2.0.0-beta.28.1",
3
+ "version": "2.0.0-beta.28.3",
4
4
  "description": "Atticus plugin SDK (contract C4): interfaces for extractors, dialects, ingestors and adapters.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",