@maycombhq/sdk 2.0.0-beta.28.5 → 2.0.0-beta.30

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,69 @@
1
+ /**
2
+ * ADR 0205 step 4 (the owner's answer of 2026-11-19): what the app's server keeps in memory
3
+ * between Applies, so the next one doesn't read it back from disk: the last build's record texts
4
+ * and the facts parses (core's memo and the build cache's parses not yet on disk). Up to about
5
+ * 1 GB more at 100,000 records, let go:
6
+ * - ten minutes after the last Apply (`appMemoryApplied`; a page's read or a preview is no Apply),
7
+ * or ten minutes after something was kept with no Apply since;
8
+ * - at once when memory runs low: the heap three quarters full, or the machine's or the
9
+ * container's memory nearly used (`systemMemory`), checked on each use (the system's at most
10
+ * once a second) and every half minute on a timer, so an idle server lets go too;
11
+ * - when the last server closes.
12
+ * Off outside the server (`atticus ui` turns it on): a command builds once and ends.
13
+ */
14
+ export declare const appMemory: {
15
+ on: boolean;
16
+ idleMs: number;
17
+ /** The heap's share that is low (of V8's limit). */
18
+ lowAt: number;
19
+ /** The machine's (or container's) free share that is low, and the least free that is. */
20
+ lowFree: number;
21
+ lowFreeMinBytes: number;
22
+ /** How often the timer checks, and how often a use reads the system's memory at most. */
23
+ checkMs: number;
24
+ systemEveryMs: number;
25
+ /** The tests: the machine's memory in place of `systemMemory()`. */
26
+ system?: () => {
27
+ free: number;
28
+ total: number;
29
+ };
30
+ };
31
+ /**
32
+ * The memory this process may still use and the most it may, in bytes: the machine's
33
+ * (`os.freemem`, `os.totalmem`), or its container's where a cgroup limits it lower (Linux: the
34
+ * process's own cgroup, from /proc/self/cgroup, and those above it, the one with the least room:
35
+ * cgroup v2's memory.max and memory.current, less the file cache it can give back, or v1's
36
+ * limit_in_bytes and usage_in_bytes). Windows and macOS have no cgroup files: the machine's.
37
+ */
38
+ export declare function systemMemoryOf(read: (path: string) => string | undefined, os: {
39
+ freemem: () => number;
40
+ totalmem: () => number;
41
+ }): {
42
+ free: number;
43
+ total: number;
44
+ };
45
+ /** This machine's (or container's) memory now. */
46
+ export declare const systemMemory: () => {
47
+ free: number;
48
+ total: number;
49
+ };
50
+ /**
51
+ * What to let go when the app's memory is let go (each keeper registers its own), and what it
52
+ * holds, for the measurement (`appMemoryHeld`).
53
+ */
54
+ export declare function onAppMemoryRelease(release: () => void, held?: () => Record<string, number>): void;
55
+ /** What the keepers hold now, in bytes, by what it is. */
56
+ export declare function appMemoryHeld(): Record<string, number>;
57
+ /** Let go of everything kept for the app now. */
58
+ export declare function releaseAppMemory(): void;
59
+ /**
60
+ * Whether a keeper may keep (or use) what it holds for the app now: on, and memory not low
61
+ * (else everything is let go first). A keeper that keeps with no Apply pending starts the ten
62
+ * minutes; it doesn't start them again (only an Apply does, `appMemoryApplied`).
63
+ */
64
+ export declare function appMemoryInUse(): boolean;
65
+ /** An Apply ran in the app's server: what it keeps is kept ten more minutes from now. */
66
+ export declare function appMemoryApplied(): void;
67
+ /** A server starts keeping (`atticus ui`); the last to close stops, letting go. */
68
+ export declare function startAppMemory(): void;
69
+ export declare function stopAppMemory(): void;
@@ -1,12 +1,33 @@
1
+ /**
2
+ * Atticus's own agents, which draft, judge and review: a `by` that names one is an AI, never a
3
+ * person (ADR 0203 A.4). Matched exactly (assistantActor); a hyphenated handle ending `-critic`
4
+ * or `-naysayer` (every critic lens and every persona's naysayer) is matched by that suffix.
5
+ * assistantActor always knows them, as the whole handle or an email's local part; the org
6
+ * pack's names (assistantNames, in @maycombhq/changes) only as the whole handle.
7
+ * packages/changes/test/assistant-names.test.ts reads every agent id the code defines and
8
+ * checks each is here.
9
+ */
10
+ export declare const BUILT_IN_AGENTS: readonly string[];
1
11
  /**
2
12
  * The name a `by` matched when it names an AI agent or runtime rather than a person (ADR 0115
3
- * addendum, 2026-10-25): one of the assistants Atticus writes files for, or its short name (the
4
- * part before its first hyphen); a runtime kind; a generic word for an AI; a Git host's bot
5
- * account; or one of `known`, which the caller fills from the org pack (its agents' ids, the models
6
- * it allows). A handle matches a name when it is the name, or starts or ends with it joined by a
7
- * hyphen, dot, underscore or space ("copilot-agent", "ai-reviewer"); an email is read by its local
8
- * part. Undefined for a person. Facts about the words only: Atticus can't see who typed them, so
9
- * this is a record and a speed bump, and the pull request a person approves stays the gate.
13
+ * addendum, 2026-10-25; ADR 0203 A.4). Three rules:
14
+ *
15
+ * 1. One of the assistants Atticus writes files for, or its short name (the part before its first
16
+ * hyphen); a runtime kind; a generic word for an AI; a Git host's bot account. Such a word
17
+ * matches when it is the handle, or starts or ends it joined by a hyphen, dot, underscore or
18
+ * space ("copilot-agent", "ai-reviewer"); an email is read by its local part.
19
+ * 2. One of Atticus's own agents (BUILT_IN_AGENTS): the whole `by`, or an email's local part,
20
+ * exactly, case aside ("feature-placer@…" is the agent). One of `known`, which the caller
21
+ * fills from the org pack (its agents, its persona files, the models it allows): the whole
22
+ * `by` only, exactly, case aside, never an email's local part: a persona's name is often a
23
+ * role's, and a team mailbox of that name ("security@…", "qa@…") is a person. Never a part
24
+ * of either, so "m.judge@…" or "judge.smith" is a person.
25
+ * 3. A handle that ends `-critic` or `-naysayer` and is one hyphenated word of letters and digits
26
+ * (every critic lens and every persona's naysayer is named so): not an email, a dotted name,
27
+ * or words with spaces or underscores, which are people's.
28
+ *
29
+ * Undefined for a person. Facts about the words only: Atticus can't see who typed them, so this
30
+ * is a record and a speed bump, and the pull request a person approves stays the gate.
10
31
  */
