@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.
Files changed (88) hide show
  1. package/npm/core/ai-decisions.d.ts +373 -0
  2. package/npm/core/api.d.ts +15888 -3797
  3. package/npm/core/app-memory.d.ts +69 -0
  4. package/npm/core/assistant-actor.d.ts +28 -7
  5. package/npm/core/audit.d.ts +174 -0
  6. package/npm/core/canary.d.ts +369 -0
  7. package/npm/core/cancel.d.ts +20 -0
  8. package/npm/core/catalog.d.ts +220 -66
  9. package/npm/core/change-types-migrate.d.ts +14 -0
  10. package/npm/core/cite.d.ts +88 -6
  11. package/npm/core/contract-check.d.ts +276 -0
  12. package/npm/core/curated.d.ts +10 -0
  13. package/npm/core/decision-batches.d.ts +29 -0
  14. package/npm/core/declarable-routes.d.ts +52 -0
  15. package/npm/core/declared-links.d.ts +210 -0
  16. package/npm/core/eol.d.ts +5 -0
  17. package/npm/core/fact-paths.d.ts +14 -0
  18. package/npm/core/facts-callers.d.ts +23 -1
  19. package/npm/core/facts-carry.d.ts +8 -2
  20. package/npm/core/facts-deps.d.ts +85 -0
  21. package/npm/core/facts-join-prototype.d.ts +66 -4
  22. package/npm/core/facts-join-vendor.d.ts +67 -7
  23. package/npm/core/facts-join.d.ts +476 -2
  24. package/npm/core/facts-terms.d.ts +108 -0
  25. package/npm/core/facts.d.ts +155 -1
  26. package/npm/core/field-places.d.ts +109 -0
  27. package/npm/core/file-pool.d.ts +84 -0
  28. package/npm/core/fs.d.ts +205 -7
  29. package/npm/core/glob-plain.d.ts +34 -0
  30. package/npm/core/glob.d.ts +14 -0
  31. package/npm/core/hash-cache.d.ts +53 -0
  32. package/npm/core/host-questions.d.ts +273 -1
  33. package/npm/core/identity.d.ts +20 -8
  34. package/npm/core/index.d.ts +38 -0
  35. package/npm/core/initialisms.d.ts +62 -0
  36. package/npm/core/kept-files.d.ts +17 -0
  37. package/npm/core/light.d.ts +5 -0
  38. package/npm/core/link-candidates.d.ts +224 -0
  39. package/npm/core/link-evidence.d.ts +212 -0
  40. package/npm/core/log.d.ts +2 -0
  41. package/npm/core/manifest-edit.d.ts +83 -6
  42. package/npm/core/merge.d.ts +28 -0
  43. package/npm/core/metarepo.d.ts +26 -1
  44. package/npm/core/migrate.d.ts +3 -2
  45. package/npm/core/org-notes.d.ts +180 -0
  46. package/npm/core/orgpack-defaults.d.ts +30 -6
  47. package/npm/core/orgpack-load.d.ts +24 -0
  48. package/npm/core/paths.d.ts +23 -0
  49. package/npm/core/printer.d.ts +18 -0
  50. package/npm/core/process-trees.d.ts +109 -0
  51. package/npm/core/profile-migrate.d.ts +13 -0
  52. package/npm/core/question-order.d.ts +23 -0
  53. package/npm/core/question-owners.d.ts +57 -0
  54. package/npm/core/question-proposals.d.ts +77 -0
  55. package/npm/core/question-roles.d.ts +84 -0
  56. package/npm/core/questions.d.ts +123 -6
  57. package/npm/core/record-cache.d.ts +122 -2
  58. package/npm/core/repo-files.d.ts +66 -0
  59. package/npm/core/repo-reads.d.ts +44 -0
  60. package/npm/core/roles-migrate.d.ts +10 -0
  61. package/npm/core/run-log.d.ts +341 -0
  62. package/npm/core/runtime-migrate.d.ts +18 -0
  63. package/npm/core/schema/ai.d.ts +61 -13
  64. package/npm/core/schema/common.d.ts +32 -8
  65. package/npm/core/schema/component-type.d.ts +193 -0
  66. package/npm/core/schema/conventions.d.ts +80 -0
  67. package/npm/core/schema/dialect.d.ts +12 -12
  68. package/npm/core/schema/fact-corrections.d.ts +112 -2
  69. package/npm/core/schema/facts.d.ts +743 -23
  70. package/npm/core/schema/frameworks.d.ts +12 -12
  71. package/npm/core/schema/kinds.d.ts +230 -66
  72. package/npm/core/schema/orgpack.d.ts +248 -24
  73. package/npm/core/schema/question.d.ts +281 -5
  74. package/npm/core/schema/reading-rules.d.ts +51 -0
  75. package/npm/core/schema/repo-type.d.ts +20 -2
  76. package/npm/core/schema/review.d.ts +30 -9
  77. package/npm/core/schema/scan-verify.d.ts +77 -0
  78. package/npm/core/schema/version.d.ts +4 -1
  79. package/npm/core/schema/workspace.d.ts +29 -11
  80. package/npm/core/setup-edit.d.ts +107 -0
  81. package/npm/core/shared-maps.d.ts +146 -0
  82. package/npm/core/stack-helpers.d.ts +32 -0
  83. package/npm/core/version-order.d.ts +14 -0
  84. package/npm/fs-repo.d.ts +2 -1
  85. package/npm/index.js +14248 -6710
  86. package/npm/listing.d.ts +14 -0
  87. package/npm/sandbox.d.ts +2 -1
  88. package/package.json +1 -1
