Repository navigation
Expand file tree
/
Copy pathclosure-policy.ts
More file actions
86 lines (82 loc) · 5.41 KB
/
Copy pathclosure-policy.ts
File metadata and controls
86 lines (82 loc) · 5.41 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
/**
* What the wire-surface closure is allowed to stop at (#1432, review P1).
*
* The closure walk fails closed: every type name a listed declaration
* references must resolve to a listed declaration, or to an entry here. There
* is no silent skip, because the silent skip WAS the defect — a listed type
* could grow `foo?: ImportedShape` from an unlisted module and stay green.
*
* Two kinds of stop, kept apart because they are different claims:
*
* - an EXTERNAL MODULE is outside this repository, so there is no declaration
* to digest and no way for a change to it to ship in our tarball;
* - a WAIVER is a repo declaration the walk reaches that is genuinely not
* payload — transport plumbing, a local error class, a callback type. Each
* one is a claim someone has to defend in review, which is the point.
*
* A waiver stops the walk. If a waived type later starts carrying payload,
* moving it into `surface.ts` is the fix, not widening this file.
*/
/**
* Module specifiers whose types have no declaration site in this repo. Prefix
* match, so `node:http` covers `node:http2` only if spelled out — keep them
* exact enough to mean something.
*/
const WIRE_EXTERNAL_MODULES: Readonly<Record<string, string>> = {
'node:http': 'Node HTTP request/response objects are the transport, not the payload on it.',
'node:stream': 'Stream plumbing carries bytes; the bytes themselves are digested elsewhere.',
undici: 'HTTP client types belong to the transport library, not to our wire contract.',
};
/**
* Repo declarations the closure reaches that are deliberately not wire
* surface. Key is `<file>#<name>`; the value has to say why a change to it
* cannot change what a skewed peer parses.
*/
export const WIRE_CLOSURE_WAIVERS: Readonly<Record<string, string>> = {
'packages/kernel/src/errors.ts#AppError':
'The local error CLASS. Only its projection onto the wire is contractual, and that projection is DaemonError, which is listed.',
'packages/kernel/src/errors.ts#AppErrorCode':
'Error-code vocabulary is carried as a plain string in DaemonError.code; adding a code cannot change the envelope a peer parses.',
'packages/kernel/src/errors.ts#AppErrorDetails':
'Local detail bag behind AppError; the wire form is DaemonError.details, typed as Record<string, unknown> and listed.',
'src/daemon-client/daemon-client-metadata.ts#DaemonInfo':
'Client-side record of where a daemon is listening (pid, ports, state dir). Never serialized into a request or response.',
'src/daemon/daemon-request.ts#DaemonRequest':
'Server-side narrowing of the listed kernel DaemonRequest; the declaration that fixes the shape is packages/kernel/src/contracts.ts#DaemonRequest.',
'src/daemon/daemon-request.ts#DaemonResponse':
'Re-export alias of the listed kernel DaemonResponse; the shape is fixed by packages/kernel/src/contracts.ts#DaemonResponse.',
'src/daemon/daemon-request.ts#DaemonArtifact':
'Re-export alias of the listed kernel DaemonArtifact; the shape is fixed by packages/kernel/src/contracts.ts#DaemonArtifact.',
'src/remote/upload-stream.ts#UploadStreamProgressOptions':
'Byte-progress callback options for local upload rendering. The bytes counted are digested through the request/response declarations; these options never cross the wire.',
'src/remote/upload-progress.ts#UploadProgressSink':
'A callback for client-local upload progress rendering. Its events never leave the client, unlike the daemon progress stream, whose envelope and events are listed.',
'packages/contracts/src/request-progress.ts#RequestProgressSink':
'A callback type (event) => void. The event it receives is RequestProgressEvent, which is listed; the sink itself never crosses the wire.',
// The CLI flag/option vocabulary embedded in DaemonCommandRequest. This is
// the one waiver pair that stops a large subtree, so it is the one to
// challenge first — the reasoning is ADR 0006's own, not convenience.
//
// These types are the CLI-SIDE projection. They do not cross the boundary as
// typed fields: DaemonRequest carries `input?: Record<string, unknown>` and
// `flags?: Record<string, unknown>`, both listed, and the flag vocabulary
// lands inside those bags as plain keys. ADR 0006 then classifies a new flag
// as additive ("new optional request fields or flags that older daemons can
// ignore or reject with a normal command error"), explicitly NOT a bump. So
// digesting them would fire the gate on every new CLI flag for a change the
// decision says needs no acknowledgment — and a gate that cries wolf gets
// its acks rubber-stamped, which costs more than the coverage buys.
//
// If a flag ever becomes a typed field on DaemonRequest, that changes
// DaemonRequest's own digest, and the right fix is to list the type here
// rather than widen this waiver.
'packages/contracts/src/request-envelope.ts#InternalRequestOptions':
'CLI-side option projection; reaches the peer inside DaemonRequest.input/flags (Record<string, unknown>, both listed), and ADR 0006 calls new flags additive.',
'packages/contracts/src/command-flags.ts#CommandFlags':
'CLI-side flag vocabulary; reaches the peer inside DaemonRequest.flags (Record<string, unknown>, listed), and ADR 0006 calls new flags additive.',
};
export function isExternalWireSpecifier(specifier: string): boolean {
return Object.keys(WIRE_EXTERNAL_MODULES).some(
(prefix) => specifier === prefix || specifier.startsWith(`${prefix}/`),
);
}