11
32
  export declare function assistantActor(by: string, known?: readonly string[]): string | undefined;
12
33
  /** Whether a finding's resolution was recorded by an AI rather than a person. */
@@ -8,3 +8,17 @@ export declare function migrateChangeTypesText(text: string): {
8
8
  text: string;
9
9
  changed: boolean;
10
10
  };
11
+ /** The quick type's entry on one line, for a person to add to a list written that way. */
12
+ export declare const QUICK_ENTRY_ONE_LINE: string;
13
+ /**
14
+ * Add the quick change type (ADR 0201) at the end of a change-types.yaml's `types`. The entry is
15
+ * put into the text after the list's last line, at the list's own indent and line endings, so
16
+ * comments and every other entry stay byte for byte. Unchanged when the file doesn't read as
17
+ * change types or already has a type `quick`; when it keeps its types on one line, `why` says so.
18
+ */
19
+ export declare function addQuickTypeText(text: string): {
20
+ text: string;
21
+ changed: boolean;
22
+ /** Unchanged because the list is a flow sequence (`types: [ … ]`): a person adds the entry. */
23
+ why?: "one-line";
24
+ };
@@ -1,4 +1,5 @@
1
1
  import { type LineChange } from "./manifest-edit.js";
2
+ import { type ArrowEnd, type DeclaredLink } from "./schema/orgpack.js";
2
3
  /**
3
4
  * G3 (ADR 0174): what a person declares on the canvas that the code can't show, written to the
4
5
  * profile that has the system, comments and order kept, for review. A topic the system publishes
@@ -109,3 +110,101 @@ export declare function declaredOf(root: string, system: string): Promise<{
109
110
  rel?: string;
110
111
  list: DeclaredOnFile[];
111
112
  }>;
113
+ /** A declared arrow as a person asks for it: the two ends, why, and whether it is built yet. */
114
+ export interface ArrowAsked {
115
+ from: ArrowEnd;
116
+ to: ArrowEnd;
117
+ why: string;
118
+ planned?: boolean;
119
+ }
120
+ /** One declared arrow as the profiles hold it, with the file it is in. */
121
+ export interface DeclaredArrow extends DeclaredLink {
122
+ platform: string;
123
+ /** The profile, relative to the metarepo's org pack: `profiles/<platform>/profile.yaml`. */
124
+ file: string;
125
+ }
126
+ /** Every declared arrow of the profiles, in the profiles' order then the file's. */
127
+ export declare function declaredArrows(op: {
128
+ profiles: readonly {
129
+ platform: string;
130
+ profile?: {
131
+ links?: readonly DeclaredLink[];
132
+ };
133
+ }[];
134
+ }): DeclaredArrow[];
135
+ /**
136
+ * ADR 0204 1.4: write a declared arrow as one item of the profile's `links` (or, with `preview`,
137
+ * say the lines it changes), in `platform`'s profile: the caller's, else the callee's (the caller
138
+ * works it out). The profile moves to version 3 (the number only); comments and order are kept,
139
+ * and the write is refused whole if the file changed since it was read, or if the pair is listed.
140
+ */
141
+ export declare function declareArrow(root: string, a: ArrowAsked, o: {
142
+ by: string;
143
+ at: string;
144
+ platform: string;
145
+ preview?: boolean;
146
+ /**
147
+ * ADR 0204 3.1 (`add-system`): a system only the code names, added to this profile's systems
148
+ * in the same write as the arrow, with who and when on its id (as the canvas adds one).
149
+ */
150
+ addSystem?: {
151
+ id: string;
152
+ name: string;
153
+ boundary: "vendor" | "internal";
154
+ };
155
+ }): Promise<{
156
+ rel: string;
157
+ changes: LineChange[];
158
+ written: boolean;
159
+ before: string;
160
+ wrote?: string;
161
+ /** The version the profile was at, when this write raised it (Undo puts it back). */
162
+ raisedFrom?: number;
163
+ }>;
164
+ /**
165
+ * ADR 0204 1.7 and 2.4: take one declared arrow out of `platform`'s profile (Retire the declared
166
+ * arrow, Undo, Remove it): exactly that item's lines, and the `links:` key when it was the last;
167
+ * every other byte as it was, the version too. `preview` says the lines and writes nothing.
168
+ */
169
+ export declare function retireArrow(root: string, a: {
170
+ from: ArrowEnd;
171
+ to: ArrowEnd;
172
+ }, o: {
173
+ platform: string;
174
+ preview?: boolean;
175
+ /**
176
+ * Undo (ADR 0204 2.4): the version the arrow's write raised the profile from, put back on
177
+ * its own line when no arrow is left, so the file is again exactly as it was.
178
+ */
179
+ lowerTo?: number;
180
+ }): Promise<{
181
+ rel: string;
182
+ changes: LineChange[];
183
+ written: boolean;
184
+ before: string;
185
+ wrote: string;
186
+ /**
187
+ * The second review of ADR 0204: an Undo's `lowerTo` below what the profile now needs (a topic
188
+ * added since needs version 2): the profile stays at the version it needs, said in these words.
189
+ */
190
+ keptAt?: {
191
+ version: number;
192
+ why: string;
193
+ };
194
+ }>;
195
+ /**
196
+ * ADR 0204 2.4: Undo of an arrow whose write added a system (`addSystem`): the system goes too,
197
+ * only while it is still exactly as added (its fields hash to its comment's), nothing else names
198
+ * it in the profile and (`inUse`, ADR 0174, the second review) no pairing or answered question
199
+ * names it: the caller works that out from the estate. Else it is left, with why, said by the
200
+ * caller.
201
+ */
202
+ export declare function removeAddedSystem(root: string, o: {
203
+ platform: string;
204
+ system: string;
205
+ inUse?: boolean;
206
+ }): Promise<{
207
+ removed: boolean;
208
+ rel: string;
209
+ why?: "changed" | "named" | "in-use";
210
+ }>;
@@ -586,6 +586,44 @@ export declare function registrableDomain(host: string): string | undefined;
586
586
  * no key that reads as a host). The measure uses it to tell which outside system took a call.
