@maycombhq/sdk 2.0.0-beta.28 → 2.0.0-beta.28.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/npm/core/api.d.ts CHANGED
@@ -576,8 +576,53 @@ import { z } from "zod";
576
576
  * `problems` by place, nothing written), writes them, then builds once, as one local job whose
577
577
  * result is `MapEditsResult` (with the caller repos they touch). A problem may carry
578
578
  * `problems`. Additive only.
579
+ * 3.14.0 (beta.28.1, "nothing slow runs silently"): the Connect panel's read and its preview as
580
+ * jobs. GET /api/links/candidates with `job=1` and POST /api/links/connect with `job: true`
581
+ * answer 202 JobAccepted at once; the job prints each step (its progress message is the last
582
+ * line it said), Stop (POST /api/jobs/{jobId}/cancel) ends it between steps, and its result's
583
+ * `answer` is the answer the request gives without `job` (or `problem`, refused). Without
584
+ * `job`, both answer as before. GET /api/facts/{repo}/preview takes `job=1` the same way (the
585
+ * panel after a correction). Additive only.
586
+ * Also in 3.14.0 (beta.28.1, field report 4): connecting two boxes never dead-ends. GET
587
+ * /api/links/candidates lists every call of A: one that has an arrow drawn is `joined` (with
588
+ * `joins`, the box it goes to), to move from the same panel; one the join ties to something no
589
+ * arrow is drawn for is `undrawn`, as loose as one that joins nothing; one placed outside to a
590
+ * target no box draws is listed `outside` with `joins`, where before it was left out; one with
591
+ * an arrow to this very box is `here` (`now`, its API: a pairing with that API is refused,
592
+ * 409); one a person paired with the box it goes to says who (`pairedBy`). POST
593
+ * /api/declared-links (and Edit the map's adds) from a box no System of the profiles is (a repo
594
+ * the manifest lists with no System) adds that System to the repo's profile first, and says so
595
+ * (`created`), and Undo of its last declaration takes that System away again (`removed`).
596
+ * Additive only.
597
+ * Also in 3.14.0 (beta.28.1, field report 5): Apply (POST /api/facts/{repo}/apply) writes the kept facts
598
+ * with the rejected ones left out (`verify --write` exit 3): its job ends done, code 0, and
599
+ * its result (`FactsApplyResult`) carries `leftOut`, how many facts were left out, beside the
600
+ * lines naming each with the file to fix it in. Additive only. Apply to every repo (POST
601
+ * /api/facts/apply-all) the same: a repo that wrote with facts left out is applied, and its
602
+ * result carries `leftOut` (all repos) and `leftOutRepos` (how many repos left some out).
603
+ * 3.15.0 (beta.28.2, ADR 0197 "beta.28.1 and older reading version 2"): a refused build's
604
+ * `reasons` (BuildRefusalView: GET /api/build's `pending.refused` and `last.refused`, a scan's
605
+ * and an Apply's job result) may be `newer-atticus`: catalog/sources/build.json or a slot was
606
+ * written by a newer Atticus, at a version of its format this one doesn't read. Its `message`
607
+ * says so, its `command` is `npm i -g @maycombhq/atticus@beta`, and nothing was written; it is
608
+ * never `not-upgraded`. The Apply preview's `confirm.refused` may list it the same way. The
609
+ * upgrade job (POST /api/upgrade) refuses on such a catalog with the same words; GET
610
+ * /api/upgrade then lists no `pending` step and says why in `newerCatalog`, and GET
611
+ * /api/build/undo offers no `plan` (its `problem` says why). Every route
612
+ * that writes one of the build's inputs (the build, scan, Apply, undo, prune, the upgrade, the
613
+ * map's edits and deletes, corrections, call corrections, pairings, declared links and boxes,
614
+ * answers, triage, the AI's decisions, the baseline, initiatives, an owner question's send,
615
+ * starting a run, the org pack's files, patterns, sources, adapters and AI settings, a file
616
+ * promoted into inputs/, repos and owners) answers 409 on such a catalog before it writes
617
+ * anything: a problem whose `refused` is `{ reasons: ["newer-atticus"], message, newer }`,
618
+ * `newer` (BuildRefusalView's, optional) naming each file a newer Atticus wrote with its
619
+ * version and the newest one this Atticus reads. Additive only.
620
+ * Also in 3.15.0 (ADR 0197 review): a `hand-edits` refusal may carry `unreadableManifest: true`,
621
+ * when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
622
+ * `command` is the build again with `--discard-edits` of every record file, never the curate.
623
+ * Additive only.
579
624
  */
580
- export declare const API_VERSION = "3.13.0";
625
+ export declare const API_VERSION = "3.15.0";
581
626
  export declare const DEFAULT_PORT = 4321;
582
627
  /** RFC 9457 problem details, used for every error. */
583
628
  /**
@@ -3967,6 +4012,7 @@ export declare const BuildRefusalView: z.ZodObject<{
3967
4012
  "large-removals": "large-removals";
3968
4013
  "hand-edits": "hand-edits";
3969
4014
  "not-upgraded": "not-upgraded";
4015
+ "newer-atticus": "newer-atticus";
3970
4016
  }>>;
3971
4017
  message: z.ZodString;
3972
4018
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4043,6 +4089,14 @@ export declare const BuildRefusalView: z.ZodObject<{
4043
4089
  repo: z.ZodString;
4044
4090
  why: z.ZodString;
4045
4091
  }, z.core.$strip>>>;
4092
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4093
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4094
+ path: z.ZodString;
4095
+ name: z.ZodString;
4096
+ field: z.ZodString;
4097
+ version: z.ZodNumber;
4098
+ reads: z.ZodNumber;
4099
+ }, z.core.$strip>>>;
4046
4100
  command: z.ZodString;
4047
4101
  plan: z.ZodOptional<z.ZodString>;
4048
4102
  }, z.core.$strip>;
@@ -4078,6 +4132,7 @@ export declare const BuildReportView: z.ZodObject<{
4078
4132
  "large-removals": "large-removals";
4079
4133
  "hand-edits": "hand-edits";
4080
4134
  "not-upgraded": "not-upgraded";
4135
+ "newer-atticus": "newer-atticus";
4081
4136
  }>>;
4082
4137
  message: z.ZodString;
4083
4138
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4154,6 +4209,14 @@ export declare const BuildReportView: z.ZodObject<{
4154
4209
  repo: z.ZodString;
4155
4210
  why: z.ZodString;
4156
4211
  }, z.core.$strip>>>;
4212
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4213
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4214
+ path: z.ZodString;
4215
+ name: z.ZodString;
4216
+ field: z.ZodString;
4217
+ version: z.ZodNumber;
4218
+ reads: z.ZodNumber;
4219
+ }, z.core.$strip>>>;
4157
4220
  command: z.ZodString;
4158
4221
  plan: z.ZodOptional<z.ZodString>;
4159
4222
  }, z.core.$strip>>;
@@ -4292,6 +4355,7 @@ export declare const CatalogBuildView: z.ZodObject<{
4292
4355
  "large-removals": "large-removals";
4293
4356
  "hand-edits": "hand-edits";
4294
4357
  "not-upgraded": "not-upgraded";
4358
+ "newer-atticus": "newer-atticus";
4295
4359
  }>>;
4296
4360
  message: z.ZodString;
4297
4361
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4368,6 +4432,14 @@ export declare const CatalogBuildView: z.ZodObject<{
4368
4432
  repo: z.ZodString;
4369
4433
  why: z.ZodString;
4370
4434
  }, z.core.$strip>>>;
4435
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4436
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4437
+ path: z.ZodString;
4438
+ name: z.ZodString;
4439
+ field: z.ZodString;
4440
+ version: z.ZodNumber;
4441
+ reads: z.ZodNumber;
4442
+ }, z.core.$strip>>>;
4371
4443
  command: z.ZodString;
4372
4444
  plan: z.ZodOptional<z.ZodString>;
4373
4445
  }, z.core.$strip>>;
@@ -4391,6 +4463,7 @@ export declare const CatalogBuildView: z.ZodObject<{
4391
4463
  "large-removals": "large-removals";
4392
4464
  "hand-edits": "hand-edits";
4393
4465
  "not-upgraded": "not-upgraded";
4466
+ "newer-atticus": "newer-atticus";
4394
4467
  }>>;
4395
4468
  message: z.ZodString;
4396
4469
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4467,6 +4540,14 @@ export declare const CatalogBuildView: z.ZodObject<{
4467
4540
  repo: z.ZodString;
4468
4541
  why: z.ZodString;
4469
4542
  }, z.core.$strip>>>;
4543
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
4544
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
4545
+ path: z.ZodString;
4546
+ name: z.ZodString;
4547
+ field: z.ZodString;
4548
+ version: z.ZodNumber;
4549
+ reads: z.ZodNumber;
4550
+ }, z.core.$strip>>>;
4470
4551
  command: z.ZodString;
4471
4552
  plan: z.ZodOptional<z.ZodString>;
4472
4553
  }, z.core.$strip>>;
@@ -4899,6 +4980,7 @@ export declare const MapEditsResult: z.ZodObject<{
4899
4980
  "large-removals": "large-removals";
4900
4981
  "hand-edits": "hand-edits";
4901
4982
  "not-upgraded": "not-upgraded";
4983
+ "newer-atticus": "newer-atticus";
4902
4984
  }>>;
4903
4985
  message: z.ZodString;
4904
4986
  removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -4975,11 +5057,129 @@ export declare const MapEditsResult: z.ZodObject<{
4975
5057
  repo: z.ZodString;
4976
5058
  why: z.ZodString;
4977
5059
  }, z.core.$strip>>>;
5060
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
5061
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
5062
+ path: z.ZodString;
5063
+ name: z.ZodString;
5064
+ field: z.ZodString;
5065
+ version: z.ZodNumber;
5066
+ reads: z.ZodNumber;
5067
+ }, z.core.$strip>>>;
4978
5068
  command: z.ZodString;
4979
5069
  plan: z.ZodOptional<z.ZodString>;
4980
5070
  }, z.core.$strip>>;
4981
5071
  }, z.core.$strip>;
4982
5072
  export type MapEditsResultT = z.infer<typeof MapEditsResult>;
5073
+ /**
5074
+ * 3.14.0: the result of POST /api/facts/{repo}/apply's job (GET /api/jobs/{id}'s `result`): its
5075
+ * code and the lines verify printed; `refused`, the listing of a build that waits for a confirm;
5076
+ * `leftOut` (beta.28.1), how many rejected facts the write left out (the lines name each); `next`,
5077
+ * a step to take first (Sync the repos).
5078
+ */
5079
+ export declare const FactsApplyResult: z.ZodObject<{
5080
+ code: z.ZodNumber;
5081
+ lines: z.ZodArray<z.ZodString>;
5082
+ refused: z.ZodOptional<z.ZodObject<{
5083
+ reasons: z.ZodArray<z.ZodEnum<{
5084
+ "nothing-read": "nothing-read";
5085
+ empty: "empty";
5086
+ "unexplained-removals": "unexplained-removals";
5087
+ "large-removals": "large-removals";
5088
+ "hand-edits": "hand-edits";
5089
+ "not-upgraded": "not-upgraded";
5090
+ "newer-atticus": "newer-atticus";
5091
+ }>>;
5092
+ message: z.ZodString;
5093
+ removals: z.ZodOptional<z.ZodArray<z.ZodObject<{
5094
+ path: z.ZodString;
5095
+ kind: z.ZodString;
5096
+ id: z.ZodString;
5097
+ repos: z.ZodArray<z.ZodString>;
5098
+ explainedBy: z.ZodArray<z.ZodString>;
5099
+ reasons: z.ZodOptional<z.ZodArray<z.ZodEnum<{
5100
+ input: "input";
5101
+ build: "build";
5102
+ archived: "archived";
5103
+ manifest: "manifest";
5104
+ curated: "curated";
5105
+ slot: "slot";
5106
+ }>>>;
5107
+ inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
5108
+ what: z.ZodEnum<{
5109
+ other: "other";
5110
+ inputs: "inputs";
5111
+ "org-pack": "org-pack";
5112
+ proposals: "proposals";
5113
+ shared: "shared";
5114
+ answers: "answers";
5115
+ pairings: "pairings";
5116
+ curated: "curated";
5117
+ traffic: "traffic";
5118
+ federated: "federated";
5119
+ }>;
5120
+ path: z.ZodString;
5121
+ }, z.core.$strip>>>;
5122
+ }, z.core.$strip>>>;
5123
+ unexplained: z.ZodOptional<z.ZodArray<z.ZodObject<{
5124
+ path: z.ZodString;
5125
+ kind: z.ZodString;
5126
+ id: z.ZodString;
5127
+ repos: z.ZodArray<z.ZodString>;
5128
+ explainedBy: z.ZodArray<z.ZodString>;
5129
+ reasons: z.ZodOptional<z.ZodArray<z.ZodEnum<{
5130
+ input: "input";
5131
+ build: "build";
5132
+ archived: "archived";
5133
+ manifest: "manifest";
5134
+ curated: "curated";
5135
+ slot: "slot";
5136
+ }>>>;
5137
+ inputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
5138
+ what: z.ZodEnum<{
5139
+ other: "other";
5140
+ inputs: "inputs";
5141
+ "org-pack": "org-pack";
5142
+ proposals: "proposals";
5143
+ shared: "shared";
5144
+ answers: "answers";
5145
+ pairings: "pairings";
5146
+ curated: "curated";
5147
+ traffic: "traffic";
5148
+ federated: "federated";
5149
+ }>;
5150
+ path: z.ZodString;
5151
+ }, z.core.$strip>>>;
5152
+ }, z.core.$strip>>>;
5153
+ allowRemovals: z.ZodOptional<z.ZodNumber>;
5154
+ edits: z.ZodOptional<z.ZodArray<z.ZodObject<{
5155
+ path: z.ZodString;
5156
+ how: z.ZodEnum<{
5157
+ added: "added";
5158
+ changed: "changed";
5159
+ deleted: "deleted";
5160
+ }>;
5161
+ }, z.core.$strip>>>;
5162
+ discardEdits: z.ZodOptional<z.ZodNumber>;
5163
+ unread: z.ZodOptional<z.ZodArray<z.ZodObject<{
5164
+ repo: z.ZodString;
5165
+ why: z.ZodString;
5166
+ }, z.core.$strip>>>;
5167
+ unreadableManifest: z.ZodOptional<z.ZodLiteral<true>>;
5168
+ newer: z.ZodOptional<z.ZodArray<z.ZodObject<{
5169
+ path: z.ZodString;
5170
+ name: z.ZodString;
5171
+ field: z.ZodString;
5172
+ version: z.ZodNumber;
5173
+ reads: z.ZodNumber;
5174
+ }, z.core.$strip>>>;
5175
+ command: z.ZodString;
5176
+ plan: z.ZodOptional<z.ZodString>;
5177
+ }, z.core.$strip>>;
5178
+ leftOut: z.ZodOptional<z.ZodNumber>;
5179
+ leftOutRepos: z.ZodOptional<z.ZodNumber>;
5180
+ next: z.ZodOptional<z.ZodUnknown>;
5181
+ }, z.core.$strip>;
5182
+ export type FactsApplyResultT = z.infer<typeof FactsApplyResult>;
4983
5183
  /**
4984
5184
  * 3.12.0 (ADR 0195 point 6): GET /api/build/upgrade, the upgrade to source slots as a dry run,
4985
5185
  * exactly what `atticus upgrade --json` lists under `slots`: every file `atticus upgrade --yes`
@@ -6243,6 +6443,18 @@ export declare const VerifyPreviewView: z.ZodObject<{
6243
6443
  head: z.ZodString;
6244
6444
  commit: z.ZodString;
6245
6445
  }, z.core.$strip>>;
6446
+ confirm: z.ZodOptional<z.ZodObject<{
6447
+ removals: z.ZodOptional<z.ZodNumber>;
6448
+ edits: z.ZodOptional<z.ZodNumber>;
6449
+ refused: z.ZodOptional<z.ZodArray<z.ZodEnum<{
6450
+ "nothing-read": "nothing-read";
6451
+ empty: "empty";
6452
+ "unexplained-removals": "unexplained-removals";
6453
+ "newer-atticus": "newer-atticus";
6454
+ }>>>;
6455
+ upgrade: z.ZodOptional<z.ZodLiteral<true>>;
6456
+ command: z.ZodOptional<z.ZodString>;
6457
+ }, z.core.$strip>>;
6246
6458
  staleCorrections: z.ZodArray<z.ZodString>;
6247
6459
  }, z.core.$strip>>;
6248
6460
  unavailable: z.ZodOptional<z.ZodEnum<{
@@ -13484,10 +13696,16 @@ export declare const CandidateCallView: z.ZodObject<{
13484
13696
  outside: "outside";
13485
13697
  left: "left";
13486
13698
  missed: "missed";
13699
+ joined: "joined";
13487
13700
  unresolved: "unresolved";
13701
+ undrawn: "undrawn";
13702
+ here: "here";
13488
13703
  }>;
13489
13704
  why: z.ZodOptional<z.ZodString>;
13490
13705
  paired: z.ZodOptional<z.ZodString>;
13706
+ joins: z.ZodOptional<z.ZodString>;
13707
+ now: z.ZodOptional<z.ZodString>;
13708
+ pairedBy: z.ZodOptional<z.ZodString>;
13491
13709
  suggestion: z.ZodOptional<z.ZodObject<{
13492
13710
  api: z.ZodString;
13493
13711
  score: z.ZodNumber;
@@ -13548,10 +13766,16 @@ export declare const LinkCandidatesView: z.ZodObject<{
13548
13766
  outside: "outside";
13549
13767
  left: "left";
13550
13768
  missed: "missed";
13769
+ joined: "joined";
13551
13770
  unresolved: "unresolved";
13771
+ undrawn: "undrawn";
13772
+ here: "here";
13552
13773
  }>;
13553
13774
  why: z.ZodOptional<z.ZodString>;
13554
13775
  paired: z.ZodOptional<z.ZodString>;
13776
+ joins: z.ZodOptional<z.ZodString>;
13777
+ now: z.ZodOptional<z.ZodString>;
13778
+ pairedBy: z.ZodOptional<z.ZodString>;
13555
13779
  suggestion: z.ZodOptional<z.ZodObject<{
13556
13780
  api: z.ZodString;
13557
13781
  score: z.ZodNumber;
@@ -14085,6 +14309,7 @@ export declare const UpgradeView: z.ZodObject<{
14085
14309
  files: z.ZodArray<z.ZodString>;
14086
14310
  }, z.core.$strip>>;
14087
14311
  upgraded: z.ZodOptional<z.ZodArray<z.ZodString>>;
14312
+ newerCatalog: z.ZodOptional<z.ZodString>;
14088
14313
  }, z.core.$strip>;
14089
14314
  /**
14090
14315
  * 3.5.0: what a setup edit changed, or with `preview: true` would change: the file
@@ -14292,6 +14517,7 @@ export declare const ConnectLinksRequest: z.ZodObject<{
14292
14517
  }, z.core.$strip>>>;
14293
14518
  rule: z.ZodOptional<z.ZodBoolean>;
14294
14519
  preview: z.ZodOptional<z.ZodBoolean>;
14520
+ job: z.ZodOptional<z.ZodBoolean>;
14295
14521
  }, z.core.$strip>;
14296
14522
  export declare const ConnectLinksResult: z.ZodObject<{
14297
14523
  written: z.ZodBoolean;
@@ -14376,6 +14602,14 @@ export declare const FileChangeResult: z.ZodObject<{
14376
14602
  }, z.core.$strip>>;
14377
14603
  verify: z.ZodString;
14378
14604
  commit: z.ZodString;
14605
+ created: z.ZodOptional<z.ZodObject<{
14606
+ system: z.ZodString;
14607
+ file: z.ZodString;
14608
+ }, z.core.$strip>>;
14609
+ removed: z.ZodOptional<z.ZodObject<{
14610
+ system: z.ZodString;
14611
+ file: z.ZodString;
14612
+ }, z.core.$strip>>;
14379
14613
  }, z.core.$strip>;
14380
14614
  /**
14381
14615
  * ADR 0179: a stroke drawn on the canvas for a change (a call, a topic, a table, a step removed
@@ -3,6 +3,13 @@ export declare class CancelledError extends Error {
3
3
  }
4
4
  /** Run `fn` with `signal` as the signal of everything it starts. */
