@maycombhq/sdk 2.0.0-beta.10 → 2.0.0-beta.11

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,251 @@
1
+ import { z } from "zod";
2
+ import type { FactEnd, FactsJoinResult } from "./facts-join.js";
3
+ import type { VendorCallMatch } from "./facts-join-vendor.js";
4
+ import type { Fact } from "./schema/facts.js";
5
+ /** A field a spec lists: a request or response property or parameter, or a message's field. */
6
+ export declare const SpecField: z.ZodObject<{
7
+ side: z.ZodEnum<{
8
+ message: "message";
9
+ request: "request";
10
+ response: "response";
11
+ }>;
12
+ name: z.ZodString;
13
+ type: z.ZodOptional<z.ZodString>;
14
+ required: z.ZodOptional<z.ZodBoolean>;
15
+ in: z.ZodOptional<z.ZodString>;
16
+ number: z.ZodOptional<z.ZodNumber>;
17
+ at: z.ZodString;
18
+ }, z.core.$strict>;
19
+ export type SpecFieldT = z.infer<typeof SpecField>;
20
+ export declare const SPEC_FORMATS: readonly ["openapi", "protobuf", "avro", "json-schema", "asyncapi"];
21
+ /**
22
+ * One operation or one message a spec file describes, as the contract check reads it. An
23
+ * operation has a method and a path (with the server's path in front); a message has the name
24
+ * of its type (a proto message's full name, an Avro record's, a JSON Schema's title) and, when
25
+ * the spec says (AsyncAPI), the topic it travels on.
26
+ */
27
+ export declare const ContractSpec: z.ZodObject<{
28
+ kind: z.ZodEnum<{
29
+ message: "message";
30
+ operation: "operation";
31
+ }>;
32
+ format: z.ZodEnum<{
33
+ openapi: "openapi";
34
+ "json-schema": "json-schema";
35
+ avro: "avro";
36
+ protobuf: "protobuf";
37
+ asyncapi: "asyncapi";
38
+ }>;
39
+ role: z.ZodEnum<{
40
+ schema: "schema";
41
+ consumer: "consumer";
42
+ own: "own";
43
+ }>;
44
+ file: z.ZodString;
45
+ line: z.ZodNumber;
46
+ method: z.ZodOptional<z.ZodString>;
47
+ path: z.ZodOptional<z.ZodString>;
48
+ entry: z.ZodOptional<z.ZodString>;
49
+ name: z.ZodOptional<z.ZodString>;
50
+ topic: z.ZodOptional<z.ZodString>;
51
+ id: z.ZodOptional<z.ZodString>;
52
+ fields: z.ZodArray<z.ZodObject<{
53
+ side: z.ZodEnum<{
54
+ message: "message";
55
+ request: "request";
56
+ response: "response";
57
+ }>;
58
+ name: z.ZodString;
59
+ type: z.ZodOptional<z.ZodString>;
60
+ required: z.ZodOptional<z.ZodBoolean>;
61
+ in: z.ZodOptional<z.ZodString>;
62
+ number: z.ZodOptional<z.ZodNumber>;
63
+ at: z.ZodString;
64
+ }, z.core.$strict>>;
65
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
66
+ status: z.ZodString;
67
+ at: z.ZodString;
68
+ }, z.core.$strict>>>;
69
+ }, z.core.$strict>;
70
+ export type ContractSpecT = z.infer<typeof ContractSpec>;
71
+ /**
72
+ * The facts companion `<repo>.specs.yaml` (ADR 0164): the specs a repo's checkout holds, read at
73
+ * the facts' commit by `atticus verify <repo> --write`, so the contract check reads the same
74
+ * specs on every run without the checkout.
75
+ */
76
+ export declare const SpecsFile: z.ZodObject<{
77
+ schemaVersion: z.ZodLiteral<1>;
78
+ repo: z.ZodString;
79
+ commit: z.ZodOptional<z.ZodString>;
80
+ specs: z.ZodArray<z.ZodObject<{
81
+ kind: z.ZodEnum<{
82
+ message: "message";
83
+ operation: "operation";
84
+ }>;
85
+ format: z.ZodEnum<{
86
+ openapi: "openapi";
87
+ "json-schema": "json-schema";
88
+ avro: "avro";
89
+ protobuf: "protobuf";
90
+ asyncapi: "asyncapi";
91
+ }>;
92
+ role: z.ZodEnum<{
93
+ schema: "schema";
94
+ consumer: "consumer";
95
+ own: "own";
96
+ }>;
97
+ file: z.ZodString;
98
+ line: z.ZodNumber;
99
+ method: z.ZodOptional<z.ZodString>;
100
+ path: z.ZodOptional<z.ZodString>;
101
+ entry: z.ZodOptional<z.ZodString>;
102
+ name: z.ZodOptional<z.ZodString>;
103
+ topic: z.ZodOptional<z.ZodString>;
104
+ id: z.ZodOptional<z.ZodString>;
105
+ fields: z.ZodArray<z.ZodObject<{
106
+ side: z.ZodEnum<{
107
+ message: "message";
108
+ request: "request";
109
+ response: "response";
110
+ }>;
111
+ name: z.ZodString;
112
+ type: z.ZodOptional<z.ZodString>;
113
+ required: z.ZodOptional<z.ZodBoolean>;
114
+ in: z.ZodOptional<z.ZodString>;
115
+ number: z.ZodOptional<z.ZodNumber>;
116
+ at: z.ZodString;
117
+ }, z.core.$strict>>;
118
+ errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
119
+ status: z.ZodString;
120
+ at: z.ZodString;
121
+ }, z.core.$strict>>>;
122
+ }, z.core.$strict>>;
123
+ }, z.core.$strict>;
124
+ export type SpecsFileT = z.infer<typeof SpecsFile>;
125
+ /** The specs of a system outside the estate, taken in through intake (O2). */
126
+ export interface OutsideSpecs {
127
+ system: string;
128
+ name: string;
129
+ specs: readonly ContractSpecT[];
130
+ }
131
+ export declare const CONTRACT_KINDS: readonly ["field-missing", "field-extra", "field-not-sent", "field-required", "field-type", "field-number", "error-unlisted", "error-unanswered"];
132
+ export type ContractKind = (typeof CONTRACT_KINDS)[number];
133
+ /** One end of a comparison: who says it (a repo's code, a spec), the value, and its line. */
134
+ export interface ContractEnd {
135
+ /** The repo whose code or spec it is, or the outside system. */
136
+ repo?: string;
137
+ system?: string;
138
+ /** What this end is, in words: `forge-portal-bff's call`, `the spec forge-accounts-v1.yaml`. */
139
+ what: string;
140
+ value?: string;
141
+ /** path:line. */
142
+ at?: string;
143
+ }
144
+ export interface ContractMismatch {
145
+ /** Stable: the link, the boundary, the kind, the side and the field or status. */
146
+ id: string;
147
+ /** The catalog Interface of the link, when the join gives one. */
148
+ interface?: string;
149
+ /** Every Interface it concerns: the link's, and each gateway hop's forwarding call's. */
150
+ interfaces?: string[];
151
+ /** The call the link starts at (the publish, for a topic). */
152
+ call: FactEnd;
153
+ /** What it reaches: an entry of the estate, or an outside system. */
154
+ entry?: FactEnd;
155
+ system?: string;
156
+ /** `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced. */
157
+ status: "mismatch" | "unconfirmed";
158
+ kind: ContractKind;
159
+ side?: "request" | "response" | "message";
160
+ field?: string;
161
+ error?: string;
162
+ /** The side that sends (or, for a response, reads) and the side that takes (or returns). */
163
+ sender: ContractEnd;
164
+ receiver: ContractEnd;
165
+ /** The mapping lines the comparison went through (`repo path:line`), in order. */
166
+ via?: string[];
167
+ /** The mapping that isn't traced, when `unconfirmed`. */
168
+ untraced?: string;
169
+ message: string;
170
+ }
171
+ /** A link compared: how many boundaries had something on both sides, and what was found. */
172
+ export interface ContractLink {
173
+ key: string;
174
+ interface?: string;
175
+ /** Every Interface the link's check concerns: its own, and each gateway hop's forwarding call's. */
176
+ interfaces?: string[];
177
+ call: FactEnd;
178
+ entry?: FactEnd;
179
+ system?: string;
180
+ kind: "rest" | "topic" | "outside";
181
+ method?: string;
182
+ path: string;
183
+ /** The gateway routes on the way, in order (`repo` of each). */
184
+ through: string[];
185
+ /** The specs read for it (`file:line`, the repo's or intake's). */
186
+ specs: string[];
187
+ /** Boundaries where both sides said something about the payload. */
188
+ compared: number;
189
+ mismatches: number;
190
+ unconfirmed: number;
191
+ }
192
+ export interface ContractCheckResult {
193
+ links: ContractLink[];
194
+ findings: ContractMismatch[];
195
+ counts: {
196
+ links: number;
197
+ compared: number;
198
+ mismatches: number;
199
+ unconfirmed: number;
200
+ };
201
+ }
202
+ export interface ContractCheckInput {
203
+ repos: readonly {
204
+ repo: string;
205
+ facts: readonly Fact[];
206
+ }[];
207
+ join: FactsJoinResult;
208
+ /** Every repo's `<repo>.specs.yaml` on file. */
209
+ specs?: readonly SpecsFileT[];
210
+ /** The specs of systems outside the estate, from intake. */
211
+ outside?: readonly OutsideSpecs[];
212
+ /** The calls to outside systems matched to their spec's operations (`joinVendorOperations`). */
213
+ vendorMatches?: readonly VendorCallMatch[];
214
+ }
215
+ /** The words of the check, in one place: the CLI, the API and the app say these. */
216
+ export declare const CONTRACT_WORDS: {
217
+ extra: (side: string, name: string, s: string, sAt: string, r: string) => string;
218
+ notSent: (side: string, name: string, r: string, rAt: string, s: string) => string;
219
+ missing: (name: string, s: string, sAt: string, r: string) => string;
220
+ messageMissing: (name: string, r: string, rAt: string, s: string) => string;
221
+ messageExtra: (name: string, s: string, sAt: string, r: string) => string;
222
+ undocumented: (name: string, r: string, rAt: string, s: string) => string;
223
+ required: (side: string, name: string, a: string, aAt: string, b: string, bAt: string) => string;
224
+ type: (side: string, name: string, a: string, at: string, aAt: string, b: string, bt: string, bAt: string) => string;
225
+ number: (n: number, a: string, an: string, aAt: string, b: string, bn: string, bAt: string) => string;
226
+ errorUnlisted: (status: string, r: string, rAt: string, s: string, spec: boolean) => string;
227
+ errorUnanswered: (status: string, s: string, sAt: string, r: string) => string;
228
+ unconfirmed: (message: string, untraced: string) => string;
229
+ };
230
+ /**
231
+ * The `transform` a reader gives the field fact that names a publish's or listener's message type
232
+ * (ADR 0164): the field's `name` is the type as the line writes it (`PaymentSettled`, the
233
+ * generated proto class or the Avro record), its `type` the full name when the code gives one
234
+ * (`forge.payments.v1.PaymentSettled`), cited where the publish or the listener names it. It is
235
+ * no field of the payload: it ties the payload to its spec.
236
+ */
237
+ export declare const MESSAGE_TYPE_TRANSFORM = "message type";
238
+ export declare const isMessageType: (f: {
239
+ side?: string;
240
+ transform?: string;
241
+ }) => boolean;
242
+ /** A `transform` that says the field travels inside the field it is mapped to (an envelope). */
243
+ export declare const ENVELOPE_TRANSFORM: RegExp;
244
+ /** Compare the payload on both sides of every link the join made, and of every call to an outside system with a spec. */
245
+ export declare function checkContracts(input: ContractCheckInput): ContractCheckResult;
246
+ /**
247
+ * The findings a newer spec of an outside system brings (ADR 0164): those against `next` that
248
+ * the same calls didn't have against `prev`, by kind, side and field. What the Outside systems
249
+ * page shows when a vendor's or a team's new spec is taken in.
250
+ */
251
+ export declare function newFindings(next: readonly ContractMismatch[], prev: readonly ContractMismatch[]): ContractMismatch[];
@@ -207,6 +207,11 @@ export declare const PROTOTYPE_WORDS: {
207
207
  auth: (mine: string, at: string, repo: string, theirs: string, theirAt: string) => string;
208
208
  left: (what: string, who: string) => string;
209
209
  };
