ezship 0.1.16 → 0.1.17

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/session.d.mts CHANGED
@@ -1,9 +1,8 @@
1
- // Hand-written declarations for cli/session.mjs: Session State (docs/adr/0088).
1
+ // Hand-written declarations for cli/session.mjs: Session State (docs/adr/0214).
2
2
  import type { Shape } from "./shape.d.mts";
3
3
 
4
4
  export const SESSION_FILE: "session.ts";
5
- export const SESSION_PATH: "/_ez/session";
6
- export const SESSION_VERSION_KEY: "~session";
5
+ export { SESSION_PATH, SESSION_VERSION_KEY } from "./paths.d.mts";
7
6
  export const SESSION_LIMITS: Readonly<{ keys: number; valueBytes: number }>;
8
7
 
9
8
  /** `saved` survives sign-out and devices; `signedIn` ends with the sign-in. */
package/session.mjs CHANGED
@@ -1,4 +1,4 @@
1
- // Session State (docs/adr/0088): typed per-viewer values an Instance declares in `global/session.ts`. The
1
+ // Session State (docs/adr/0214): typed per-viewer values an Instance declares in `global/session.ts`. The
2
2
  // file is TypeScript the Pipeline compiles, but its `Saved` and `SignedIn` types are written in the JSON TYPE
3
3
  // subset (shape.mjs), so the Host can read them without a compiler and check every write. Pure and
4
4
  // zero-dependency, like the rest of the contract.
@@ -9,10 +9,8 @@ import { parseShape, shapeError } from "./shape.mjs";
9
9
 
10
10
  /** The Global Workspace file that declares Provided values and Session State. */
11
11
  export const SESSION_FILE = "session.ts";
12
- /** Where a page reads (GET) and writes (PUT `/<key>`) its viewer's Session State, under the Site's prefix. */
13
- export const SESSION_PATH = "/_ez/session";
14
- /** The viewer's own counter in the live version map (docs/adr/0053); no Table can have this name. */
15
- export const SESSION_VERSION_KEY = "~session";
12
+ // The page's path and the viewer's counter in the live version map are in paths.mjs (docs/adr/0216).
13
+ export { SESSION_PATH, SESSION_VERSION_KEY } from "./paths.mjs";
16
14
  /** At most this many keys per Instance, each value at most this many bytes of JSON. */
17
15
  export const SESSION_LIMITS = Object.freeze({ keys: 32, valueBytes: 4096 });
18
16
 
package/shape.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- // Hand-written declarations for cli/shape.mjs: a JSON column's declared TYPE (docs/adr/0078).
1
+ // Hand-written declarations for cli/shape.mjs: a JSON column's declared TYPE (docs/adr/0236).
2
2
 
3
3
  export type Shape =
4
4
  | { kind: "string" | "number" | "boolean" | "null" | "unknown" | "date" | "epoch" | "cents" }
@@ -8,7 +8,7 @@ export type Shape =
8
8
  | { kind: "union"; of: Shape[] };
9
9
 
10
10
  export function isCalendarDate(value: unknown): value is string;
11
- /** `maxLength` defaults to a column's 2,000 characters; Session State (ADR 0088) declares a whole object. */
11
+ /** `maxLength` defaults to a column's 2,000 characters; Session State (ADR 0214) declares a whole object. */
12
12
  export function parseShape(text: string, maxLength?: number): { shape: Shape } | { error: string };
13
13
  export function printShape(shape: Shape): string;
14
14
  export function shapeError(shape: Shape, value: unknown, path: string): string | null;
package/shape.mjs CHANGED
@@ -1,4 +1,4 @@
1
- // A JSON column's declared shape (docs/adr/0078): `<col> JSON TYPE '<shape>'` in db/schema.sql, written in a
1
+ // A JSON column's declared shape (docs/adr/0236): `<col> JSON TYPE '<shape>'` in db/schema.sql, written in a
2
2
  // small TypeScript subset. The same parse gives the generated TypeScript type and the validator every page and
3
3
  // function write passes through. Pure and zero-dependency, like the rest of the contract.
4
4
  //
package/signup.mjs CHANGED
@@ -1,11 +1,11 @@
1
- /** The public bootstrap exception (ADRs 0062, 0064). Provisioning has one destination: the trial Host. */
1
+ /** The public bootstrap exception (ADR 0245). Provisioning has one destination: the trial Host. */
2
2
  export const TRIAL_HOST = "https://api.ezship.dev";
3
3
  export const TRIAL_STATUS_PATH = "/api/trial";
4
4
  export const SIGNUP_ROUTES = Object.freeze({
5
5
  start: "/cli/signup/start",
6
6
  complete: "/cli/signup/complete",
7
7
  });