5
5
  export declare function withSignal<T>(signal: AbortSignal, fn: () => Promise<T>): Promise<T>;
6
+ /** Run `fn` with `commit` as what `commitCurrent()` inside it calls. */
7
+ export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>): Promise<T>;
8
+ /**
9
+ * Say the job this code runs in has started writing: Stop is no longer heard. True when a job
10
+ * heard it (it says a late Stop itself); false outside one.
11
+ */
12
+ export declare function commitCurrent(): boolean;
6
13
  /** The signal of the job this code runs in, if it runs in one. */
7
14
  export declare function currentSignal(): AbortSignal | undefined;
8
15
  /** Stop here when the job was cancelled. */
@@ -31,6 +31,12 @@ export declare class DeclareError extends Error {
31
31
  readonly code: "not-found" | "invalid" | "exists";
32
32
  constructor(code: "not-found" | "invalid" | "exists", message: string);
33
33
  }
34
+ /**
35
+ * The re-review of beta.28.1: a short hash of the System as the canvas added it, in its comment,
36
+ * so Undo takes it away only while it is still exactly that (no field a person changed since).
37
+ */
38
+ export declare const addedHash: (s: Record<string, unknown>) => string;
39
+ export declare const addedComment: (by: string, at: string, hash: string) => string;
34
40
  /** The comment a declaration carries: which side, who and when. */
