@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.
- package/npm/core/api.d.ts +3168 -930
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/declared-links.d.ts +99 -0
- package/npm/core/facts-join.d.ts +38 -0
- package/npm/core/facts.d.ts +96 -1
- package/npm/core/fs.d.ts +39 -1
- package/npm/core/index.d.ts +2 -0
- package/npm/core/light.d.ts +1 -0
- package/npm/core/link-candidates.d.ts +24 -0
- package/npm/core/orgpack-defaults.d.ts +6 -0
- package/npm/core/orgpack-load.d.ts +5 -0
- package/npm/core/profile-migrate.d.ts +8 -6
- package/npm/core/record-cache.d.ts +17 -0
- package/npm/core/run-log.d.ts +11 -1
- package/npm/core/schema/frameworks.d.ts +2 -2
- package/npm/core/schema/orgpack.d.ts +74 -6
- package/npm/core/schema/review.d.ts +21 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/index.js +890 -44
- package/npm/sandbox.d.ts +2 -1
- package/package.json +1 -1
|
@@ -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
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
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
|
+
}>;
|
package/npm/core/facts-join.d.ts
CHANGED
|
@@ -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;
|
package/npm/core/facts.d.ts
CHANGED
|
@@ -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. */
|
package/npm/core/index.d.ts
CHANGED
|
@@ -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";
|
package/npm/core/light.d.ts
CHANGED
|
@@ -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
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* alias is a topic is a person's call. A version-1
|
|
6
|
-
* step for it; `addProfileSystem` applies
|
|
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> {
|
package/npm/core/run-log.d.ts
CHANGED
|
@@ -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[];
|