587
587
  */
588
588
  export declare function callHostOf(f: Call, repoFacts: readonly Fact[]): string | undefined;
589
+ /** How a host nothing the join reads gives a value is worded (`unsetHostOf`). */
590
+ export type UnsetHostForm = "token" | "variable" | "setting" | "set";
591
+ /**
592
+ * What the join knows of the settings when it words an unset host: the names its settings have
593
+ * (`settingNameKey` of each config fact's key, the estate's), and whether the call's repo has
594
+ * settings with camelCase keys (the review of 5cc4ce87: then a camelCase name is a setting's).
595
+ */
596
+ export interface UnsetHostSettings {
597
+ names?: ReadonlySet<string>;
598
+ camel?: boolean;
599
+ }
600
+ /** A setting's key in camelCase (`ledgerUrl`, `forge.ledgerUrl`): a lower letter, then an upper. */
601
+ export declare const camelSettingKey: (key: string) => boolean;
602
+ /**
603
+ * The owner, 2026-11-19 (ADR 0195, the beta.28.1 addendum's sub-addendum): a host nothing the
604
+ * join reads gives a value, by how it is written. `token`: a build, deploy or config token
605
+ * (`@name@`, `${NAME}`, `${forge.ledger.url}`, `$NAME`, `%NAME%`), asked about as "a deploy token
606
+ * nothing sets". `variable`: a variable of the code's (`${baseUrl}`, `${this.cfg.url}`,
607
+ * `${process.env.X}`, Kotlin's and Groovy's `$baseUrl`, PowerShell's `$env:X`), asked about as "a
608
+ * variable Atticus couldn't find the value of". Only as the whole host (the scheme aside), read at
609
+ * the start of the value or after a scheme or a space (a loose end's raw names its method first).
610
+ * Camel Simple's names (`${header.x}`, `${body}`) are the route's message, and none.
611
+ *
612
+ * The review of 5cc4ce87 (I2), given what the join knows of the settings: `set`, a name a setting
613
+ * of the estate has (`settings.names`), whatever its form: never "a deploy token nothing sets",
614
+ * since a setting has that key, but one that gave no host for this call; and `setting`, a
615
+ * camelCase name (`${ledgerUrl}`, `$ledgerUrl`) nothing sets, where the call's repo has settings
616
+ * with camelCase keys (`settings.camel`): worded as a setting, else as a variable of the code's.
617
+ * `name` is the setting's name the host is written with (`FORGE_LEDGER_URL` of
618
+ * `%FORGE_LEDGER_URL%`).
619
+ */
620
+ export declare function unsetHostOf(value: string | undefined, settings?: UnsetHostSettings): {
621
+ host: string;
622
+ form: UnsetHostForm;
623
+ name: string;
624
+ } | undefined;
625
+ /** The question for a call whose whole host nothing gives a value, worded by its form. */
626
+ export declare function unsetHostQuestion(host: string, form: UnsetHostForm, repo: string, name?: string): string;
589
627
  export declare function placeholderIn(s: string | undefined): {
590
628
  name: string;
591
629
  fallback?: string;
@@ -48,6 +48,32 @@ export declare function newerFactOf(json: unknown, line?: number): NewerFact | u
48
48
  * own and kept as written; anything else wrong is a wrong fact, refused for the assistant to fix.
49
49
  */
50
50
  export declare function newerShapeOf(json: unknown, issues: readonly z.core.$ZodIssue[], line?: number): NewerFact | undefined;
51
+ /**
52
+ * ADR 0205 step 3: a facts file is parsed once for its bytes. Each parse is kept, serialized
53
+ * (`v8.serialize`, which keeps -0 and fields set to undefined), by the SHA-256 of the text, in
54
+ * this process (a bounded memo) and, where a build installed one, in the build cache's store on
55
+ * disk; a text with the same bytes is the same parse, handed back as a fresh copy.
56
+ */
57
+ export declare const factsParseHooks: {
58
+ /** The way before step 3: every text parsed. */
59
+ off?: boolean;
60
+ /** The equivalence tests: each kept parse checked against a parse of the text, or a throw. */
61
+ check?: boolean;
62
+ /** The build cache's store on disk, by the text's hash (installed by the scanner). */
63
+ store?: {
64
+ get(textSha: string): Uint8Array | undefined;
65
+ put(textSha: string, kept: Uint8Array): void;
66
+ /** A parse of this text was used from the memo: the store keeps its copy. */
67
+ used(textSha: string): void;
68
+ };
69
+ };
70
+ /** How often a kept parse was used, and a text parsed (the tests). */
71
+ export declare const factsParseStats: {
72
+ kept: number;
73
+ parsed: number;
74
+ };
75
+ /** Forget this process's kept parses (a test of the store on disk; a server letting memory go). */
76
+ export declare function forgetFactsParses(): void;
51
77
  export declare function parseFacts(text: string): ParseFactsResult;
52
78
  /**
53
79
  * A facts file's line as it may be kept where people read it (`<repo>.rejected.jsonl`), beta.25
@@ -107,6 +133,74 @@ export interface ProjectResult {
107
133
  }
108
134
  /** A name as a part of a projected catalog id: its slug, with dots made dashes (a component, a store). */
109
135
  export declare const factIdPart: (text: string) => string;
136
+ /**
137
+ * ADR 0124 addendum E-ids (the owner, 2026-11-19): the id of the loose end a fact leaves,
138
+ * `unresolved.<repo>.<rest>`, the repo as the other ids name it (`factIdPart`, as a component
139
+ * named for its repo is), so the same fact id in two repos is two records. `rest` is the call's
140
+ * fact id (`factIdPart`), or a listener's Endpoint id (`<component>.<name>`).
141
+ */
142
+ export declare const unresolvedIdOf: (repo: string, rest: string) => string;
143
+ /**
144
+ * The second whole-release review of beta.30: another repo id among `ids` that names the same
145
+ * loose-end id as `id` (`forge.api` and `forge-api`), so the map couldn't tell their loose ends
146
+ * apart. The id scheme is C1's and stays: two such repo ids are refused where a repo id is written.
147
+ */
148
+ export declare function repoIdTwinOf(id: string, ids: Iterable<string>): string | undefined;
149
+ /**
150
+ * A twin pair in the one order every place says it (the review of b30/review2-fixes): sorted by
151
+ * cmpText, so doctor, the stages, a build, a scan, selfcheck and GET /api/build name the pair
152
+ * alike and suggest renaming the same repo, the second.
153
+ */
154
+ export declare const repoIdTwinPair: (x: string, y: string) => [string, string];
155
+ /** Why two repo ids can't both be: the words every refusal of repoIdTwinOf's pair starts with. */
156
+ export declare const repoIdTwinWords: (x: string, y: string) => string;
157
+ /** A pair of repo ids that name one loose-end id, and the way on: rename the second (repoIdTwinPair). */
158
+ export declare const repoIdTwinWarning: (x: string, y: string) => string;
159
+ /**
160
+ * Every pair of repo ids that name one loose-end id, whatever order they are listed in: for each
161
+ * loose-end id, its repo ids sorted (cmpText), the first with each of the others, the pairs
162
+ * sorted. What a merge of two pull requests, or a hand edit, can leave on disk past the refusals
163
+ * where an id is written (doctor, selfcheck, a build, the stages).
164
+ */
165
+ export declare function repoIdTwins(ids: Iterable<string>): [string, string][];
166
+ /**
167
+ * ADR 0124 addendum E-ids: an Unresolved record the facts projection made, by the id each repo's
168
+ * own record has now, once per repo its evidence names, sorted. Before beta.30 the id carried no
169
+ * repo (`unresolved.<fact id>`, `unresolved.<component>.<name>` for a listener), so two repos'
170
+ * loose ends with one fact id were one record citing one of them; such an id is named again with
171
+ * each repo its evidence names. A record of the new form gives its own id. Told apart by shape,
172
+ * which is unambiguous: a call's fact id part and an Endpoint's name have no dot (`factIdPart`).
173
+ * Anything else (a built-in reader's loose end, `<owner>.<kind>.<hash>`; no repo): none.
174
+ */
175
+ export declare function unresolvedIdsNow(r: {
176
+ kind: string;
177
+ id: string;
178
+ unresolvedKind?: unknown;
179
+ owner?: unknown;
180
+ evidence?: readonly {
181
+ repo?: string | undefined;
182
+ }[];
183
+ }): string[];
184
+ /**
185
+ * ADR 0124 addendum E-ids: whether an id, with no record to tell by, is a loose end's id of the
186
+ * form before beta.30: a call's `unresolved.<fact id>` (no dot after it), or a listener's
187
+ * `unresolved.<component>.on-<topic>` (one dot, then an event Endpoint's name). For words only;
188
+ * `unresolvedIdsNow` tells a record's for sure.
189
+ */
190
+ export declare function oldLooseEndId(id: string): boolean;
191
+ /**
192
+ * ADR 0124 addendum E-ids (the review of 5cc4ce87, I1): whether an id, with no record to tell
193
+ * by, may be a loose end's id of the form before beta.30, given the repos' id parts
194
+ * (`factIdPart` of each repo): what `oldLooseEndId` reads, or a listener of a component whose id
195
+ * has a dot (`unresolved.forge.ledger.on-x`), whose first part is no repo's (under a repo's id,
196
+ * the same shape is the new form).
197
+ */
198
+ export declare function mayBeOldLooseEndId(id: string, repoParts: ReadonlySet<string>): boolean;
199
+ /**
200
+ * ADR 0124 addendum E-ids: the id a loose end of the new form (`unresolved.<repo>.<rest>`) had
201
+ * before beta.30 (`unresolved.<rest>`); undefined for a record of any other form.
202
+ */
203
+ export declare function oldIdOfLooseEnd(r: Parameters<typeof unresolvedIdsNow>[0]): string | undefined;
110
204
  /** The Endpoint id an entry fact projects to in its component (`projectFacts`). */
111
205
  export declare function entryEndpointId(f: FactOf<"entry">, component: string): string;
112
206
  /**
@@ -148,6 +242,7 @@ export declare function catalogAuth(f: FactOf<"entry">): FactOf<"entry">["auth"]
148
242
  * Facts to C1. Ids are made from the claims, so the same facts give the same ids:
149
243
  * Endpoint `<component>.<method-path>`, Interface `if-<hash>`, DataStore `<store>`,
150
244
  * Table `<store>.<table>`, Column `<store>.<table>.<column>`, Schema `<endpoint>.<side>`,
151
- * Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`.
245
+ * Deployment `<component>.<env>`, Setting `<component>.<key>`, Flow `<component>.<name>`,
246
+ * Unresolved `unresolved.<repo>.<call>` (ADR 0124 addendum E-ids).
152
247
  */
153
248
  export declare function projectFacts(input: readonly Fact[], opts?: ProjectOptions): ProjectResult;
package/npm/core/fs.d.ts CHANGED
@@ -139,6 +139,11 @@ export interface LockInfo {
139
139
  host: string;
140
140
  startedAt: string;
141
141
  what: string;
142
+ /**
143
+ * ADR 0205 step 2: `caches` once its writer gave its result and is writing its local caches
144
+ * (`caching`): a lock left so by a process that stopped then was of a catalog written whole.
145
+ */
146
+ phase?: "caches";
142
147
  }
143
148
  export declare class LockHeldError extends Error {
144
149
  readonly held: LockInfo;
@@ -154,10 +159,41 @@ export declare function readLock(root: string, name: string, o?: {
154
159
  }): Promise<(LockInfo & {
155
160
  stale: boolean;
156
161
  }) | undefined>;
162
+ /** The tests' fault (the property tests, ADR 0205): the process stops after its result. */
163
+ export declare const afterResultHooks: {
164
+ /**
165
+ * The next `runAfterResult` never runs its work: its writer's lock is left as a process that
166
+ * stopped there leaves it (held by no one here, so the next taker takes it over). Once.
167
+ */
168
+ die?: boolean;
169
+ };
170
+ /**
171
+ * ADR 0205 step 2 (the owner's answer of 2026-11-19: "done" is shown while the caches are
172
+ * written under the lock): run `work` after the caller has given its result. The work must end
173
+ * by releasing the lock its writer holds (`under`: the metarepo and the lock's name). A later
174
+ * `acquireLock` of that lock in this process waits for it first, so the next writer here never
175
+ * meets that lock held; a taker of another lock doesn't wait. A failure is swallowed, since the
176
+ * work is only a cache's (a cache not written is no cache).
177
+ */
178
+ export declare function runAfterResult(work: () => Promise<void>, under?: {
179
+ root: string;
180
+ name: string;
181
+ }): void;
182
+ /** How many `runAfterResult` works of this process haven't ended (the tests). */
183
+ export declare function afterResultPending(): number;
184
+ /**
185
+ * Wait for the `runAfterResult` works of this process: every one (a server closing, a command
186
+ * ending), or only those under one lock (its next taker).
187
+ */
188
+ export declare function settleAfterResult(under?: {
189
+ root: string;
190
+ name: string;
191
+ }): Promise<void>;
157
192
  /**
158
193
  * Take a lock for a long write (a scan): one at a time per metarepo. A lock whose process is
159
194
  * gone was cut short (a crash, a closed terminal); it is taken over and reported as
160
- * `interrupted`, so the caller can say the last run didn't finish.
195
+ * `interrupted`, so the caller can say the last run didn't finish. A writer of this process
196
+ * still writing its caches after its result (`runAfterResult`) is waited for first.
161
197
  */
162
198
  export declare function acquireLock(root: string, name: string, what: string, now?: () => Date,
163
199
  /** A lock older than this is taken over (Windows reuses a dead process's PID). */
@@ -165,6 +201,8 @@ o?: {
165
201
  maxAgeMs?: number;
166
202
  }): Promise<{
167
203
  release: () => Promise<void>;
204
+ /** ADR 0205 step 2: the result is given; the caches are written next, under this lock. */
205
+ caching: () => Promise<void>;
168
206
  interrupted?: LockInfo;
169
207
  }>;
170
208
  /** The lock file beside a file two processes write (`<file>.lock`): no facts-folder reader takes it for a file of its own. */
@@ -3,6 +3,7 @@ export * from "./schema/kinds.js";
3
3
  export * from "./schema/facts.js";
4
4
  export * from "./schema/fact-corrections.js";
5
5
  export * from "./facts.js";
6
+ export * from "./app-memory.js";
6
7
  export * from "./fact-paths.js";
7
8
  export * from "./migration-files.js";
8
9
  export * from "./facts-join.js";
@@ -66,6 +67,7 @@ export * from "./hash-cache.js";
66
67
  export * from "./kept-files.js";
67
68
  export * from "./log.js";
68
69
  export * from "./run-log.js";
70
+ export * from "./version-order.js";
69
71
  export * from "./printer.js";
70
72
  export * from "./zip.js";
71
73
  export * from "./words.js";
@@ -10,3 +10,4 @@ export { recordedCommand, retitleTerminalRuns, runLogKept, runTitle, startTermin
10
10
  export { printToCurrent, withPrinter } from "./printer.js";
11
11
  export { atticusHandles, onAtticusSignal } from "./process-trees.js";
12
12
  export { keyIsSecret } from "./cite.js";
13
+ export { atticusVersionOf, newerThan } from "./version-order.js";
@@ -92,6 +92,18 @@ export interface CandidateCall {
92
92
  * ADR 0199: also who paired a `paired` call with this box.
93
93
  */
94
94
  pairedBy?: string;
95
+ /**
96
+ * Beta.30 (the owner's field report, "it's connected to the wrong box"): for a call that goes
97
+ * somewhere already, how that was decided, as the estate's join says: `code`, the call's own
98
+ * fact names the box; `address`, its host or base path is the box's; `path`, only its path
99
+ * matched (a guess); `gateway`, a gateway's route forwards it there (`through` the gateway's
100
+ * repo); `answer`, a person's answer to a question; `paired`, a person's pairing; `ai`, the
101
+ * AI's pairing or answer; `kept`, the map draws an arrow from the call's line that this read's
102
+ * join doesn't place (kept from an earlier read, as an upgrade adopts them). `who` is who
103
+ * answered or paired. The caller that reads the files adds when, the question and a
104
+ * pairing's reason.
105
+ */
106
+ how?: CandidateHow;
95
107
  suggestion?: {
96
108
  api: string;
97
109
  score: number;
@@ -106,6 +118,18 @@ export interface CandidateCall {
106
118
  /** The best is well ahead of the rest and scores high: safe to pair without a look. */
107
119
  confident?: boolean;
108
120
  }
121
+ export interface CandidateHow {
122
+ by: "code" | "address" | "path" | "gateway" | "answer" | "paired" | "ai" | "kept";
123
+ who?: string;
124
+ /** For gateway: the repo of the gateway whose route forwards the call. */
125
+ through?: string;
126
+ /** When it was answered or paired, the question answered, a pairing's reason (the caller's). */
127
+ at?: string;
128
+ question?: string;
129
+ reason?: string;
130
+ }
131
+ /** How a join was decided, in the kinds Connect says (the join's own words, never a guess). */
132
+ export declare function howOfJoin(j: FactsJoinResult["joins"][number]): CandidateHow;
109
133
  export type SuggestWhy = "same-path" | "prefix" | "parameter" | "names-alike"
110
134
  /** The call's path, with its settings resolved, is the API's. */
111
135
  | "setting"
@@ -1,3 +1,9 @@
1
+ import { ChangeType } from "./schema/orgpack.js";
2
+ /**
3
+ * The quick path's type (ADR 0201): a plain OpenSpec change, with no stage. `specs` is listed
4
+ * because a change with no spec delta isn't valid OpenSpec. Quick by its shape (`quickPathOf`).
5
+ */
6
+ export declare const QUICK_CHANGE_TYPE: ChangeType;
1
7
  export declare const DEFAULT_CHANGE_TYPES: {
2
8
  schemaVersion: 1 | 2;
3
9
  types: {
@@ -70,6 +70,11 @@ export interface OrgPack {
70
70
  defaulted: string[];
71
71
  problems: OrgPackProblem[];
72
72
  }
73
+ /**
74
+ * ADR 0203 A.1: the prefix of the built-in gates a stage's own blocking findings are written to
75
+ * (`stage-feature`, `stage-architecture`, …). A gates.yaml gate may not take it.
76
+ */
77
+ export declare const STAGE_GATE_PREFIX = "stage-";
73
78
  /**
74
79
  * Read and validate a whole org pack. Never throws for content problems: every schema or
75
80
  * cross-file problem is listed in `problems` with its file, so a team sees all of them at
@@ -1,11 +1,13 @@
1
1
  /**
2
- * profile.yaml version 1 → 2 (ADR 0162 amendment). Version 2 adds a system's `topics`; a file
3
- * without them names no topic, as version 1 did, so the step writes the new number only and keeps
4
- * the file's comments, order and line layout. Nothing is moved from `aliases` to `topics`: which
5
- * alias is a topic is a person's call. A version-1 profile stays valid, so `atticus upgrade` has no
6
- * step for it; `addProfileSystem` applies this when it writes a topic.
2
+ * profile.yaml moved up to the version a write needs (ADR 0162 amendment: 2 for a system's
3
+ * `topics`; ADR 0204: 3 for the declared arrows, `links`). A file without what the new version
4
+ * adds says what it said, so the step writes the new number only and keeps the file's comments,
5
+ * order and line layout. Nothing is moved: which alias is a topic is a person's call. A version-1
6
+ * or 2 profile stays valid, so `atticus upgrade` has no step for it; `addProfileSystem` applies
7
+ * this when it writes a topic (to 2), `declareArrow` when it writes an arrow (to 3). A file at
8
+ * `to` or above is left as it is.
7
9
  */
8
- export declare function migrateProfileText(text: string): {
10
+ export declare function migrateProfileText(text: string, to?: number): {
9
11
  text: string;
10
12
  changed: boolean;
11
13
  };
@@ -41,6 +41,13 @@ export declare const RACY_MS = 2000;
41
41
  /** Tests set the clock a parse is kept at (ms; default `Date.now`). */
42
42
  export declare const recordCacheHooks: {
43
43
  now?: () => number;
44
+ /** The tests: the size limit of the parses kept in memory, in place of `MEMORY_MAX`. */
45
+ memoryMaxBytes?: number;
46
+ /**
47
+ * ADR 0205's proof: each parse a read takes from memory is checked against the parse of its
48
+ * file as the cache on disk would give it (its JSON), or a throw.
49
+ */
50
+ checkMemory?: boolean;
44
51
  };
45
52
  /** One file's parse: the value, or why the file isn't valid. Never both. */
46
53
  export interface Parsed<T> {
@@ -75,6 +82,10 @@ interface Entry {
75
82
  * ends it between two lots with CancelledError (beta.28.3).
76
83
  */
77
84
  export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>, signal?: AbortSignal): Promise<O[]>;
85
+ /** How many reads took their parses from memory (the tests). */
86
+ export declare const recordCacheStats: {
87
+ fromMemory: number;
88
+ };
78
89
  /**
79
90
  * Read and parse every named file of a folder, reusing the parses kept from an earlier run for
80
91
  * the files that haven't changed. `name` names the kind of file (`catalog`, `spec`), `version`
@@ -108,6 +119,12 @@ export declare function readParsedFiles<T>(o: {
108
119
  * CancelledError; nothing is kept of a stopped read.
109
120
  */
110
121
  signal?: AbortSignal;
122
+ /**
123
+ * ADR 0205 step 4: a writer's read, in the app's server: its parses kept in memory between
124
+ * reads too (frozen, handed out without a copy), and taken from there. Outside a server, or
125
+ * with `keep: false`, nothing changes.
126
+ */
127
+ memory?: boolean;
111
128
  }): Promise<Parsed<T>[]>;
112
129
  /** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
113
130
  export interface KeptParses<T> {
@@ -75,6 +75,12 @@ export interface TerminalRunRecord {
75
75
  };
76
76
  /** A job the app started that was still running when the app closed. */
77
77
  appClosed?: true;
78
+ /**
79
+ * Beta.30 (ADR 0202 point 10): the longest time, in milliseconds, the command printed
80
+ * nothing: between two of its lines (progress lines included), before its first and after its
81
+ * last. A run from before beta.30 has none.
82
+ */
83
+ longestQuietMs?: number;
78
84
  }
79
85
  /** A record as read: `stale` when its process is gone though it never said it ended. */
80
86
  export type TerminalRunView = TerminalRunRecord & {
@@ -208,7 +214,11 @@ export interface TerminalRunRecorder {
208
214
  /** Print a line (or several, split at newlines) to the run's log. */
209
215
  line(text: string): void;
210
216
  /** Record how it ended: 0 done, 130 or 143 (Ctrl+C, a stop) cancelled, else failed. */
211
- end(code: number, how?: "crash" | "app-closed"): void;
217
+ end(code: number, how?: "crash" | "app-closed"): void; /**
218
+ * ADR 0202 points 9 and 10: the command waits on a person's answer (`true`), or has it
219
+ * (`false`). The time between the two is the person's, never the command's silence.
220
+ */
221
+ waits(on: boolean): void;
212
222
  }
213
223
  export interface StartRunOptions {
214
224
  positionals: readonly string[];