35
41
  export declare const declaredComment: (by: string, at: string, side?: "publishes" | "listens") => string;
36
42
  /**
@@ -41,6 +47,17 @@ export declare function declareLink(root: string, d: Declared, o: {
41
47
  by: string;
42
48
  at: string;
43
49
  preview?: boolean;
50
+ /**
51
+ * Beta.28.1 (field report 4): a system no profile has yet, which the canvas draws for a repo
52
+ * the manifest lists with no System of the profiles (the box takes the repo's id, or the
53
+ * manifest's `system`): added to its platform's profile in the same write, so a person
54
+ * declaring a link from that box never has to make the System first.
55
+ */
56
+ create?: {
57
+ platform: string;
58
+ name?: string;
59
+ owner?: string;
60
+ };
44
61
  }): Promise<{
45
62
  rel: string;
46
63
  changes: LineChange[];
@@ -49,7 +66,18 @@ export declare function declareLink(root: string, d: Declared, o: {
49
66
  before: string;
50
67
  /** The bytes it wrote (what a take-back expects to find). */
51
68
  wrote?: string;
69
+ /** Beta.28.1: the system added to the profile first (`create`), when it had none. */
70
+ created?: string;
52
71
  }>;
72
+ /**
73
+ * Beta.28.1 (field hunt G5): `after`, a whole document as the yaml library writes it, with every
74
+ * line it has unchanged from `before` (the file as written, LF) given back as `before` wrote it:
75
+ * a flow list's padding (`[dv, qa, prod]`), its quotes, its spacing. `before` as the library
76
+ * writes it is lined up with `before` line for line (the library keeps the lines and comments of
77
+ * a document it only reads); a line of `after` that is one of those, in order, is that line of
78
+ * `before`. Where the two don't line up (the library joined or split a line), `after` as it is.
79
+ */
80
+ export declare function keepUntouchedLines(written: string, after: string): string;
53
81
  /**
54
82
  * Undo: remove a declared topic or call from the system's list, exactly that one. Beta.28 (the
55
83
  * review of Edit the map): only that item's lines go (and the list's key when it was the last),
@@ -59,11 +87,16 @@ export declare function undeclareLink(root: string, d: {
59
87
  kind: "topic" | "call";
60
88
  system: string;
61
89
  value: string;
90
+ }, o?: {
91
+ /** A pairing or an answer names the system: a System the canvas added for it stays. */
92
+ inUse?: boolean;
62
93
  }): Promise<{
63
94
  rel: string;
64
95
  changes: LineChange[];
65
96
  before: string;
66
97
  wrote: string;
98
+ /** S3: the System the canvas added, taken away with its last declaration. */
99
+ removed?: string;
67
100
  }>;