8
- /** ADR 0064: the verification email's Studio button opens `<studio>/#signup=<link>`. */
8
+ /** ADR 0245: the verification email's Studio button opens `<studio>/#signup=<link>`. */
9
9
  export const SIGNUP_LINK_RE = /^[A-Za-z0-9]{43}$/;
10
10
 
11
11
  /**
package/types.d.mts CHANGED
@@ -6,7 +6,7 @@
6
6
  export type { Conflict, Declaration, LiveSchema, Plan, PlanSummary, Table } from "./schema.d.mts";
7
7
 
8
8
  /**
9
- * A Builder's role in one Instance (docs/adr/0025). `limited` edits and deploys Sites and invites Members;
9
+ * A Builder's role in one Instance (docs/adr/0202). `limited` edits and deploys Sites and invites Members;
10
10
  * `builder` additionally pushes the Global Workspace and creates Sites; `admin` additionally archives and
11
11
  * restricts Sites, manages Builders and roles, and changes the Instance's settings and assets.
12
12
  */
@@ -17,15 +17,15 @@ export type Version = {
17
17
  n: number;
18
18
  by: string | null;
19
19
  at: number | null;
20
- /** The Push's message (docs/adr/0093), where the Version comes from a retained Version: versions, pull --version, push. */
20
+ /** The Push's message (docs/adr/0211), where the Version comes from a retained Version: versions, pull --version, push. */
21
21
  message?: string | null;
22
- /** `ez versions` of a Site (docs/adr/0141): when a deploy last shipped this Version, null when none has. */
22
+ /** `ez versions` of a Site (docs/adr/0211): when a deploy last shipped this Version, null when none has. */
23
23
  deployedAt?: number | null;
24
24
  /** `ez versions` of a Site: this is the Version the Site's latest deploy shipped, what Members see now. */
25
25
  live?: boolean;
26
26
  };
27
27
 
