@maycombhq/sdk 2.0.0-beta.28.3 → 2.0.0-beta.28.5

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
@@ -621,8 +621,48 @@ import { z } from "zod";
621
621
  * when catalog/sources/build.json is there but doesn't read (edited or merged by hand). Its
622
622
  * `command` is the build again with `--discard-edits` of every record file, never the curate.
623
623
  * Additive only.
624
+ * 3.16.0 (beta.28.4, ADR 0198): POST /api/facts/apply-all takes an optional body, `{ repos? }`
625
+ * (FactsApplyAllRequest): only those repos are applied (the map's bar sends the repos whose
626
+ * corrections wait, GET /api/propose's `applyFirst`), in id order whatever order they come in;
627
+ * 400, and no job, when a repo listed has no facts on file. Without `repos` it applies every
628
+ * repo read so far, as before. Its job's result (FactsApplyResult) gains `applied` and
629
+ * `notApplied`, the repos by name. While it runs over several repos its job's `progress` counts
630
+ * them (`done` of `total`: the repos finished). Stop is heard between its repos: a repo's
631
+ * write under way finishes whole, then the job ends `cancelled` with `stopped: true` in its
632
+ * result and the repos never reached under `notApplied`. Additive only.
633
+ * Also in 3.16.0 (beta.28.4, ADR 0199, two field reports on a 40-repo estate): POST
634
+ * /api/setup/repos/plan takes `job: true` for a folder of clones: 202 JobAccepted at once, the
635
+ * job says each folder as it comes to it ("Reading forge-ledger (4 of 40)…") and hears Stop
636
+ * between folders, and its result's `answer` is the ReposPlanView (or `problem`); the refusals
637
+ * the request knows at once (no such folder, several platforms and none chosen) still come as
638
+ * the answer. With or without `job`, a folder's repo a manifest lists already is told by its
639
+ * clone URL and not read (it is in `listed`, as before), and a folder that takes over a minute
640
+ * to read is in `skipped` with that reason. Additive only.
641
+ * Also in 3.16.0 (ADR 0199, "it says it's paired, but I don't see the line"): GET
642
+ * /api/links/candidates says of each `paired` call whether the map draws its arrow to this box
643
+ * (`drawn`), and of the view whether A's corrections are newer than A's last Apply
644
+ * (`applyPending`). A `paired` call also carries who paired it (`pairedBy`), any call with a
645
+ * pairing whether it is the AI's (`pairedAi`), and a pairing whose two ends are in one
646
+ * component that component (`inside`: no arrow is drawn for it). A pairing with a gateway's
647
+ * route the join carries on to the service behind it says so (`joins`, `onward: forwarded`,
648
+ * and on other boxes' rows `pairedWith`), an AI pairing a person's answer outranks says that
649
+ * (`onward: outranked`), and the view says when no catalog is built yet (`noCatalog`).
650
+ * Additive only.
651
+ * 3.17.0 (ADR 0200, a field report on beta.28.4: a line drawn from another team's system to a
652
+ * gateway proxy was turned round): GET /api/declared-links/routes lists what a system can be
653
+ * declared to call: the repos that have gateway routes (`gateways`) and, with `repo`, that
654
+ * repo's routes to pick from (`target`: each with its method, path, handler, the line it was
655
+ * read from, the words that declare it, whether the system declared it already, and any other
656
+ * repo the same words land on), or that it has none (`gateway: false`, with its entries
657
+ * counted, its manifest `type`, and `looksLikeGateway` when that type reads like a gateway's
658
+ * but isn't one the join takes): a declared call lands only on a gateway route. `inProfile`
659
+ * is false for a system only the code names, whose declaration would be refused. POST /api/declared-links, for
660
+ * `kind: call`, takes `routes` (1 to 200) in place of `route`: each is one line of the
661
+ * profile, written once, in a fixed order (sorted) whatever order they come in, in one write;
662
+ * 409 and nothing written when the profile has one already; 400 with neither or both. A
663
+ * request with `route` answers as before. Additive only.
624
664
  */
625
- export declare const API_VERSION = "3.15.0";
665
+ export declare const API_VERSION = "3.17.0";
626
666
  export declare const DEFAULT_PORT = 4321;
627
667
  /** RFC 9457 problem details, used for every error. */
628
668
  /**
@@ -2292,10 +2332,10 @@ export declare const RunView: z.ZodObject<{
2292
2332
  }, z.core.$strict>>;
2293
2333
  stepClass: z.ZodOptional<z.ZodEnum<{
2294
2334
  read: "read";
2335
+ quick: "quick";
2295
2336
  draft: "draft";
2296
2337
  critic: "critic";
2297
2338
  knowledge: "knowledge";
2298
- quick: "quick";
2299
2339
  }>>;
2300
2340
  model: z.ZodOptional<z.ZodString>;
2301
2341
  assistant: z.ZodOptional<z.ZodObject<{
@@ -2402,10 +2442,10 @@ export declare const RunListItem: z.ZodObject<{
2402
2442
  }, z.core.$strict>>;
2403
2443
  stepClass: z.ZodOptional<z.ZodEnum<{
2404
2444
  read: "read";
2445
+ quick: "quick";
2405
2446
  draft: "draft";
2406
2447
  critic: "critic";
2407
2448
  knowledge: "knowledge";
2408
- quick: "quick";
2409
2449
  }>>;
2410
2450
  model: z.ZodOptional<z.ZodString>;
2411
2451
  assistant: z.ZodOptional<z.ZodObject<{
@@ -2531,10 +2571,10 @@ export declare const RunDoneView: z.ZodObject<{
2531
2571
  }, z.core.$strict>>;
2532
2572
  stepClass: z.ZodOptional<z.ZodEnum<{
2533
2573
  read: "read";
2574
+ quick: "quick";
2534
2575
  draft: "draft";
2535
2576
  critic: "critic";
2536
2577
  knowledge: "knowledge";
2537
- quick: "quick";
2538
2578
  }>>;
2539
2579
  model: z.ZodOptional<z.ZodString>;
2540
2580
  assistant: z.ZodOptional<z.ZodObject<{
@@ -2666,10 +2706,10 @@ export declare const RunList: z.ZodObject<{
2666
2706
  }, z.core.$strict>>;
2667
2707
  stepClass: z.ZodOptional<z.ZodEnum<{
2668
2708
  read: "read";
2709
+ quick: "quick";
2669
2710
  draft: "draft";
2670
2711
  critic: "critic";
2671
2712
  knowledge: "knowledge";
2672
- quick: "quick";
2673
2713
  }>>;
2674
2714
  model: z.ZodOptional<z.ZodString>;
2675
2715
  assistant: z.ZodOptional<z.ZodObject<{
@@ -2785,10 +2825,10 @@ export declare const RunTranscript: z.ZodObject<{
2785
2825
  }, z.core.$strict>>;
2786
2826
  stepClass: z.ZodOptional<z.ZodEnum<{
2787
2827
  read: "read";
2828
+ quick: "quick";
2788
2829
  draft: "draft";
2789
2830
  critic: "critic";
2790
2831
  knowledge: "knowledge";
2791
- quick: "quick";
2792
2832
  }>>;
2793
2833
  model: z.ZodOptional<z.ZodString>;
2794
2834
  assistant: z.ZodOptional<z.ZodObject<{
@@ -5177,6 +5217,9 @@ export declare const FactsApplyResult: z.ZodObject<{
5177
5217
  }, z.core.$strip>>;
5178
5218
  leftOut: z.ZodOptional<z.ZodNumber>;
5179
5219
  leftOutRepos: z.ZodOptional<z.ZodNumber>;
5220
+ applied: z.ZodOptional<z.ZodArray<z.ZodString>>;
5221
+ notApplied: z.ZodOptional<z.ZodArray<z.ZodString>>;
5222
+ stopped: z.ZodOptional<z.ZodLiteral<true>>;
5180
5223
  next: z.ZodOptional<z.ZodUnknown>;
5181
5224
  }, z.core.$strip>;
5182
5225
  export type FactsApplyResultT = z.infer<typeof FactsApplyResult>;
@@ -10433,6 +10476,15 @@ export declare const FactsApplyRequest: z.ZodObject<{
10433
10476
  discardEdits: z.ZodOptional<z.ZodNumber>;
10434
10477
  plan: z.ZodOptional<z.ZodString>;
10435
10478
  }, z.core.$strict>;
10479
+ /**
10480
+ * 3.16.0 (ADR 0198): POST /api/facts/apply-all's body. `repos`: apply only these repos (the
10481
+ * repos whose corrections wait, as GET /api/propose's `applyFirst` lists them), in id order
10482
+ * whatever order they come in; 400, and no job, when one has no facts on file. Left out: every
10483
+ * repo read so far, as `atticus verify --all --write`.
10484
+ */
10485
+ export declare const FactsApplyAllRequest: z.ZodObject<{
10486
+ repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
10487
+ }, z.core.$strict>;
10436
10488
  export declare const ScanRequest: z.ZodObject<{
10437
10489
  repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
10438
10490
  full: z.ZodDefault<z.ZodBoolean>;
@@ -13703,6 +13755,14 @@ export declare const CandidateCallView: z.ZodObject<{
13703
13755
  }>;
13704
13756
  why: z.ZodOptional<z.ZodString>;
13705
13757
  paired: z.ZodOptional<z.ZodString>;
13758
+ drawn: z.ZodOptional<z.ZodBoolean>;
13759
+ inside: z.ZodOptional<z.ZodString>;
13760
+ pairedAi: z.ZodOptional<z.ZodBoolean>;
13761
+ pairedWith: z.ZodOptional<z.ZodString>;
13762
+ onward: z.ZodOptional<z.ZodEnum<{
13763
+ forwarded: "forwarded";
13764
+ outranked: "outranked";
13765
+ }>>;
13706
13766
  joins: z.ZodOptional<z.ZodString>;
13707
13767
  now: z.ZodOptional<z.ZodString>;
13708
13768
  pairedBy: z.ZodOptional<z.ZodString>;
@@ -13773,6 +13833,14 @@ export declare const LinkCandidatesView: z.ZodObject<{
13773
13833
  }>;
13774
13834
  why: z.ZodOptional<z.ZodString>;
13775
13835
  paired: z.ZodOptional<z.ZodString>;
13836
+ drawn: z.ZodOptional<z.ZodBoolean>;
13837
+ inside: z.ZodOptional<z.ZodString>;
13838
+ pairedAi: z.ZodOptional<z.ZodBoolean>;
13839
+ pairedWith: z.ZodOptional<z.ZodString>;
13840
+ onward: z.ZodOptional<z.ZodEnum<{
13841
+ forwarded: "forwarded";
13842
+ outranked: "outranked";
13843
+ }>>;
13776
13844
  joins: z.ZodOptional<z.ZodString>;
13777
13845
  now: z.ZodOptional<z.ZodString>;
13778
13846
  pairedBy: z.ZodOptional<z.ZodString>;
@@ -13835,6 +13903,8 @@ export declare const LinkCandidatesView: z.ZodObject<{
13835
13903
  question: z.ZodString;
13836
13904
  calls: z.ZodNumber;
13837
13905
  }, z.core.$strip>>;
13906
+ applyPending: z.ZodOptional<z.ZodBoolean>;
13907
+ noCatalog: z.ZodOptional<z.ZodBoolean>;
13838
13908
  }, z.core.$strip>;
13839
13909
  /** ADR 0178 part 2: Copilot matches A's loose calls with B's APIs; a person ticks the proposals. */
13840
13910
  export declare const MatchLinksRequest: z.ZodObject<{
@@ -14357,6 +14427,7 @@ export declare const ReposPlanRequest: z.ZodObject<{
14357
14427
  urls: z.ZodOptional<z.ZodString>;
14358
14428
  dir: z.ZodOptional<z.ZodString>;
14359
14429
  platform: z.ZodOptional<z.ZodString>;
14430
+ job: z.ZodOptional<z.ZodBoolean>;
14360
14431
  }, z.core.$strict>;
14361
14432
  export declare const PlannedRepoView: z.ZodObject<{
14362
14433
  id: z.ZodString;
@@ -14588,9 +14659,59 @@ export declare const DeclareLinkRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
14588
14659
  }, z.core.$strip>, z.ZodObject<{
14589
14660
  kind: z.ZodLiteral<"call">;
14590
14661
  system: z.ZodString;
14591
- route: z.ZodString;
14662
+ route: z.ZodOptional<z.ZodString>;
14663
+ routes: z.ZodOptional<z.ZodArray<z.ZodString>>;
14592
14664
  preview: z.ZodOptional<z.ZodBoolean>;
14593
14665
  }, z.core.$strip>], "kind">;
14666
+ /** 3.17 (ADR 0200): a gateway route a system can be declared to call. */
14667
+ export declare const DeclarableRouteView: z.ZodObject<{
14668
+ id: z.ZodString;
14669
+ method: z.ZodOptional<z.ZodString>;
14670
+ path: z.ZodString;
14671
+ handler: z.ZodOptional<z.ZodString>;
14672
+ at: z.ZodString;
14673
+ say: z.ZodString;
14674
+ declared: z.ZodOptional<z.ZodBoolean>;
14675
+ also: z.ZodOptional<z.ZodArray<z.ZodString>>;
14676
+ }, z.core.$strip>;
14677
+ /**
14678
+ * 3.17 (ADR 0200): what a system can be declared to call. `gateways`: the repos that have
14679
+ * gateway routes. `target`: the repo asked about, its routes by path then method, or
14680
+ * `gateway: false` for a repo with none (a declared call lands only on a gateway route).
14681
+ */
14682
+ export declare const DeclarableRoutesView: z.ZodObject<{
14683
+ system: z.ZodString;
14684
+ inProfile: z.ZodBoolean;
14685
+ gateways: z.ZodArray<z.ZodObject<{
14686
+ repo: z.ZodString;
14687
+ routes: z.ZodNumber;
14688
+ }, z.core.$strip>>;
14689
+ target: z.ZodOptional<z.ZodObject<{
14690
+ repo: z.ZodString;
14691
+ gateway: z.ZodBoolean;
14692
+ routes: z.ZodArray<z.ZodObject<{
14693
+ id: z.ZodString;
14694
+ method: z.ZodOptional<z.ZodString>;
14695
+ path: z.ZodString;
14696
+ handler: z.ZodOptional<z.ZodString>;
14697
+ at: z.ZodString;
14698
+ say: z.ZodString;
14699
+ declared: z.ZodOptional<z.ZodBoolean>;
14700
+ also: z.ZodOptional<z.ZodArray<z.ZodString>>;
14701
+ }, z.core.$strip>>;
14702
+ entries: z.ZodNumber;
14703
+ type: z.ZodOptional<z.ZodString>;
14704
+ manifest: z.ZodOptional<z.ZodString>;
14705
+ looksLikeGateway: z.ZodOptional<z.ZodBoolean>;
14706
+ notRead: z.ZodOptional<z.ZodObject<{
14707
+ why: z.ZodEnum<{
14708
+ "not-read": "not-read";
14709
+ unverified: "unverified";
14710
+ }>;
14711
+ command: z.ZodString;
14712
+ }, z.core.$strip>>;
14713
+ }, z.core.$strip>>;
14714
+ }, z.core.$strip>;
14594
14715
  export declare const FileChangeResult: z.ZodObject<{
14595
14716
  written: z.ZodBoolean;
14596
14717
  files: z.ZodArray<z.ZodObject<{
@@ -14905,6 +15026,8 @@ export declare const RuleFromPairingResult: z.ZodObject<{
14905
15026
  export type RuleFromPairingResultT = z.infer<typeof RuleFromPairingResult>;
14906
15027
  export type DeclareLinkRequestT = z.infer<typeof DeclareLinkRequest>;
14907
15028
  export type FileChangeResultT = z.infer<typeof FileChangeResult>;
15029
+ export type DeclarableRouteViewT = z.infer<typeof DeclarableRouteView>;
15030
+ export type DeclarableRoutesViewT = z.infer<typeof DeclarableRoutesView>;
14908
15031
  export type SketchStrokeRequestT = z.infer<typeof SketchStrokeRequest>;
14909
15032
  export type SketchResultT = z.infer<typeof SketchResult>;
14910
15033
  export type AddableViewT = z.infer<typeof AddableView>;
@@ -10,6 +10,13 @@ export declare function withCommit<T>(commit: () => void, fn: () => Promise<T>):
10
10
  * heard it (it says a late Stop itself); false outside one.
11
11
  */
12
12
  export declare function commitCurrent(): boolean;
13
+ /** Run `fn` with `release` as what `releaseCurrent()` inside it calls. */
14
+ export declare function withRelease<T>(release: () => void, fn: () => Promise<T>): Promise<T>;
15
+ /**
16
+ * Say the write this job started (`commitCurrent`) has ended and nothing is being written: only
17
+ * between two whole writes, never inside one. True when a job heard it; false outside one.
18
+ */
19
+ export declare function releaseCurrent(): boolean;
13
20
  /** The signal of the job this code runs in, if it runs in one. */
14
21
  export declare function currentSignal(): AbortSignal | undefined;
15
22
  /**
@@ -153,7 +153,11 @@ export interface ContractMismatch {
153
153
  /** What it reaches: an entry of the estate, or an outside system. */
154
154
  entry?: FactEnd;
155
155
  system?: string;
156
- /** `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced. */
156
+ /**
157
+ * `mismatch`: the two sides disagree; `unconfirmed`: a mapping on the way isn't traced, or the
158
+ * difference rests on a field whose place in its payload the facts don't give (the message
159
+ * says which).
160
+ */
157
161
  status: "mismatch" | "unconfirmed";
158
162
  kind: ContractKind;
159
163
  side?: "request" | "response" | "message";
@@ -164,7 +168,7 @@ export interface ContractMismatch {
164
168
  receiver: ContractEnd;
165
169
  /** The mapping lines the comparison went through (`repo path:line`), in order. */
166
170
  via?: string[];
167
- /** The mapping that isn't traced, when `unconfirmed`. */
171
+ /** The mapping that isn't traced, when `unconfirmed` for that reason. */
168
172
  untraced?: string;
169
173
  message: string;
170
174
  }
@@ -231,6 +235,17 @@ export declare const CONTRACT_WORDS: {
231
235
  errorUnlisted: (status: string, r: string, rAt: string, s: string, spec: boolean) => string;
232
236
  errorUnanswered: (status: string, s: string, sAt: string, r: string) => string;
233
237
  unconfirmed: (message: string, untraced: string) => string;
238
+ /** Addendum of 2026-11-17: a difference that rests on a place the facts don't give. */
239
+ unplaced: (message: string, why: string) => string;
240
+ place: (why: string) => string;
241
+ shared: (n: number, tail: string, r: string) => string;
242
+ noRoot: (s: string, side: string) => string;
243
+ nothingInside: (s: string, name: string) => string;
244
+ unlisted: (r: string, name: string) => string;
245
+ itemsUnread: (r: string, name: string) => string;
246
+ elsewhere: (names: readonly string[]) => string;
247
+ renamed: (name: string) => string;
248
+ sameAt: (names: readonly string[]) => string;
234
249
  };
235
250
  /**
236
251
  * The `transform` a reader gives the field fact that names a publish's or listener's message type
@@ -0,0 +1,52 @@
1
+ import type { JoinRepo } from "./facts-join.js";
2
+ /**
3
+ * ADR 0200: the gateway routes a person can declare a caller of, listed to pick from. A declared
4
+ * call (the profile's `calls`, A-callers) lands only on a gateway route: an entry of a gateway
5
+ * repo, or any repo's entry under a proxy bundle folder. An ordinary service's entry is not one,
6
+ * and the join places no declaration on it. The routes come from the same rule the join uses
7
+ * (`gatewayRouteFacts`), and the words offered for each are words the join places on it
8
+ * (`declaredRouteMatches`). Pure.
9
+ */
10
+ export interface DeclarableRoute {
11
+ /** The route's entry fact. */
12
+ id: string;
13
+ method?: string;
14
+ path: string;
15
+ /** The handler or proxy flow that serves it, where the facts name one. */
16
+ handler?: string;
17
+ /** path:line of the line it was read from. */
18
+ at: string;
19
+ /**
20
+ * What the declaration says to mean this route: `METHOD /path` where no other route of the
21
+ * estate is served on those words, else its handler where that names only this one.
22
+ */
23
+ say: string;
24
+ /** The system declared it already (by either way of naming it). */
25
+ declared?: true;
26
+ /** The other repos whose route the same words name: the declaration lands there too. */
27
+ also?: string[];
28
+ }
29
+ export interface DeclarableRoutes {
30
+ /** The repo has gateway routes. */
31
+ gateway: boolean;
32
+ routes: DeclarableRoute[];
33
+ /** How many entries the repo has on record, routes or not. */
34
+ entries: number;
35
+ }
36
+ interface Input {
37
+ repos: readonly JoinRepo[];
38
+ /** The gateway bundle folders, as given to the join (the estate's conventions). */
39
+ bundleFolders?: readonly string[] | undefined;
40
+ }
41
+ /** The gateway routes of `repo`, by path then method, each with the words that declare it. */
42
+ export declare function declarableRoutes(input: Input & {
43
+ repo: string;
44
+ /** The routes the system declared already, as its profile says them. */
45
+ declared: readonly string[];
46
+ }): DeclarableRoutes;
47
+ /** The repos that have gateway routes, by id, with how many. */
48
+ export declare function declarableGateways(input: Input): {
49
+ repo: string;
50
+ routes: number;
51
+ }[];
52
+ export {};
@@ -15,6 +15,12 @@ export type Declared = {
15
15
  kind: "call";
16
16
  system: string;
17
17
  route: string;
18
+ }
19
+ /** ADR 0200: several gateway routes in one write, one line each. */
20
+ | {
21
+ kind: "call";
22
+ system: string;
23
+ routes: readonly string[];
18
24
  };
19
25
  export interface DeclaredOnFile {
20
26
  kind: "topic" | "call";
@@ -1,6 +1,6 @@
1
1
  import type { CatalogRecord } from "./catalog.js";
2
2
  import { type FacingWords, type FactEnd, type FactsJoinResult, type GatewayFacing, type JoinRepo } from "./facts-join.js";
3
- import type { CallerKind } from "./schema/facts.js";
3
+ import type { CallerKind, FactOf } from "./schema/facts.js";
4
4
  import type { Profile } from "./schema/orgpack.js";
5
5
  /**
6
6
  * Who a gateway route lets in (ADR 0124 addendum A-callers). A route's own files usually name
@@ -127,6 +127,26 @@ export declare function declaredCallsOf(profiles: readonly {
127
127
  platform: string;
128
128
  profile?: Profile;
129
129
  }[]): DeclaredCallInput[];
130
+ /**
131
+ * Whether the route a person named (a declared call's `route`) is this gateway route: its handler
132
+ * (`proxy/flow`, any case), or `METHOD /path` as the gateway serves it (ANY for a route read with
133
+ * no method; a trailing slash is neither here nor there). The one rule, for the join and for the
134
+ * routes offered to declare (ADR 0200).
135
+ */
136
+ export declare function declaredRouteMatches(route: {
137
+ handler?: string | undefined;
138
+ method?: string | undefined;
139
+ path: string;
140
+ }, said: string): boolean;
141
+ /**
142
+ * The entry facts of the estate that are gateway routes (A-callers): every entry of a gateway
143
+ * repo, and any repo's entry cited under a proxy bundle folder. The one rule, for the join and
144
+ * for the routes offered to declare (ADR 0200).
145
+ */
146
+ export declare function gatewayRouteFacts(repos: readonly JoinRepo[], bundleFolders?: readonly string[]): {
147
+ repo: string;
148
+ fact: FactOf<"entry">;
149
+ }[];
130
150
  /** Who each gateway route of the estate lets in, and the chain from each declared caller. */
131
151
  export declare function joinCallers(input: JoinCallersInput): CallersResult;
132
152
  /** A chain in one line: `Harbor Desk (declared; app harbor-desk-portal) → edge-gateway … → …`. */
@@ -0,0 +1,109 @@
1
+ import type { Fact, FactOf } from "./schema/facts.js";
2
+ /**
3
+ * A field's place in its payload, built from the facts alone (ADR 0164, addendum of 2026-11-17).
4
+ *
5
+ * A reader writes one field fact per field of each class a payload is made of, each cited on its
6
+ * declaration in the class's own file, by the name the field has there: `depot`, not
7
+ * `receipt.stamps[].depot`. What says where a class sits is the field that holds it: a
8
+ * field whose declared type names the class (`List<Stamp> stamps`). So, per
9
+ * owner and side:
10
+ *
11
+ * - **A class** is the fields cited in one file (the verifier checked each on its line, so the
12
+ * file is the one thing about membership that is not the reader's choice of words). Where one
13
+ * file holds several classes, the fields whose id carries a type's name
14
+ * (`field.stamp.reason`) are that type's.
15
+ * - **A parent** of a class is a field of the same owner and side whose type names it: the
16
+ * fact's `type`, and where that is left out the type the cited line declares for it. A list
17
+ * gives `[]`; a wrapper that only passes its value on (`Optional<X>`, `ResponseEntity<X>`) is
18
+ * no level. A map gives a place nobody can name (its keys are data). A class named inside any
19
+ * other generic type (`Page<Item>`) is placed through that type's own fields when they are on
20
+ * record (`Envelope<Order>` with `T content`), and has no place anyone can name when not.
21
+ * - **A path** is the parent's path, then the field's name; through as many levels as the facts
22
+ * hold, at every place a class is reached from, never round a class that holds itself twice.
23
+ * - **An envelope mapping** (`mappedTo` a field, `transform: envelope …`, ADR 0164 §2) places
24
+ * one field under another, as before; where the field's class is itself held, by type, by a
25
+ * field under that envelope, the type's path is the place (`data.customer.name`).
26
+ * - **A dotted name** (`receipt.depot_token`) is the reader's own path: where it starts with the
27
+ * end of its class's place it is not prefixed again. It places itself only, never its siblings.
28
+ * - **Roots**: every class no field points at that holds another class is a root (a body and
29
+ * an error body, a base class and the class that extends it): its fields are top-level.
30
+ *
31
+ * A field whose place isn't sure carries `unplaced`, the reason in words. Two kinds. A doubt that
32
+ * only says *where* (a class nothing points at beside classes that hold others; classes that
33
+ * only hold each other) matters only to a difference that depends on where: the check ignores
34
+ * it when the other side has that name nowhere, or once. A doubt that `decides` (a map; a
35
+ * generic type whose shape isn't on record; an envelope mapping and a type that name different
36
+ * parents; a dotted name that doesn't fit its class's place; more places than are compared)
37
+ * leaves any difference on the field unconfirmed.
38
+ *
39
+ * Pure: the same fields give the same places whatever order they come in. No file is read.
40
+ */
41
+ type Field = FactOf<"field">;
42
+ /** One place a field has on the wire. */
43
+ export interface FieldPlace {
44
+ /** The path from the payload's root: `receipt.stamps[].depot`. */
45
+ name: string;
46
+ /** The ids of the fields that hold it, from the root down. */
47
+ via: string[];
48
+ /** Why the place isn't sure, in words. */
49
+ unplaced?: string;
50
+ /** The doubt holds whatever the other side has: any difference on the field is unconfirmed. */
51
+ decides?: true;
52
+ /** The place is a second turn round a class that holds itself. */
53
+ again?: true;
54
+ /**
55
+ * The path starts at a class nothing holds that holds others, and nothing on the way is in
56
+ * doubt: built, not just written. `root` is that class (its file).
57
+ */
58
+ sure?: true;
59
+ root?: string;
60
+ }
61
+ /** A class whose place in a payload isn't on record. */
62
+ export interface LooseClass {
63
+ owner: string;
64
+ side: string;
65
+ /** The class as its file names it. */
66
+ class: string;
67
+ file: string;
68
+ /** Its fields' ids. */
69
+ fields: string[];
70
+ why: string;
71
+ }
72
+ /** A class a type names, and how the type holds it. */
73
+ interface TypeRef {
74
+ ident: string;
75
+ /** `inside`: within a generic type that is no list, wrapper or map (`outer`). */
76
+ kind: "one" | "list" | "map" | "inside";
77
+ outer?: string;
78
+ }
79
+ /**
80
+ * The identifiers a type names, each with how it is held: alone, in a list (`List<X>`, `X[]`,
81
+ * `[]X`, `list[X]`, `repeated X`), in a map, or inside another generic type. A qualified name
82
+ * counts by its last part; quoted values (an enum's) are left out.
83
+ */
84
+ export declare function typeRefs(type: string): TypeRef[];
85
+ /**
86
+ * The type the cited line declares for the field, when the fact has none: the line's text is the
87
+ * quote, the field the token that reads as its cited value or its name (`depotToken` for
88
+ * `depot_token`). Java, C#, Kotlin, TypeScript, Python and Go forms; anything else gives nothing.
89
+ */
90
+ export declare function declaredTypeOf(f: Pick<Field, "name" | "type" | "cite">): string | undefined;
91
+ export interface FieldPlaces {
92
+ /** Each field's places, by id; a header's and a field with no class is its own name. */
93
+ of: (f: Field) => FieldPlace[];
94
+ /** The classes whose place isn't on record. */
95
+ loose: () => Omit<LooseClass, "owner" | "side">[];
96
+ }
97
+ /**
98
+ * The places of the fields of one owner and side (mapping facts between two payloads and a
99
+ * mapper's dropped end left out by the caller).
100
+ */
101
+ export declare function placeFields(input: readonly Field[], side: string): FieldPlaces;
102
+ /**
103
+ * The classes of a repo's payloads whose place isn't on record (for `atticus verify`): per entry
104
+ * or call and side, each class no field of that payload reaches, with why. The fields are those
105
+ * the contract check compares: a mapping between two payloads (a gateway policy's) and the end
106
+ * of a mapper that doesn't travel are left out, as `checkContracts` leaves them.
107
+ */
108
+ export declare function looseFieldClasses(facts: readonly Fact[]): LooseClass[];
109
+ export {};
@@ -63,11 +63,22 @@ export declare function textShaOf(bytes: Buffer): string;
63
63
  export declare function hashFilesIn(dir: string, rels: readonly string[], o?: {
64
64
  raw?: boolean;
65
65
  signal?: AbortSignal;
66
- }): Promise<FileHash[]>;
66
+ ctime?: boolean;
67
+ }): Promise<(FileHash & {
68
+ ctimeMs?: number;
69
+ ino?: number;
70
+ })[]>;
67
71
  /**
68
72
  * Every named file's size and time (ms, floored), in the order of `rels`; none for one not there.
69
- * With `signal`, a stop ends the read part way and fails the call with CancelledError.
73
+ * With `signal`, a stop ends the read part way and fails the call with CancelledError. With
74
+ * `ctime`, each file's change time too (`ctimeMs`: the last change of its bytes or its times,
75
+ * which no program sets) and its identity (`ino`: the inode, NTFS's file id; 0 where the
76
+ * platform reports none): hash-cache.ts keeps a hash by them.
70
77
  */
71
78
  export declare function statFilesIn(dir: string, rels: readonly string[], o?: {
72
79
  signal?: AbortSignal;
73
- }): Promise<(FileStat | undefined)[]>;
80
+ ctime?: boolean;
81
+ }): Promise<((FileStat & {
82
+ ctimeMs?: number;
83
+ ino?: number;
84
+ }) | undefined)[]>;
package/npm/core/fs.d.ts CHANGED
@@ -21,7 +21,19 @@ export declare function writeFileAtomic(path: string, data: string | Uint8Array,
21
21
  sha: string;
22
22
  writtenAt: number;
23
23
  }) => void;
24
+ /**
25
+ * Only the quick tries when the file is held (`HeldOptions`): a cache's write, which may
26
+ * fail at no cost, never waits the long wait.
27
+ */
28
+ quick?: boolean;
24
29
  }): Promise<void>;