68
101
  /** A system's declarations, with who and when where the canvas wrote them. */
69
102
  export declare function declaredOf(root: string, system: string): Promise<{
@@ -608,6 +608,20 @@ export declare function keyRefIn(s: string | undefined): {
608
608
  } | undefined;
609
609
  /** Join every call of the estate's facts to the entry that serves it, or say why not. */
610
610
  export declare function joinFacts(input: JoinFactsInput): FactsJoinResult;
611
+ /**
612
+ * Beta.28.1 (the review of "nothing slow runs silently"): joinFacts, giving way every
613
+ * JOIN_YIELD_EVERY calls, so a caller that awaits `tick` between (joinFactsAsync) lets a
614
+ * heartbeat, a Console line or a Stop through during a long join. The same join either way.
615
+ */
616
+ export declare function joinFactsAsync(input: JoinFactsInput, tick: () => Promise<void>): Promise<FactsJoinResult>;
617
+ /** How many calls the join reads between two points where it gives way. */
618
+ export declare const JOIN_YIELD_EVERY = 200;
619
+ /** Work written as steps (a generator that yields where it may give way), run to its end. */
620
+ export declare function runSteps<T>(g: Generator<void, T, void>): T;
621
+ /** The same, awaiting `tick` at each point it may give way. */
622
+ export declare function runStepsAsync<T>(g: Generator<void, T, void>, tick: () => Promise<void>): Promise<T>;
623
+ /** joinFacts as steps: see joinFactsAsync. */
624
+ export declare function joinFactsSteps(input: JoinFactsInput): Generator<void, FactsJoinResult, void>;
611
625
  /** The path a joined Interface records: the entry's, normalised (a gRPC or SOAP name as written). */
612
626
  export declare function servedPath(e: Entry): string;
613
627
  /** A gateway route's GatewayRoute id: `gw-<component>-<method>-<path>`, no dots (as a hop names one). */
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Reading and hashing many small files (beta.28.2): a catalog's 100,000 record files took 10 to
3
+ * 13 s to hash through the promise API, four calls each (open, stat, read, close) handed to
4
+ * libuv's thread pool and back, and each text decoded, its line endings replaced and encoded again
5
+ * to be hashed. Here a few worker threads read them with the synchronous calls, one file at a
6
+ * time each (so no more than one open file a worker: no EMFILE, on Windows either), and hash the
7
+ * bytes; the main thread stays free (a progress line, Stop between steps) and gets the results in
8
+ * the order of the paths, whatever the order the workers finish in. Every byte of every file is
9
+ * read: nothing is taken from a file's size and time. A small folder, or a process where a worker
10
+ * can't start, is read in this thread instead, to the same results.
11
+ */
12
+ /** A file's size and time (ms, floored), as `stat` gives them. */
13
+ export interface FileStat {
14
+ size: number;
15
+ mtimeMs: number;
16
+ }
17
+ /** A file's size and time, and the hash of its text with its line endings LF (`textShaOf`). */
18
+ export interface FileHash extends FileStat {
19
+ sha: string;
20
+ }
21
+ /**
22
+ * How the files are read: tests force a number of workers (0: this thread) and the smallest
23
+ * folder read by workers. By default 2 to 4 workers (one fewer than the CPUs, at least 2), for
24
+ * folders of `MIN_FILES` files or more.
25
+ */
26
+ export declare const filePoolHooks: {
27
+ workers?: number;
28
+ minFiles?: number;
29
+ /** A test's workers that fail as they start (as one that can't: ERR_WORKER_INIT_FAILED, OOM). */
30
+ failStart?: boolean;
31
+ /** A test's workers that start and never say they are ready (nor fail, nor exit). */
32
+ neverReady?: boolean;
33
+ /** How long the workers have to say they are ready (default `START_TIMEOUT_MS`). */
34
+ startTimeoutMs?: number;
35
+ };
36
+ /**
37
+ * How long the workers have to say they are ready before this thread reads instead (the final
38
+ * review of beta.28.2: a worker that neither answered nor failed hung the build). A worker starts
39
+ * in tens of milliseconds; 10 s is a host so loaded that this thread would be no slower.
40
+ */
41
+ export declare const START_TIMEOUT_MS = 10000;
42
+ /**
43
+ * The hash of a file's text, read as UTF-8, with its line endings LF: `sha256Of` of that text.
44
+ * Bytes that are UTF-8 with no CR are that text's own bytes, so they are hashed as they are;
45
+ * any other (a CR, a byte that isn't UTF-8, read as U+FFFD) are decoded first, as a read gives.
46
+ */
47
+ export declare function textShaOf(bytes: Buffer): string;
48
+ /**
49
+ * Every named file under `dir` (paths with forward slashes), read whole and hashed: its text hash
50
+ * (`textShaOf`), size and time, in the order of `rels`. A file that can't be opened or read fails
51
+ * the call with that error (its `code`: ENOENT for one gone since it was listed). With `raw`, the
52
+ * hash is of the file's bytes as they are (sha256, no line endings made LF): a parse kept by it
53
+ * is of exactly those bytes (record-cache.ts).
54
+ */
55
+ export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
56
+ raw?: boolean;
57
+ }): Promise<FileHash[]>;
58
+ /** Every named file's size and time (ms, floored), in the order of `rels`; none for one not there. */
59
+ export declare function statFilesIn(dir: string, rels: readonly string[]): Promise<(FileStat | undefined)[]>;
package/npm/core/fs.d.ts CHANGED
@@ -5,7 +5,30 @@
5
5
  * Windows a rename can fail for a moment while a virus scanner or indexer holds the file:
