@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 +130 -7
- package/npm/core/cancel.d.ts +7 -0
- package/npm/core/contract-check.d.ts +17 -2
- package/npm/core/declarable-routes.d.ts +52 -0
- package/npm/core/declared-links.d.ts +6 -0
- package/npm/core/facts-callers.d.ts +21 -1
- package/npm/core/field-places.d.ts +109 -0
- package/npm/core/file-pool.d.ts +14 -3
- package/npm/core/fs.d.ts +94 -1
- package/npm/core/glob-plain.d.ts +34 -0
- package/npm/core/hash-cache.d.ts +53 -0
- package/npm/core/index.d.ts +3 -0
- package/npm/core/link-candidates.d.ts +48 -0
- package/npm/core/repo-files.d.ts +6 -0
- package/npm/core/schema/ai.d.ts +2 -2
- package/npm/core/schema/orgpack.d.ts +1 -1
- package/npm/index.js +281 -34
- package/package.json +1 -1
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.
|
|
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>;
|
package/npm/core/cancel.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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 {};
|
package/npm/core/file-pool.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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;
|