@mostra/runtime 0.0.0-stage → 0.1.0

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.
Files changed (114) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +39 -2
  3. package/dist/bin.d.ts +1 -0
  4. package/dist/bin.js +236 -0
  5. package/dist/bin.js.map +1 -0
  6. package/dist/builder/child/main.d.ts +1 -0
  7. package/dist/builder/child/main.js +1408 -0
  8. package/dist/builder/child/main.js.map +1 -0
  9. package/dist/child-xrHmytks.js +49 -0
  10. package/dist/child-xrHmytks.js.map +1 -0
  11. package/dist/deps/child/install.d.ts +1 -0
  12. package/dist/deps/child/install.js +33 -0
  13. package/dist/deps/child/install.js.map +1 -0
  14. package/dist/index.d.ts +221 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +3 -0
  17. package/dist/instance-D7_UVdoN.js +15752 -0
  18. package/dist/instance-D7_UVdoN.js.map +1 -0
  19. package/dist/types-NjNy7gXX.js +57 -0
  20. package/dist/types-NjNy7gXX.js.map +1 -0
  21. package/package.json +87 -3
  22. package/src/actions/index.ts +622 -0
  23. package/src/addressing/index.ts +281 -0
  24. package/src/bin.ts +240 -0
  25. package/src/builder/child/dev.ts +383 -0
  26. package/src/builder/child/fields.ts +363 -0
  27. package/src/builder/child/main.ts +47 -0
  28. package/src/builder/child/plugins.ts +195 -0
  29. package/src/builder/child/scan.ts +459 -0
  30. package/src/builder/child/spa.ts +348 -0
  31. package/src/builder/coverage.ts +72 -0
  32. package/src/builder/index.ts +406 -0
  33. package/src/builder/types.ts +180 -0
  34. package/src/deps/child/install.ts +30 -0
  35. package/src/deps/index.ts +918 -0
  36. package/src/deps/installer.ts +321 -0
  37. package/src/deps/lock.ts +82 -0
  38. package/src/deps/scan.ts +266 -0
  39. package/src/deps/specifier.ts +64 -0
  40. package/src/deps/warm.ts +57 -0
  41. package/src/dev/index.ts +518 -0
  42. package/src/faults.ts +65 -0
  43. package/src/gate.ts +55 -0
  44. package/src/gateway/actions.ts +268 -0
  45. package/src/gateway/browser.ts +650 -0
  46. package/src/gateway/capabilities.ts +739 -0
  47. package/src/gateway/controls.ts +91 -0
  48. package/src/gateway/dev.ts +119 -0
  49. package/src/gateway/http.ts +229 -0
  50. package/src/gateway/index.ts +1209 -0
  51. package/src/gateway/integrity.ts +117 -0
  52. package/src/gateway/listener.ts +217 -0
  53. package/src/gateway/routes.ts +197 -0
  54. package/src/gateway/serve.ts +138 -0
  55. package/src/gc/index.ts +451 -0
  56. package/src/home/acquire.ts +276 -0
  57. package/src/home/index.ts +16 -0
  58. package/src/home/paths.ts +192 -0
  59. package/src/home/platform.ts +34 -0
  60. package/src/home/record.ts +76 -0
  61. package/src/home/settings.ts +113 -0
  62. package/src/index.ts +30 -0
  63. package/src/instance/index.ts +942 -0
  64. package/src/interaction/ephemeral.ts +300 -0
  65. package/src/interaction/events.ts +355 -0
  66. package/src/interaction/fields.ts +392 -0
  67. package/src/interaction/index.ts +1009 -0
  68. package/src/interaction/outbox.ts +493 -0
  69. package/src/interaction/policy.ts +26 -0
  70. package/src/interaction/results.ts +341 -0
  71. package/src/interaction/runs.ts +313 -0
  72. package/src/interaction/signals.ts +120 -0
  73. package/src/interaction/submissions.ts +585 -0
  74. package/src/interaction/subscriptions.ts +258 -0
  75. package/src/interaction/viewers.ts +173 -0
  76. package/src/interaction/wait.ts +201 -0
  77. package/src/ledger/index.ts +442 -0
  78. package/src/ledger/migrations.ts +583 -0
  79. package/src/ledger/requests.ts +105 -0
  80. package/src/ledger/types.ts +28 -0
  81. package/src/live/index.ts +573 -0
  82. package/src/log.ts +316 -0
  83. package/src/processes/child.ts +67 -0
  84. package/src/processes/environment.ts +64 -0
  85. package/src/processes/identity.ts +191 -0
  86. package/src/processes/index.ts +19 -0
  87. package/src/processes/manager.ts +543 -0
  88. package/src/protocol-server/client.ts +94 -0
  89. package/src/protocol-server/index.ts +91 -0
  90. package/src/protocol-server/server.ts +509 -0
  91. package/src/protocol-server/streams.ts +81 -0
  92. package/src/publish/checks.ts +92 -0
  93. package/src/publish/digest.ts +87 -0
  94. package/src/publish/index.ts +23 -0
  95. package/src/publish/manifest.ts +409 -0
  96. package/src/publish/methods.ts +96 -0
  97. package/src/publish/publisher.ts +913 -0
  98. package/src/publish/source.ts +272 -0
  99. package/src/publish/tar.ts +110 -0
  100. package/src/registry/index.ts +481 -0
  101. package/src/registry/store.ts +136 -0
  102. package/src/secrets/index.ts +223 -0
  103. package/src/service/idle.ts +64 -0
  104. package/src/service/index.ts +3 -0
  105. package/src/service/unit.ts +250 -0
  106. package/src/verify/fields.ts +125 -0
  107. package/src/verify/index.ts +913 -0
  108. package/src/verify/regression.ts +157 -0
  109. package/src/verify/runner.ts +230 -0
  110. package/src/verify/sandbox.ts +407 -0
  111. package/src/verify/typecheck.ts +371 -0
  112. package/src/workers/index.ts +17 -0
  113. package/src/workers/launcher.ts +260 -0
  114. package/src/workers/pool.ts +708 -0