6
6
  * it is retried a few times before giving up.
7
7
  */
8
- export declare function writeFileAtomic(path: string, data: string | Uint8Array): Promise<void>;
8
+ export declare function writeFileAtomic(path: string, data: string | Uint8Array, o?: {
9
+ /**
10
+ * Told the size and time (ms, floored) of the file as written (beta.28.2: a writer keeps its
11
+ * parse by them): the temporary file's, taken on its handle before the rename (which keeps
12
+ * them), when the file has the same once renamed; not told when they differ (the file was
13
+ * changed meanwhile, or the system set another time on close). With them, the sha256 of the
14
+ * bytes written and `writtenAt`, the clock (ms) as the write began: a parse kept by them is
15
+ * checked by that hash while the file's time is within the timestamp's grain of `writtenAt`
16
+ * (record-cache.ts, `RACY_MS`).
17
+ */
18
+ stat?: (s: {
19
+ size: number;
20
+ mtimeMs: number;
21
+ sha: string;
22
+ writtenAt: number;
23
+ }) => void;
24
+ }): Promise<void>;
25
+ /**
26
+ * Copy a file the way `writeFileAtomic` writes one: to a temporary file beside the target, then
27
+ * renamed over it. The copy is made by the system (a copy-on-write clone where the file system
28
+ * has them, APFS, Btrfs or XFS; else a copy in the kernel), so the bytes never pass through
29
+ * JavaScript (beta.28.1: a 60-repo estate's build.json is 180 MB).
30
+ */
31
+ export declare function copyFileAtomic(from: string, path: string): Promise<void>;
9
32
  /** A file changed on disk between being read and being written back: nothing was written. */