@@ -0,0 +1,373 @@
1
+ import { z } from "zod";
2
+ import type { AuditTally } from "./audit.js";
3
+ import type { DecideSettings } from "./schema/orgpack.js";
4
+ import { type DecideBar, type Question } from "./schema/question.js";
5
+ /**
6
+ * ADR 0181: AI decides first, people correct, and a correction spreads. The pure parts: what the
7
+ * AI may decide, the bar a decision must meet to be applied without a person, the rule a
8
+ * person's correction spreads (as ADR 0153's `--match`: a path prefix, a host or a topic
9
+ * pattern), the batch record that makes every application one Undo away, and the pause when the
10
+ * sample audit (ADR 0148) puts the AI's decisions below the organisation's bar.
11
+ *
12
+ * An AI decision is a third kind of answer, beside a fact verified from code and a person's word:
13
+ * Atticus writes it (never the session), as the AI's, with the run that made it.
14
+ */
15
+ /**
16
+ * What a pairing's shapes say (ADR 0178): its call's one best API (`suggestion`, left out when two
17
+ * are as likely as each other) and whether it is confident.
18
+ */
19
+ export interface ShapesOfCall {
20
+ suggestion?: {
21
+ api: string;
22
+ score: number;
23
+ } | undefined;
24
+ confident?: boolean | undefined;
25
+ }
26
+ /**
27
+ * The bar an AI pairing of a call with `api` meets (ADR 0181, part 1), or undefined when it meets
28
+ * none and stays a proposal. `confident`: the shapes rank the same API first, at 0.85 or more and
29
+ * 0.2 ahead of the next (ADR 0178); `agrees-with-shapes`: the shapes rank it first, alone;
30
+ * `person-rule`: a person's rule covers the call and names the same box. The citation check is
31
+ * the caller's.
32
+ */
33
+ export declare function pairingBar(call: ShapesOfCall, api: string, o?: {
34
+ ruleAgrees?: boolean;
35
+ }): DecideBar | undefined;
36
+ /**
37
+ * Why the AI may not decide this question with this option, or undefined when it may (ADR 0181):
38
+ * only an open question about where a call goes (a target or a system on file), at its repo's
39
+ * scope, and only an option that names one place. Never words (a free-text question), a scope
40
+ * wider than the repo, a hosts answer (it writes the repos manifest for every caller) or a topics
41
+ * answer (it changes the org pack's profile), the picker, "Not all to one place" or "None of these".
42
+ */
43
+ export declare function questionAiProblem(q: Question, option: number | undefined): string | undefined;
44
+ /**
45
+ * The bar an AI answer meets (ADR 0181), or undefined: `agrees-with-shapes` when the option is the
46
+ * one the shapes rank first (a targets question lists its suggestions best first, each with the
47
+ * lines that give it), `person-rule` when a person's rule covers the question and names the same.
48
+ * The citation check (the proposal's lines, ADR 0144) is the caller's.
49
+ */
50
+ export declare function questionBar(q: Question, option: number, o: {
51
+ shapesFirst: boolean;
52
+ ruleAgrees?: boolean;
53
+ }): DecideBar | undefined;
54
+ /** What a rule is matched against: a call's path, the host it calls, or its topic. */
55
+ export interface RuleSubject {
56
+ path?: string | undefined;
57
+ host?: string | undefined;
58
+ topic?: string | undefined;
59
+ }
60
+ export type RuleKind = "path" | "host" | "topic";
61
+ /**
62
+ * The rule a person's correction spreads (ADR 0181, part 2): the path prefix, host pattern or
63
+ * topic pattern the corrected item shares with its siblings (the other items the AI decided the
64
+ * same way), as ADR 0153's `--match` takes it. Without a sibling sharing more, the corrected item's
65
+ * own folder (`/forge/limits/{id}` → `/forge/limits/**`), its host's parent domain, or its topic's
66
+ * family. Shown to the person before anything is saved; they may change it.
67
+ *
68
+ * Review round 48: the longest prefix shared with at least one sibling, not the prefix all the
69
+ * siblings share, so one distant sibling never widens `/api/v1/limits/**` to `/api/v1/**`; and a
70
+ * shared path of two segments or fewer that is wider than the item's own folder is too wide (as
71
+ * `/**` is): the item's own folder is taken instead.
72
+ */
73
+ export declare function deriveMatch(item: RuleSubject, siblings: readonly RuleSubject[]): {
74
+ kind: RuleKind;
75
+ match: string;
76
+ };
77
+ /** Whether a rule (a path prefix, a host pattern or a topic pattern) covers an item. */
78
+ export declare function matchCovers(match: string, item: RuleSubject): boolean;
79
+ /** The kind of a rule, from its words. */
80
+ export declare const ruleKindOf: (match: string, item?: RuleSubject) => RuleKind;
81
+ /**
82
+ * A batch's id: `b-<yyyymmdd>-<hhmmss>-<6 hex>`, the time in UTC and a random part, so two batches
83
+ * in the same second are told apart.
84
+ */
85
+ export declare function newBatchId(now: Date, rand?: () => number): string;
86
+ /** A pairing line a batch wrote or took away, exactly as it is in the repo's corrections file. */
87
+ export declare const BatchLink: z.ZodObject<{
88
+ kind: z.ZodLiteral<"link">;
89
+ repo: z.ZodString;
90
+ fact: z.ZodString;
91
+ line: z.ZodString;
92
+ }, z.core.$strict>;
93
+ /**
94
+ * A question a batch answered or opened again, with the answer it had before (none when open).
95
+ * Review round 48 (additive): for an AI answer taken up from a proposal, the proposal file's text
96
+ * as it was (`proposal`), so Undo puts it back for a person to review.
97
+ */
98
+ export declare const BatchQuestion: z.ZodObject<{
99
+ kind: z.ZodLiteral<"question">;
100
+ id: z.ZodString;
101
+ before: z.ZodOptional<z.ZodObject<{
102
+ option: z.ZodOptional<z.ZodNumber>;
103
+ text: z.ZodOptional<z.ZodString>;
104
+ by: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
105
+ kind: z.ZodLiteral<"ai">;
106
+ runtime: z.ZodEnum<{
107
+ "hand-off": "hand-off";
108
+ "copilot-acp": "copilot-acp";
109
+ }>;
110
+ run: z.ZodString;
111
+ bar: z.ZodOptional<z.ZodEnum<{
112
+ confident: "confident";
113
+ "agrees-with-shapes": "agrees-with-shapes";
114
+ "person-rule": "person-rule";
115
+ }>>;
116
+ }, z.core.$strict>]>;
117
+ at: z.ZodISODateTime;
118
+ scope: z.ZodObject<{
119
+ level: z.ZodEnum<{
120
+ repo: "repo";
121
+ "repo-type": "repo-type";
122
+ }>;
123
+ id: z.ZodString;
124
+ }, z.core.$strict>;
125
+ skill: z.ZodOptional<z.ZodString>;
126
+ match: z.ZodOptional<z.ZodString>;
127
+ proposal: z.ZodOptional<z.ZodObject<{
128
+ by: z.ZodString;
129
+ at: z.ZodISODateTime;
130
+ cites: z.ZodArray<z.ZodObject<{
131
+ repo: z.ZodOptional<z.ZodString>;
132
+ file: z.ZodString;
133
+ line: z.ZodNumber;
134
+ quote: z.ZodString;
135
+ }, z.core.$strict>>;
136
+ }, z.core.$strict>>;
137
+ batch: z.ZodOptional<z.ZodString>;
138
+ rule: z.ZodOptional<z.ZodObject<{
139
+ from: z.ZodString;
140
+ match: z.ZodString;
141
+ }, z.core.$strict>>;
142
+ }, z.core.$strict>>;
143
+ proposal: z.ZodOptional<z.ZodString>;
144
+ }, z.core.$strict>;
145
+ export declare const BatchItem: z.ZodDiscriminatedUnion<[z.ZodObject<{
146
+ kind: z.ZodLiteral<"link">;
147
+ repo: z.ZodString;
148
+ fact: z.ZodString;
149
+ line: z.ZodString;
150
+ }, z.core.$strict>, z.ZodObject<{
151
+ kind: z.ZodLiteral<"question">;
152
+ id: z.ZodString;
153
+ before: z.ZodOptional<z.ZodObject<{
154
+ option: z.ZodOptional<z.ZodNumber>;
155
+ text: z.ZodOptional<z.ZodString>;
156
+ by: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
157
+ kind: z.ZodLiteral<"ai">;
158
+ runtime: z.ZodEnum<{
159
+ "hand-off": "hand-off";
160
+ "copilot-acp": "copilot-acp";
161
+ }>;
162
+ run: z.ZodString;
163
+ bar: z.ZodOptional<z.ZodEnum<{
164
+ confident: "confident";
165
+ "agrees-with-shapes": "agrees-with-shapes";
166
+ "person-rule": "person-rule";
167
+ }>>;
168
+ }, z.core.$strict>]>;
169
+ at: z.ZodISODateTime;
170
+ scope: z.ZodObject<{
171
+ level: z.ZodEnum<{
172
+ repo: "repo";
173
+ "repo-type": "repo-type";
174
+ }>;
175
+ id: z.ZodString;
176
+ }, z.core.$strict>;
177
+ skill: z.ZodOptional<z.ZodString>;
178
+ match: z.ZodOptional<z.ZodString>;
179
+ proposal: z.ZodOptional<z.ZodObject<{
180
+ by: z.ZodString;
181
+ at: z.ZodISODateTime;
182
+ cites: z.ZodArray<z.ZodObject<{
183
+ repo: z.ZodOptional<z.ZodString>;
184
+ file: z.ZodString;
185
+ line: z.ZodNumber;
186
+ quote: z.ZodString;
187
+ }, z.core.$strict>>;
188
+ }, z.core.$strict>>;
189
+ batch: z.ZodOptional<z.ZodString>;
190
+ rule: z.ZodOptional<z.ZodObject<{
191
+ from: z.ZodString;
192
+ match: z.ZodString;
193
+ }, z.core.$strict>>;
194
+ }, z.core.$strict>>;
195
+ proposal: z.ZodOptional<z.ZodString>;
196
+ }, z.core.$strict>], "kind">;
197
+ export type BatchItemT = z.infer<typeof BatchItem>;
198
+ /**
199
+ * ADR 0181: the record of one batch: decisions the AI applied from one run (`ai`), or a person's
200
+ * correction and what its rule applied (`rule`). `applied` are the lines it appended and the
201
+ * answers it wrote; `reverted` the AI lines it took away and the AI answers it opened again, kept
202
+ * so Undo puts them back. Undo removes exactly the batch's own lines and answers, never a later
203
+ * one, and records who undid it and when. A file per batch under `decisions/`, committed in the
204
+ * pull request with the lines it names.
205
+ */
206
+ export declare const DecisionBatch: z.ZodObject<{
207
+ schema: z.ZodLiteral<1>;
208
+ id: z.ZodString;
209
+ kind: z.ZodEnum<{
210
+ ai: "ai";
211
+ rule: "rule";
212
+ }>;
213
+ at: z.ZodISODateTime;
214
+ by: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
215
+ kind: z.ZodLiteral<"ai">;
216
+ runtime: z.ZodEnum<{
217
+ "hand-off": "hand-off";
218
+ "copilot-acp": "copilot-acp";
219
+ }>;
220
+ run: z.ZodString;
221
+ bar: z.ZodOptional<z.ZodEnum<{
222
+ confident: "confident";
223
+ "agrees-with-shapes": "agrees-with-shapes";
224
+ "person-rule": "person-rule";
225
+ }>>;
226
+ }, z.core.$strict>]>;
227
+ correction: z.ZodOptional<z.ZodObject<{
228
+ item: z.ZodString;
229
+ answer: z.ZodString;
230
+ rule: z.ZodOptional<z.ZodObject<{
231
+ from: z.ZodString;
232
+ match: z.ZodString;
233
+ kind: z.ZodEnum<{
234
+ path: "path";
235
+ host: "host";
236
+ topic: "topic";
237
+ }>;
238
+ }, z.core.$strict>>;
239
+ run: z.ZodOptional<z.ZodString>;
240
+ shape: z.ZodOptional<z.ZodString>;
241
+ }, z.core.$strict>>;
242
+ applied: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
243
+ kind: z.ZodLiteral<"link">;
244
+ repo: z.ZodString;
245
+ fact: z.ZodString;
246
+ line: z.ZodString;
247
+ }, z.core.$strict>, z.ZodObject<{
248
+ kind: z.ZodLiteral<"question">;
249
+ id: z.ZodString;
250
+ before: z.ZodOptional<z.ZodObject<{
251
+ option: z.ZodOptional<z.ZodNumber>;
252
+ text: z.ZodOptional<z.ZodString>;
253
+ by: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
254
+ kind: z.ZodLiteral<"ai">;
255
+ runtime: z.ZodEnum<{
256
+ "hand-off": "hand-off";
257
+ "copilot-acp": "copilot-acp";
258
+ }>;
259
+ run: z.ZodString;
260
+ bar: z.ZodOptional<z.ZodEnum<{
261
+ confident: "confident";
262
+ "agrees-with-shapes": "agrees-with-shapes";
263
+ "person-rule": "person-rule";
264
+ }>>;
265
+ }, z.core.$strict>]>;
266
+ at: z.ZodISODateTime;
267
+ scope: z.ZodObject<{
268
+ level: z.ZodEnum<{
269
+ repo: "repo";
270
+ "repo-type": "repo-type";
271
+ }>;
272
+ id: z.ZodString;
273
+ }, z.core.$strict>;
274
+ skill: z.ZodOptional<z.ZodString>;
275
+ match: z.ZodOptional<z.ZodString>;
276
+ proposal: z.ZodOptional<z.ZodObject<{
277
+ by: z.ZodString;
278
+ at: z.ZodISODateTime;
279
+ cites: z.ZodArray<z.ZodObject<{
280
+ repo: z.ZodOptional<z.ZodString>;
281
+ file: z.ZodString;
282
+ line: z.ZodNumber;
283
+ quote: z.ZodString;
284
+ }, z.core.$strict>>;
285
+ }, z.core.$strict>>;
286
+ batch: z.ZodOptional<z.ZodString>;
287
+ rule: z.ZodOptional<z.ZodObject<{
288
+ from: z.ZodString;
289
+ match: z.ZodString;
290
+ }, z.core.$strict>>;
291
+ }, z.core.$strict>>;
292
+ proposal: z.ZodOptional<z.ZodString>;
293
+ }, z.core.$strict>], "kind">>;
294
+ reverted: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
295
+ kind: z.ZodLiteral<"link">;
296
+ repo: z.ZodString;
297
+ fact: z.ZodString;
298
+ line: z.ZodString;
299
+ }, z.core.$strict>, z.ZodObject<{
300
+ kind: z.ZodLiteral<"question">;
301
+ id: z.ZodString;
302
+ before: z.ZodOptional<z.ZodObject<{
303
+ option: z.ZodOptional<z.ZodNumber>;
304
+ text: z.ZodOptional<z.ZodString>;
305
+ by: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
306
+ kind: z.ZodLiteral<"ai">;
307
+ runtime: z.ZodEnum<{
308
+ "hand-off": "hand-off";
309
+ "copilot-acp": "copilot-acp";
310
+ }>;
311
+ run: z.ZodString;
312
+ bar: z.ZodOptional<z.ZodEnum<{
313
+ confident: "confident";
314
+ "agrees-with-shapes": "agrees-with-shapes";
315
+ "person-rule": "person-rule";
316
+ }>>;
317
+ }, z.core.$strict>]>;
318
+ at: z.ZodISODateTime;
319
+ scope: z.ZodObject<{
320
+ level: z.ZodEnum<{
321
+ repo: "repo";
322
+ "repo-type": "repo-type";
323
+ }>;
324
+ id: z.ZodString;
325
+ }, z.core.$strict>;
326
+ skill: z.ZodOptional<z.ZodString>;
327
+ match: z.ZodOptional<z.ZodString>;
328
+ proposal: z.ZodOptional<z.ZodObject<{
329
+ by: z.ZodString;
330
+ at: z.ZodISODateTime;
331
+ cites: z.ZodArray<z.ZodObject<{
332
+ repo: z.ZodOptional<z.ZodString>;
333
+ file: z.ZodString;
334
+ line: z.ZodNumber;
335
+ quote: z.ZodString;
336
+ }, z.core.$strict>>;
337
+ }, z.core.$strict>>;
338
+ batch: z.ZodOptional<z.ZodString>;
339
+ rule: z.ZodOptional<z.ZodObject<{
340
+ from: z.ZodString;
341
+ match: z.ZodString;
342
+ }, z.core.$strict>>;
343
+ }, z.core.$strict>>;
344
+ proposal: z.ZodOptional<z.ZodString>;
345
+ }, z.core.$strict>], "kind">>;
346
+ undone: z.ZodOptional<z.ZodObject<{
347
+ by: z.ZodString;
348
+ at: z.ZodISODateTime;
349
+ }, z.core.$strict>>;
350
+ }, z.core.$strict>;
351
+ export type DecisionBatchT = z.infer<typeof DecisionBatch>;
352
+ /** ADR 0181: corrections of the same shape that make a reading rule worth proposing (ADR 0176). */
353
+ export declare const RULE_AFTER_CORRECTIONS = 3;
354
+ export interface DecideNow {
355
+ links: "auto" | "propose";
356
+ questions: "auto" | "propose";
357
+ /** Deciding is paused back to propose: why, in words Home shows, and the audit's numbers. */
358
+ paused?: {
359
+ why: string;
360
+ precision: number;
361
+ low: number | null;
362
+ high: number | null;
363
+ answered: number;
364
+ minPrecision: number;
365
+ };
366
+ }
367
+ /**
368
+ * Whether the AI decides now (ADR 0181, part 3): as runtime.yaml's `decide` says, unless the
369
+ * sample audit of the AI's decisions (ADR 0148, the AI kind) puts them right less often than
370
+ * `decide.minPrecision`; then both go back to propose and `paused` says why. With nothing audited
371
+ * yet, as configured.
372
+ */
373
+ export declare function aiPause(settings: DecideSettings, tally: AuditTally | undefined): DecideNow;