28
- /** Credential-free Instance connection information, served at /.well-known/ezship (ADR 0026). */
28
+ /** Credential-free Instance connection information, served at /.well-known/ezship (ADR 0202). */
29
29
  export type InstanceDiscovery = {
30
30
  version: 1;
31
31
  uid: string;
@@ -38,9 +38,9 @@ export type InstanceDiscovery = {
38
38
  /** Email-verified, demo-Host-only bootstrap; never a general lifecycle API. */
39
39
  export type SignupInput = { email: string; name: string; source: "cli" | "plugin" | "web" };
40
40
  export type SignupChallenge = { receipt: string; expiresAt: number };
41
- /** `studio` is the trial's Studio address; the verification email's button opens it signed in (ADR 0064). */
41
+ /** `studio` is the trial's Studio address; the verification email's button opens it signed in (ADR 0245). */
42
42
  export type SignupResult = { connection: InstanceDiscovery; token: string; studio: string };
43
- /** Credential-free facts about an active signup trial on its own API origin (ADR 0063). */
43
+ /** Credential-free facts about an active signup trial on its own API origin (ADR 0245). */
44
44
  export type SignupTrialStatus = { uid: string; instance: string; expiresAt: number };
45
45
 
46
46
  /** An Instance's settings (the `instances` row). One Instance == one customer == the unit of tenancy. */
@@ -83,14 +83,14 @@ export type WorkspaceInfo = Site & {
83
83
  appUrl: string | null;
84
84
  role: BuilderRole;
85
85
  /**
86
- * The Global Workspace's Version the Site's latest deploy compiled in (docs/adr/0141; 0 when Global was never
87
- * pushed then), null when the Site has no recorded deploy. Absent from a Host older than the field.
86
+ * The Global Workspace's Version the Site's latest deploy compiled in (docs/adr/0211; 0 when Global was never
87
+ * pushed then), null when the Site has no recorded deploy.
88
88
  */
89
- deployedGlobal?: number | null;
89
+ deployedGlobal: number | null;
90
90
  };
91
91
 
92
92
  /**
93
- * What a Site's next deploy brings in from the Global Workspace (`ez status`, docs/adr/0141): the Version its
93
+ * What a Site's next deploy brings in from the Global Workspace (`ez status`, docs/adr/0211): the Version its
94
94
  * live app was built with, the newest pushed one, and the files changed between them that reach an app only at
95
95
  * a deploy (`pinnedGlobalPath`). `paths` is null when the live one is no longer retained.
96
96
  */
@@ -101,7 +101,7 @@ export type GlobalSinceDeploy = {
101
101
  };
102
102
 
103
103
  /**
104
- * What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/0096), which took
104
+ * What a push did (Workspace.pushAll). A Global push also lists its Live changes (docs/adr/0224), which took
105
105
  * effect for every deployed Site at once; everything else reaches a Site at its next Preview or Deploy.
106
106
  */
107
107
  export type PushResult = {
@@ -109,16 +109,16 @@ export type PushResult = {
109
109
  written: string[];
110
110
  deleted: string[];
111
111
  live?: LiveChange[];
112
- /** What changed access rules do to Members' rows (docs/adr/0098); present when a READ or WRITE changed. */
112
+ /** What changed access rules do to Members' rows (docs/adr/0225); present when a READ or WRITE changed. */
113
113
  report?: AccessReport[];
114
- /** What the pushed guards would have done to the last 7 days of writes (docs/adr/0099). */
114
+ /** What the pushed guards would have done to the last 7 days of writes (docs/adr/0226). */
115
115
  rulesReport?: RulesReport[];
116
116
  /** `ez global push --dry-run`: checked and reported, nothing saved; `version` is the current one. */
117
117
  dryRun?: true;
118
118
  };
119
119
 
120
120
  /**
121
- * One guard's replay (docs/adr/0099): of `replayed` recent writes to `table`, how many it would have
121
+ * One guard's replay (docs/adr/0226): of `replayed` recent writes to `table`, how many it would have
122
122
  * refused, by whom (History actor ids), with a few of its messages.
123
123
  */
124
124
  export type RulesReport = {
@@ -130,7 +130,7 @@ export type RulesReport = {
130
130
  };
131
131
 
132
132
  /**
133
- * One changed rule's effect (docs/adr/0098): per Member, how many rows they may read (or write) after the
133
+ * One changed rule's effect (docs/adr/0225): per Member, how many rows they may read (or write) after the
134
134
  * Push, and how many they gain and lose. Only Members whose rows change are listed; `sampled` of the
135
135
  * Instance's `total` active Members were compared (at most 200).
136
136
  */
@@ -143,7 +143,7 @@ export type AccessReport = {
143
143
  };
144
144
 
145
145
  /**
146
- * One Live change of a Global push (docs/adr/0096). A default (docs/adr/0097) is printed as declared, null
146
+ * One Live change of a Global push (docs/adr/0224). A default (docs/adr/0224) is printed as declared, null
147
147
  * for none; `nulls` counts the existing rows a new default does not fill.
148
148
  */
149
149
  export type LiveChange =
@@ -157,18 +157,18 @@ export type LiveChange =
157
157
  }
158
158
  | { kind: "access"; table: string; op: "read" | "write"; from: string; to: string }
159
159
  | { kind: "scope"; from: string | null; to: string | null }
160
- /** The GROUP statements (docs/adr/0101), normalized; null for none. */
160
+ /** The GROUP statements (docs/adr/0225), normalized; null for none. */
161
161
  | { kind: "groups"; from: string | null; to: string | null }
162
- /** Table rules (docs/adr/0099): the Tables whose rules this Push compiled, empty when it removed them all. */
162
+ /** Table rules (docs/adr/0226): the Tables whose rules this Push compiled, empty when it removed them all. */
163
163
  | { kind: "rules"; tables: string[] }
164
- /** Workflows (docs/adr/0103): the Tables whose workflow this Push added, changed or removed. */
164
+ /** Workflows (docs/adr/0227): the Tables whose workflow this Push added, changed or removed. */
165
165
  | { kind: "workflows"; tables: string[] }
166
- /** Schedules (ADR 0136): the schedules.json entries this Push added, changed or removed. */
166
+ /** Schedules (ADR 0230): the schedules.json entries this Push added, changed or removed. */
167
167
  | { kind: "schedules"; names: string[] }
168
- /** Jobs (ADR 0136): the jobs/ files this Push added, changed or removed. */
168
+ /** Jobs (ADR 0230): the jobs/ files this Push added, changed or removed. */
169
169
  | { kind: "jobs"; names: string[] }
170
170
  /**
171
- * An integrity constraint added or removed (docs/adr/0109): SINGLETON, EXACTLY ONE OF (its columns) or
171
+ * An integrity constraint added or removed (docs/adr/0222): SINGLETON, EXACTLY ONE OF (its columns) or
172
172
  * ON DELETE RESTRICT (the referencing column, of `table`).
173
173
  */
174
174
  | IntegrityChange
@@ -182,7 +182,7 @@ export type IntegrityChange = {
182
182
  added: boolean;
183
183
  };
184
184
 
185
- /** What a deploy did (Workspace.deploy), including what it did to the App Database (docs/adr/0007). */
185
+ /** What a deploy did (Workspace.deploy), including what it did to the App Database (docs/adr/0217). */
186
186
  export type DeployResult = {
187
187
  deployedAt: number;
188
188
  files: string[];
@@ -190,11 +190,11 @@ export type DeployResult = {
190
190
  schema: { created: string[]; added: string[]; indexed: string[] };
191
191
  /** The Global Workspace's Version compiled into this deploy (0 when it has never been pushed). */
192
192
  global: number;
193
- /** What deployed but will not work yet, such as an Integration the Instance has not set (ADR 0092). */
193
+ /** What deployed but will not work yet, such as an Integration the Instance has not set (ADR 0231). */
194
194
  warnings?: string[];
195
195
  };
196
196
 
197
- // ---- hosted Previews (docs/adr/0013) ----
197
+ // ---- hosted Previews (docs/adr/0212) ----
198
198
 
199
199
  /** Where a Preview's files came from. */
200
200
  export type PreviewSource = { kind: "upload" } | { kind: "version"; n: number };
@@ -225,7 +225,7 @@ export type PreviewRow = {
225
225
  activeAt: number;
226
226
  };
227
227
  /**
228
- * Another Builder's Preview of this Site, as `ez preview ls --others` lists it (docs/adr/0141): who holds it
228
+ * Another Builder's Preview of this Site, as `ez preview ls --others` lists it (docs/adr/0211): who holds it
229
229
  * and when it was last uploaded to or opened, never its URL or diagnostics, which stay its owner's.
230
230
  */
231
231
  export type OtherPreview = {
@@ -240,13 +240,13 @@ export type OtherPreview = {
240
240
  export type PreviewResult = PreviewRow & { schema: DeployResult["schema"] };
241
241
 
242
242
  /**
243
- * `ez link` (docs/adr/0059): an address that opens the Site's app, or one of the caller's Previews, signed in
243
+ * `ez link` (docs/adr/0203): an address that opens the Site's app, or one of the caller's Previews, signed in
244
244
  * as the caller's own Member identity. The token is in the fragment; it works once, until `expiresAt`.
245
245
  */
246
246
  export type AppLink = { url: string; expiresAt: number };
247
247
 
248
248
  /**
249
- * `ez support` (docs/adr/0080): a Builder's request to the Host's Developers. `site` is the Site the client
249
+ * `ez support` (docs/adr/0208): a Builder's request to the Host's Developers. `site` is the Site the client
250
250
  * was bound to, or null; `diagnostics` are what the Host recorded with it (its build, the client's contract,
251
251
  * the opening request's id); `resolution` is the Developer's note on closing, if any.
252
252
  */
@@ -265,7 +265,7 @@ export type SupportRequest = {
265
265
  };
266
266
 
267
267
  /**
268
- * Integrations (docs/adr/0092, 0094, 0138, 0140): an Instance's named external service. Nobody reads a
268
+ * Integrations (docs/adr/0231, 0252): an Instance's named external service. Nobody reads a
269
269
  * credential back: the wire carries its type, its header or parameter name and its last four characters
270
270
  * (`hint`, empty for a value under 8 characters).
271
271
  */
@@ -274,12 +274,12 @@ export type IntegrationCredentialInfo =
274
274
  | { type: "query"; param: string; hint: string }
275
275
  | { type: "basic"; user: string; hint: string }
276
276
  | IntegrationOAuthInfo;
277
- /** How an OAuth client gets its token (docs/adr/0140, a draft: only the configuration is built). */
277
+ /** How an OAuth client gets its token (docs/adr/0252, a draft: only the configuration is built). */
278
278
  export type OAuthGrant = "client-credentials" | "password" | "authorization-code";
279
279
  /** How the client authenticates at the token endpoint: HTTP Basic, or its id and secret in the form. */
280
280
  export type OAuthClientAuth = "basic" | "post";
281
281
  /**
282
- * Whether the Host holds a grant for a binding. Until ADR 0140's flows are built every OAuth binding is
282
+ * Whether the Host holds a grant for a binding. Until ADR 0231's flows are built every OAuth binding is
283
283
  * `not connected` and its calls are refused `grant`.
284
284
  */
285
285
  export type OAuthStatus = "not connected" | "connected" | "needs-reconnect";
@@ -304,7 +304,7 @@ export type IntegrationOAuthInfo = {
304
304
  connection: Record<string, string>;
305
305
  };
306
306
  /**
307
- * A header or query parameter the Host adds to every request a binding makes (docs/adr/0138). Code can
307
+ * A header or query parameter the Host adds to every request a binding makes (docs/adr/0231). Code can
308
308
  * neither set nor override it. A plain one is shown in full; a secret one only by its hint.
309
309
  */
310
310
  export type IntegrationValueInfo =
@@ -331,7 +331,7 @@ export type Integration = {
331
331
  updatedBy: string;
332
332
  /**
333
333
  * What `ez integration set` or `preview` removed: the secret values of a binding whose origin changed
334
- * (docs/adr/0138). Only on the answer to that command.
334
+ * (docs/adr/0231). Only on the answer to that command.
335
335
  */
336
336
  removedValues?: string[];
337
337
  };
@@ -382,7 +382,7 @@ export type IntegrationPreviewInput =
382
382
  | { origin: string; credential: IntegrationCredential | null }
383
383
  | { production: true }
384
384
  | { none: true };
385
- /** ADR 0092's refusal categories for an Integration call. */
385
+ /** ADR 0231's refusal categories for an Integration call. */
386
386
  export type IntegrationRefusal =
387
387
  | "address"
388
388
  | "origin"
@@ -431,7 +431,7 @@ export type IntegrationTest = { path: string; method?: string; preview?: boolean
431
431
  * A Builder as listed for an Instance (`ez builders`). `role` is their role in *that* Instance; `lastSignInAt`
432
432
  * is null until they first sign in anywhere (an unclaimed invite), and `invitedAt` is when they were last
433
433
  * invited anywhere: together they say whether the invite is still claimable (`inviteStatus` in the contract,
434
- * docs/adr/0025). `protected` marks a PROTECTED_ADMINS address.
434
+ * docs/adr/0202). `protected` marks a PROTECTED_ADMINS address.
435
435
  */
436
436
  export type BuilderRow = {
437
437
  id: string;
@@ -454,7 +454,7 @@ export type MemberRow = {
454
454
  memberSince: number;
455
455
  lastSignInAt: number | null;
456
456
  invitedAt: number | null;
457
- /** The Member's groups on the roster (docs/adr/0098), sorted. */
457
+ /** The Member's groups on the roster (docs/adr/0225), sorted. */
458
458
  groups: string[];
459
459
  };
460
460
 
@@ -462,7 +462,7 @@ export type MemberRow = {
462
462
  export type PersonRow = { id: string; email: string; name: string | null };
463
463
 
464
464
  /** Who may open a Site (`ez site access`): the restricted flag and both allow-lists (empty when unrestricted). */
465
- /** Who may open a Restricted Site: its Builders, its Members, and the Members of its groups (docs/adr/0101). */
465
+ /** Who may open a Restricted Site: its Builders, its Members, and the Members of its groups (docs/adr/0225). */
466
466
  export type SiteAccess = {
467
467
  restricted: boolean;
468
468
  builders: PersonRow[];
@@ -510,22 +510,22 @@ export type Me = {
510
510
  /** One entry per Table in the Instance's App Database (`ez db tables`). */
511
511
  export type TableInfo = {
512
512
  name: string;
513
- /** column -> description as declared ("TEXT NOT NULL REFERENCES people"), or the storage type if nobody declares it */
513
+ /** column -> description as declared ("TEXT REFERENCES people"), or the storage type if nobody declares it */
514
514
  columns: Record<string, string>;
515
515
  indexes: string[][];
516
- /** the unique indexes' column lists (docs/adr/0046); a sequence column has one */
517
- unique?: string[][];
516
+ /** the unique indexes' column lists (docs/adr/0217); a sequence column has one */
517
+ unique: string[][];
518
518
  rows: number;
519
519
  /** the Sites of this Instance whose Declaration includes this table */
520
520
  sites: string[];
521
- /** the Table this is the History of (docs/adr/0040), or null for a Table */
521
+ /** the Table this is the History of (docs/adr/0218), or null for a Table */
522
522
  history: string | null;
523
523
  };
524
524
  /** `ez db sql`: rows for a read (capped, `truncated` says so), changed-row count for a write. */
525
525
  export type SqlResult =
526
526
  | { rows: Record<string, unknown>[]; truncated: boolean }
527
527
  | { changed: number };
528
- /** `ez db redact` (docs/adr/0106): declared columns of a Table to blank in its rows and their History. */
528
+ /** `ez db redact` (docs/adr/0218): declared columns of a Table to blank in its rows and their History. */
529
529
  export type RedactInput = {
530
530
  table: string;
531
531
  columns: string[];
@@ -538,7 +538,7 @@ export type RedactInput = {
538
538
  /** Current rows changed, and History rows blanked. */
539
539
  export type RedactResult = { changed: number; history: number };
540
540
 
541
- /** An Instance asset (`ez asset ls`, docs/adr/0014): a name, an immutable object, a frozen URL. */
541
+ /** An Instance asset (`ez asset ls`, docs/adr/0213): a name, an immutable object, a frozen URL. */
542
542
  export type AssetRow = {
543
543
  id: string;
544
544
  name: string;
@@ -551,7 +551,7 @@ export type AssetRow = {
551
551
  url: string;
552
552
  };
553
553
  /**
554
- * An App Attachment (docs/adr/0047): a file on one FILE column of one row. `row` is null until a row write
554
+ * An App Attachment (docs/adr/0221): a file on one FILE column of one row. `row` is null until a row write
555
555
  * binds it. `url` is Site-relative: `_ez/attachments/<id>` under any Site's prefix.
556
556
  */
557
557
  export type AttachmentRow = {
@@ -585,7 +585,7 @@ export type UploadTicket = {
585
585
  upload: { method: "PUT"; url: string; headers: Record<string, string> };
586
586
  };
587
587
 
588
- // ---- the Builder's wire (docs/adr/0012) ----
588
+ // ---- the Builder's wire (docs/adr/0209) ----
589
589
 
590
590
  import type { Diagnostic } from "./commands.d.mts";
591
591
  export type { Diagnostic };
@@ -594,13 +594,13 @@ export type { Diagnostic };
594
594
  export type BuildInput = {
595
595
  files: Record<string, string>;
596
596
  global?: Record<string, string>;
597
- /** `types` stops after the Rules and the type check: a Global check's look at each Site (docs/adr/0078).
598
- * `format` formats the `.ts`/`.tsx` files and answers only the changed ones as `files` (docs/adr/0089).
597
+ /** `types` stops after the Rules and the type check: a Global check's look at each Site (docs/adr/0236).
598
+ * `format` formats the `.ts`/`.tsx` files and answers only the changed ones as `files` (docs/adr/0237).
599
599
  * `rules` checks a Global Working Copy with `files` as a stand-in Site and answers its Table rules
600
- * artifact (docs/adr/0099) as `files[RULES_ARTIFACT]`. */
600
+ * artifact (docs/adr/0226) as `files[RULES_ARTIFACT]`. */
601
601
  mode: "check" | "build" | "types" | "format" | "rules";
602
602
  title?: string;
603
- /** A Preview build: stamps source locations for the Studio's inspector (docs/adr/0068). */
603
+ /** A Preview build: stamps source locations for the Studio's inspector (docs/adr/0212). */
604
604
  preview?: boolean;
605
605
  };
606
606
  export type BuildManifest = { entry: "index.html"; files: string[] };
@@ -609,20 +609,20 @@ export type FunctionArtifact = {
609
609
  id: string;
610
610
  names: string[];
611
611
  /**
612
- * The functions whose options say `{ api: true }` (docs/adr/0119): the only ones an API Key may call. The
612
+ * The functions whose options say `{ api: true }` (docs/adr/0232): the only ones an API Key may call. The
613
613
  * artifact's `__api` entry describes their inputs.
614
614
  */
615
615
  api?: string[];
616
616
  /**
617
- * Scheduled jobs (ADRs 0076, 0136), reached only by a run: an invocation whose context carries `run`. Only
617
+ * Scheduled jobs (ADR 0230), reached only by a run: an invocation whose context carries `run`. Only
618
618
  * the Instance's job artifact, compiled at Global Push, has them.
619
619
  */
620
620
  jobs?: string[];
621
621
  /**
622
- * The Integration names each entry's code can reach (ADR 0092), following its imports of sibling
622
+ * The Integration names each entry's code can reach (ADR 0231), following its imports of sibling
623
623
  * functions; the Host refuses any other name, and Deploy and Preview check the Integrations' Sites.
624
624
  */
625
- /** Listeners (docs/adr/0092), reached only by an event: an invocation whose context carries `event`. */
625
+ /** Listeners (docs/adr/0231), reached only by an event: an invocation whose context carries `event`. */
626
626
  listeners?: string[];
627
627
  integrations?: {
628
628
  functions: Record<string, string[]>;
@@ -631,14 +631,14 @@ export type FunctionArtifact = {
631
631
  };
632
632
  code: string;
633
633
  /**
634
- * A rules artifact's (docs/adr/0099, 0103) code per name: a Table's rules or `workflow:<table>`, so a call
634
+ * A rules artifact's (docs/adr/0226, 0227) code per name: a Table's rules or `workflow:<table>`, so a call
635
635
  * evaluates that alone. `code` holds them all, and answers any name without a part.
636
636
  */
637
637
  parts?: Record<string, string>;
638
638
  };
639
639
  export type FunctionResult = { result: unknown; artifact: string };
640
640
  /**
641
- * One listeners.json entry (docs/adr/0092): `listeners/<name>.ts`, its events' source and how a delivery is
641
+ * One listeners.json entry (docs/adr/0231): `listeners/<name>.ts`, its events' source and how a delivery is
642
642
  * verified. `header` and `idHeader` are the `token` scheme's.
643
643
  */
644
644
  export type ListenerEntry = {
@@ -683,7 +683,7 @@ export type ListenerEvent = {
683
683
  body?: string;
684
684
  };
685
685
  /**
686
- * An API Key as `ez key list` shows it (docs/adr/0119, docs/adr/0151): never the key, only its first characters.
686
+ * An API Key as `ez key list` shows it (docs/adr/0232): never the key, only its first characters.
687
687
  * `actor` is what History records its writes as; `sites` is whose `{ api: true }` functions it may call.
688
688
  */
689
689
  export type ApiKey = {
@@ -707,7 +707,7 @@ export type ApiKeyInput = {
707
707
  };
708
708
  /** A new API Key: `key` is shown this once and never stored. `url` is the Data API's door. */
709
709
  export type CreatedApiKey = { apiKey: ApiKey; key: string; url: string };
710
- /** One global/schedules.json entry (ADRs 0076, 0136): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
710
+ /** One global/schedules.json entry (ADR 0230): run `global/jobs/<job>.ts` with `input` on a UTC `cron`. */
711
711
  export type ScheduleEntry = {
712
712
  name: string;
713
713
  cron: string;
@@ -715,8 +715,8 @@ export type ScheduleEntry = {
715
715
  input: Record<string, unknown>;
716
716
  };
717
717
  /**
718
- * One of the Instance's schedules (ADRs 0076, 0136): its entry, when it last changed or was resumed, its next
719
- * due time by its cron, its latest run, and when and by whom it was paused, or null (ADR 0120).
718
+ * One of the Instance's schedules (ADR 0230): its entry, when it last changed or was resumed, its next
719
+ * due time by its cron, its latest run, and when and by whom it was paused, or null (ADR 0230).
720
720
  */
721
721
  export type Schedule = ScheduleEntry & {
722
722
  since: number;
@@ -724,7 +724,7 @@ export type Schedule = ScheduleEntry & {
724
724
  last: ScheduleRun | null;
725
725
  paused: { at: number; by: string } | null;
726
726
  };
727
- /** What a scheduled job's context carries as `run` (ADR 0076); `due` is ISO, UTC. */
727
+ /** What a scheduled job's context carries as `run` (ADR 0230); `due` is ISO, UTC. */
728
728
  export type JobRun = { schedule: string; due: string; trigger: "schedule" | "manual" };
729
729
  /** One run of a schedule: `due` and the times are ms since the epoch. */
730
730
  export type ScheduleRun = {
@@ -738,16 +738,16 @@ export type ScheduleRun = {
738
738
  finishedAt: number | null;
739
739
  };
740
740
  /**
741
- * What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0048); absent in a browser. `call` runs
741
+ * What ezship Desktop's preload exposes as `window.ezDesktop` (ADR 0235); absent in a browser. `call` runs
742
742
  * one local function of the Site under `prefix` from the artifact with that build id and answers its result.
743
743
  */
744
- /** What the Desktop hands a local function (ADR 0048): the Member, the Site and this computer's folder for it. */
744
+ /** What the Desktop hands a local function (ADR 0235): the Member, the Site and this computer's folder for it. */
745
745
  export type LocalContext = {
746
746
  user: Readonly<{ id: string; email: string; name: string | null }>;
747
747
  site: Readonly<{ instance: string; id: string; prefix: string }>;
748
748
  desktop: Readonly<{ version: string; dataDir: string }>;
749
749
  };
750
- /** One published Desktop release file (ADR 0048), as the operator API lists it. */
750
+ /** One published Desktop release file (ADR 0235), as the operator API lists it. */
751
751
  export type DesktopFile = {
752
752
  filename: string;
753
753
  contentType: string;
@@ -758,7 +758,7 @@ export type DesktopBridge = {
758
758
  version: string;
759
759
  call(prefix: string, artifact: string, name: string, input: unknown): Promise<unknown>;
760
760
  };
761
- /** Private build output (docs/adr/0105): every Global Document of the build's snapshot, compiled for QuickJS. */
761
+ /** Private build output (docs/adr/0233): every Global Document of the build's snapshot, compiled for QuickJS. */
762
762
  export type DocumentArtifact = { id: string; names: string[]; code: string };
763
763
  /** One element of a rendered Document, as the template stage returns it and the renderer reads it. */
764
764
  export type DocumentNode = { t: string; p: Record<string, unknown>; c: (DocumentNode | string)[] };
@@ -775,7 +775,7 @@ export type RenderRequest = RenderOptions & {
775
775
  preview?: string;
776
776
  files?: Record<string, string>;
777
777
  };
778
- /** A Render (docs/adr/0105). `file` is its Document File's id once ready; `url` its app-host path. */
778
+ /** A Render (docs/adr/0233). `file` is its Document File's id once ready; `url` its app-host path. */
779
779
  export type RenderRow = {
780
780
  id: string;
781
781
  site: string;
@@ -793,7 +793,7 @@ export type RenderRow = {
793
793
  finishedAt: number | null;
794
794
  };
795
795
  /**
796
- * An Email (docs/adr/0149): `queued` until the runner hands it on, `sending` while it does; `sent` (the mail
796
+ * An Email (docs/adr/0234): `queued` until the runner hands it on, `sending` while it does; `sent` (the mail
797
797
  * service accepted it) and `logged` (a Host whose transport is the log) are delivered; `failed` was refused or
798
798
  * never delivered within a day; `uncertain` was handed on but its answer was lost, and is never retried;
799
799
  * `dropped` was never sent, `reason` says why.
@@ -840,11 +840,11 @@ export type BuildResult =
840
840
  ok: true;
841
841
  manifest: BuildManifest;
842
842
  files: Record<string, string>;
843
- /** Warnings (severity 2) the build passed with (docs/adr/0078); absent from older Builders. */
843
+ /** Warnings (severity 2) the build passed with (docs/adr/0236); present only when there are some. */
844
844
  warnings?: Diagnostic[];
845
845
  };
846
846
 
847
- /** `ez format` (docs/adr/0089): the files whose text the formatter changed, or why it could not run. */
847
+ /** `ez format` (docs/adr/0237): the files whose text the formatter changed, or why it could not run. */
848
848
  export type FormatResult = { files: Record<string, string>; diagnostics: Diagnostic[] };
849
849
 
850
850
  /** A single-use initial password setup link, returned only to an Admin. */
@@ -863,7 +863,7 @@ export type DataQuery = {
863
863
  order?: string[];
864
864
  limit?: number;
865
865
  offset?: number;
866
- /** false: past the active scope (docs/adr/0098). */
866
+ /** false: past the active scope (docs/adr/0225). */
867
867
  scope?: false;
868
868
  };
869
869
  export type AggregateQuery = {
@@ -884,21 +884,21 @@ export type DataResult<R = Record<string, unknown>> = {
884
884
  version: number;
885
885
  truncated: boolean;
886
886
  /**
887
- * The version of every Table the query read (docs/adr/0102): its own, the ones it included and those its
887
+ * The version of every Table the query read (docs/adr/0219): its own, the ones it included and those its
888
888
  * where went through. A live query reruns when any of them moves.
889
889
  */
890
890
  versions?: Record<string, number>;
891
- /** Some row's reverse include held more children than it brought (docs/adr/0102). */
891
+ /** Some row's reverse include held more children than it brought (docs/adr/0219). */
892
892
  truncatedChildren?: true;
893
893
  };
894
894
  /**
895
- * The viewer's Session State (docs/adr/0088): what `GET <prefix>/_ez/session` answers and the page config
895
+ * The viewer's Session State (docs/adr/0214): what `GET <prefix>/_ez/session` answers and the page config
896
896
  * carries. `values` holds only what the viewer stored and the declaration still accepts; defaults fill the rest.
897
897
  */
898
898
  export type SessionState = { values: Record<string, unknown>; version: number };
899
899
  export type ActorRow = {
900
900
  id: string;
901
- /** Listeners and schedules (docs/adr/0092, 0136) write as `listener:<site>/<name>`, `schedule:<name>`. */
901
+ /** Listeners and schedules (docs/adr/0231, 0230) write as `listener:<site>/<name>`, `schedule:<name>`. */
902
902
  kind: "builder" | "user" | "listener" | "schedule";
903
903
  name: string;
904
904
  email: string;
package/update-check.mjs CHANGED
@@ -1,4 +1,4 @@
1
- // Whether a newer `ez` is on npm (docs/adr/0111): at most one registry request a day, remembered in
1
+ // Whether a newer `ez` is on npm (docs/adr/0206): at most one registry request a day, remembered in
2
2
  // `~/.ez/update-check.json`, and a one-line notice on standard error at most once a day while one is. Nothing
3
3
  // here ever fails a command: an offline machine, a slow registry or an unreadable file mean no notice.
4
4
  // Zero dependencies, Node 20+.
package/workflow.d.mts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { Declaration } from "./schema.d.mts";
2
2
 
3
- /** An action's `from` that lets an insert start with it (docs/adr/0103). */
3
+ /** An action's `from` that lets an insert start with it (docs/adr/0227). */
4
4
  export const WORKFLOW_NEW: "@new";
5
5
  /** An action's `to` that returns the row to the state it had before its current one, from its History. */
6
6
  export const WORKFLOW_PREVIOUS: "@previous";
@@ -44,7 +44,7 @@ export type WorkflowAction = {
44
44
  /** An automatic action's children: child Table -> its column that references this Table. */
45
45
  children?: Record<string, string>;
46
46
  };
47
- /** A Table's workflow (docs/adr/0103) as the Host enforces it, checked at Push. */
47
+ /** A Table's workflow (docs/adr/0227) as the Host enforces it, checked at Push. */
48
48
  export type WorkflowMeta = {
49
49
  column: string;
50
50
  initial: string;
@@ -57,6 +57,12 @@ export function checkWorkflow(
57
57
  raw: unknown,
58
58
  schema: Declaration,
59
59
  ): { workflow: WorkflowMeta } | { error: string };
60
+ /** What a workflow's written names break of the schema and the naming rule, as a Push would say it; null when none. */
61
+ export function checkWorkflowNames(
62
+ table: string,
63
+ shape: WorkflowShape,
64
+ schema: Declaration,
65
+ ): string | null;
60
66
  /** Whether the names a file declares are the ones its compiled form describes. */
61
67
  export function sameNames(shape: WorkflowShape, meta: WorkflowMeta): boolean;
62
68
  /** A name spaced and capitalised: the default label. */