@@ -0,0 +1,481 @@
1
+ /**
2
+ * The registry (DATA_MODEL §2, §3): which artifacts and versions exist, which source path each
3
+ * artifact is bound to, and the content-addressed version store on disk. The publish module
4
+ * commits a version through {@link Registry.commit}, one ledger transaction that resolves the
5
+ * artifact's identity, inserts the version, binds the source and appends the events
6
+ * (ARCHITECTURE §3 step 6). `artifact/list` and `artifact/get` read through it.
7
+ */
8
+ import {
9
+ type ArtifactDetail,
10
+ type ArtifactManifest,
11
+ type ArtifactRef,
12
+ type ArtifactSummary,
13
+ createDiagnostic,
14
+ RpcError,
15
+ type SubmissionPolicy,
16
+ type VersionSummary,
17
+ } from "@mostra/protocol";
18
+ import type { Faults } from "../faults.ts";
19
+ import { appendEvent, policyInForce } from "../interaction/index.ts";
20
+ import { type Ledger, type LedgerDb, type RequestKey, recordResult } from "../ledger/index.ts";
21
+ import { openVersionStore, type VersionStore } from "./store.ts";
22
+
23
+ export { fsyncPath, removeTree, type VersionStore } from "./store.ts";
24
+
25
+ interface ArtifactRow {
26
+ id: string;
27
+ title: string;
28
+ family: string | null;
29
+ links_json: string;
30
+ policy_json: string | null;
31
+ policy_chosen_json: string | null;
32
+ created_at: string;
33
+ latest_version_id: string | null;
34
+ }
35
+
36
+ interface VersionRow {
37
+ id: string;
38
+ artifact_id: string;
39
+ number: number;
40
+ source_digest: string;
41
+ env_digest: string;
42
+ output_digest: string;
43
+ manifest_json: string;
44
+ forced_codes_json: string | null;
45
+ published_at: string;
46
+ verify_json?: string | null;
47
+ /** When gc collected its files (D140), from `version_collected`; absent or null otherwise. */
48
+ collected_at?: string | null;
49
+ }
50
+
51
+ /** Version rows with their collection, if any (D140 item 14). */
52
+ const VERSION_ROWS =
53
+ "SELECT version.*, (SELECT collected_at FROM version_collected WHERE version_id = version.id) AS collected_at FROM version";
54
+
55
+ /** A version to commit (ARCHITECTURE §3 step 6). */
56
+ export interface VersionCommit {
57
+ /** The artifact the publish resolved before building. */
58
+ readonly artifactId: string;
59
+ /** The real path of the source (D51). */
60
+ readonly bindingPath: string;
61
+ /** The manifest's `id`, when it has one. */
62
+ readonly manifestId: string | undefined;
63
+ readonly versionId: string;
64
+ readonly sourceDigest: string;
65
+ readonly envDigest: string;
66
+ /** Absent when the version already exists (a reuse). */
67
+ readonly outputDigest: string | undefined;
68
+ readonly manifest: ArtifactManifest;
69
+ /** The policy this publish names; it sticks for later publishes that name none (D102). */
70
+ readonly policy: SubmissionPolicy | undefined;
71
+ /** The home's policy (`HomeConfig.submission`, D102). */
72
+ readonly homePolicy?: SubmissionPolicy | undefined;
73
+ readonly forcedCodes: readonly string[];
74
+ /**
75
+ * What verify found for this version (D138 item 4): `pass` only when its verdict had no error
76
+ * and nothing was forced. Absent when no verify ran (a reuse, a repair).
77
+ */
78
+ readonly verify?: { readonly status: "pass" | "fail"; readonly verifyRevision: string };
79
+ /**
80
+ * Whether `path` still claims `artifactId` in its manifest (D51): a moved source no longer does,
81
+ * a copy still does. Runs inside the transaction, so it must be synchronous.
82
+ */
83
+ readonly stillClaims: (path: string, artifactId: string) => boolean;
84
+ /** Test fault points: `publish:in-commit` runs inside the transaction, before it commits. */
85
+ readonly faults?: Faults;
86
+ /**
87
+ * The publish's `requestId` (H-03): its receipt is recorded in the same transaction, so a retry
88
+ * after any crash replays exactly what the first attempt committed.
89
+ */
90
+ readonly request?: RequestKey | undefined;
91
+ /** Runs inside the transaction, after the version and the binding are written. */
92
+ readonly inTransaction?: (db: LedgerDb) => void;
93
+ }
94
+
95
+ /** What a commit recorded. */
96
+ export interface CommittedVersion {
97
+ readonly version: number;
98
+ /** The cursor of the version's `version.published` event. */
99
+ readonly cursor: string;
100
+ readonly reused: boolean;
101
+ }
102
+
103
+ /** The registry of one home. */
104
+ export interface Registry {
105
+ readonly store: VersionStore;
106
+ /**
107
+ * The artifact a source would publish as, before building (D51): the manifest's `id`, else the
108
+ * artifact its path is bound to, else a new one. {@link Registry.commit} checks it again.
109
+ */
110
+ identityFor(bindingPath: string, manifestId: string | undefined, generate: () => string): string;
111
+ /** The artifact a source path is bound to, if any (D51). */
112
+ artifactAt(bindingPath: string): string | undefined;
113
+ /** The newest version of an artifact whose recorded verdict passed (D138 item 4). */
114
+ passedVersion(artifactId: string): string | undefined;
115
+ /** The version row of `versionId`, if it was committed. */
116
+ hasVersion(versionId: string): boolean;
117
+ /** Commits a version in one ledger transaction. Throws `MOSTRA_PUBLISH_ID_CONFLICT` for a copied ID. */
118
+ commit(input: VersionCommit): CommittedVersion;
119
+ /** The source path an artifact was last published from. */
120
+ sourceOf(artifactId: string): string | undefined;
121
+ /** One committed version: its artifact, number, output digest and manifest (WP-08's workers). */
122
+ version(versionId: string):
123
+ | {
124
+ readonly artifactId: string;
125
+ readonly number: number;
126
+ readonly outputDigest: string;
127
+ readonly manifest: ArtifactManifest;
128
+ /** The error codes `--force` recorded when it was published (D41). */
129
+ readonly forcedCodes: readonly string[];
130
+ /** The verdict it was published on (D138 item 4); absent before verify existed. */
131
+ readonly verify?: { readonly status: "pass" | "fail"; readonly verifyRevision: string };
132
+ }
133
+ | undefined;
134
+ /** Every artifact's latest version, by artifact ID. */
135
+ latestVersions(): ReadonlyMap<string, string>;
136
+ list(filter?: { readonly family?: string }): ArtifactSummary[];
137
+ /** One artifact in full; `MOSTRA_ARTIFACT_NOT_FOUND` when unknown. */
138
+ get(ref: ArtifactRef): ArtifactDetail;
139
+ /** Removes staging, and version directories and snapshots without a ledger row (FAILURE_MODEL §3). */
140
+ recover(): Promise<{ readonly versions: string[]; readonly snapshots: string[] }>;
141
+ }
142
+
143
+ function conflict(message: string): RpcError {
144
+ return new RpcError(createDiagnostic("MOSTRA_PUBLISH_ID_CONFLICT", { message }));
145
+ }
146
+
147
+ function notFound(message: string): RpcError {
148
+ return new RpcError(createDiagnostic("MOSTRA_ARTIFACT_NOT_FOUND", { message }));
149
+ }
150
+
151
+ const versionSummary = (row: VersionRow): VersionSummary => {
152
+ const forced = row.forced_codes_json ? (JSON.parse(row.forced_codes_json) as string[]) : [];
153
+ return {
154
+ id: row.id,
155
+ number: row.number,
156
+ publishedAt: row.published_at,
157
+ sourceDigest: row.source_digest,
158
+ envDigest: row.env_digest,
159
+ outputDigest: row.output_digest,
160
+ ...(forced.length > 0 ? { forcedDiagnostics: forced } : {}),
161
+ ...(row.collected_at ? { collected: row.collected_at } : {}),
162
+ };
163
+ };
164
+
165
+ /** Opens the registry over a home's ledger and version store. */
166
+ export async function openRegistry(options: {
167
+ readonly home: string;
168
+ readonly ledger: Ledger;
169
+ }): Promise<Registry> {
170
+ const { ledger } = options;
171
+ const store = await openVersionStore(options.home);
172
+
173
+ const boundArtifact = (db: LedgerDb, path: string): string | undefined =>
174
+ db.get<{ artifact_id: string }>("SELECT artifact_id FROM source_binding WHERE path = ?", path)
175
+ ?.artifact_id;
176
+
177
+ const summary = (
178
+ db: LedgerDb,
179
+ row: ArtifactRow,
180
+ ): { summary: ArtifactSummary; latest: VersionRow | undefined } => {
181
+ const latest = row.latest_version_id
182
+ ? db.get<VersionRow>(`${VERSION_ROWS} WHERE id = ?`, row.latest_version_id)
183
+ : undefined;
184
+ const manifest = latest ? (JSON.parse(latest.manifest_json) as ArtifactManifest) : undefined;
185
+ const source = db.get<{ path: string }>(
186
+ "SELECT path FROM source_binding WHERE artifact_id = ? ORDER BY bound_at DESC, path LIMIT 1",
187
+ row.id,
188
+ )?.path;
189
+ const result: ArtifactSummary = {
190
+ id: row.id,
191
+ title: row.title,
192
+ ...(manifest?.description !== undefined ? { description: manifest.description } : {}),
193
+ ...(row.family !== null ? { family: row.family } : {}),
194
+ links: JSON.parse(row.links_json) as ArtifactSummary["links"],
195
+ mode: manifest?.mode ?? "spa",
196
+ ...(row.policy_json ? { policy: JSON.parse(row.policy_json) as SubmissionPolicy } : {}),
197
+ ...(source !== undefined ? { source } : {}),
198
+ createdAt: row.created_at,
199
+ ...(latest ? { latestVersion: versionSummary(latest) } : {}),
200
+ };
201
+ return { summary: result, latest };
202
+ };
203
+
204
+ return {
205
+ store,
206
+ identityFor(bindingPath, manifestId, generate) {
207
+ if (manifestId !== undefined) return manifestId;
208
+ return ledger.read((db) => boundArtifact(db, bindingPath)) ?? generate();
209
+ },
210
+ artifactAt(bindingPath) {
211
+ return ledger.read((db) => boundArtifact(db, bindingPath));
212
+ },
213
+ passedVersion(artifactId) {
214
+ return ledger.read(
215
+ (db) =>
216
+ db.get<{ id: string }>(
217
+ "SELECT id FROM version WHERE artifact_id = ? AND json_extract(verify_json, '$.status') = 'pass' ORDER BY number DESC LIMIT 1",
218
+ artifactId,
219
+ )?.id,
220
+ );
221
+ },
222
+ hasVersion(versionId) {
223
+ return ledger.read(
224
+ (db) => db.get("SELECT 1 FROM version WHERE id = ?", versionId) !== undefined,
225
+ );
226
+ },
227
+ commit(input) {
228
+ return ledger.write((db) => {
229
+ const now = new Date().toISOString();
230
+ // Identity (D51): the manifest's id wins; a path bound elsewhere follows it; a moved source
231
+ // rebinds; a copy that still claims the id is a conflict.
232
+ if (input.manifestId !== undefined) {
233
+ const others = db.all<{ path: string }>(
234
+ "SELECT path FROM source_binding WHERE artifact_id = ? AND path != ?",
235
+ input.manifestId,
236
+ input.bindingPath,
237
+ );
238
+ for (const { path } of others) {
239
+ if (input.stillClaims(path, input.manifestId)) {
240
+ throw conflict(
241
+ `${input.bindingPath} and ${path} both claim the artifact ID ${input.manifestId}.`,
242
+ );
243
+ }
244
+ db.run("DELETE FROM source_binding WHERE path = ?", path);
245
+ }
246
+ }
247
+ const resolved =
248
+ input.manifestId ?? boundArtifact(db, input.bindingPath) ?? input.artifactId;
249
+ if (resolved !== input.artifactId) {
250
+ throw new RpcError(
251
+ createDiagnostic("MOSTRA_PUBLISH_SOURCE_CHANGED", {
252
+ message: `The artifact ${input.bindingPath} belongs to changed while it was being published.`,
253
+ }),
254
+ );
255
+ }
256
+
257
+ let artifact = db.get<ArtifactRow>("SELECT * FROM artifact WHERE id = ?", input.artifactId);
258
+ if (!artifact) {
259
+ db.run(
260
+ "INSERT INTO artifact (id, title, family, links_json, policy_json, created_at, latest_version_id) VALUES (?, ?, ?, ?, ?, ?, NULL)",
261
+ input.artifactId,
262
+ input.manifest.title,
263
+ input.manifest.family ?? null,
264
+ JSON.stringify(input.manifest.links ?? []),
265
+ null,
266
+ now,
267
+ );
268
+ appendEvent(db, {
269
+ artifactId: input.artifactId,
270
+ type: "artifact.created",
271
+ payload: { title: input.manifest.title, family: input.manifest.family ?? null },
272
+ });
273
+ artifact = db.get<ArtifactRow>(
274
+ "SELECT * FROM artifact WHERE id = ?",
275
+ input.artifactId,
276
+ ) as ArtifactRow;
277
+ }
278
+
279
+ const existing = db.get<VersionRow>("SELECT * FROM version WHERE id = ?", input.versionId);
280
+ let number: number;
281
+ let cursor: string | undefined;
282
+ if (existing) {
283
+ number = existing.number;
284
+ // Publishing a collected version's exact source restored its files (D140 item 14).
285
+ db.run("DELETE FROM version_collected WHERE version_id = ?", input.versionId);
286
+ if (artifact.latest_version_id === input.versionId) {
287
+ cursor = db
288
+ .get<{ cursor: number }>(
289
+ "SELECT MAX(cursor) AS cursor FROM event WHERE artifact_id = ? AND type = 'version.published' AND json_extract(payload_json, '$.versionId') = ?",
290
+ input.artifactId,
291
+ input.versionId,
292
+ )
293
+ ?.cursor?.toString();
294
+ }
295
+ } else {
296
+ if (input.outputDigest === undefined)
297
+ throw new Error("A new version needs its output digest.");
298
+ number =
299
+ db.get<{ next: number }>(
300
+ "SELECT COALESCE(MAX(number), 0) + 1 AS next FROM version WHERE artifact_id = ?",
301
+ input.artifactId,
302
+ )?.next ?? 1;
303
+ db.run(
304
+ "INSERT INTO version (id, artifact_id, number, source_digest, env_digest, output_digest, manifest_json, forced_codes_json, published_at, verify_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
305
+ input.versionId,
306
+ input.artifactId,
307
+ number,
308
+ input.sourceDigest,
309
+ input.envDigest,
310
+ input.outputDigest,
311
+ JSON.stringify(input.manifest),
312
+ input.forcedCodes.length > 0 ? JSON.stringify(input.forcedCodes) : null,
313
+ now,
314
+ input.verify ? JSON.stringify(input.verify) : null,
315
+ );
316
+ }
317
+ if (cursor === undefined) {
318
+ // A new version, or an earlier one published again: it becomes the latest (D09).
319
+ cursor = appendEvent(db, {
320
+ artifactId: input.artifactId,
321
+ type: "version.published",
322
+ payload: {
323
+ versionId: input.versionId,
324
+ number,
325
+ forcedCodes: [...input.forcedCodes],
326
+ ...(existing ? { republished: true } : {}),
327
+ },
328
+ });
329
+ }
330
+ const manifest = existing
331
+ ? (JSON.parse(existing.manifest_json) as ArtifactManifest)
332
+ : input.manifest;
333
+ // D102: the policy in force, resolved at each publish and stored: this publish's policy, or
334
+ // the one an earlier publish chose, then the home's, then the manifest's request.
335
+ const chosen =
336
+ input.policy ??
337
+ (artifact.policy_chosen_json === null
338
+ ? undefined
339
+ : (JSON.parse(artifact.policy_chosen_json) as SubmissionPolicy));
340
+ const policy = policyInForce(chosen, input.homePolicy, manifest.submission);
341
+ db.run(
342
+ "UPDATE artifact SET title = ?, family = ?, links_json = ?, policy_json = ?, policy_chosen_json = ?, latest_version_id = ? WHERE id = ?",
343
+ manifest.title,
344
+ manifest.family ?? null,
345
+ JSON.stringify(manifest.links ?? []),
346
+ JSON.stringify(policy),
347
+ chosen === undefined ? null : JSON.stringify(chosen),
348
+ input.versionId,
349
+ input.artifactId,
350
+ );
351
+ db.run(
352
+ "INSERT INTO source_binding (path, artifact_id, bound_at) VALUES (?, ?, ?) ON CONFLICT(path) DO UPDATE SET artifact_id = excluded.artifact_id, bound_at = excluded.bound_at",
353
+ input.bindingPath,
354
+ input.artifactId,
355
+ now,
356
+ );
357
+ input.inTransaction?.(db);
358
+ const committed = { version: number, cursor, reused: existing !== undefined };
359
+ if (input.request !== undefined) {
360
+ const receipt = {
361
+ artifactId: input.artifactId,
362
+ versionId: input.versionId,
363
+ ...committed,
364
+ ...(input.forcedCodes.length > 0 ? { forcedDiagnostics: [...input.forcedCodes] } : {}),
365
+ };
366
+ recordResult(db, input.request, receipt);
367
+ }
368
+ input.faults?.at("publish:in-commit");
369
+ return committed;
370
+ });
371
+ },
372
+ version(versionId) {
373
+ return ledger.read((db) => {
374
+ const row = db.get<VersionRow>("SELECT * FROM version WHERE id = ?", versionId);
375
+ return row
376
+ ? {
377
+ artifactId: row.artifact_id,
378
+ number: row.number,
379
+ outputDigest: row.output_digest,
380
+ manifest: JSON.parse(row.manifest_json) as ArtifactManifest,
381
+ forcedCodes: row.forced_codes_json
382
+ ? (JSON.parse(row.forced_codes_json) as string[])
383
+ : [],
384
+ ...(row.verify_json
385
+ ? {
386
+ verify: JSON.parse(row.verify_json) as {
387
+ status: "pass" | "fail";
388
+ verifyRevision: string;
389
+ },
390
+ }
391
+ : {}),
392
+ }
393
+ : undefined;
394
+ });
395
+ },
396
+ latestVersions() {
397
+ return ledger.read(
398
+ (db) =>
399
+ new Map(
400
+ db
401
+ .all<{ id: string; latest_version_id: string }>(
402
+ "SELECT id, latest_version_id FROM artifact WHERE latest_version_id IS NOT NULL",
403
+ )
404
+ .map((row) => [row.id, row.latest_version_id]),
405
+ ),
406
+ );
407
+ },
408
+ sourceOf(artifactId) {
409
+ return ledger.read(
410
+ (db) =>
411
+ db.get<{ path: string }>(
412
+ "SELECT path FROM source_binding WHERE artifact_id = ? ORDER BY bound_at DESC, path LIMIT 1",
413
+ artifactId,
414
+ )?.path,
415
+ );
416
+ },
417
+ list(filter = {}) {
418
+ return ledger.read((db) => {
419
+ const rows = db.all<ArtifactRow & { published_at: string }>(
420
+ `SELECT artifact.*, version.published_at FROM artifact
421
+ JOIN version ON version.id = artifact.latest_version_id
422
+ ${filter.family !== undefined ? "WHERE artifact.family = ?" : ""}
423
+ ORDER BY (SELECT MAX(cursor) FROM event
424
+ WHERE event.artifact_id = artifact.id AND event.type = 'version.published') DESC,
425
+ artifact.id`,
426
+ ...(filter.family !== undefined ? [filter.family] : []),
427
+ );
428
+ return rows.map((row) => summary(db, row).summary);
429
+ });
430
+ },
431
+ get(ref) {
432
+ return ledger.read((db) => {
433
+ const id =
434
+ "artifactId" in ref ? ref.artifactId : (boundArtifact(db, ref.path) ?? undefined);
435
+ const row =
436
+ id === undefined
437
+ ? undefined
438
+ : db.get<ArtifactRow>("SELECT * FROM artifact WHERE id = ?", id);
439
+ if (!row) {
440
+ throw notFound(
441
+ "artifactId" in ref
442
+ ? `No artifact ${ref.artifactId} was published in this home.`
443
+ : `No artifact was published from ${ref.path} in this home.`,
444
+ );
445
+ }
446
+ const { summary: base, latest } = summary(db, row);
447
+ const versions = db
448
+ .all<VersionRow>(`${VERSION_ROWS} WHERE artifact_id = ? ORDER BY number DESC`, row.id)
449
+ .map(versionSummary);
450
+ return {
451
+ ...base,
452
+ manifest: latest
453
+ ? (JSON.parse(latest.manifest_json) as ArtifactManifest)
454
+ : { title: row.title },
455
+ versions,
456
+ };
457
+ });
458
+ },
459
+ async recover() {
460
+ const known = ledger.read((db) => ({
461
+ // A collected version's files are what gc removes; one an interrupted gc left behind goes
462
+ // now (D140 item 14).
463
+ versions: new Set(
464
+ db
465
+ .all<{ id: string }>(
466
+ "SELECT id FROM version WHERE id NOT IN (SELECT version_id FROM version_collected)",
467
+ )
468
+ .map((row) => row.id),
469
+ ),
470
+ snapshots: new Set(
471
+ db
472
+ .all<{ artifact_id: string; source_digest: string }>(
473
+ "SELECT artifact_id, source_digest FROM version WHERE id NOT IN (SELECT version_id FROM version_collected)",
474
+ )
475
+ .map((row) => `${row.artifact_id}/${row.source_digest}.tar.zst`),
476
+ ),
477
+ }));
478
+ return store.sweep(known);
479
+ },
480
+ };
481
+ }
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The content-addressed version store on disk (DATA_MODEL §1, FAILURE_MODEL §3): `versions/<id>/`
3
+ * and `sources/<artifactId>/<sourceDigest>.tar.zst`. A version directory is assembled in staging,
4
+ * made read-only and synced, then renamed into place; it becomes visible only when its ledger row
5
+ * commits, and anything without a row is removed at the next start.
6
+ */
7
+ import { closeSync, fsyncSync, openSync } from "node:fs";
8
+ import { chmod, lstat, mkdir, readdir, rename, rm, stat } from "node:fs/promises";
9
+ import { join } from "node:path";
10
+
11
+ /** Calls `visit` for every entry under `dir`, children before their directory. */
12
+ async function walk(
13
+ dir: string,
14
+ visit: (path: string, isDirectory: boolean) => Promise<void>,
15
+ ): Promise<void> {
16
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
17
+ const path = join(dir, entry.name);
18
+ if (entry.isDirectory()) await walk(path, visit);
19
+ await visit(path, entry.isDirectory());
20
+ }
21
+ }
22
+
23
+ /**
24
+ * Syncs a file or a directory to disk. A file that can't be synced fails the caller (its bytes
25
+ * would not be durable); a directory may not support it on some file systems, and only that
26
+ * case is tolerated (EINVAL, ENOTSUP, EISDIR, EPERM, EACCES on `open`).
27
+ */
28
+ export function fsyncPath(path: string, directory = false): void {
29
+ let fd: number | undefined;
30
+ try {
31
+ fd = openSync(path, "r");
32
+ fsyncSync(fd);
33
+ } catch (error) {
34
+ const code = (error as NodeJS.ErrnoException).code;
35
+ const unsupported = ["EINVAL", "ENOTSUP", "EISDIR", "EPERM", "EACCES"];
36
+ if (!directory || !unsupported.includes(code ?? "")) throw error;
37
+ } finally {
38
+ if (fd !== undefined) closeSync(fd);
39
+ }
40
+ }
41
+
42
+ /**
43
+ * Makes a tree read-only (files 0444, directories 0555) and syncs it to disk. The top directory is
44
+ * left writable when `keepTop` is set: renaming a directory needs write access to it, to update `..`.
45
+ */
46
+ export async function sealTree(dir: string, keepTop = false): Promise<void> {
47
+ await walk(dir, async (path, isDirectory) => {
48
+ await chmod(path, isDirectory ? 0o555 : 0o444);
49
+ fsyncPath(path, isDirectory);
50
+ });
51
+ if (!keepTop) await chmod(dir, 0o555);
52
+ fsyncPath(dir, true);
53
+ }
54
+
55
+ /** Removes a tree, sealed or not. Missing trees are fine. */
56
+ export async function removeTree(dir: string): Promise<void> {
57
+ try {
58
+ const info = await lstat(dir);
59
+ if (info.isDirectory()) {
60
+ await chmod(dir, 0o755);
61
+ await walk(dir, async (path, isDirectory) => {
62
+ if (isDirectory) await chmod(path, 0o755);
63
+ }).catch(() => {});
64
+ }
65
+ } catch {
66
+ return;
67
+ }
68
+ await rm(dir, { recursive: true, force: true });
69
+ }
70
+
71
+ /** The version store of one home. */
72
+ export interface VersionStore {
73
+ readonly versionsDir: string;
74
+ readonly sourcesDir: string;
75
+ /** Where staging directories live (`cache/staging`), on the same file system as `versions/`. */
76
+ readonly stagingDir: string;
77
+ versionDir(versionId: string): string;
78
+ snapshotPath(artifactId: string, sourceDigest: string): string;
79
+ /** Seals `built` and renames it to `versions/<versionId>`, replacing a leftover without a row. */
80
+ promote(built: string, versionId: string): Promise<void>;
81
+ /** Removes staging, and version directories and snapshots no ledger row names. */
82
+ sweep(known: {
83
+ readonly versions: ReadonlySet<string>;
84
+ readonly snapshots: ReadonlySet<string>;
85
+ }): Promise<{ readonly versions: string[]; readonly snapshots: string[] }>;
86
+ }
87
+
88
+ /** Opens the version store of the home at `home`, creating its directories. */
89
+ export async function openVersionStore(home: string): Promise<VersionStore> {
90
+ const versionsDir = join(home, "versions");
91
+ const sourcesDir = join(home, "sources");
92
+ const stagingDir = join(home, "cache", "staging");
93
+ for (const dir of [versionsDir, sourcesDir, stagingDir])
94
+ await mkdir(dir, { recursive: true, mode: 0o700 });
95
+ const versionDir = (versionId: string): string => join(versionsDir, versionId);
96
+ return {
97
+ versionsDir,
98
+ sourcesDir,
99
+ stagingDir,
100
+ versionDir,
101
+ snapshotPath: (artifactId, sourceDigest) =>
102
+ join(sourcesDir, artifactId, `${sourceDigest}.tar.zst`),
103
+ async promote(built, versionId) {
104
+ await sealTree(built, true);
105
+ const target = versionDir(versionId);
106
+ // A directory without a ledger row is a leftover of an interrupted publish (FAILURE_MODEL §3).
107
+ await removeTree(target);
108
+ await rename(built, target);
109
+ await chmod(target, 0o555);
110
+ fsyncPath(target, true);
111
+ fsyncPath(versionsDir, true);
112
+ },
113
+ async sweep(known) {
114
+ const removed = { versions: [] as string[], snapshots: [] as string[] };
115
+ await removeTree(stagingDir);
116
+ await mkdir(stagingDir, { recursive: true, mode: 0o700 });
117
+ for (const name of await readdir(versionsDir)) {
118
+ if (!known.versions.has(name)) {
119
+ await removeTree(join(versionsDir, name));
120
+ removed.versions.push(name);
121
+ }
122
+ }
123
+ for (const artifact of await readdir(sourcesDir)) {
124
+ const dir = join(sourcesDir, artifact);
125
+ if (!(await stat(dir)).isDirectory()) continue;
126
+ for (const name of await readdir(dir)) {
127
+ if (!known.snapshots.has(`${artifact}/${name}`)) {
128
+ await rm(join(dir, name), { force: true });
129
+ removed.snapshots.push(`${artifact}/${name}`);
130
+ }
131
+ }
132
+ }
133
+ return removed;
134
+ },
135
+ };
136
+ }