210
+ /**
211
+ * The family a declared type belongs to, compared across languages; undefined when unsure. The
212
+ * contract check (ADR 0164) reads it too, with protobuf's and Avro's scalar names.
213
+ */
214
+ export declare function typeFamily(t: string | undefined): string | undefined;
210
215
  /**
211
216
  * The values an enum field's `type` lists (ADR 0142), as the facts write it: a union of quoted
212
217
  * literals (`"captured" | "failed"`), a named list (`ChargeStatus(CAPTURED|FAILED)`,
@@ -0,0 +1,108 @@
1
+ import type { CatalogRecord } from "./catalog.js";
2
+ import { type FactEnd, type FactsJoinResult, type JoinRepo } from "./facts-join.js";
3
+ import type { TermRole } from "./schema/facts.js";
4
+ /**
5
+ * The organisation's terms across the estate (ADR 0163). A `term` fact records an identifier of
6
+ * the organisation's own (a CMDB id, an application id) as a repo writes it, with the role a note
7
+ * or the file's own words give it: `owner` (the value names the repo's own system), `consumer`
8
+ * (it names a system the repo lets in), `none` or `unknown`. Atticus knows no term; it only
9
+ * compares the values the facts cite, word for word:
10
+ *
11
+ * - an owner value ties its repo to its system;
12
+ * - a consumer value points to the repo whose owner value is the same;
13
+ * - the same value in two repos that no owner and consumer explain is a possible link: inferred,
14
+ * flagged, shown for a person to confirm;
15
+ * - a repo's consumers are who its routes let in: on a gateway they become AccessGrants on its
16
+ * routes, so the critic names them when a route changes;
17
+ * - and they are checked against the calls the join found: a repo calling the routes whose owner
18
+ * value isn't listed is a finding, a listed consumer that makes no call is a note.
19
+ *
20
+ * Pure: the same facts and join give the same result.
21
+ */
22
+ /** A term as one repo writes it. */
23
+ export interface TermSeen extends FactEnd {
24
+ term: string;
25
+ value: string;
26
+ role: TermRole;
27
+ /** path:line of the line that gives it its role. */
28
+ meaningAt?: string;
29
+ /** The note's key, or its words quoted. */
30
+ note?: string;
31
+ }
32
+ /** A consumer a repo lists, and the repo whose own value it is, when one says so. */
33
+ export interface TermConsumer {
34
+ listedBy: TermSeen;
35
+ owner?: TermSeen;
36
+ }
37
+ /** The flag a possible link by a shared value carries: a guess for a person to confirm. */
38
+ export declare const LINKED_BY_TERM_VALUE = "linked-by-term-value";
39
+ /** The same value in two or more repos, which no owner and its consumers explain. */
40
+ export interface PossibleTermLink {
41
+ value: string;
42
+ seen: TermSeen[];
43
+ inferred: true;
44
+ flag: typeof LINKED_BY_TERM_VALUE;
45
+ }
46
+ /** A consumer let in to a route: an access grant, read from the route repo's term facts. */
47
+ export interface TermGrant {
48
+ route: FactEnd;
49
+ gatewayRoute: string;
50
+ consumer: TermSeen;
51
+ owner?: TermSeen;
52
+ }
53
+ /**
54
+ * What the consumers a repo lists say against the calls the join found. `caller-not-listed`: a
55
+ * repo calls its routes and none of its own values is listed (a finding); `caller-no-id`: a repo
56
+ * calls them and no fact of it names its own value, so whether it is listed is unknown (a note,
57
+ * review 12); `listed-no-call`: a listed consumer's repo is known and makes no call into them (a
58
+ * note).
59
+ */
60
+ export type TermAccessFinding = {
61
+ reason: "caller-not-listed" | "caller-no-id";
62
+ repo: string;
63
+ route: FactEnd;
64
+ call: FactEnd;
65
+ /** The caller's own values (owner terms), none of which is listed. */
66
+ callerValues: string[];
67
+ message: string;
68
+ } | {
69
+ reason: "listed-no-call";
70
+ repo: string;
71
+ consumer: TermSeen;
72
+ owner: TermSeen;
73
+ message: string;
74
+ };
75
+ export interface TermsResult {
76
+ /** Every term of the estate, by repo and fact id. */
77
+ terms: TermSeen[];
78
+ consumers: TermConsumer[];
79
+ possible: PossibleTermLink[];
80
+ grants: TermGrant[];
81
+ access: TermAccessFinding[];
82
+ }
83
+ export interface JoinTermsInput {
84
+ repos: readonly JoinRepo[];
85
+ /** The estate's join (`joinFacts`), whole: the calls into each repo's routes come from it. */
86
+ join?: FactsJoinResult;
87
+ /** The gateway bundle folders (ADR 0147), as given to `joinFacts`. */
88
+ bundleFolders?: readonly string[];
89
+ }
90
+ /** Who owns, lists and shares each value, and what the lists say against the calls. */
91
+ export declare function joinTerms(input: JoinTermsInput): TermsResult;
92
+ /** The flag a term's AccessGrant carries beside its `caller:<term>`, so it is told apart. */
93
+ export declare const termFlag: (term: string) => string;
94
+ /**
95
+ * The consumers a gateway repo's term facts list, as C1 AccessGrants on its routes (ADR 0163):
96
+ * one per consumer and route, the subject the value as written, the resource the route's
97
+ * GatewayRoute, cited on the value's line and the line giving it its role. `caller:<term>` lets
98
+ * the critic name them as a route's consumers when the route changes, as it names a route's own
99
+ * callers (A-callers). C1 as it is: no schema change.
100
+ */
101
+ export declare function termGrantRecords(result: TermsResult, repos: readonly JoinRepo[], o?: {
102
+ only?: readonly string[];
103
+ }): CatalogRecord[];
104
+ /**
105
+ * The flag an owner term gives its repo's Component (ADR 0163): `term:<term>=<value>`, the
106
+ * identifier the organisation knows the system by. `flags` is C1's existing optional field.
107
+ */
108
+ export declare const ownerTermFlag: (term: string, value: string) => string;
package/npm/core/fs.d.ts CHANGED
@@ -38,7 +38,7 @@ export declare function acquireLock(root: string, name: string, what: string, no
38
38
  * person's assistant (ADR 0124 addendum A-probe) and the parses kept between runs
39
39
  * (`cache/`, record-cache.ts).
40
40
  */
41
- export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/"];
41
+ export declare const LOCAL_ONLY: readonly ["me.yaml", "logs/", "locks/", "backups/", "history/", "probe/", "cache/", "map-all/"];
42
42
  /**
43
43
  * Make sure .atticus/.gitignore keeps this machine's files out of Git. It lives inside
44
44
  * .atticus/, so it works the same in a metarepo and in a repo adopted in place (where Atticus
@@ -12,6 +12,27 @@ export declare const HOSTS_STEP = "scan-hosts";
12
12
  */
13
13
  export declare const TARGETS_STEP_ID = "facts-targets";
14
14
  export declare const TARGETS_SPLIT_LABEL = "Not all to one place";
15
+ /**
16
+ * ADR 0162 (F8): the option of a targets question that opens the picker of the whole estate (the
17
+ * manifest's repos, the profiles' systems, the teams). It names nothing: it is never an answer.
18
+ */
19
+ export declare const TARGETS_ANOTHER_LABEL = "Another repo\u2026";
20
+ /**
21
+ * ADR 0162 (F8): the step that asks who owns a topic or queue the repo publishes to or listens on
22
+ * that no estate repo serves the other side of, and its option that opens the picker (a system of
23
+ * the profile, or a team): the answer adds the topic to that system's aliases, so the merge lands
24
+ * the publish or the listener on it, as a file change for review.
25
+ */
26
+ export declare const TOPICS_STEP_ID = "facts-topics";
27
+ export declare const TOPICS_OUTSIDE_LABEL = "A topic owned by another team or vendor";
28
+ /** A topics question's words: what the repo does with the topic, and the topic. */
29
+ export declare const topicQuestionText: (topic: string, component: string, side: "publish" | "listen") => string;
30
+ /** The topic a topics question asks about, read back from its words. */
31
+ export declare function topicOfQuestion(q: {
32
+ question: string;
33
+ }): string | undefined;
34
+ /** The options that open the picker: they name nothing, so they are never an answer. */
35
+ export declare const PICKER_LABELS: ReadonlySet<string>;
15
36
  /** The last option of a hosts question: no repo of the estate answers on it. */
16
37
  export declare const HOSTS_NONE = "None of these";
17
38
  /**
@@ -48,6 +69,30 @@ export declare function addOutsideSystem(root: string, repo: string, host: strin
48
69
  profile: string;
49
70
  added: boolean;
50
71
  }>;
72
+ /**
73
+ * ADR 0162 (F8): put a system a person named in a targets answer into the profile whose
74
+ * repos.manifest.yaml lists the repo that asked: a vendor (boundary vendor), or another team's
75
+ * system (boundary internal, owner the team's id from roles.yaml). Written as a file change in the
76
+ * metarepo, for review in the pull request, never to a shared system. `added` is false when a
77
+ * system of the profiles already has the id. Throws when no manifest lists the repo, or the
78
+ * profile would not be valid.
79
+ */
80
+ export declare function addProfileSystem(root: string, repo: string, s: {
81
+ id: string;
82
+ name: string;
83
+ boundary: "internal" | "vendor";
84
+ owner?: string;
85
+ /**
86
+ * The topics and queues it owns (ADR 0162 amendment): written under `topics`, never
87
+ * `aliases`, with the profile at schema version 2.
88
+ */
89
+ topics?: string[];
90
+ }): Promise<{
91
+ id: string;
92
+ profile: string;
93
+ added: boolean;
94
+ topics?: string[];
95
+ }>;
51
96
  /**
52
97
  * Put a host under a repo's `hosts` in the repos.manifest.yaml that lists it, keeping the
53
98
  * file's comments and order. `added` is false when the repo already lists it. Throws when no
@@ -10,8 +10,11 @@ export * from "./facts-join-vendor.js";
10
10
  export * from "./facts-join-prototype.js";
11
11
  export * from "./facts-carry.js";
12
12
  export * from "./facts-callers.js";
13
+ export * from "./facts-terms.js";
14
+ export * from "./org-notes.js";
13
15
  export * from "./link-evidence.js";
14
16
  export * from "./shared-maps.js";
17
+ export * from "./contract-check.js";
15
18
  export * from "./audit.js";
16
19
  export * from "./stack-helpers.js";
17
20
  export * from "./cite.js";
@@ -48,6 +51,7 @@ export * from "./change-types-migrate.js";
48
51
  export * from "./sources-migrate.js";
49
52
  export * from "./runtime-migrate.js";
50
53
  export * from "./roles-migrate.js";
54
+ export * from "./profile-migrate.js";
51
55
  export * from "./metarepo.js";
52
56
  export * from "./fs.js";
53
57
  export * from "./record-cache.js";
@@ -28,6 +28,8 @@ export interface MergeSystem {
28
28
  boundary: "product" | "internal" | "vendor";
29
29
  owner?: string;
30
30
  aliases: string[];
31
+ /** ADR 0162 amendment: the topics and queues it owns, kept apart from its aliases. */
32
+ topics?: string[];
31
33
  /** Copied to the System record (ADR 0040: saas marks a SaaS vendor). */
32
34
  tags?: string[];
33
35
  }
