@maycombhq/sdk 2.0.0-beta.1 → 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.
Files changed (102) hide show
  1. package/{dist → npm}/cache.d.ts +1 -1
  2. package/npm/core/api.d.ts +7964 -0
  3. package/npm/core/assistant-actor.d.ts +15 -0
  4. package/npm/core/audit.d.ts +153 -0
  5. package/npm/core/branches.d.ts +21 -0
  6. package/npm/core/cancel.d.ts +9 -0
  7. package/npm/core/catalog.d.ts +4735 -0
  8. package/npm/core/change-types-migrate.d.ts +10 -0
  9. package/npm/core/cite.d.ts +54 -0
  10. package/npm/core/contract-check.d.ts +251 -0
  11. package/npm/core/curated.d.ts +37 -0
  12. package/npm/core/fact-paths.d.ts +14 -0
  13. package/npm/core/facts-callers.d.ts +152 -0
  14. package/npm/core/facts-carry.d.ts +36 -0
  15. package/npm/core/facts-join-prototype.d.ts +239 -0
  16. package/npm/core/facts-join-vendor.d.ts +110 -0
  17. package/npm/core/facts-join.d.ts +482 -0
  18. package/npm/core/facts-terms.d.ts +108 -0
  19. package/npm/core/facts.d.ts +94 -0
  20. package/npm/core/fs.d.ts +47 -0
  21. package/npm/core/gates-migrate.d.ts +10 -0
  22. package/npm/core/host-questions.d.ts +111 -0
  23. package/npm/core/identity.d.ts +17 -0
  24. package/npm/core/index.d.ts +77 -0
  25. package/npm/core/json-schema.d.ts +20 -0
  26. package/npm/core/judgments.d.ts +63 -0
  27. package/npm/core/light.d.ts +8 -0
  28. package/npm/core/link-evidence.d.ts +212 -0
  29. package/npm/core/log.d.ts +49 -0
  30. package/npm/core/manifest-edit.d.ts +57 -0
  31. package/npm/core/merge.d.ts +85 -0
  32. package/npm/core/metarepo.d.ts +91 -0
  33. package/npm/core/migrate.d.ts +32 -0
  34. package/npm/core/migration-files.d.ts +13 -0
  35. package/npm/core/org-notes.d.ts +180 -0
  36. package/npm/core/orgpack-defaults.d.ts +199 -0
  37. package/npm/core/orgpack-load.d.ts +102 -0
  38. package/npm/core/profile-migrate.d.ts +11 -0
  39. package/npm/core/question-order.d.ts +23 -0
  40. package/npm/core/question-owners.d.ts +53 -0
  41. package/npm/core/question-proposals.d.ts +77 -0
  42. package/npm/core/questions.d.ts +312 -0
  43. package/npm/core/record-cache.d.ts +52 -0
  44. package/npm/core/refs.d.ts +9 -0
  45. package/npm/core/repo-description.d.ts +44 -0
  46. package/npm/core/repo-reads.d.ts +44 -0
  47. package/npm/core/roles-migrate.d.ts +9 -0
  48. package/npm/core/runtime-migrate.d.ts +11 -0
  49. package/npm/core/schema/ai.d.ts +397 -0
  50. package/npm/core/schema/change.d.ts +244 -0
  51. package/npm/core/schema/common.d.ts +135 -0
  52. package/npm/core/schema/conventions.d.ts +80 -0
  53. package/npm/core/schema/dialect.d.ts +801 -0
  54. package/npm/core/schema/executors.d.ts +396 -0
  55. package/npm/core/schema/fact-corrections.d.ts +56 -0
  56. package/npm/core/schema/facts.d.ts +1773 -0
  57. package/npm/core/schema/frameworks.d.ts +371 -0
  58. package/npm/core/schema/judgment.d.ts +77 -0
  59. package/npm/core/schema/kinds.d.ts +5168 -0
  60. package/npm/core/schema/layout.d.ts +25 -0
  61. package/npm/core/schema/orgpack.d.ts +1193 -0
  62. package/npm/core/schema/plugin.d.ts +73 -0
  63. package/npm/core/schema/question.d.ts +230 -0
  64. package/npm/core/schema/repo-type.d.ts +127 -0
  65. package/npm/core/schema/review.d.ts +558 -0
  66. package/npm/core/schema/scan-settings.d.ts +34 -0
  67. package/npm/core/schema/scan-verify.d.ts +535 -0
  68. package/npm/core/schema/spec.d.ts +269 -0
  69. package/npm/core/schema/version.d.ts +10 -0
  70. package/npm/core/schema/workspace.d.ts +330 -0
  71. package/npm/core/serialize.d.ts +17 -0
  72. package/npm/core/shared-maps.d.ts +146 -0
  73. package/npm/core/sources-migrate.d.ts +15 -0
  74. package/npm/core/specs.d.ts +66 -0
  75. package/npm/core/stack-helpers.d.ts +32 -0
  76. package/npm/core/tar-read.d.ts +13 -0
  77. package/npm/core/template.d.ts +101 -0
  78. package/npm/core/words.d.ts +13 -0
  79. package/npm/core/zip-read.d.ts +37 -0
  80. package/npm/core/zip.d.ts +13 -0
  81. package/npm/index.js +10097 -0
  82. package/{dist → npm}/plugin.d.ts +1 -1
  83. package/{dist → npm}/runner.d.ts +1 -1
  84. package/package.json +10 -11
  85. package/dist/cache.js +0 -115
  86. package/dist/cache.js.map +0 -1
  87. package/dist/fs-repo.js +0 -120
  88. package/dist/fs-repo.js.map +0 -1
  89. package/dist/index.js +0 -7
  90. package/dist/index.js.map +0 -1
  91. package/dist/parse-cache.js +0 -275
  92. package/dist/parse-cache.js.map +0 -1
  93. package/dist/plugin.js +0 -85
  94. package/dist/plugin.js.map +0 -1
  95. package/dist/runner.js +0 -209
  96. package/dist/runner.js.map +0 -1
  97. package/dist/sandbox.js +0 -443
  98. package/dist/sandbox.js.map +0 -1
  99. /package/{dist → npm}/fs-repo.d.ts +0 -0
  100. /package/{dist → npm}/index.d.ts +0 -0
  101. /package/{dist → npm}/parse-cache.d.ts +0 -0
  102. /package/{dist → npm}/sandbox.d.ts +0 -0
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The name a `by` matched when it names an AI agent or runtime rather than a person (ADR 0115
3
+ * addendum, 2026-10-25): one of the assistants Atticus writes files for, or its short name (the
4
+ * part before its first hyphen); a runtime kind; a generic word for an AI; a Git host's bot
5
+ * account; or one of `known`, which the caller fills from the org pack (its agents' ids, the models
6
+ * it allows). A handle matches a name when it is the name, or starts or ends with it joined by a
7
+ * hyphen, dot, underscore or space ("copilot-agent", "ai-reviewer"); an email is read by its local
8
+ * part. Undefined for a person. Facts about the words only: Atticus can't see who typed them, so
9
+ * this is a record and a speed bump, and the pull request a person approves stays the gate.
10
+ */
11
+ export declare function assistantActor(by: string, known?: readonly string[]): string | undefined;
12
+ /** Whether a finding's resolution was recorded by an AI rather than a person. */
13
+ export declare const isAssistantResolution: (r: {
14
+ by: string;
15
+ } | undefined, known?: readonly string[]) => boolean;
@@ -0,0 +1,153 @@
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
+ link: "link";
21
+ fact: "fact";
22
+ }>;
23
+ of: z.ZodString;
24
+ claim: z.ZodString;
25
+ cites: z.ZodArray<z.ZodString>;
26
+ fact: z.ZodOptional<z.ZodString>;
27
+ value: z.ZodOptional<z.ZodString>;
28
+ to: z.ZodOptional<z.ZodString>;
29
+ answer: z.ZodOptional<z.ZodEnum<{
30
+ unsure: "unsure";
31
+ wrong: "wrong";
32
+ right: "right";
33
+ }>>;
34
+ note: z.ZodOptional<z.ZodString>;
35
+ by: z.ZodOptional<z.ZodString>;
36
+ at: z.ZodOptional<z.ZodString>;
37
+ }, z.core.$strict>;
38
+ export type AuditItemT = z.infer<typeof AuditItem>;
39
+ export declare const AuditDraw: z.ZodObject<{
40
+ seed: z.ZodString;
41
+ size: z.ZodNumber;
42
+ commit: z.ZodOptional<z.ZodString>;
43
+ at: z.ZodString;
44
+ }, z.core.$strict>;
45
+ export type AuditDrawT = z.infer<typeof AuditDraw>;
46
+ export declare const AuditFile: z.ZodObject<{
47
+ schema: z.ZodLiteral<1>;
48
+ repo: z.ZodString;
49
+ draws: z.ZodArray<z.ZodObject<{
50
+ seed: z.ZodString;
51
+ size: z.ZodNumber;
52
+ commit: z.ZodOptional<z.ZodString>;
53
+ at: z.ZodString;
54
+ }, z.core.$strict>>;
55
+ items: z.ZodArray<z.ZodObject<{
56
+ id: z.ZodString;
57
+ kind: z.ZodEnum<{
58
+ link: "link";
59
+ fact: "fact";
60
+ }>;
61
+ of: z.ZodString;
62
+ claim: z.ZodString;
63
+ cites: z.ZodArray<z.ZodString>;
64
+ fact: z.ZodOptional<z.ZodString>;
65
+ value: z.ZodOptional<z.ZodString>;
66
+ to: z.ZodOptional<z.ZodString>;
67
+ answer: z.ZodOptional<z.ZodEnum<{
68
+ unsure: "unsure";
69
+ wrong: "wrong";
70
+ right: "right";
71
+ }>>;
72
+ note: z.ZodOptional<z.ZodString>;
73
+ by: z.ZodOptional<z.ZodString>;
74
+ at: z.ZodOptional<z.ZodString>;
75
+ }, z.core.$strict>>;
76
+ }, z.core.$strict>;
77
+ export type AuditFileT = z.infer<typeof AuditFile>;
78
+ export declare const AUDIT_DEFAULT_SIZE = 10;
79
+ export declare function parseAuditFile(text: string): {
80
+ ok: true;
81
+ file: AuditFileT;
82
+ } | {
83
+ ok: false;
84
+ issues: string[];
85
+ };
86
+ export declare function serializeAuditFile(file: AuditFileT): string;
87
+ /**
88
+ * The facts an audit may draw: those the verifier kept that a reader wrote. A person's own fact
89
+ * (a correction) is their word already, and one not yet checked isn't kept; neither is drawn.
90
+ */
91
+ export declare function auditCandidates(facts: readonly Fact[]): AuditItemT[];
92
+ /**
93
+ * A reproducible random sample: `size` facts and `size` links (all of them when there are
94
+ * fewer), the same for the same candidates and seed whatever order they come in.
95
+ */
96
+ export declare function drawAudit(o: {
97
+ facts: readonly AuditItemT[];
98
+ links: readonly AuditItemT[];
99
+ size: number;
100
+ seed: string;
101
+ }): AuditItemT[];
102
+ /**
103
+ * A draw added to the file on record: items already there keep their answers, new ones are
104
+ * added unanswered, and a draw with the same seed, size and commit isn't recorded twice.
105
+ */
106
+ export declare function mergeDraw(file: AuditFileT | undefined, repo: string, items: readonly AuditItemT[], draw: AuditDrawT): AuditFileT;
107
+ /**
108
+ * The Wilson score interval at 95%, rounded to three places: honest for a small sample and for
109
+ * a precision of 0 or 1, where the plain p ± 2σ is not. Undefined with nothing answered.
110
+ */
111
+ export declare function wilson(right: number, n: number): {
112
+ low: number;
113
+ high: number;
114
+ } | undefined;
115
+ export interface AuditTally {
116
+ drawn: number;
117
+ right: number;
118
+ wrong: number;
119
+ unsure: number;
120
+ /** Drawn and not answered yet. */
121
+ open: number;
122
+ /** Drawn, but the fact or link is no longer as the person saw it: left out of the count. */
123
+ gone: number;
124
+ /** right / (right + wrong); null with neither. */
125
+ precision: number | null;
126
+ low: number | null;
127
+ high: number | null;
128
+ }
129
+ export interface AuditPrecision {
130
+ facts: AuditTally;
131
+ byKind: Record<string, AuditTally>;
132
+ links: AuditTally;
133
+ /** Links by how they were joined (ADR 0135's flags). */
134
+ byHow: Record<string, AuditTally>;
135
+ }
136
+ /**
137
+ * Precision from the answers: of the items answered right or wrong, the share right, with the
138
+ * Wilson interval. Unsure and unanswered items are counted apart and never in the share; `keep`
139
+ * drops an item whose fact or link has changed since it was drawn (counted as gone).
140
+ */
141
+ export declare function auditPrecision(items: readonly AuditItemT[], keep?: (i: AuditItemT) => boolean): AuditPrecision;
142
+ /** Several repos' precision summed: the estate's. */
143
+ export declare function sumAuditPrecision(list: readonly AuditPrecision[]): AuditPrecision;
144
+ /**
145
+ * Whether a fact item is still the fact the person saw: the same id, citing the same line with
146
+ * the same value. Used to keep an answer standing, and to show a right one as `verified: sample`.
147
+ */
148
+ export declare function auditItemHolds(i: AuditItemT, facts: ReadonlyMap<string, Fact>): boolean;
149
+ /**
150
+ * The facts a person answered right in a sample audit that are still as they saw them: shown as
151
+ * `verified: sample` where the facts are read for a person (the facts file keeps `line`).
152
+ */
153
+ export declare function sampleConfirmed(audit: AuditFileT | undefined, facts: readonly Fact[]): Set<string>;
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Branch naming (frozen in the build specification):
3
+ * - `change/<change-id>` in each code repo a change touches
4
+ * - `task/<change-id>/<task-id>` for an AI task run, merged into the change branch by PR
5
+ * - `handoff/<change-id>/<phase>` for a hand-off PR in the metarepo
6
+ *
7
+ * `change/x` and `change/x/y` can't both exist in one repo (Git stores refs as paths),
8
+ * which is why task branches have their own prefix.
9
+ */
10
+ export type BranchKind = "change" | "task" | "handoff";
11
+ export interface ParsedBranch {
12
+ kind: BranchKind;
13
+ change: string;
14
+ task?: string;
15
+ phase?: string;
16
+ }
17
+ export declare function changeBranch(changeId: string): string;
18
+ export declare function taskBranch(changeId: string, taskId: string): string;
19
+ export declare function handoffBranch(changeId: string, phase: string): string;
20
+ /** Parse an Atticus branch name; returns undefined for any other branch. */
21
+ export declare function parseBranch(branch: string): ParsedBranch | undefined;
@@ -0,0 +1,9 @@
1
+ export declare class CancelledError extends Error {
2
+ constructor(message?: string);
3
+ }
4
+ /** Run `fn` with `signal` as the signal of everything it starts. */
5
+ export declare function withSignal<T>(signal: AbortSignal, fn: () => Promise<T>): Promise<T>;
6
+ /** The signal of the job this code runs in, if it runs in one. */
7
+ export declare function currentSignal(): AbortSignal | undefined;
8
+ /** Stop here when the job was cancelled. */
9
+ export declare function throwIfCancelled(): void;