10
33
  export declare class FileChangedError extends Error {
11
34
  readonly path: string;
@@ -60,6 +60,7 @@ export * from "./fs.js";
60
60
  export * from "./glob.js";
61
61
  export * from "./repo-files.js";
62
62
  export * from "./record-cache.js";
63
+ export * from "./file-pool.js";
63
64
  export * from "./kept-files.js";
64
65
  export * from "./log.js";
65
66
  export * from "./run-log.js";
@@ -8,7 +8,23 @@ import type { Fact } from "./schema/facts.js";
8
8
  */
9
9
  export type LooseStatus = "asked" | "missed" | "left" | "outside" | "unresolved"
10
10
  /** Already paired by a person with an API of this box. */
11
- | "paired";
11
+ | "paired"
12
+ /**
13
+ * Beta.28.1: the join ties it to another box (or this one) and an arrow is drawn for it:
14
+ * listed so it can be moved here from the same panel, never ticked unseen.
15
+ */
16
+ | "joined"
17
+ /**
18
+ * Beta.28.1: the join ties it to something, and no arrow is drawn for it (its own component,
19
+ * or no Interface of it on the canvas): as loose as a call that joins nothing.
20
+ */
21
+ | "undrawn"
22
+ /**
23
+ * The review of beta.28.1 (S2): the join ties it to this very box and an arrow is drawn for it
24
+ * (`now` the API it goes to): it goes here already, so nothing is suggested for it, and a
25
+ * pairing with the API it goes to would be a redundant line (refused).
26
+ */
27
+ | "here";
12
28
  export interface CandidateApi {
13
29
  /** The entry's fact id, or the operation's id in the spec. */
14
30
  id: string;
@@ -33,6 +49,18 @@ export interface CandidateCall {
33
49
  why?: string;
34
50
  /** For paired: the API it is paired with. */
35
51
  paired?: string;
52
+ /**
53
+ * Beta.28.1: the box the join ties it to now (a repo, or an outside target), for a call that
54
+ * is joined, undrawn or outside: where it goes, or would go, before it is moved.
55
+ */
56
+ joins?: string;
57
+ /** For here: the API of this box it goes to now (an entry's fact id), when the join names one. */
58
+ now?: string;
59
+ /**
60
+ * The review of beta.28.1 (N3): who paired it with the box it goes to now (another box): a
61
+ * pairing here replaces that person's word, which the panel says before it is written.
62
+ */
63
+ pairedBy?: string;
36
64
  suggestion?: {
37
65
  api: string;
38
66
  score: number;
@@ -100,4 +128,25 @@ export declare function linkCandidates(o: {
100
128
  };
101
129
  /** A's settings by key (its config facts with a value), to fill a call's `${key}` in. */
102
130
  settings?: Readonly<Record<string, string>>;
131
+ /**
132
+ * Beta.28.1: whether the canvas draws a join's arrow (its Interface is in the catalog). A join
133
+ * of a call to its own component is never drawn, whatever this says. Default: every other is.
134
+ */
135
+ drawn?: (j: FactsJoinResult["joins"][number]) => boolean;
136
+ /**
137
+ * Beta.28.1: whether the canvas draws a call placed outside the estate to this target (an
138
+ * outside system of the profile takes it). Default: none is, so the call is listed loose.
139
+ */
140
+ drawnOutside?: (target: string, call: string) => boolean;
141
+ /**
142
+ * Whether a repo, a component or a system is drawn in the box connected to (a repo's own id,
143
+ * its components; a system's repos and their components). Default: the box's own id only.
144
+ */
145
+ inBox?: (name: string) => boolean;
146
+ /**
147
+ * The review of beta.28.1 (S4): the box the built catalog draws a call's arrow to (an
148
+ * Interface current in it citing the call's line), for a call the join doesn't place: the
149
+ * canvas is what the person sees, so a drawn call is never listed as loose.
150
+ */
151
+ drawnTo?: (call: string) => string | undefined;
103
152
  }): LinkCandidates;
@@ -1,4 +1,18 @@
1
+ /**
2
+ * ADR 0187: where a line printed by a command goes besides its own output, while it runs inside
3
+ * the app's job. The job (in the server) sets the printer; the command line's `main`, and the
4
+ * app's routes that run a command's code, pass each line they print to `printToCurrent`. Outside
5
+ * a job there is no printer and nothing happens. No schema here: the command line loads it first.
6
+ */
7
+ /**
8
+ * Beta.28.1: how a line is printed. `now`: a progress line (a step of long work), sent to the
9
+ * Console at once rather than in the next batch of lines, so it is there before the step's work
10
+ * keeps the thread.
11
+ */
12
+ export interface PrintOptions {
13
+ now?: boolean;
14
+ }
1
15
  /** Run `work` with every line printed inside it (at any depth, across awaits) going to `print`. */
2
- export declare function withPrinter<T>(print: (line: string) => void, work: () => T): T;
16
+ export declare function withPrinter<T>(print: (line: string, o?: PrintOptions) => void, work: () => T): T;
3
17
  /** Print a line to the job this code runs in, if any. */
4
- export declare function printToCurrent(line: string): void;
18
+ export declare function printToCurrent(line: string, o?: PrintOptions): void;
@@ -1,3 +1,4 @@
1
+ import { type FileStat } from "./file-pool.js";
1
2
  /**
2
3
  * Record files read and parsed once, then kept between runs (ADR 0119, with its addendum of
3
4
  * 2026-10-26). A metarepo's catalog is about 1,500 files and its specs 400 more; reading and
@@ -16,13 +17,40 @@
16
17
  *
17
18
  * Nothing here decides what a file means: the caller's `parse` does, and only its output (the
18
19
  * record, or the problem with the file) is kept.
20
+ *
21
+ * Racily clean files (the final review of beta.28.2, Git's rule of the same name). A file system
22
+ * keeps a file's time to a grain (FAT 2 s, HFS+ 1 s, some SMB and NFS mounts 1 s or more), so a
23
+ * same-size edit made within that grain of a read or a write can keep the time the parse was kept
24
+ * by, and size and time alone would serve the old text. So each parse is kept with the clock as
25
+ * it was taken (`at`: before the bytes parsed were read, or before a writer wrote them), and one
26
+ * whose file's time is no more than `RACY_MS` before `at` is "racy": it keeps the sha256 of the
27
+ * bytes parsed, and is reused only when the file still hashes to them (read in the file pool's
28
+ * workers; cheaper than a parse), then kept again as of the hash's read when by then it is no
29
+ * longer racy (the next command, seconds on: from then on its stat alone decides). A parse whose
30
+ * file's time is more than `RACY_MS` before `at` is trusted by size and time, as before: any edit
31
+ * after `at` has a time after `at` less the grain, so it can't keep that time. A parse kept with no `at` (an older cache) is racy, and with no hash it is
32
+ * parsed again. The rule takes this machine's clock and the file system's to agree to within the
33
+ * grain (a mount whose server runs more than `RACY_MS` behind can still serve a stale parse, as
34
+ * Git can).
35
+ */
36
+ /**
37
+ * The widest timestamp grain allowed for (FAT's 2 s): a parse kept of a file whose time was
38
+ * within this of the moment it was kept is checked by its hash before it is reused.
19
39
  */
40
+ export declare const RACY_MS = 2000;
41
+ /** Tests set the clock a parse is kept at (ms; default `Date.now`). */
42
+ export declare const recordCacheHooks: {
43
+ now?: () => number;
44
+ };
20
45
  /** One file's parse: the value, or why the file isn't valid. Never both. */
21
46
  export interface Parsed<T> {
22
47
  /** The file, relative to the folder, with forward slashes. */
23
48
  rel: string;
24
49
  value?: T;
25
50
  problem?: string;
51
+ /** With `withStats`: the file's size and time (ms, floored) as this read found them (-1: none). */
52
+ size?: number;
53
+ mtimeMs?: number;
26
54
  }
27
55
  /** What a caller's parse says about one file. */
28
56
  export type ParseOutcome<T> = {
@@ -32,6 +60,16 @@ export type ParseOutcome<T> = {
32
60
  ok: false;
33
61
  message: string;
34
62
  };
63
+ interface Entry {
64
+ size: number;
65
+ mtimeMs: number;
66
+ /** The clock (ms) as the parse was kept: before its bytes were read, or written. None: racy. */
67
+ at?: number;
68
+ /** A racy entry's sha256 of the bytes parsed (none once it isn't racy). */
69
+ sha?: string;
70
+ value?: unknown;
71
+ problem?: string;
72
+ }
35
73
  /** Run `f` over the items, up to `AT_ONCE` at a time, keeping the order. */
36
74
  export declare function mapAtOnce<I, O>(items: I[], f: (item: I) => Promise<O>): Promise<O[]>;
37
75
  /**
@@ -49,4 +87,60 @@ export declare function readParsedFiles<T>(o: {
49
87
  parse: (text: string, rel: string) => ParseOutcome<T>;
50
88
  /** The root of the metarepo this run is working in; none means no cache (read-only). */
51
89
  cacheRoot?: string;
90
+ /**
91
+ * False: the parses kept under `cacheRoot` are read, and nothing is written there (a preview,
92
+ * which writes nothing: beta.28.1, it parsed a 100,000-record catalog from its files).
93
+ */
94
+ keep?: boolean;
95
+ /** Each file's size and time with its parse (beta.28.1: a write matches them to its own read). */
96
+ withStats?: boolean;
97
+ /**
98
+ * Told what this read keeps under `cacheRoot` (not called when it keeps nothing): a writer that
99
+ * then writes some of the files adds their parses with `keepParses` (beta.28.2).
100
+ */
101
+ kept?: (k: KeptParses<T>) => void;
52
102
  }): Promise<Parsed<T>[]>;
103
+ /** What a read kept of a folder's parses (`readParsedFiles`'s `kept`), for `keepParses`. */
104
+ export interface KeptParses<T> {
105
+ readonly memo: {
106
+ root: string;
107
+ file: string;
108
+ };
109
+ readonly version: string;
110
+ readonly dir: string;
111
+ /** The kept parses by path, as that read left them. */
112
+ readonly entries: ReadonlyMap<string, Entry>;
113
+ /** Only to tie the type to the parse's value. */
114
+ readonly _value?: T;
115
+ }
116
+ /**
117
+ * Add the parses of files a writer wrote since its read (`k`) to what that read kept, and forget
118
+ * the files it removed (beta.28.2: a catalog write rewrites its features and glossary terms,
119
+ * megabytes of YAML, and the next read parsed them again). Each file is kept by the size and time
120
+ * it had as it was written, with the parse of the text the writer wrote there, which is what a
121
+ * read of it would parse; a file whose size or time is another now (changed since), or gone, isn't
122
+ * kept. A file written moments ago is racy (its time is within `RACY_MS` of the write): it is kept
123
+ * with the hash of the bytes written (`writeFileAtomic`'s `stat` gives it, and the clock as the
124
+ * write began), so the next read reuses it only when the file still hashes to them; one with no
125
+ * hash is parsed again by the next read. A cache that can't be written costs the next read its
126
+ * parses.
127
+ */
128
+ export declare function keepParses<T>(k: KeptParses<T>, o: {
129
+ /**
130
+ * Each file written, with the size and time it had as it was written (`writeFileAtomic`'s
131
+ * `stat`): it is kept only while it still has exactly those, so an edit made since (of the
132
+ * same size too: its time differs, or within the grain its hash does) is parsed by the next
133
+ * read, never served the writer's text. `sha` and `writtenAt` as `writeFileAtomic` gives them.
134
+ */
135
+ files: readonly {
136
+ rel: string;
137
+ value?: T;
138
+ problem?: string;
139
+ at: FileStat & {
140
+ sha?: string;
141
+ writtenAt?: number;
142
+ };
143
+ }[];
144
+ removed: readonly string[];
145
+ }): Promise<void>;
146
+ export {};
package/npm/index.js CHANGED
@@ -6992,7 +6992,9 @@ var BuildRefusalView = z31.object({
6992
6992
  "unexplained-removals",
6993
6993
  "large-removals",
6994
6994
  "hand-edits",
6995
- "not-upgraded"
6995
+ "not-upgraded",
6996
+ // 3.15.0 (beta.28.2, ADR 0197): build.json or a slot a newer Atticus wrote.
6997
+ "newer-atticus"
6996
6998
  ])),
6997
6999
  message: z31.string(),
6998
7000
  removals: z31.array(BuildRemoval).optional(),
@@ -7002,6 +7004,28 @@ var BuildRefusalView = z31.object({
7002
7004
  discardEdits: z31.number().int().optional(),
7003
7005
  /** A scan that read nothing: each repo it couldn't read in full, and why. */
7004
7006
  unread: z31.array(z31.object({ repo: z31.string(), why: z31.string() })).optional(),
7007
+ /**
7008
+ * 3.15.0 (beta.28.2, ADR 0197): a `hand-edits` refusal because build.json is there but doesn't
7009
+ * read (edited or merged by hand). The only way on is to build again with `discardEdits` (every
7010
+ * record file); its edits are not to be made curated.
7011
+ */
7012
+ unreadableManifest: z31.literal(true).optional(),
7013
+ /**
7014
+ * 3.15.0 (beta.28.2, ADR 0197): a `newer-atticus` refusal's files a newer Atticus wrote
7015
+ * (build.json, a slot), each with its version field, the version it has and the newest one
7016
+ * this Atticus reads, as the 409 problem's `refused.newer` and the command line's --json say.
7017
+ */
7018
+ newer: z31.array(z31.object({
7019
+ /** Metarepo-relative, '/'-separated. */
7020
+ path: z31.string(),
7021
+ /** What the words call it: `build.json`, or its path. */
7022
+ name: z31.string(),
7023
+ /** The version field (`version`, `slotVersion`, `factsSchemaVersion`). */
7024
+ field: z31.string(),
7025
+ version: z31.number().int(),
7026
+ /** The newest version of it this Atticus reads. */
7027
+ reads: z31.number().int()
7028
+ })).optional(),
7005
7029
  /** What goes on in a terminal (the build, the hand edits' curate, or the upgrade). */
7006
7030
  command: z31.string(),
7007
7031
  /**
@@ -7201,6 +7225,15 @@ var MapEditsResult = z31.object({
7201
7225
  */
7202
7226
  refused: BuildRefusalView.optional()
7203
7227
  });
7228
+ var FactsApplyResult = z31.object({
7229
+ code: z31.number().int(),
7230
+ lines: z31.array(z31.string()),
7231
+ refused: BuildRefusalView.optional(),
7232
+ leftOut: z31.number().int().positive().optional(),
7233
+ /** Apply to every repo's (POST /api/facts/apply-all): how many repos left facts out. */
7234
+ leftOutRepos: z31.number().int().positive().optional(),
7235
+ next: z31.unknown().optional()
7236
+ });
7204
7237
  var CatalogUpgradeView = z31.object({
7205
7238
  pending: z31.boolean(),
7206
7239
  records: z31.number().int(),
@@ -7616,6 +7649,22 @@ var VerifyPreviewView = z31.object({
7616
7649
  }).optional(),
7617
7650
  /** The checkout's HEAD is past the facts' commit: verify reads the changed files' facts again. */
7618
7651
  headMoved: z31.object({ head: z31.string(), commit: z31.string() }).optional(),
7652
+ /**
7653
+ * 3.14.0 (beta.28.1): what the Apply's guards will say (ADR 0195 point 4), absent when it
7654
+ * writes without a word. It waits for a person's confirm when its build removes more than
7655
+ * the guard's limit (`removals`, how many it lists) or files under catalog/generated were
7656
+ * changed by hand (`edits`, how many), with the command that confirms exactly them; it
7657
+ * refuses whatever is confirmed when `refused` lists reasons (removals nothing explains,
7658
+ * an empty build, nothing read), and no command is given; on a catalog from before the
7659
+ * slots (`upgrade`) the command is `atticus upgrade`.
7660
+ */
7661
+ confirm: z31.object({
7662
+ removals: z31.number().int().optional(),
7663
+ edits: z31.number().int().optional(),
7664
+ refused: z31.array(z31.enum(["nothing-read", "empty", "unexplained-removals", "newer-atticus"])).optional(),
7665
+ upgrade: z31.literal(true).optional(),
7666
+ command: z31.string().optional()
7667
+ }).optional(),
7619
7668
  /** Corrections on file that meet no fact in this read (kept, applied when it is read again). */
7620
7669
  staleCorrections: z31.array(z31.string())
7621
7670
  }).optional(),
@@ -9556,9 +9605,30 @@ var CandidateCallView = z31.object({
9556
9605
  method: z31.string().optional(),
9557
9606
  path: z31.string(),
9558
9607
  at: z31.string(),
9559
- status: z31.enum(["asked", "missed", "left", "outside", "unresolved", "paired"]),
9608
+ /**
9609
+ * 3.14: `joined`, a call with an arrow drawn already, listed so it can be moved to this box;
9610
+ * `undrawn`, a call the join ties to something no arrow is drawn for, as loose as any;
9611
+ * `here`, a call with an arrow to this very box (`now` its API), never suggested again.
9612
+ */
9613
+ status: z31.enum([
9614
+ "asked",
9615
+ "missed",
9616
+ "left",
9617
+ "outside",
9618
+ "unresolved",
9619
+ "paired",
9620
+ "joined",
9621
+ "undrawn",
9622
+ "here"
9623
+ ]),
9560
9624
  why: z31.string().optional(),
9561
9625
  paired: z31.string().optional(),
9626
+ /** 3.14: the box the call goes to now (a repo, or an outside target), before it is moved. */
9627
+ joins: z31.string().optional(),
9628
+ /** 3.14: for `here`, the API of this box the call goes to now. */
9629
+ now: z31.string().optional(),
9630
+ /** 3.14: who paired the call with the box it goes to now, when a person did. */
9631
+ pairedBy: z31.string().optional(),
9562
9632
  suggestion: CandidateSuggestion.optional(),
9563
9633
  /** 2.57: the APIs it most likely is, best first, at most three. */
9564
9634
  suggestions: z31.array(CandidateSuggestion).max(3).optional(),
@@ -9841,7 +9911,12 @@ var UpgradeView = z31.object({
9841
9911
  * committed yet, besides the stamp. Final round: the panel reads them from the upgrade job's
9842
9912
  * result, and offers Propose for the stamp alone too.
9843
9913
  */
9844
- upgraded: z31.array(z31.string()).optional()
9914
+ upgraded: z31.array(z31.string()).optional(),
9915
+ /**
9916
+ * 3.15.0 (beta.28.2, ADR 0197): the catalog was built by a newer Atticus, in words that say to
9917
+ * upgrade Atticus (never `atticus upgrade`); `pending` is then empty, as the upgrade refuses.
9918
+ */
9919
+ newerCatalog: z31.string().optional()
9845
9920
  });
9846
9921
  var FileEditView = z31.object({
9847
9922
  path: z31.string(),
@@ -10003,7 +10078,12 @@ var ConnectLinksRequest = z31.object({
10003
10078
  /** Answer A's open target question with /** to B, so calls read later follow it too. */
10004
10079
  rule: z31.boolean().optional(),
10005
10080
  /** Say what it would write and what the next verify --write changes; write nothing. */
10006
- preview: z31.boolean().optional()
10081
+ preview: z31.boolean().optional(),
10082
+ /**
10083
+ * 3.14.0 (beta.28.1): run it as a job (202 and its id at once; its steps are the job's lines,
10084
+ * Stop ends it between them, and its result `answer` is this request's result, or `problem`).
10085
+ */
10086
+ job: z31.boolean().optional()
10007
10087
  });
10008
10088
  var ConnectLinksResult = z31.object({
10009
10089
  written: z31.boolean(),
@@ -10061,7 +10141,17 @@ var FileChangeResult = z31.object({
10061
10141
  written: z31.boolean(),
10062
10142
  files: z31.array(z31.object({ file: z31.string(), changes: z31.array(LineChangeView) })),
10063
10143
  verify: z31.string(),
10064
- commit: z31.string()
10144
+ commit: z31.string(),
10145
+ /**
10146
+ * 3.14: the System added to a profile first, for a declaration from a box no profile had (a
10147
+ * repo the manifest lists with no System): the person is told it was added, and where.
10148
+ */
10149
+ created: z31.object({ system: z31.string(), file: z31.string() }).optional(),
10150
+ /**
10151
+ * 3.14: the System the canvas added for a declaration, taken away with its last one (Undo):
10152
+ * the person is told it went, and from where.
10153
+ */
10154
+ removed: z31.object({ system: z31.string(), file: z31.string() }).optional()
10065
10155
  });
10066
10156
  var SketchStrokeRequest = z31.object({
10067
10157
  stroke: z31.object({ kind: z31.enum(["call", "topic", "table", "remove", "retarget", "undo", "retire"]) }).passthrough(),
@@ -11661,8 +11751,13 @@ var OPS = {
11661
11751
  id: "previewVerifyWrite",
11662
11752
  summary: "After a correction: the commands to run (atticus verify <repo> --write, then the git steps with the exact files) and what that write will change in the facts and the catalog (links moved, added, removed; facts dropped or edited), computed in-process without writing (ADR 0149)",
11663
11753
  tag: "workspace",
11664
- params: [p("repo"), q("fact", str3, "The fact corrected, for the branch and commit message")],
11754
+ params: [
11755
+ p("repo"),
11756
+ q("fact", str3, "The fact corrected, for the branch and commit message"),
11757
+ q("job", str3, "3.14.0: 1 runs the preview as a job (202 JobAccepted; its steps are its lines, Stop ends it between them, its result `answer` is this view or `problem`)")
11758
+ ],
11665
11759
  ok: { status: 200, schema: "VerifyPreviewView", description: "OK" },
11760
+ alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job=1`)" },
11666
11761
  errors: [400, 404]
11667
11762
  }
11668
11763
  },
@@ -11783,14 +11878,14 @@ var OPS = {
11783
11878
  "/api/facts/{repo}/apply": {
11784
11879
  post: {
11785
11880
  id: "applyFacts",
11786
- summary: "2.65.0 (ADR 0183): run atticus verify <repo> --write, as Apply after an answer or a correction; 3.12.0: with the counts that confirm a refused build",
11881
+ summary: "2.65.0 (ADR 0183): run atticus verify <repo> --write, as Apply after an answer or a correction; 3.12.0: with the counts that confirm a refused build; 3.14.0: a rejected fact is left out and the rest written (leftOut in the result)",
11787
11882
  tag: "workspace",
11788
11883
  params: [p("repo")],
11789
11884
  body: FactsApplyRequest,
11790
11885
  ok: {
11791
11886
  status: 202,
11792
11887
  schema: "JobAccepted",
11793
- description: "Started: its job's result is the code and the lines verify printed"
11888
+ description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, a refused build's listing, and (3.14.0) leftOut, how many rejected facts the write left out"
11794
11889
  },
11795
11890
  // 2.68.0: 409 while another local step (Apply, Propose, Bring in) runs.
11796
11891
  errors: [400, 409]
@@ -12224,19 +12319,22 @@ var OPS = {
12224
12319
  params: [
12225
12320
  q("from", str3, "Box A: the caller's repo"),
12226
12321
  q("to", str3, "Box B: a repo of the manifest"),
12227
- q("system", str3, "Box B: an outside system of the profile (instead of to)")
12322
+ q("system", str3, "Box B: an outside system of the profile (instead of to)"),
12323
+ q("job", str3, "3.14.0: 1 runs the read as a job (202 JobAccepted; its steps are its lines, Stop ends it between them, its result `answer` is this view or `problem`)")
12228
12324
  ],
12229
12325
  ok: { status: 200, schema: "LinkCandidatesView", description: "OK" },
12326
+ alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job=1`)" },
12230
12327
  errors: [400, 404]
12231
12328
  }
12232
12329
  },
12233
12330
  "/api/links/connect": {
12234
12331
  post: {
12235
12332
  id: "connectLinks",
12236
- summary: "Pair box A's calls with box B's APIs (ADR 0174, G1): a link line per pair in A's corrections, and with rule a /** answer; with preview, what it would write and the next verify --write changes",
12333
+ summary: "Pair box A's calls with box B's APIs (ADR 0174, G1): a link line per pair in A's corrections, and with rule a /** answer; with preview, what it would write and the next verify --write changes. 3.14.0: with `job: true`, 202 JobAccepted at once; the job's result `answer` is this result, or `problem`",
12237
12334
  tag: "views",
12238
12335
  body: ConnectLinksRequest,
12239
12336
  ok: { status: 200, schema: "ConnectLinksResult", description: "OK" },
12337
+ alsoOk: { status: 202, schema: "JobAccepted", description: "Started as a job (`job: true`)" },
12240
12338
  errors: [400, 404, 409, 422]
12241
12339
  }
12242
12340
  },
@@ -12291,7 +12389,7 @@ var OPS = {
12291
12389
  ok: {
12292
12390
  status: 202,
12293
12391
  schema: "JobAccepted",
12294
- description: "Started: its job's result is the code and the lines verify printed"
12392
+ description: "Started: its job's result is FactsApplyResult: the code and the lines verify printed, and (3.14.0) leftOut and leftOutRepos when repos wrote with rejected facts left out (applied, code 0)"
12295
12393
  },
12296
12394
  errors: [409]
12297
12395
  }
@@ -14044,6 +14142,7 @@ var SPEC_CACHE_VERSION = `spec@${FLOW_SCHEMA_VERSION}.${SPEC_HEADER_SCHEMA_VERSI
14044
14142
  // packages/core/dist/cancel.js
14045
14143
  import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
14046
14144
  var store = new AsyncLocalStorage2();
14145
+ var commits = new AsyncLocalStorage2();
14047
14146
 
14048
14147
  // packages/core/dist/assistant-actor.js
14049
14148
  init_ai();
@@ -14613,13 +14712,13 @@ function fsScanCache(dir) {
14613
14712
  throw new Error(`unsafe repo name: ${repo}`);
14614
14713
  const keep = new Set(keepCommits);
14615
14714
  let removed = 0;
14616
- let commits;
14715
+ let commits2;
14617
14716
  try {
14618
- commits = await readdir2(join3(dir, repo));
14717
+ commits2 = await readdir2(join3(dir, repo));
14619
14718
  } catch {
14620
14719
  return 0;
14621
14720
  }
14622
- for (const c of commits) {
14721
+ for (const c of commits2) {
14623
14722
  if (!keep.has(c)) {
14624
14723
  await rm(join3(dir, repo, c), { recursive: true, force: true });
14625
14724
  removed++;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maycombhq/sdk",
3
- "version": "2.0.0-beta.28",
3
+ "version": "2.0.0-beta.28.2",
4
4
  "description": "Atticus plugin SDK (contract C4): interfaces for extractors, dialects, ingestors and adapters.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",