@@ -42,6 +44,11 @@ export interface MergePattern {
42
44
  sameSystem?: boolean;
43
45
  };
44
46
  }
47
+ /**
48
+ * ADR 0162 (F8): the flag on an Interface a topic or queue makes to an outside system because the
49
+ * profile names the topic under the system's topics: a person's word, not the code's.
50
+ */
51
+ export declare const DECLARED_TOPIC = "declared-topic";
45
52
  export interface MergeInput {
46
53
  records: CatalogRecord[];
47
54
  repos: MergeRepo[];
@@ -38,7 +38,7 @@ export declare function evidenceDirOf(root: string): string;
38
38
  * person's corrections, the verifier's report, and the read plan of a repo read in parts
39
39
  * (addendum A-ledger). None of them is a facts file of its own.
40
40
  */
41
- export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml", ".audit.yaml", ".contracts.yaml", ".gaps.md"];
41
+ export declare const FACTS_COMPANIONS: readonly [".questions.jsonl", ".rejected.jsonl", ".reviewed.jsonl", ".corrections.jsonl", ".verify.yaml", ".read-plan.yaml", ".audit.yaml", ".contracts.yaml", ".specs.yaml", ".gaps.md"];
42
42
  /**
43
43
  * The repo a file in the facts folder belongs to, and whether it is the repo's facts file
44
44
  * (`<repo>.jsonl`) or one of its companions; undefined for any other file. Every place that lists
@@ -14,8 +14,9 @@ export interface MigrationResult {
14
14
  * current schema version, in canonical form. Readers accept old files anyway; migrating once
15
15
  * keeps diffs clean afterwards. A file that isn't a catalog record (no known `kind`) is not
16
16
  * touched, nor is an old one that fails C1: it is reported, so nothing is half-migrated.
17
- * Version 1 → 2 (ADR 0031) and 2 → 3 (ADR 0125) change only `schemaVersion`: version 3 adds
18
- * `required` on a Schema field, and a migrated record gains none, since nothing knew it. The
17
+ * Version 1 → 2 (ADR 0031), 2 → 3 (ADR 0125) and 3 → 4 (ADR 0164) change only `schemaVersion`:
18
+ * version 3 adds `required` on a Schema field, and a migrated record gains none, since nothing
19
+ * knew it; version 4 adds `protobuf` to a Schema's formats, which no older record can hold. The
19
20
  * canonical form also writes list defaults a hand-written file left out, exactly as a scan
20
21
  * would write the record. `versions` limits it to files at those versions (each `atticus
21
22
  * upgrade` step lists its own); what it writes is always the current version.