30
+ /**
31
+ * Write a file unless it already holds exactly these bytes: then it is left alone, its time
32
+ * too, and false is returned (beta.28.5: a run that works out a file's content again never
33
+ * replaces the file with itself; on Windows each replacement is a chance to meet a program that
34
+ * holds the file, and a time that moved for nothing makes every reader of it read it again).
35
+ */
36
+ export declare function writeFileIfDiffers(path: string, data: string): Promise<boolean>;
25
37
  /**
26
38
  * Copy a file the way `writeFileAtomic` writes one: to a temporary file beside the target, then
27
39
  * renamed over it. The copy is made by the system (a copy-on-write clone where the file system
@@ -40,7 +52,88 @@ export declare class FileChangedError extends Error {
40
52
  * an editor) is never overwritten: that throws FileChangedError instead.
41
53
  */
42
54
  export declare function writeFileIfUnchanged(path: string, before: string | undefined, data: string): Promise<void>;
43
- export declare function renameRetrying(from: string, to: string, tries?: number): Promise<void>;
55
+ /**
56
+ * How long a write waits on Windows for a file another program holds (beta.28.5): the owner's
57
+ * run over forty repos ended on a raw EPERM after the 5 s there were, a file of the facts folder
58
+ * open in an editor or read by an assistant's session at that moment.
59
+ */
60
+ export declare const HELD_WAIT_MS = 45000;
61
+ /**
62
+ * The wait once a file has stayed held in this process: a cause that doesn't go away (a
63
+ * read-only folder, a program that keeps the folder open) costs the long wait once, not once a
64
+ * file or once a repo of a run over forty.
65
+ */
66
+ export declare const HELD_AGAIN_MS = 5000;
67
+ /**
68
+ * Tests' Windows: a rename and a removal that fail, a wait that takes no time, the platform,
69
+ * where the line that says a write is waiting goes (standard error by default), and the
70
+ * temporary file's removal.
71
+ */
72
+ export declare const fsHooks: {
73
+ rename?: (from: string, to: string) => Promise<void>;
74
+ /** `removeHeld`'s removal. */
75
+ remove?: (path: string) => Promise<void>;
76
+ sleep?: (ms: number) => Promise<void>;
77
+ platform?: NodeJS.Platform;
78
+ say?: (line: string) => void;
79
+ /** The removal of a failed write's temporary file. */
80
+ rm?: (path: string) => Promise<void>;
81
+ };
82
+ /**
83
+ * A file stayed held by another program (Windows: open in an editor, read by an assistant's
84
+ * session, scanned) for the whole wait: nothing was written, the file is as it was, and the
85
+ * temporary file is removed. A run over several repos reports the repo and goes on.
86
+ */
87
+ export declare class FileHeldError extends Error {
88
+ readonly path: string;
89
+ readonly waitedMs: number;
90
+ readonly cause?: unknown | undefined;
91
+ readonly code = "ATTICUS_FILE_HELD";
92
+ constructor(path: string, waitedMs: number, cause?: unknown | undefined);
93
+ }
94
+ /**
95
+ * Whether an error is the file system's (a file held, no room, no permission, too many open
96
+ * files: Node's system errors, which name the call that failed) rather than a bug. A run over
97
+ * several repos says such a repo is not applied and goes on; any other error is thrown on.
98
+ */
99
+ export declare function isFileSystemError(e: unknown): boolean;
100
+ /** Tests: forget that a file stayed held. */
101
+ export declare function forgetHeld(): void;
102
+ /**
103
+ * The signal that ends a wait for a held file besides the job's own (`currentSignal`): a
104
+ * command run in a terminal sets its Ctrl+C here, and clears it when it ends.
105
+ */
106
+ export declare function setHeldWaitSignal(signal: AbortSignal | undefined): void;
107
+ /** How a held file is waited for. */
108
+ export interface HeldOptions {
109
+ /**
110
+ * Only the quick tries (about 5 s), then the system's error, as before beta.28.5: a cache's
111
+ * write, which may fail at no cost, and a folder's rename.
112
+ */
113
+ quick?: boolean;
114
+ /** Ends the wait too (CancelledError), besides the job's Stop and the terminal's Ctrl+C. */
115
+ signal?: AbortSignal;
116
+ /** The quick tries (9: about 5 s). */
117
+ tries?: number;
118
+ }
119
+ /**
120
+ * Remove the temporary files an earlier run left in `dir` for the files whose names start with
121
+ * `prefix` (a write whose temporary file could not be removed, or a process that was killed):
122
+ * those older than an hour, so a write in progress in another process is never touched. Says
123
+ * which it removed; a folder that can't be listed or a file that can't be removed is no error.
124
+ */
125
+ export declare function sweepStaleTmp(dir: string, prefix: string): Promise<string[]>;
126
+ /**
127
+ * Rename, waiting for a held target as `retryHeld` says. The third argument is the options, or
128
+ * the number of quick tries (as before beta.28.5).
129
+ */
130
+ export declare function renameRetrying(from: string, to: string, o?: HeldOptions | number): Promise<void>;
131
+ /**
132
+ * Remove a file, waiting for one another program holds as a write waits (beta.28.5, the
133
+ * review: a plain `rm` of a held file threw the system's EPERM and ended a run over forty
134
+ * repos, as the rename had). A file that isn't there is no error.
135
+ */
136
+ export declare function removeHeld(path: string, o?: HeldOptions): Promise<void>;
44
137
  export interface LockInfo {
45
138
  pid: number;
46
139
  host: string;