@maycombhq/sdk 2.0.0-beta.3 → 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/ai-decisions.d.ts +373 -0
- package/npm/core/api.d.ts +15888 -3797
- package/npm/core/app-memory.d.ts +69 -0
- package/npm/core/assistant-actor.d.ts +28 -7
- package/npm/core/audit.d.ts +174 -0
- package/npm/core/canary.d.ts +369 -0
- package/npm/core/cancel.d.ts +20 -0
- package/npm/core/catalog.d.ts +220 -66
- package/npm/core/change-types-migrate.d.ts +14 -0
- package/npm/core/cite.d.ts +88 -6
- package/npm/core/contract-check.d.ts +276 -0
- package/npm/core/curated.d.ts +10 -0
- package/npm/core/decision-batches.d.ts +29 -0
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +210 -0
- package/npm/core/eol.d.ts +5 -0
- package/npm/core/fact-paths.d.ts +14 -0
- package/npm/core/facts-callers.d.ts +23 -1
- package/npm/core/facts-carry.d.ts +8 -2
- package/npm/core/facts-deps.d.ts +85 -0
- package/npm/core/facts-join-prototype.d.ts +66 -4
- package/npm/core/facts-join-vendor.d.ts +67 -7
- package/npm/core/facts-join.d.ts +476 -2
- package/npm/core/facts-terms.d.ts +108 -0
- package/npm/core/facts.d.ts +155 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +84 -0
- package/npm/core/fs.d.ts +205 -7
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/glob.d.ts +14 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/host-questions.d.ts +273 -1
- package/npm/core/identity.d.ts +20 -8
- package/npm/core/index.d.ts +38 -0
- package/npm/core/initialisms.d.ts +62 -0
- package/npm/core/kept-files.d.ts +17 -0
- package/npm/core/light.d.ts +5 -0
- package/npm/core/link-candidates.d.ts +224 -0
- package/npm/core/link-evidence.d.ts +212 -0
- package/npm/core/log.d.ts +2 -0
- package/npm/core/manifest-edit.d.ts +83 -6
- package/npm/core/merge.d.ts +28 -0
- package/npm/core/metarepo.d.ts +26 -1
- package/npm/core/migrate.d.ts +3 -2
- package/npm/core/org-notes.d.ts +180 -0
- package/npm/core/orgpack-defaults.d.ts +30 -6
- package/npm/core/orgpack-load.d.ts +24 -0
- package/npm/core/paths.d.ts +23 -0
- package/npm/core/printer.d.ts +18 -0
- package/npm/core/process-trees.d.ts +109 -0
- package/npm/core/profile-migrate.d.ts +13 -0
- package/npm/core/question-order.d.ts +23 -0
- package/npm/core/question-owners.d.ts +57 -0
- package/npm/core/question-proposals.d.ts +77 -0
- package/npm/core/question-roles.d.ts +84 -0
- package/npm/core/questions.d.ts +123 -6
- package/npm/core/record-cache.d.ts +122 -2
- package/npm/core/repo-files.d.ts +66 -0
- package/npm/core/repo-reads.d.ts +44 -0
- package/npm/core/roles-migrate.d.ts +10 -0
- package/npm/core/run-log.d.ts +341 -0
- package/npm/core/runtime-migrate.d.ts +18 -0
- package/npm/core/schema/ai.d.ts +61 -13
- package/npm/core/schema/common.d.ts +32 -8
- package/npm/core/schema/component-type.d.ts +193 -0
- package/npm/core/schema/conventions.d.ts +80 -0
- package/npm/core/schema/dialect.d.ts +12 -12
- package/npm/core/schema/fact-corrections.d.ts +112 -2
- package/npm/core/schema/facts.d.ts +743 -23
- package/npm/core/schema/frameworks.d.ts +12 -12
- package/npm/core/schema/kinds.d.ts +230 -66
- package/npm/core/schema/orgpack.d.ts +248 -24
- package/npm/core/schema/question.d.ts +281 -5
- package/npm/core/schema/reading-rules.d.ts +51 -0
- package/npm/core/schema/repo-type.d.ts +20 -2
- package/npm/core/schema/review.d.ts +30 -9
- package/npm/core/schema/scan-verify.d.ts +77 -0
- package/npm/core/schema/version.d.ts +4 -1
- package/npm/core/schema/workspace.d.ts +29 -11
- package/npm/core/setup-edit.d.ts +107 -0
- package/npm/core/shared-maps.d.ts +146 -0
- package/npm/core/stack-helpers.d.ts +32 -0
- package/npm/core/version-order.d.ts +14 -0
- package/npm/fs-repo.d.ts +2 -1
- package/npm/index.js +14248 -6710
- package/npm/listing.d.ts +14 -0
- 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. */
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import type { Fact } from "./schema/facts.js";
|
|
3
|
+
/**
|
|
4
|
+
* The sample audit (plan item P3, ADR 0148): a person confirms a handful of a repo's kept facts
|
|
5
|
+
* and of the links the estate join makes from it, drawn at random but reproducibly from a seed,
|
|
6
|
+
* and the answers give a precision on the real estate. The answers are a person's record,
|
|
7
|
+
* `<repo>.audit.yaml` beside the facts, committed in a pull request like any other file of the
|
|
8
|
+
* metarepo; nothing is sent anywhere.
|
|
9
|
+
*
|
|
10
|
+
* The verifier never takes an audit's word into the facts file (a reader can't vouch for itself,
|
|
11
|
+
* and `atticus verify` writes `verified: line` on every fact a reader made): a right answer shows
|
|
12
|
+
* as `verified: sample` where the facts are read for a person (the Map's facts list), as long as
|
|
13
|
+
* the fact still cites the line the person saw. Pure: the caller reads and writes the file.
|
|
14
|
+
*/
|
|
15
|
+
export declare const AUDIT_ANSWERS: readonly ["right", "wrong", "unsure"];
|
|
16
|
+
export type AuditAnswer = (typeof AUDIT_ANSWERS)[number];
|
|
17
|
+
export declare const AuditItem: z.ZodObject<{
|
|
18
|
+
id: z.ZodString;
|
|
19
|
+
kind: z.ZodEnum<{
|
|
20
|
+
ai: "ai";
|
|
21
|
+
link: "link";
|
|
22
|
+
fact: "fact";
|
|
23
|
+
}>;
|
|
24
|
+
of: z.ZodString;
|
|
25
|
+
claim: z.ZodString;
|
|
26
|
+
cites: z.ZodArray<z.ZodString>;
|
|
27
|
+
fact: z.ZodOptional<z.ZodString>;
|
|
28
|
+
value: z.ZodOptional<z.ZodString>;
|
|
29
|
+
to: z.ZodOptional<z.ZodString>;
|
|
30
|
+
decided: z.ZodOptional<z.ZodString>;
|
|
31
|
+
run: z.ZodOptional<z.ZodString>;
|
|
32
|
+
answer: z.ZodOptional<z.ZodEnum<{
|
|
33
|
+
right: "right";
|
|
34
|
+
wrong: "wrong";
|
|
35
|
+
unsure: "unsure";
|
|
36
|
+
}>>;
|
|
37
|
+
note: z.ZodOptional<z.ZodString>;
|
|
38
|
+
by: z.ZodOptional<z.ZodString>;
|
|
39
|
+
at: z.ZodOptional<z.ZodString>;
|
|
40
|
+
}, z.core.$strict>;
|
|
41
|
+
export type AuditItemT = z.infer<typeof AuditItem>;
|
|
42
|
+
export declare const AuditDraw: z.ZodObject<{
|
|
43
|
+
seed: z.ZodString;
|
|
44
|
+
size: z.ZodNumber;
|
|
45
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
46
|
+
at: z.ZodString;
|
|
47
|
+
}, z.core.$strict>;
|
|
48
|
+
export type AuditDrawT = z.infer<typeof AuditDraw>;
|
|
49
|
+
export declare const AuditFile: z.ZodObject<{
|
|
50
|
+
schema: z.ZodLiteral<1>;
|
|
51
|
+
repo: z.ZodString;
|
|
52
|
+
draws: z.ZodArray<z.ZodObject<{
|
|
53
|
+
seed: z.ZodString;
|
|
54
|
+
size: z.ZodNumber;
|
|
55
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
56
|
+
at: z.ZodString;
|
|
57
|
+
}, z.core.$strict>>;
|
|
58
|
+
items: z.ZodArray<z.ZodObject<{
|
|
59
|
+
id: z.ZodString;
|
|
60
|
+
kind: z.ZodEnum<{
|
|
61
|
+
ai: "ai";
|
|
62
|
+
link: "link";
|
|
63
|
+
fact: "fact";
|
|
64
|
+
}>;
|
|
65
|
+
of: z.ZodString;
|
|
66
|
+
claim: z.ZodString;
|
|
67
|
+
cites: z.ZodArray<z.ZodString>;
|
|
68
|
+
fact: z.ZodOptional<z.ZodString>;
|
|
69
|
+
value: z.ZodOptional<z.ZodString>;
|
|
70
|
+
to: z.ZodOptional<z.ZodString>;
|
|
71
|
+
decided: z.ZodOptional<z.ZodString>;
|
|
72
|
+
run: z.ZodOptional<z.ZodString>;
|
|
73
|
+
answer: z.ZodOptional<z.ZodEnum<{
|
|
74
|
+
right: "right";
|
|
75
|
+
wrong: "wrong";
|
|
76
|
+
unsure: "unsure";
|
|
77
|
+
}>>;
|
|
78
|
+
note: z.ZodOptional<z.ZodString>;
|
|
79
|
+
by: z.ZodOptional<z.ZodString>;
|
|
80
|
+
at: z.ZodOptional<z.ZodString>;
|
|
81
|
+
}, z.core.$strict>>;
|
|
82
|
+
}, z.core.$strict>;
|
|
83
|
+
export type AuditFileT = z.infer<typeof AuditFile>;
|
|
84
|
+
export declare const AUDIT_DEFAULT_SIZE = 10;
|
|
85
|
+
export declare function parseAuditFile(text: string): {
|
|
86
|
+
ok: true;
|
|
87
|
+
file: AuditFileT;
|
|
88
|
+
} | {
|
|
89
|
+
ok: false;
|
|
90
|
+
issues: string[];
|
|
91
|
+
};
|
|
92
|
+
export declare function serializeAuditFile(file: AuditFileT): string;
|
|
93
|
+
/**
|
|
94
|
+
* The facts an audit may draw: those the verifier kept that a reader wrote. A person's own fact
|
|
95
|
+
* (a correction) is their word already, and one not yet checked isn't kept; neither is drawn.
|
|
96
|
+
*/
|
|
97
|
+
export declare function auditCandidates(facts: readonly Fact[]): AuditItemT[];
|
|
98
|
+
declare function shuffled<T extends {
|
|
99
|
+
id: string;
|
|
100
|
+
}>(list: readonly T[], seed: string): T[];
|
|
101
|
+
/**
|
|
102
|
+
* The same shuffle for another draw (ADR 0196, the canaries' words and removals): by id, then the
|
|
103
|
+
* seeded generator, so the same list and seed give the same order on any machine.
|
|
104
|
+
*/
|
|
105
|
+
export declare const seededShuffle: typeof shuffled;
|
|
106
|
+
/**
|
|
107
|
+
* A reproducible random sample: `size` facts and `size` links (all of them when there are
|
|
108
|
+
* fewer), the same for the same candidates and seed whatever order they come in.
|
|
109
|
+
*/
|
|
110
|
+
export declare function drawAudit(o: {
|
|
111
|
+
facts: readonly AuditItemT[];
|
|
112
|
+
links: readonly AuditItemT[];
|
|
113
|
+
/** ADR 0181: the AI's decisions standing for the repo (its pairings and answers). */
|
|
114
|
+
ai?: readonly AuditItemT[];
|
|
115
|
+
size: number;
|
|
116
|
+
seed: string;
|
|
117
|
+
}): AuditItemT[];
|
|
118
|
+
/**
|
|
119
|
+
* A draw added to the file on record: items already there keep their answers, new ones are
|
|
120
|
+
* added unanswered, and a draw with the same seed, size and commit isn't recorded twice.
|
|
121
|
+
*/
|
|
122
|
+
export declare function mergeDraw(file: AuditFileT | undefined, repo: string, items: readonly AuditItemT[], draw: AuditDrawT): AuditFileT;
|
|
123
|
+
/**
|
|
124
|
+
* The Wilson score interval at 95%, rounded to three places: honest for a small sample and for
|
|
125
|
+
* a precision of 0 or 1, where the plain p ± 2σ is not. Undefined with nothing answered.
|
|
126
|
+
*/
|
|
127
|
+
export declare function wilson(right: number, n: number): {
|
|
128
|
+
low: number;
|
|
129
|
+
high: number;
|
|
130
|
+
} | undefined;
|
|
131
|
+
export interface AuditTally {
|
|
132
|
+
drawn: number;
|
|
133
|
+
right: number;
|
|
134
|
+
wrong: number;
|
|
135
|
+
unsure: number;
|
|
136
|
+
/** Drawn and not answered yet. */
|
|
137
|
+
open: number;
|
|
138
|
+
/** Drawn, but the fact or link is no longer as the person saw it: left out of the count. */
|
|
139
|
+
gone: number;
|
|
140
|
+
/** right / (right + wrong); null with neither. */
|
|
141
|
+
precision: number | null;
|
|
142
|
+
low: number | null;
|
|
143
|
+
high: number | null;
|
|
144
|
+
}
|
|
145
|
+
export interface AuditPrecision {
|
|
146
|
+
facts: AuditTally;
|
|
147
|
+
byKind: Record<string, AuditTally>;
|
|
148
|
+
links: AuditTally;
|
|
149
|
+
/** Links by how they were joined (ADR 0135's flags). */
|
|
150
|
+
byHow: Record<string, AuditTally>;
|
|
151
|
+
/** ADR 0181: the AI's decisions (its pairings and answers), apart from the facts and links. */
|
|
152
|
+
ai: AuditTally;
|
|
153
|
+
/** ADR 0181: the AI's decisions by what they decided: `link` or `question`. */
|
|
154
|
+
byAi: Record<string, AuditTally>;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Precision from the answers: of the items answered right or wrong, the share right, with the
|
|
158
|
+
* Wilson interval. Unsure and unanswered items are counted apart and never in the share; `keep`
|
|
159
|
+
* drops an item whose fact or link has changed since it was drawn (counted as gone).
|
|
160
|
+
*/
|
|
161
|
+
export declare function auditPrecision(items: readonly AuditItemT[], keep?: (i: AuditItemT) => boolean): AuditPrecision;
|
|
162
|
+
/** Several repos' precision summed: the estate's. */
|
|
163
|
+
export declare function sumAuditPrecision(list: readonly AuditPrecision[]): AuditPrecision;
|
|
164
|
+
/**
|
|
165
|
+
* Whether a fact item is still the fact the person saw: the same id, citing the same line with
|
|
166
|
+
* the same value. Used to keep an answer standing, and to show a right one as `verified: sample`.
|
|
167
|
+
*/
|
|
168
|
+
export declare function auditItemHolds(i: AuditItemT, facts: ReadonlyMap<string, Fact>): boolean;
|
|
169
|
+
/**
|
|
170
|
+
* The facts a person answered right in a sample audit that are still as they saw them: shown as
|
|
171
|
+
* `verified: sample` where the facts are read for a person (the facts file keeps `line`).
|
|
172
|
+
*/
|
|
173
|
+
export declare function sampleConfirmed(audit: AuditFileT | undefined, facts: readonly Fact[]): Set<string>;
|
|
174
|
+
export {};
|
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type AuditPrecision } from "./audit.js";
|
|
3
|
+
import type { Fact } from "./schema/facts.js";
|
|
4
|
+
/**
|
|
5
|
+
* Canaries (plan item Z2, ADR 0196): in a scratch copy of a repo, never committed, Atticus plants
|
|
6
|
+
* a few synthetic entries, calls, topics and config keys and comments out a few real ones the
|
|
7
|
+
* verified facts cite. The person's assistant reads the copy as it reads any repo; the reader
|
|
8
|
+
* must find the planted and miss the removed. That gives recall, and a fabrication rate the
|
|
9
|
+
* verifier can't see (a claim about a line that is there but commented out passes the check that
|
|
10
|
+
* the value is on the line), on the organisation's own code, with nobody labelling anything.
|
|
11
|
+
* Misreadings of real lines are the sample audit's (P3, ADR 0148); the two side by side say how
|
|
12
|
+
* often a claim graded as backed is wrong (the silent error rate, as two numbers, never pooled).
|
|
13
|
+
*
|
|
14
|
+
* Pure: the caller plants, reads and writes the files. Nothing here names a stack or framework;
|
|
15
|
+
* the templates that plant are `@maycombhq/verify`'s.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* Where a canary's reports are kept, relative to the root: `reports/canaries`, or
|
|
19
|
+
* `.atticus/reports/canaries` when Atticus is adopted in a repo. One file per run,
|
|
20
|
+
* `<date>-<repo>.yaml`; the only thing a canary writes in the metarepo.
|
|
21
|
+
*/
|
|
22
|
+
export declare const canaryReportsRelOf: (root: string) => string;
|
|
23
|
+
/**
|
|
24
|
+
* A repo's name as a canary takes it (review of ADR 0196): letters, digits, `.`, `_` and `-`,
|
|
25
|
+
* starting with a letter or digit, and never `..`, so no name reaches outside the folder it
|
|
26
|
+
* names a file in; and no Windows device name (`con`, `nul.txt`), as the run folder holds the
|
|
27
|
+
* copy as `<repo>/` and a report is named after the repo.
|
|
28
|
+
*/
|
|
29
|
+
export declare const isCanaryRepoName: (repo: string) => boolean;
|
|
30
|
+
/**
|
|
31
|
+
* The folder every run folder is made in, right in the system's temporary folder: made 0700 and
|
|
32
|
+
* this user's own, so no other user can make or swap a run folder in it (review of ADR 0196). Its
|
|
33
|
+
* name, like a run folder's, says nothing of a canary: a run folder is the read's workspace.
|
|
34
|
+
*/
|
|
35
|
+
export declare const CANARY_READS_DIR = "atticus-reads";
|
|
36
|
+
/**
|
|
37
|
+
* A metarepo's id in a run folder's name: the first 8 characters of its state folder's name
|
|
38
|
+
* (`metarepoStateDir`, ADR 0186), so a run folder is known as this metarepo's and no other's.
|
|
39
|
+
*/
|
|
40
|
+
export declare const isCanaryMetarepoId: (id: string) => boolean;
|
|
41
|
+
/** The start of a run folder's name: `<repo>-<id8>-`, then the six characters mkdtemp adds. */
|
|
42
|
+
export declare const canaryRunPrefix: (repo: string, id: string) => string;
|
|
43
|
+
/**
|
|
44
|
+
* Whether a folder's base name is a run folder of this repo's and this metarepo's,
|
|
45
|
+
* `<repo>-<id8>-XXXXXX`: neutral on purpose (review of ADR 0196), as the folder is the workspace
|
|
46
|
+
* the read is made in.
|
|
47
|
+
*/
|
|
48
|
+
export declare const isCanaryRunName: (name: string, repo: string, id: string) => boolean;
|
|
49
|
+
/** The repo and metarepo id a run folder's base name is of, or undefined when it is no run's. */
|
|
50
|
+
export declare function canaryRunOf(name: string): {
|
|
51
|
+
repo: string;
|
|
52
|
+
id: string;
|
|
53
|
+
} | undefined;
|
|
54
|
+
/** What a planted item stands for: a route served, a call made, a topic, a config key. */
|
|
55
|
+
export declare const CANARY_WHATS: readonly ["entry", "call", "topic-in", "topic-out", "config"];
|
|
56
|
+
export type CanaryWhat = (typeof CANARY_WHATS)[number];
|
|
57
|
+
export declare const CanaryPlanted: z.ZodObject<{
|
|
58
|
+
id: z.ZodString;
|
|
59
|
+
kind: z.ZodEnum<{
|
|
60
|
+
config: "config";
|
|
61
|
+
entry: "entry";
|
|
62
|
+
call: "call";
|
|
63
|
+
}>;
|
|
64
|
+
what: z.ZodEnum<{
|
|
65
|
+
config: "config";
|
|
66
|
+
entry: "entry";
|
|
67
|
+
call: "call";
|
|
68
|
+
"topic-in": "topic-in";
|
|
69
|
+
"topic-out": "topic-out";
|
|
70
|
+
}>;
|
|
71
|
+
stack: z.ZodString;
|
|
72
|
+
file: z.ZodString;
|
|
73
|
+
line: z.ZodNumber;
|
|
74
|
+
claim: z.ZodString;
|
|
75
|
+
needle: z.ZodString;
|
|
76
|
+
}, z.core.$strict>;
|
|
77
|
+
export type CanaryPlantedT = z.infer<typeof CanaryPlanted>;
|
|
78
|
+
export declare const CanaryRemoved: z.ZodObject<{
|
|
79
|
+
id: z.ZodString;
|
|
80
|
+
fact: z.ZodString;
|
|
81
|
+
kind: z.ZodString;
|
|
82
|
+
file: z.ZodString;
|
|
83
|
+
line: z.ZodNumber;
|
|
84
|
+
claim: z.ZodString;
|
|
85
|
+
value: z.ZodString;
|
|
86
|
+
needle: z.ZodString;
|
|
87
|
+
how: z.ZodLiteral<"commented">;
|
|
88
|
+
}, z.core.$strict>;
|
|
89
|
+
export type CanaryRemovedT = z.infer<typeof CanaryRemoved>;
|
|
90
|
+
/** An item a stack's template has that wasn't planted, and why (the repo couldn't serve it). */
|
|
91
|
+
export declare const CanarySkipped: z.ZodObject<{
|
|
92
|
+
stack: z.ZodString;
|
|
93
|
+
what: z.ZodEnum<{
|
|
94
|
+
config: "config";
|
|
95
|
+
entry: "entry";
|
|
96
|
+
call: "call";
|
|
97
|
+
"topic-in": "topic-in";
|
|
98
|
+
"topic-out": "topic-out";
|
|
99
|
+
}>;
|
|
100
|
+
reason: z.ZodString;
|
|
101
|
+
}, z.core.$strict>;
|
|
102
|
+
export type CanarySkippedT = z.infer<typeof CanarySkipped>;
|
|
103
|
+
/**
|
|
104
|
+
* The answer key a plant keeps on this machine (never in the copy, never in the metarepo). The
|
|
105
|
+
* run folder is kept by its base name only, `<repo>-<id8>-XXXXXX` (review of ADR 0196): its path
|
|
106
|
+
* is rebuilt under `<temporary folder>/atticus-reads` and checked (the metarepo's id included)
|
|
107
|
+
* before anything in it is read, written or deleted, so a key edited by hand can't point anywhere
|
|
108
|
+
* else.
|
|
109
|
+
*/
|
|
110
|
+
export declare const CanaryKey: z.ZodObject<{
|
|
111
|
+
schema: z.ZodLiteral<1>;
|
|
112
|
+
repo: z.ZodString;
|
|
113
|
+
seed: z.ZodString;
|
|
114
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
115
|
+
run: z.ZodString;
|
|
116
|
+
reads: z.ZodOptional<z.ZodString>;
|
|
117
|
+
stacks: z.ZodArray<z.ZodString>;
|
|
118
|
+
planted: z.ZodArray<z.ZodObject<{
|
|
119
|
+
id: z.ZodString;
|
|
120
|
+
kind: z.ZodEnum<{
|
|
121
|
+
config: "config";
|
|
122
|
+
entry: "entry";
|
|
123
|
+
call: "call";
|
|
124
|
+
}>;
|
|
125
|
+
what: z.ZodEnum<{
|
|
126
|
+
config: "config";
|
|
127
|
+
entry: "entry";
|
|
128
|
+
call: "call";
|
|
129
|
+
"topic-in": "topic-in";
|
|
130
|
+
"topic-out": "topic-out";
|
|
131
|
+
}>;
|
|
132
|
+
stack: z.ZodString;
|
|
133
|
+
file: z.ZodString;
|
|
134
|
+
line: z.ZodNumber;
|
|
135
|
+
claim: z.ZodString;
|
|
136
|
+
needle: z.ZodString;
|
|
137
|
+
}, z.core.$strict>>;
|
|
138
|
+
removed: z.ZodArray<z.ZodObject<{
|
|
139
|
+
id: z.ZodString;
|
|
140
|
+
fact: z.ZodString;
|
|
141
|
+
kind: z.ZodString;
|
|
142
|
+
file: z.ZodString;
|
|
143
|
+
line: z.ZodNumber;
|
|
144
|
+
claim: z.ZodString;
|
|
145
|
+
value: z.ZodString;
|
|
146
|
+
needle: z.ZodString;
|
|
147
|
+
how: z.ZodLiteral<"commented">;
|
|
148
|
+
}, z.core.$strict>>;
|
|
149
|
+
skipped: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
150
|
+
stack: z.ZodString;
|
|
151
|
+
what: z.ZodEnum<{
|
|
152
|
+
config: "config";
|
|
153
|
+
entry: "entry";
|
|
154
|
+
call: "call";
|
|
155
|
+
"topic-in": "topic-in";
|
|
156
|
+
"topic-out": "topic-out";
|
|
157
|
+
}>;
|
|
158
|
+
reason: z.ZodString;
|
|
159
|
+
}, z.core.$strict>>>;
|
|
160
|
+
at: z.ZodString;
|
|
161
|
+
}, z.core.$strict>;
|
|
162
|
+
export type CanaryKeyT = z.infer<typeof CanaryKey>;
|
|
163
|
+
/** A share with its count and the Wilson interval at 95% (null with nothing to count). */
|
|
164
|
+
export declare const CanaryRate: z.ZodObject<{
|
|
165
|
+
k: z.ZodNumber;
|
|
166
|
+
n: z.ZodNumber;
|
|
167
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
168
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
169
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
170
|
+
}, z.core.$strict>;
|
|
171
|
+
export type CanaryRateT = z.infer<typeof CanaryRate>;
|
|
172
|
+
export declare const CanaryReport: z.ZodObject<{
|
|
173
|
+
schema: z.ZodLiteral<1>;
|
|
174
|
+
repo: z.ZodString;
|
|
175
|
+
commit: z.ZodOptional<z.ZodString>;
|
|
176
|
+
seed: z.ZodString;
|
|
177
|
+
at: z.ZodString;
|
|
178
|
+
by: z.ZodString;
|
|
179
|
+
stacks: z.ZodArray<z.ZodString>;
|
|
180
|
+
read: z.ZodObject<{
|
|
181
|
+
facts: z.ZodNumber;
|
|
182
|
+
kept: z.ZodNumber;
|
|
183
|
+
rejected: z.ZodNumber;
|
|
184
|
+
unread: z.ZodDefault<z.ZodNumber>;
|
|
185
|
+
}, z.core.$strict>;
|
|
186
|
+
planted: z.ZodArray<z.ZodObject<{
|
|
187
|
+
kind: z.ZodEnum<{
|
|
188
|
+
config: "config";
|
|
189
|
+
entry: "entry";
|
|
190
|
+
call: "call";
|
|
191
|
+
}>;
|
|
192
|
+
id: z.ZodString;
|
|
193
|
+
what: z.ZodEnum<{
|
|
194
|
+
config: "config";
|
|
195
|
+
entry: "entry";
|
|
196
|
+
call: "call";
|
|
197
|
+
"topic-in": "topic-in";
|
|
198
|
+
"topic-out": "topic-out";
|
|
199
|
+
}>;
|
|
200
|
+
stack: z.ZodString;
|
|
201
|
+
result: z.ZodEnum<{
|
|
202
|
+
rejected: "rejected";
|
|
203
|
+
found: "found";
|
|
204
|
+
missed: "missed";
|
|
205
|
+
}>;
|
|
206
|
+
}, z.core.$strict>>;
|
|
207
|
+
skipped: z.ZodDefault<z.ZodArray<z.ZodObject<{
|
|
208
|
+
stack: z.ZodString;
|
|
209
|
+
what: z.ZodEnum<{
|
|
210
|
+
config: "config";
|
|
211
|
+
entry: "entry";
|
|
212
|
+
call: "call";
|
|
213
|
+
"topic-in": "topic-in";
|
|
214
|
+
"topic-out": "topic-out";
|
|
215
|
+
}>;
|
|
216
|
+
reason: z.ZodString;
|
|
217
|
+
}, z.core.$strict>>>;
|
|
218
|
+
removed: z.ZodArray<z.ZodObject<{
|
|
219
|
+
file: z.ZodString;
|
|
220
|
+
value: z.ZodString;
|
|
221
|
+
line: z.ZodNumber;
|
|
222
|
+
kind: z.ZodString;
|
|
223
|
+
id: z.ZodString;
|
|
224
|
+
fact: z.ZodString;
|
|
225
|
+
claim: z.ZodString;
|
|
226
|
+
how: z.ZodLiteral<"commented">;
|
|
227
|
+
result: z.ZodEnum<{
|
|
228
|
+
absent: "absent";
|
|
229
|
+
rejected: "rejected";
|
|
230
|
+
kept: "kept";
|
|
231
|
+
elsewhere: "elsewhere";
|
|
232
|
+
}>;
|
|
233
|
+
by: z.ZodOptional<z.ZodString>;
|
|
234
|
+
}, z.core.$strict>>;
|
|
235
|
+
recall: z.ZodObject<{
|
|
236
|
+
k: z.ZodNumber;
|
|
237
|
+
n: z.ZodNumber;
|
|
238
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
239
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
240
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
241
|
+
}, z.core.$strict>;
|
|
242
|
+
fabrication: z.ZodObject<{
|
|
243
|
+
k: z.ZodNumber;
|
|
244
|
+
n: z.ZodNumber;
|
|
245
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
246
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
247
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
248
|
+
}, z.core.$strict>;
|
|
249
|
+
passed: z.ZodObject<{
|
|
250
|
+
k: z.ZodNumber;
|
|
251
|
+
n: z.ZodNumber;
|
|
252
|
+
rate: z.ZodNullable<z.ZodNumber>;
|
|
253
|
+
low: z.ZodNullable<z.ZodNumber>;
|
|
254
|
+
high: z.ZodNullable<z.ZodNumber>;
|
|
255
|
+
}, z.core.$strict>;
|
|
256
|
+
}, z.core.$strict>;
|
|
257
|
+
export type CanaryReportT = z.infer<typeof CanaryReport>;
|
|
258
|
+
export declare function parseCanaryReport(text: string): {
|
|
259
|
+
ok: true;
|
|
260
|
+
report: CanaryReportT;
|
|
261
|
+
} | {
|
|
262
|
+
ok: false;
|
|
263
|
+
issues: string[];
|
|
264
|
+
};
|
|
265
|
+
export declare const serializeCanaryReport: (r: CanaryReportT) => string;
|
|
266
|
+
/** Lowercase, every run of other characters one `-`: `W1_W2_URL`, `w1.w2-url` and `w1-w2-url` alike. */
|
|
267
|
+
export declare const foldCanary: (s: string) => string;
|
|
268
|
+
/** The words of a fact's claim a canary is matched on: its path, topic, key, name and cited value. */
|
|
269
|
+
export declare function canaryClaimText(f: Fact): string;
|
|
270
|
+
/**
|
|
271
|
+
* What a fact claims, as a removed fact is matched on: an entry's or call's method and path, its
|
|
272
|
+
* parameters left out (`get ledger-v1-transfers-param`; the path alone with no method), a config
|
|
273
|
+
* key exactly, else its cited value, folded. Second review of ADR 0196: the method is part of it,
|
|
274
|
+
* so `PUT /users` beside a removed `GET /users` is no claim of it.
|
|
275
|
+
*/
|
|
276
|
+
export declare function canaryNeedleOf(f: Fact): string;
|
|
277
|
+
/** Whether a fact is about a planted item: its kind, with the item's own words in its claim. */
|
|
278
|
+
export declare const plantedBy: (p: Pick<CanaryPlantedT, "kind" | "needle">, f: Fact) => boolean;
|
|
279
|
+
/**
|
|
280
|
+
* How a fact claims a removed one (second review of ADR 0196): `near` when it is of its kind,
|
|
281
|
+
* cites the commented line or one either side (the verifier's window), by its cite or a
|
|
282
|
+
* `cite.with` part, and claims the same: the same needle (method and path, or the key exactly).
|
|
283
|
+
* `value` when it claims it by its cited value only: it cites that very line with that value, or
|
|
284
|
+
* (an entry or call) its path is the value with the same method (a path the read wrote without
|
|
285
|
+
* the base the removed fact put in front). `elsewhere` when it has the same needle but cites
|
|
286
|
+
* neither the line nor one beside it, so may well be about another line (never counted as passed).
|
|
287
|
+
* A claim that merely holds the removed value (`/users/:id` beside a removed `/users`, a key
|
|
288
|
+
* `url-fallback` beside a removed `url`) is none of these: a fact of the line beside it.
|
|
289
|
+
*/
|
|
290
|
+
export declare function removedMatch(r: CanaryRemovedT, f: Fact): "near" | "value" | "elsewhere" | undefined;
|
|
291
|
+
/** Whether a fact claims a removed one: at its line (`near`, by needle or value) or `elsewhere`. */
|
|
292
|
+
export declare function removedBy(r: CanaryRemovedT, f: Fact): "near" | "elsewhere" | undefined;
|
|
293
|
+
export declare function canaryRate(k: number, n: number): CanaryRateT;
|
|
294
|
+
/**
|
|
295
|
+
* Score a read of the copy against the key: each planted item found by a kept fact, by a
|
|
296
|
+
* rejected one only, or missed; each removed one absent, still claimed at its line by a kept fact
|
|
297
|
+
* (a silent fabrication), claimed there only by a rejected one (the verifier caught it), or named
|
|
298
|
+
* only by a fact cited elsewhere. One fact answers for one item at most (review of ADR 0196): the
|
|
299
|
+
* planted items are matched in order, each to the first fact not yet taken, then the removed ones
|
|
300
|
+
* in passes, strongest match first (`removedMatch`). Recall and the fabrication rate with their
|
|
301
|
+
* intervals.
|
|
302
|
+
*/
|
|
303
|
+
export declare function scoreCanary(key: Pick<CanaryKeyT, "repo" | "commit" | "seed" | "stacks" | "planted" | "removed"> & {
|
|
304
|
+
skipped?: CanaryKeyT["skipped"];
|
|
305
|
+
}, read: {
|
|
306
|
+
kept: readonly Fact[];
|
|
307
|
+
rejected: readonly Fact[];
|
|
308
|
+
unread?: number;
|
|
309
|
+
}, o: {
|
|
310
|
+
at: string;
|
|
311
|
+
by: string;
|
|
312
|
+
}): CanaryReportT;
|
|
313
|
+
/**
|
|
314
|
+
* How often a claim graded as backed is wrong (ADR 0196, as revised on review): two numbers side
|
|
315
|
+
* by side, each with its count and interval, never pooled into one. Their samples are of different
|
|
316
|
+
* things (real lines a person answered; lines Atticus took out), and a pooled figure let the
|
|
317
|
+
* canaries' found plants, right by construction, pad its denominator.
|
|
318
|
+
*/
|
|
319
|
+
export interface SilentErrorRate {
|
|
320
|
+
/** The audit misread rate: kept facts and backed links answered wrong, of those answered. */
|
|
321
|
+
misread: CanaryRateT;
|
|
322
|
+
/**
|
|
323
|
+
* The canary pass-through rate: lines taken out that the read still claimed at their place and
|
|
324
|
+
* the verifier kept, of the lines taken out (less those a fact names only elsewhere).
|
|
325
|
+
*/
|
|
326
|
+
passed: CanaryRateT;
|
|
327
|
+
/** Planted items found, summed over the latest run of each repo. */
|
|
328
|
+
recall: CanaryRateT;
|
|
329
|
+
/** Removed lines the read still claimed, kept or not. */
|
|
330
|
+
fabrication: CanaryRateT;
|
|
331
|
+
/** Removed lines a reader claimed that the verifier refused: flagged, so no silent error. */
|
|
332
|
+
caught: number;
|
|
333
|
+
/** Removed lines a fact named only elsewhere: in neither count. */
|
|
334
|
+
elsewhere: number;
|
|
335
|
+
repos: {
|
|
336
|
+
audited: number;
|
|
337
|
+
canaries: number;
|
|
338
|
+
};
|
|
339
|
+
/** What the canaries' numbers cover: each stack planted in, with the items planted there. */
|
|
340
|
+
covers: {
|
|
341
|
+
stack: string;
|
|
342
|
+
what: CanaryWhat[];
|
|
343
|
+
}[];
|
|
344
|
+
}
|
|
345
|
+
/** Each stack the reports planted in, with the items planted there, in a fixed order. */
|
|
346
|
+
export declare function canaryCovers(reports: readonly {
|
|
347
|
+
planted: readonly {
|
|
348
|
+
stack: string;
|
|
349
|
+
what: CanaryWhat;
|
|
350
|
+
}[];
|
|
351
|
+
}[]): {
|
|
352
|
+
stack: string;
|
|
353
|
+
what: CanaryWhat[];
|
|
354
|
+
}[];
|
|
355
|
+
/**
|
|
356
|
+
* The two numbers (ADR 0196): the audit misread rate, from the sample audit's answers on kept
|
|
357
|
+
* facts and on links joined by something other than a guess (a misread real line, P3); and the
|
|
358
|
+
* canary pass-through rate, from the latest canary of each repo (a removed line still claimed and
|
|
359
|
+
* kept is a fabrication the verifier passed, Z2). A guessed link, a planted item missed and a
|
|
360
|
+
* fabrication the verifier refused are not silent: they are flagged or absent, the system working.
|
|
361
|
+
*/
|
|
362
|
+
export declare function silentErrorRate(audit: {
|
|
363
|
+
precision: AuditPrecision;
|
|
364
|
+
repos: number;
|
|
365
|
+
} | undefined, canaries: readonly CanaryReportT[]): SilentErrorRate;
|
|
366
|
+
/** The latest report of each repo, by when it was scored. */
|
|
367
|
+
export declare function latestCanaries(reports: readonly CanaryReportT[]): CanaryReportT[];
|
|
368
|
+
/** Whether a name is one of Windows' device names, which no canary takes on any system. */
|
|
369
|
+
export declare const isWindowsDeviceName: (name: string) => boolean;
|