@opengeni/worker-bundle 0.16.21 → 0.17.2

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 (180) hide show
  1. package/dist/activities/agent-turn.d.ts +145 -32
  2. package/dist/activities/api-integrations.d.ts +21 -0
  3. package/dist/activities/codemode-dispatcher.d.ts +35 -0
  4. package/dist/activities/codemode-token-renewal.d.ts +23 -0
  5. package/dist/activities/codex-capacity.d.ts +5 -5
  6. package/dist/activities/codex-image-generation.d.ts +21 -0
  7. package/dist/activities/context-compaction.d.ts +3 -0
  8. package/dist/activities/documents.d.ts +3 -2
  9. package/dist/activities/environment.d.ts +11 -7
  10. package/dist/activities/expiring-material-renewal.d.ts +5 -3
  11. package/dist/activities/file-upload-reaper.d.ts +7 -2
  12. package/dist/activities/gateway-image-generation.d.ts +39 -0
  13. package/dist/activities/gateway-video-generation.d.ts +53 -0
  14. package/dist/activities/generated-images.d.ts +112 -0
  15. package/dist/activities/git-credential-renewal.d.ts +2 -2
  16. package/dist/activities/goals.d.ts +2 -2
  17. package/dist/activities/google-drive-changes.d.ts +99 -0
  18. package/dist/activities/image-generation-operation.d.ts +74 -0
  19. package/dist/activities/image-generation-references.d.ts +25 -0
  20. package/dist/activities/knowledge-source-sync-driver.d.ts +23 -0
  21. package/dist/activities/knowledge-source-sync.d.ts +75 -0
  22. package/dist/activities/packs.d.ts +13 -26
  23. package/dist/activities/parent-wake.d.ts +1 -1
  24. package/dist/activities/retained-screenshot-reaper.d.ts +32 -0
  25. package/dist/activities/retained-screenshots.d.ts +129 -0
  26. package/dist/activities/rig-verification.d.ts +82 -5
  27. package/dist/activities/run-credential-renewal.d.ts +2 -2
  28. package/dist/activities/run-input.d.ts +5 -1
  29. package/dist/activities/sandbox-images.d.ts +14 -0
  30. package/dist/activities/sandbox-lease.d.ts +47 -9
  31. package/dist/activities/scheduled-tasks.d.ts +2 -2
  32. package/dist/activities/session-state.d.ts +4 -4
  33. package/dist/activities/streaming.d.ts +1 -1
  34. package/dist/activities/types.d.ts +71 -5
  35. package/dist/activities/video-generation-admission.d.ts +38 -0
  36. package/dist/activities/video-generation-credential.d.ts +7 -0
  37. package/dist/activities/video-generation-reconciliation.d.ts +13 -0
  38. package/dist/activities/video-media-validation.d.ts +34 -0
  39. package/dist/activities/video-output-retention.d.ts +36 -0
  40. package/dist/activities/video-reference-staging.d.ts +49 -0
  41. package/dist/activities/workflow-wake.d.ts +2 -2
  42. package/dist/activities/workspace-capture.d.ts +11 -1
  43. package/dist/activities-control-44KBWLSM.js +6885 -0
  44. package/dist/activities-control-44KBWLSM.js.map +1 -0
  45. package/dist/activities-control.d.ts +289 -0
  46. package/dist/activities-turn-K4CEDEGJ.js +14675 -0
  47. package/dist/activities-turn-K4CEDEGJ.js.map +1 -0
  48. package/dist/activities-turn.d.ts +17 -0
  49. package/dist/activities.d.ts +130 -147
  50. package/dist/activity-services.d.ts +10 -0
  51. package/dist/artifact-materializer-entry.d.ts +6 -0
  52. package/dist/artifact-materializer-entry.js +2662 -0
  53. package/dist/artifact-materializer-entry.js.map +1 -0
  54. package/dist/artifact-outbox-entry.d.ts +2 -0
  55. package/dist/artifact-outbox-entry.js +681 -0
  56. package/dist/artifact-outbox-entry.js.map +1 -0
  57. package/dist/chunk-E3RI3I33.js +828 -0
  58. package/dist/chunk-E3RI3I33.js.map +1 -0
  59. package/dist/chunk-GRFQTTSQ.js +448 -0
  60. package/dist/chunk-GRFQTTSQ.js.map +1 -0
  61. package/dist/chunk-KKCRGAGZ.js +3091 -0
  62. package/dist/chunk-KKCRGAGZ.js.map +1 -0
  63. package/dist/{chunk-BJUW5LCM.js → chunk-RAMNYSAW.js} +15 -12
  64. package/dist/chunk-RAMNYSAW.js.map +1 -0
  65. package/dist/concurrency.d.ts +108 -5
  66. package/dist/editable-artifact-hint-broker.d.ts +49 -0
  67. package/dist/editable-artifact-materializer-launcher.d.ts +49 -0
  68. package/dist/editable-artifact-materializer-service.d.ts +108 -0
  69. package/dist/editable-artifact-materializer-storage.d.ts +12 -0
  70. package/dist/editable-artifact-materializer-subprocess.d.ts +50 -0
  71. package/dist/editable-artifact-materializer.d.ts +262 -0
  72. package/dist/editable-artifact-outbox-dispatcher.d.ts +44 -0
  73. package/dist/editable-artifact-outbox-service.d.ts +70 -0
  74. package/dist/host-export.d.ts +1 -1
  75. package/dist/host-export.js +1 -1
  76. package/dist/index.d.ts +176 -10
  77. package/dist/index.js +675 -16460
  78. package/dist/index.js.map +1 -1
  79. package/dist/memory-pressure-guard.d.ts +57 -0
  80. package/dist/model-checkpoint-memory-collector.d.ts +22 -0
  81. package/dist/observability-metrics.d.ts +33 -0
  82. package/dist/sandbox-reaper-contract.d.ts +40 -0
  83. package/dist/sandbox-reaper-timeout.d.ts +14 -0
  84. package/dist/sandbox-resume.d.ts +40 -7
  85. package/dist/sandbox-routing.d.ts +13 -6
  86. package/dist/worker-service-lifecycle.d.ts +6 -2
  87. package/dist/workflow-bundle.js +1044 -363
  88. package/dist/workflows/activities.d.ts +7 -1
  89. package/dist/workflows/document-index.d.ts +1 -1
  90. package/dist/workflows/knowledge-source-sync.d.ts +13 -0
  91. package/dist/workflows/rig-verification.d.ts +1 -1
  92. package/dist/workflows/sandbox-reaper.d.ts +8 -0
  93. package/dist/workflows/scheduled-tasks.d.ts +1 -1
  94. package/dist/workflows/session.d.ts +2 -2
  95. package/dist/workflows/video-generation.d.ts +10 -0
  96. package/dist/workflows/workflow-wake.d.ts +1 -1
  97. package/dist/workflows.d.ts +9 -7
  98. package/package.json +34 -15
  99. package/src/activities/agent-turn.ts +1905 -559
  100. package/src/activities/api-integrations.ts +138 -0
  101. package/src/activities/codemode-dispatcher.ts +335 -0
  102. package/src/activities/codemode-token-renewal.ts +64 -0
  103. package/src/activities/codex-capacity.ts +16 -7
  104. package/src/activities/codex-image-generation.ts +56 -0
  105. package/src/activities/codex-rotation.ts +19 -5
  106. package/src/activities/context-compaction.ts +47 -6
  107. package/src/activities/documents.ts +14 -4
  108. package/src/activities/environment.ts +52 -60
  109. package/src/activities/expiring-material-renewal.ts +16 -7
  110. package/src/activities/file-upload-reaper.ts +34 -3
  111. package/src/activities/gateway-image-generation.ts +146 -0
  112. package/src/activities/gateway-video-generation.ts +298 -0
  113. package/src/activities/generated-images.ts +860 -0
  114. package/src/activities/git-credential-renewal.ts +3 -3
  115. package/src/activities/goals.ts +6 -2
  116. package/src/activities/google-drive-changes.ts +454 -0
  117. package/src/activities/image-generation-operation.ts +333 -0
  118. package/src/activities/image-generation-references.ts +118 -0
  119. package/src/activities/knowledge-source-sync-driver.ts +27 -0
  120. package/src/activities/knowledge-source-sync.ts +2840 -0
  121. package/src/activities/mcp-credentials.ts +1 -0
  122. package/src/activities/packs.ts +55 -55
  123. package/src/activities/recording.ts +4 -5
  124. package/src/activities/retained-screenshot-reaper.ts +202 -0
  125. package/src/activities/retained-screenshots.ts +1317 -0
  126. package/src/activities/rig-verification.ts +567 -77
  127. package/src/activities/run-credential-renewal.ts +9 -2
  128. package/src/activities/run-input.ts +40 -10
  129. package/src/activities/sandbox-images.ts +167 -0
  130. package/src/activities/sandbox-lease.ts +1065 -483
  131. package/src/activities/scheduled-tasks.ts +96 -7
  132. package/src/activities/session-state.ts +4 -4
  133. package/src/activities/streaming.ts +42 -3
  134. package/src/activities/types.ts +87 -5
  135. package/src/activities/video-generation-admission.ts +270 -0
  136. package/src/activities/video-generation-credential.ts +34 -0
  137. package/src/activities/video-generation-reconciliation.ts +578 -0
  138. package/src/activities/video-media-validation.ts +326 -0
  139. package/src/activities/video-output-retention.ts +314 -0
  140. package/src/activities/video-reference-staging.ts +263 -0
  141. package/src/activities/workflow-wake.ts +2 -2
  142. package/src/activities/workspace-capture.ts +77 -13
  143. package/src/activities-control.ts +54 -0
  144. package/src/activities-turn.ts +40 -0
  145. package/src/activities.ts +50 -118
  146. package/src/activity-services.ts +62 -0
  147. package/src/artifact-materializer-entry.ts +35 -0
  148. package/src/artifact-outbox-entry.ts +29 -0
  149. package/src/concurrency.ts +484 -6
  150. package/src/editable-artifact-hint-broker.ts +235 -0
  151. package/src/editable-artifact-materializer-launcher.ts +515 -0
  152. package/src/editable-artifact-materializer-service.ts +787 -0
  153. package/src/editable-artifact-materializer-storage.ts +413 -0
  154. package/src/editable-artifact-materializer-subprocess.ts +956 -0
  155. package/src/editable-artifact-materializer.ts +1289 -0
  156. package/src/editable-artifact-outbox-dispatcher.ts +244 -0
  157. package/src/editable-artifact-outbox-service.ts +438 -0
  158. package/src/host-export-pump.ts +28 -11
  159. package/src/http.ts +3 -6
  160. package/src/index.ts +277 -72
  161. package/src/memory-pressure-guard.ts +489 -0
  162. package/src/model-checkpoint-memory-collector.ts +116 -0
  163. package/src/observability-metrics.ts +202 -7
  164. package/src/sandbox-reaper-contract.ts +73 -0
  165. package/src/sandbox-reaper-timeout.ts +79 -0
  166. package/src/sandbox-resume.ts +331 -157
  167. package/src/sandbox-routing.ts +49 -39
  168. package/src/worker-service-lifecycle.ts +82 -12
  169. package/src/workflows/activities.ts +30 -0
  170. package/src/workflows/file-upload-reaper.ts +6 -1
  171. package/src/workflows/knowledge-source-sync.ts +83 -0
  172. package/src/workflows/sandbox-reaper.ts +183 -21
  173. package/src/workflows/scheduled-tasks.ts +42 -6
  174. package/src/workflows/video-generation.ts +36 -0
  175. package/src/workflows.ts +17 -1
  176. package/dist/activities/redaction.d.ts +0 -1
  177. package/dist/activities/toolspace-token-renewal.d.ts +0 -23
  178. package/dist/chunk-BJUW5LCM.js.map +0 -1
  179. package/src/activities/redaction.ts +0 -9
  180. package/src/activities/toolspace-token-renewal.ts +0 -57
@@ -0,0 +1,1289 @@
1
+ import { createHash } from "node:crypto";
2
+
3
+ import { EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES } from "@opengeni/contracts/editable-artifacts";
4
+
5
+ import type {
6
+ BoundedImmutableObjectWritePort,
7
+ BoundedObjectRead,
8
+ BoundedObjectReadPort,
9
+ } from "@opengeni/storage";
10
+ import { BoundedObjectReadError, BoundedObjectWriteError } from "@opengeni/storage";
11
+
12
+ /**
13
+ * The database role allowed to poll the cross-tenant materialization queue.
14
+ * It owns no table privileges; @opengeni/db exposes only fenced SECURITY
15
+ * DEFINER functions to this role.
16
+ */
17
+ export const EDITABLE_ARTIFACT_MATERIALIZER_DATABASE_ROLE =
18
+ "opengeni_artifact_materializer" as const;
19
+
20
+ export const EDITABLE_ARTIFACT_MATERIALIZER_MAX_SOURCE_BYTES = 512 * 1024 * 1024;
21
+ export const EDITABLE_ARTIFACT_MATERIALIZER_MAX_OUTPUT_BYTES = 512 * 1024 * 1024;
22
+ export const EDITABLE_ARTIFACT_MATERIALIZER_MAX_OPTIONS_BYTES = 256 * 1024;
23
+ export const EDITABLE_ARTIFACT_MATERIALIZER_MAX_ATTEMPTS = 20;
24
+
25
+ export type EditableArtifactMaterializationFormat =
26
+ | "xlsx"
27
+ | "pptx"
28
+ | "docx"
29
+ | "pdf"
30
+ | "png"
31
+ | "webp";
32
+
33
+ export type EditableArtifactMaterializationModality = "spreadsheet" | "presentation" | "document";
34
+
35
+ export type EditableArtifactMaterializationMimeType =
36
+ | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
37
+ | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
38
+ | "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
39
+ | "application/pdf"
40
+ | "image/png"
41
+ | "image/webp";
42
+
43
+ export type EditableArtifactMaterializationScope = Readonly<{
44
+ accountId: string;
45
+ workspaceId: string;
46
+ }>;
47
+
48
+ /**
49
+ * One immutable, self-contained input manifest returned by the global claim
50
+ * function. The source snapshot covers exactly targetHeadSequence. There is
51
+ * deliberately no "current" lookup after claim and no unbounded DB tail read.
52
+ */
53
+ export type ClaimedEditableArtifactMaterialization = Readonly<{
54
+ scope: EditableArtifactMaterializationScope;
55
+ artifactId: string;
56
+ jobId: string;
57
+ versionId: string | null;
58
+ modality: EditableArtifactMaterializationModality;
59
+ inputSnapshotId: string;
60
+ targetHeadSequence: number;
61
+ stateHash: string;
62
+ sourceObjectReference: string;
63
+ sourceByteSize: number;
64
+ sourceContentHash: string;
65
+ sourceMimeType: string;
66
+ modelSchemaVersion: number;
67
+ operationProtocolVersion: number;
68
+ snapshotProtocolVersion: number;
69
+ format: EditableArtifactMaterializationFormat;
70
+ codecId: string;
71
+ /** Canonical UTF-8 JSON, bounded and hashed by optionsHash. */
72
+ normalizedOptions: string;
73
+ optionsHash: string;
74
+ codecVersion: string;
75
+ kernelVersion: string;
76
+ fontRegistryHash: string;
77
+ policyHash: string;
78
+ attemptCount: number;
79
+ leaseOwner: string;
80
+ leaseExpiresAt: string;
81
+ }>;
82
+
83
+ export type EditableArtifactMaterializationLease = Readonly<{
84
+ scope: EditableArtifactMaterializationScope;
85
+ artifactId: string;
86
+ jobId: string;
87
+ owner: string;
88
+ attemptCount: number;
89
+ }>;
90
+
91
+ export interface EditableArtifactMaterializationStorePort {
92
+ claim(input: {
93
+ owner: string;
94
+ leaseDurationMs: number;
95
+ limit: number;
96
+ }): Promise<readonly ClaimedEditableArtifactMaterialization[]>;
97
+ renew(input: EditableArtifactMaterializationLease & { leaseDurationMs: number }): Promise<string>;
98
+ succeed(
99
+ input: EditableArtifactMaterializationLease & {
100
+ resultId: string;
101
+ blobRefId: string;
102
+ objectReference: string;
103
+ byteSize: number;
104
+ contentHash: string;
105
+ mimeType: EditableArtifactMaterializationMimeType;
106
+ verifiedAt: string;
107
+ },
108
+ ): Promise<unknown>;
109
+ fail(input: EditableArtifactMaterializationLease & { errorCode: string }): Promise<unknown>;
110
+ }
111
+
112
+ export type NativeEditableArtifactMaterializerIdentity = Readonly<{
113
+ kind: "native";
114
+ /** Parent-owned launcher facts, never copied from the codec child. */
115
+ isolation: "subprocess";
116
+ network: "denied" | "host";
117
+ officeAutomation: false;
118
+ processProtocolVersion: 1;
119
+ sandboxEnforced: boolean;
120
+ memoryLimitBytes: number;
121
+ cpuTimeLimitMs: number;
122
+ fileDescriptorLimit: number;
123
+ processLimit: number;
124
+ fileSizeLimitBytes: number;
125
+ maxOutputBytes: number;
126
+ kernelVersion: string;
127
+ codecVersions: Readonly<Record<string, string>>;
128
+ fontRegistryHash: string;
129
+ policyHash: string;
130
+ runtimeTarget: string;
131
+ supportedModelSchemaVersions: readonly number[];
132
+ supportedOperationProtocolVersions: readonly number[];
133
+ supportedSnapshotProtocolVersions: readonly number[];
134
+ }>;
135
+
136
+ export type NativeEditableArtifactMaterializationResult = Readonly<{
137
+ headSequence: number;
138
+ stateHash: string;
139
+ format: EditableArtifactMaterializationFormat;
140
+ mimeType: EditableArtifactMaterializationMimeType;
141
+ codecId: string;
142
+ codecVersion: string;
143
+ kernelVersion: string;
144
+ fontRegistryHash: string;
145
+ policyHash: string;
146
+ /** Optional precomputed facts; the independent writer/verifier still checks. */
147
+ byteSize?: number;
148
+ contentHash?: string;
149
+ /** Canonical semantics projected by the authoritative native source kernel. */
150
+ semanticHash: string;
151
+ chunks: AsyncIterable<Uint8Array>;
152
+ }>;
153
+
154
+ /**
155
+ * Production implementations must be a native Rust subprocess adapter. The
156
+ * adapter consumes a version-pinned stream, reconstructs and validates the
157
+ * canonical snapshot, and exports without Office/COM or network access.
158
+ */
159
+ export interface NativeEditableArtifactMaterializerPort {
160
+ readonly identity: NativeEditableArtifactMaterializerIdentity;
161
+ materialize(input: {
162
+ job: ClaimedEditableArtifactMaterialization;
163
+ normalizedOptions: Uint8Array;
164
+ snapshot: AsyncIterable<Uint8Array>;
165
+ signal: AbortSignal;
166
+ }): Promise<NativeEditableArtifactMaterializationResult>;
167
+ }
168
+
169
+ export type VerifiedEditableArtifactMaterialization = Readonly<{
170
+ objectReference: string;
171
+ byteSize: number;
172
+ contentHash: string;
173
+ mimeType: EditableArtifactMaterializationMimeType;
174
+ format: EditableArtifactMaterializationFormat;
175
+ codecId: string;
176
+ codecVersion: string;
177
+ }>;
178
+
179
+ /** Independent reader/parser. It must not reuse the exporting codec process. */
180
+ export interface EditableArtifactMaterializationVerifierPort {
181
+ verify(input: {
182
+ objectReference: string;
183
+ expectedByteSize: number;
184
+ expectedContentHash: string;
185
+ expectedMimeType: EditableArtifactMaterializationMimeType;
186
+ format: EditableArtifactMaterializationFormat;
187
+ codecId: string;
188
+ codecVersion: string;
189
+ expectedSemanticHash: string;
190
+ maxBytes: number;
191
+ signal: AbortSignal;
192
+ }): Promise<VerifiedEditableArtifactMaterialization>;
193
+ }
194
+
195
+ export interface EditableArtifactMaterializationSemanticVerifierPort {
196
+ verify(input: {
197
+ format: EditableArtifactMaterializationFormat;
198
+ codecId: string;
199
+ codecVersion: string;
200
+ expectedSemanticHash: string;
201
+ byteSize: number;
202
+ chunks: AsyncIterable<Uint8Array>;
203
+ signal: AbortSignal;
204
+ }): Promise<void>;
205
+ }
206
+
207
+ export interface EditableArtifactMaterializerSchedulerPort {
208
+ sleep(milliseconds: number, signal: AbortSignal): Promise<void>;
209
+ }
210
+
211
+ export interface EditableArtifactMaterializerClockPort {
212
+ now(): Date;
213
+ }
214
+
215
+ export interface EditableArtifactMaterializerLoggerPort {
216
+ warn(message: string, attributes: Readonly<Record<string, unknown>>): void;
217
+ }
218
+
219
+ export type EditableArtifactMaterializerMetricOutcome =
220
+ | "claimed"
221
+ | "succeeded"
222
+ | "dead_lettered"
223
+ | "retry_deferred"
224
+ | "lease_lost"
225
+ | "cancelled"
226
+ | "claim_failed";
227
+
228
+ export interface EditableArtifactMaterializerMetricsPort {
229
+ increment(outcome: EditableArtifactMaterializerMetricOutcome, count?: number): void;
230
+ }
231
+
232
+ export type EditableArtifactMaterializerOptions = Readonly<{
233
+ owner: string;
234
+ batchSize?: number;
235
+ concurrency?: number;
236
+ leaseDurationMs?: number;
237
+ leaseRenewIntervalMs?: number;
238
+ pollIntervalMs?: number;
239
+ claimBackoffMs?: number;
240
+ maxAttempts?: number;
241
+ maxSourceBytes?: number;
242
+ maxOutputBytes?: number;
243
+ }>;
244
+
245
+ export type EditableArtifactMaterializerDependencies = Readonly<{
246
+ store: EditableArtifactMaterializationStorePort;
247
+ sourceReader: BoundedObjectReadPort;
248
+ outputWriter: BoundedImmutableObjectWritePort;
249
+ outputVerifier: EditableArtifactMaterializationVerifierPort;
250
+ kernel: NativeEditableArtifactMaterializerPort;
251
+ scheduler: EditableArtifactMaterializerSchedulerPort;
252
+ clock: EditableArtifactMaterializerClockPort;
253
+ logger?: EditableArtifactMaterializerLoggerPort;
254
+ metrics?: EditableArtifactMaterializerMetricsPort;
255
+ }>;
256
+
257
+ export type EditableArtifactMaterializerPassSummary = Readonly<{
258
+ claimed: number;
259
+ succeeded: number;
260
+ deadLettered: number;
261
+ retryDeferred: number;
262
+ leaseLost: number;
263
+ cancelled: number;
264
+ claimFailed: boolean;
265
+ }>;
266
+
267
+ type MutableSummary = {
268
+ claimed: number;
269
+ succeeded: number;
270
+ deadLettered: number;
271
+ retryDeferred: number;
272
+ leaseLost: number;
273
+ cancelled: number;
274
+ claimFailed: boolean;
275
+ };
276
+
277
+ type NormalizedOptions = Required<EditableArtifactMaterializerOptions>;
278
+
279
+ const DEFAULT_OPTIONS = Object.freeze({
280
+ batchSize: 8,
281
+ concurrency: 2,
282
+ leaseDurationMs: 120_000,
283
+ leaseRenewIntervalMs: 30_000,
284
+ pollIntervalMs: 1_000,
285
+ claimBackoffMs: 5_000,
286
+ maxAttempts: EDITABLE_ARTIFACT_MATERIALIZER_MAX_ATTEMPTS,
287
+ maxSourceBytes: EDITABLE_ARTIFACT_MATERIALIZER_MAX_SOURCE_BYTES,
288
+ maxOutputBytes: EDITABLE_ARTIFACT_MATERIALIZER_MAX_OUTPUT_BYTES,
289
+ });
290
+
291
+ /** Closed, diagnostics-free terminal failure codes persisted in Postgres. */
292
+ export type EditableArtifactMaterializerDeadLetterCode =
293
+ | "invalid_job_manifest"
294
+ | "source_identity_mismatch"
295
+ | "source_size_limit"
296
+ | "kernel_incompatible"
297
+ | "kernel_result_mismatch"
298
+ | "unsupported_semantics"
299
+ | "output_size_limit"
300
+ | "output_verification_failed"
301
+ | "retry_exhausted";
302
+
303
+ export type EditableArtifactMaterializerFailureDiagnostic = Readonly<{
304
+ stage: "source_reader" | "native";
305
+ subcode:
306
+ | "open"
307
+ | "content_type"
308
+ | "stream_identity"
309
+ | "revalidate"
310
+ | "input_framing"
311
+ | "snapshot_open"
312
+ | "state_mismatch";
313
+ }>;
314
+
315
+ export class EditableArtifactMaterializerPermanentError extends Error {
316
+ constructor(
317
+ readonly code: EditableArtifactMaterializerDeadLetterCode,
318
+ readonly diagnostic?: EditableArtifactMaterializerFailureDiagnostic,
319
+ ) {
320
+ super(`Editable artifact materialization cannot continue: ${code}`);
321
+ this.name = "EditableArtifactMaterializerPermanentError";
322
+ }
323
+ }
324
+
325
+ export class EditableArtifactMaterializerLeaseLostError extends Error {
326
+ constructor() {
327
+ super("Editable artifact materialization lease was lost");
328
+ this.name = "EditableArtifactMaterializerLeaseLostError";
329
+ }
330
+ }
331
+
332
+ /**
333
+ * At-least-once materialization loop. Immutable content-addressed output makes
334
+ * recomputation safe; owner + attemptCount fences make DB settlement exact.
335
+ */
336
+ export class EditableArtifactMaterializer {
337
+ readonly #options: NormalizedOptions;
338
+ #activePass: Promise<EditableArtifactMaterializerPassSummary> | null = null;
339
+
340
+ constructor(
341
+ private readonly dependencies: EditableArtifactMaterializerDependencies,
342
+ options: EditableArtifactMaterializerOptions,
343
+ securityPolicy: Readonly<{ allowUnsandboxedDevelopment?: boolean }> = {},
344
+ ) {
345
+ this.#options = normalizeOptions(options);
346
+ assertNativeKernelIdentity(
347
+ dependencies.kernel.identity,
348
+ securityPolicy.allowUnsandboxedDevelopment === true,
349
+ );
350
+ }
351
+
352
+ async run(signal: AbortSignal): Promise<void> {
353
+ let claimFailed = false;
354
+ while (!signal.aborted) {
355
+ const summary = await this.dispatchOnce(signal);
356
+ claimFailed = summary.claimFailed;
357
+ if (signal.aborted) break;
358
+ const delay = claimFailed
359
+ ? this.#options.claimBackoffMs
360
+ : summary.claimed === 0
361
+ ? this.#options.pollIntervalMs
362
+ : 0;
363
+ if (delay > 0 && !(await sleepOrAbort(this.dependencies.scheduler, delay, signal))) break;
364
+ }
365
+ await this.drain();
366
+ }
367
+
368
+ /** Concurrent triggers share one bounded claim pass. */
369
+ dispatchOnce(signal?: AbortSignal): Promise<EditableArtifactMaterializerPassSummary> {
370
+ if (this.#activePass) return this.#activePass;
371
+ const pass = this.#dispatchBatch(signal);
372
+ this.#activePass = pass;
373
+ void pass.then(
374
+ () => {
375
+ if (this.#activePass === pass) this.#activePass = null;
376
+ },
377
+ () => {
378
+ if (this.#activePass === pass) this.#activePass = null;
379
+ },
380
+ );
381
+ return pass;
382
+ }
383
+
384
+ async drain(): Promise<void> {
385
+ await this.#activePass;
386
+ }
387
+
388
+ async #dispatchBatch(
389
+ parentSignal: AbortSignal | undefined,
390
+ ): Promise<EditableArtifactMaterializerPassSummary> {
391
+ const summary = mutableSummary();
392
+ if (parentSignal?.aborted) {
393
+ return freezeSummary(summary);
394
+ }
395
+ let jobs: readonly ClaimedEditableArtifactMaterialization[];
396
+ try {
397
+ jobs = await this.dependencies.store.claim({
398
+ owner: this.#options.owner,
399
+ leaseDurationMs: this.#options.leaseDurationMs,
400
+ limit: this.#options.batchSize,
401
+ });
402
+ if (!Array.isArray(jobs) || jobs.length > this.#options.batchSize) {
403
+ throw new TypeError("Materialization store returned an invalid claim batch");
404
+ }
405
+ } catch (error) {
406
+ summary.claimFailed = true;
407
+ this.#metric("claim_failed");
408
+ this.#warn("Editable artifact materialization claim failed", "claim_failed", error);
409
+ return freezeSummary(summary);
410
+ }
411
+ summary.claimed = jobs.length;
412
+ if (jobs.length > 0) this.#metric("claimed", jobs.length);
413
+
414
+ let cursor = 0;
415
+ const worker = async (): Promise<void> => {
416
+ for (;;) {
417
+ const index = cursor;
418
+ cursor += 1;
419
+ const job = jobs[index];
420
+ if (!job) return;
421
+ await this.#processJob(job, summary, parentSignal);
422
+ }
423
+ };
424
+ await Promise.all(
425
+ Array.from({ length: Math.min(jobs.length, this.#options.concurrency) }, worker),
426
+ );
427
+ return freezeSummary(summary);
428
+ }
429
+
430
+ async #processJob(
431
+ job: ClaimedEditableArtifactMaterialization,
432
+ summary: MutableSummary,
433
+ parentSignal: AbortSignal | undefined,
434
+ ): Promise<void> {
435
+ let lease: EditableArtifactMaterializationLease;
436
+ try {
437
+ lease = validateClaimedJob(job, this.#options.owner, this.dependencies.kernel.identity);
438
+ } catch (error) {
439
+ await this.#deadLetterBestEffort(job, "invalid_job_manifest", summary, error);
440
+ return;
441
+ }
442
+
443
+ if (job.attemptCount >= this.#options.maxAttempts) {
444
+ await this.#settlePermanent(lease, "retry_exhausted", summary, null);
445
+ return;
446
+ }
447
+
448
+ const operationAbort = new AbortController();
449
+ const renewalAbort = new AbortController();
450
+ const combined = combineAbortSignals(parentSignal, operationAbort.signal);
451
+ let leaseLost = false;
452
+ const renewal = this.#renewLease(lease, renewalAbort.signal, operationAbort, () => {
453
+ leaseLost = true;
454
+ });
455
+
456
+ let source: BoundedObjectRead | null = null;
457
+ try {
458
+ throwIfAborted(combined.signal);
459
+ assertJobKernelCompatibility(job, this.dependencies.kernel.identity);
460
+ const optionsBytes = canonicalOptionsBytes(job.normalizedOptions, job.optionsHash);
461
+ if (job.sourceByteSize > this.#options.maxSourceBytes) {
462
+ throw new EditableArtifactMaterializerPermanentError("source_size_limit");
463
+ }
464
+ try {
465
+ source = await this.dependencies.sourceReader.open({
466
+ opaqueReference: job.sourceObjectReference,
467
+ maxBytes: this.#options.maxSourceBytes,
468
+ expectedByteSize: job.sourceByteSize,
469
+ signal: combined.signal,
470
+ });
471
+ } catch (error) {
472
+ throw diagnoseSourceReaderFailure(error, "open");
473
+ }
474
+ if (source.contentType !== undefined && source.contentType !== job.sourceMimeType) {
475
+ throw new EditableArtifactMaterializerPermanentError("source_identity_mismatch", {
476
+ stage: "source_reader",
477
+ subcode: "content_type",
478
+ });
479
+ }
480
+ let sourceChunks: AsyncIterable<Uint8Array>;
481
+ try {
482
+ sourceChunks = source.chunks({ signal: combined.signal });
483
+ } catch (error) {
484
+ throw diagnoseSourceReaderFailure(error, "stream_identity");
485
+ }
486
+ const trackedSource = trackExactStream(
487
+ sourceChunks,
488
+ job.sourceByteSize,
489
+ job.sourceContentHash,
490
+ "source_identity_mismatch",
491
+ { stage: "source_reader", subcode: "stream_identity" },
492
+ );
493
+ let output: NativeEditableArtifactMaterializationResult;
494
+ try {
495
+ output = await this.dependencies.kernel.materialize({
496
+ job,
497
+ normalizedOptions: optionsBytes,
498
+ snapshot: trackedSource.chunks,
499
+ signal: combined.signal,
500
+ });
501
+ await trackedSource.done;
502
+ } catch (error) {
503
+ // The source wrapper can reject concurrently with the native adapter
504
+ // that is consuming it. Observe both promises so corrupt input never
505
+ // becomes an unhandled rejection after the adapter exits.
506
+ void trackedSource.done.catch(() => undefined);
507
+ throw error;
508
+ }
509
+ try {
510
+ await source.assertUnchanged(combined.signal);
511
+ } catch (error) {
512
+ throw diagnoseSourceReaderFailure(error, "revalidate");
513
+ }
514
+ validateKernelResult(job, output);
515
+
516
+ const written = await this.dependencies.outputWriter.write({
517
+ chunks: output.chunks,
518
+ contentType: output.mimeType,
519
+ maxBytes: this.#options.maxOutputBytes,
520
+ ...(output.byteSize !== undefined ? { expectedByteSize: output.byteSize } : {}),
521
+ ...(output.contentHash !== undefined ? { expectedContentHash: output.contentHash } : {}),
522
+ signal: combined.signal,
523
+ });
524
+ let verified: VerifiedEditableArtifactMaterialization;
525
+ try {
526
+ verified = await this.dependencies.outputVerifier.verify({
527
+ objectReference: written.opaqueReference,
528
+ expectedByteSize: written.byteSize,
529
+ expectedContentHash: written.contentHash,
530
+ expectedMimeType: output.mimeType,
531
+ format: job.format,
532
+ codecId: job.codecId,
533
+ codecVersion: job.codecVersion,
534
+ expectedSemanticHash: output.semanticHash,
535
+ maxBytes: this.#options.maxOutputBytes,
536
+ signal: combined.signal,
537
+ });
538
+ } catch (error) {
539
+ if (error instanceof BoundedObjectReadError) {
540
+ throw new EditableArtifactMaterializerPermanentError("output_verification_failed");
541
+ }
542
+ throw error;
543
+ }
544
+ validateIndependentVerification(job, written, verified);
545
+
546
+ renewalAbort.abort();
547
+ await renewal;
548
+ if (leaseLost) throw new EditableArtifactMaterializerLeaseLostError();
549
+ throwIfAborted(combined.signal);
550
+ await this.dependencies.store.renew({
551
+ ...lease,
552
+ leaseDurationMs: this.#options.leaseDurationMs,
553
+ });
554
+ const ids = deterministicResultIds(job, written.contentHash);
555
+ await this.dependencies.store.succeed({
556
+ ...lease,
557
+ ...ids,
558
+ objectReference: written.opaqueReference,
559
+ byteSize: written.byteSize,
560
+ contentHash: written.contentHash,
561
+ mimeType: output.mimeType,
562
+ verifiedAt: this.dependencies.clock.now().toISOString(),
563
+ });
564
+ summary.succeeded += 1;
565
+ this.#metric("succeeded");
566
+ } catch (error) {
567
+ renewalAbort.abort();
568
+ await renewal;
569
+ if (leaseLost || isLeaseFence(error)) {
570
+ summary.leaseLost += 1;
571
+ this.#metric("lease_lost");
572
+ this.#warn("Editable artifact materialization lease was lost", "lease_lost", error);
573
+ } else if (combined.signal.aborted || isAbortError(error)) {
574
+ summary.cancelled += 1;
575
+ this.#metric("cancelled");
576
+ } else {
577
+ const permanent = permanentDependencyFailure(error);
578
+ if (permanent) {
579
+ await this.#settlePermanent(lease, permanent, summary, error);
580
+ } else {
581
+ // Unknown provider/kernel failures are retryable. Do not terminally
582
+ // settle: expiry lets another owner reclaim the exact immutable input.
583
+ summary.retryDeferred += 1;
584
+ this.#metric("retry_deferred");
585
+ this.#warn(
586
+ "Editable artifact materialization will retry after lease expiry",
587
+ "retry_deferred",
588
+ error,
589
+ );
590
+ }
591
+ }
592
+ } finally {
593
+ renewalAbort.abort();
594
+ combined.dispose();
595
+ if (source) await source.close();
596
+ }
597
+ }
598
+
599
+ async #renewLease(
600
+ lease: EditableArtifactMaterializationLease,
601
+ signal: AbortSignal,
602
+ operationAbort: AbortController,
603
+ onLeaseLost: () => void,
604
+ ): Promise<void> {
605
+ while (
606
+ await sleepOrAbort(this.dependencies.scheduler, this.#options.leaseRenewIntervalMs, signal)
607
+ ) {
608
+ try {
609
+ await this.dependencies.store.renew({
610
+ ...lease,
611
+ leaseDurationMs: this.#options.leaseDurationMs,
612
+ });
613
+ } catch (error) {
614
+ onLeaseLost();
615
+ operationAbort.abort(error);
616
+ return;
617
+ }
618
+ }
619
+ }
620
+
621
+ async #settlePermanent(
622
+ lease: EditableArtifactMaterializationLease,
623
+ code: EditableArtifactMaterializerDeadLetterCode,
624
+ summary: MutableSummary,
625
+ cause: unknown,
626
+ ): Promise<void> {
627
+ try {
628
+ await this.dependencies.store.renew({
629
+ ...lease,
630
+ leaseDurationMs: this.#options.leaseDurationMs,
631
+ });
632
+ await this.dependencies.store.fail({ ...lease, errorCode: code });
633
+ summary.deadLettered += 1;
634
+ this.#metric("dead_lettered");
635
+ if (cause) this.#warn("Editable artifact materialization was dead-lettered", code, cause);
636
+ } catch (error) {
637
+ summary.leaseLost += 1;
638
+ this.#metric("lease_lost");
639
+ this.#warn("Editable artifact dead-letter settlement was fenced", "lease_lost", error);
640
+ }
641
+ }
642
+
643
+ async #deadLetterBestEffort(
644
+ job: ClaimedEditableArtifactMaterialization,
645
+ code: EditableArtifactMaterializerDeadLetterCode,
646
+ summary: MutableSummary,
647
+ cause: unknown,
648
+ ): Promise<void> {
649
+ try {
650
+ const lease = rawLease(job, this.#options.owner);
651
+ await this.#settlePermanent(lease, code, summary, cause);
652
+ } catch (error) {
653
+ summary.leaseLost += 1;
654
+ this.#metric("lease_lost");
655
+ this.#warn("Invalid materialization claim could not be settled", "lease_lost", error);
656
+ }
657
+ }
658
+
659
+ #metric(outcome: EditableArtifactMaterializerMetricOutcome, count = 1): void {
660
+ try {
661
+ this.dependencies.metrics?.increment(outcome, count);
662
+ } catch {
663
+ // Observability is never part of the correctness boundary.
664
+ }
665
+ }
666
+
667
+ #warn(message: string, code: string, error: unknown): void {
668
+ try {
669
+ this.dependencies.logger?.warn(message, {
670
+ code,
671
+ errorClass: error instanceof Error ? error.name : "UnknownError",
672
+ ...(error instanceof EditableArtifactMaterializerPermanentError && error.diagnostic
673
+ ? {
674
+ failureStage: error.diagnostic.stage,
675
+ failureSubcode: error.diagnostic.subcode,
676
+ }
677
+ : {}),
678
+ });
679
+ } catch {
680
+ // Logging is never part of the correctness boundary.
681
+ }
682
+ }
683
+ }
684
+
685
+ export type ConfiguredEditableArtifactMaterializerInput = Readonly<{
686
+ enabled: boolean;
687
+ databaseRole: string | null | undefined;
688
+ objectStorageConfigured: boolean;
689
+ dependencies?: Partial<EditableArtifactMaterializerDependencies>;
690
+ options?: EditableArtifactMaterializerOptions;
691
+ /** Explicit local-development exception; production callers must omit it. */
692
+ allowUnsandboxedDevelopment?: boolean;
693
+ }>;
694
+
695
+ /**
696
+ * Production gate. Disabled is the default. Once enabled, every privileged
697
+ * dependency and the dedicated database role are mandatory—there is no
698
+ * reference-kernel, mutable-storage, or tenant-role fallback.
699
+ */
700
+ export function createConfiguredEditableArtifactMaterializer(
701
+ input: ConfiguredEditableArtifactMaterializerInput,
702
+ ): EditableArtifactMaterializer | null {
703
+ if (!input.enabled) return null;
704
+ if (input.databaseRole !== EDITABLE_ARTIFACT_MATERIALIZER_DATABASE_ROLE) {
705
+ throw new Error("Editable artifact materializer requires its dedicated database role");
706
+ }
707
+ if (!input.objectStorageConfigured) {
708
+ throw new Error("Editable artifact materializer requires immutable object storage");
709
+ }
710
+ const dependencies = input.dependencies;
711
+ if (
712
+ !dependencies?.store ||
713
+ !dependencies.sourceReader ||
714
+ !dependencies.outputWriter ||
715
+ !dependencies.outputVerifier ||
716
+ !dependencies.kernel ||
717
+ !dependencies.scheduler ||
718
+ !dependencies.clock
719
+ ) {
720
+ throw new Error("Editable artifact materializer dependencies are incomplete");
721
+ }
722
+ assertNativeKernelIdentity(
723
+ dependencies.kernel.identity,
724
+ input.allowUnsandboxedDevelopment === true,
725
+ );
726
+ if (!input.options) throw new Error("Editable artifact materializer options are required");
727
+ return new EditableArtifactMaterializer(
728
+ dependencies as EditableArtifactMaterializerDependencies,
729
+ input.options,
730
+ input.allowUnsandboxedDevelopment === undefined
731
+ ? {}
732
+ : { allowUnsandboxedDevelopment: input.allowUnsandboxedDevelopment },
733
+ );
734
+ }
735
+
736
+ export const systemEditableArtifactMaterializerScheduler: EditableArtifactMaterializerSchedulerPort =
737
+ Object.freeze({
738
+ sleep(milliseconds: number, signal: AbortSignal): Promise<void> {
739
+ return new Promise<void>((resolve, reject) => {
740
+ if (signal.aborted) {
741
+ reject(signal.reason ?? abortError());
742
+ return;
743
+ }
744
+ const complete = () => {
745
+ signal.removeEventListener("abort", abort);
746
+ resolve();
747
+ };
748
+ const timer = setTimeout(complete, milliseconds);
749
+ timer.unref?.();
750
+ const abort = () => {
751
+ clearTimeout(timer);
752
+ signal.removeEventListener("abort", abort);
753
+ reject(signal.reason ?? abortError());
754
+ };
755
+ signal.addEventListener("abort", abort, { once: true });
756
+ });
757
+ },
758
+ });
759
+
760
+ export const systemEditableArtifactMaterializerClock: EditableArtifactMaterializerClockPort =
761
+ Object.freeze({ now: () => new Date() });
762
+
763
+ function normalizeOptions(options: EditableArtifactMaterializerOptions): NormalizedOptions {
764
+ const normalized: NormalizedOptions = Object.freeze({
765
+ owner: validateOwner(options.owner),
766
+ batchSize: options.batchSize ?? DEFAULT_OPTIONS.batchSize,
767
+ concurrency: options.concurrency ?? DEFAULT_OPTIONS.concurrency,
768
+ leaseDurationMs: options.leaseDurationMs ?? DEFAULT_OPTIONS.leaseDurationMs,
769
+ leaseRenewIntervalMs: options.leaseRenewIntervalMs ?? DEFAULT_OPTIONS.leaseRenewIntervalMs,
770
+ pollIntervalMs: options.pollIntervalMs ?? DEFAULT_OPTIONS.pollIntervalMs,
771
+ claimBackoffMs: options.claimBackoffMs ?? DEFAULT_OPTIONS.claimBackoffMs,
772
+ maxAttempts: options.maxAttempts ?? DEFAULT_OPTIONS.maxAttempts,
773
+ maxSourceBytes: options.maxSourceBytes ?? DEFAULT_OPTIONS.maxSourceBytes,
774
+ maxOutputBytes: options.maxOutputBytes ?? DEFAULT_OPTIONS.maxOutputBytes,
775
+ });
776
+ for (const [label, value] of Object.entries(normalized)) {
777
+ if (label === "owner") continue;
778
+ positiveInteger(value, label);
779
+ }
780
+ if (normalized.batchSize > 64) throw new TypeError("materializer batch size exceeds 64");
781
+ if (normalized.concurrency > normalized.batchSize) {
782
+ throw new TypeError("materializer concurrency exceeds its batch size");
783
+ }
784
+ if (normalized.leaseDurationMs < 10_000 || normalized.leaseDurationMs > 86_400_000) {
785
+ throw new TypeError("materializer lease duration must be 10 seconds to 24 hours");
786
+ }
787
+ if (normalized.leaseRenewIntervalMs * 2 >= normalized.leaseDurationMs) {
788
+ throw new TypeError("materializer renewal interval must be less than half its lease");
789
+ }
790
+ if (normalized.maxAttempts > 1_000) throw new TypeError("materializer attempts exceed 1000");
791
+ if (normalized.maxSourceBytes > EDITABLE_ARTIFACT_MATERIALIZER_MAX_SOURCE_BYTES) {
792
+ throw new TypeError("materializer source limit exceeds the protocol maximum");
793
+ }
794
+ if (normalized.maxOutputBytes > EDITABLE_ARTIFACT_MATERIALIZER_MAX_OUTPUT_BYTES) {
795
+ throw new TypeError("materializer output limit exceeds the protocol maximum");
796
+ }
797
+ return normalized;
798
+ }
799
+
800
+ function validateClaimedJob(
801
+ job: ClaimedEditableArtifactMaterialization,
802
+ owner: string,
803
+ kernel: NativeEditableArtifactMaterializerIdentity,
804
+ ): EditableArtifactMaterializationLease {
805
+ const lease = rawLease(job, owner);
806
+ if (job.leaseOwner !== owner) throw new TypeError("claimed job belongs to another owner");
807
+ positiveInteger(job.targetHeadSequence + 1, "target head sequence + 1");
808
+ positiveInteger(job.sourceByteSize, "source byte size");
809
+ positiveInteger(job.modelSchemaVersion, "model schema version");
810
+ positiveInteger(job.operationProtocolVersion, "operation protocol version");
811
+ positiveInteger(job.snapshotProtocolVersion, "snapshot protocol version");
812
+ positiveInteger(job.attemptCount, "attempt count");
813
+ stableId(job.artifactId, "artifact id");
814
+ stableId(job.jobId, "job id");
815
+ stableId(job.inputSnapshotId, "input snapshot id");
816
+ if (job.versionId !== null) stableId(job.versionId, "version id");
817
+ canonicalHash(job.stateHash, "state hash");
818
+ canonicalHash(job.sourceContentHash, "source content hash");
819
+ canonicalHash(job.optionsHash, "options hash");
820
+ canonicalHash(job.fontRegistryHash, "font registry hash");
821
+ canonicalHash(job.policyHash, "policy hash");
822
+ boundedText(job.sourceObjectReference, "source object reference", 2_048);
823
+ boundedText(job.sourceMimeType, "source mime type", 256);
824
+ boundedText(job.codecId, "codec id", 128);
825
+ boundedText(job.codecVersion, "codec version", 128);
826
+ boundedText(job.kernelVersion, "kernel version", EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES);
827
+ validateFormatForModality(job.modality, job.format);
828
+ assertJobKernelCompatibility(job, kernel);
829
+ return lease;
830
+ }
831
+
832
+ function rawLease(
833
+ job: ClaimedEditableArtifactMaterialization,
834
+ owner: string,
835
+ ): EditableArtifactMaterializationLease {
836
+ boundedText(job.scope?.accountId, "account id", 128);
837
+ boundedText(job.scope?.workspaceId, "workspace id", 128);
838
+ stableId(job.artifactId, "artifact id");
839
+ stableId(job.jobId, "job id");
840
+ positiveInteger(job.attemptCount, "attempt count");
841
+ validateOwner(owner);
842
+ return Object.freeze({
843
+ scope: Object.freeze({ ...job.scope }),
844
+ artifactId: job.artifactId,
845
+ jobId: job.jobId,
846
+ owner,
847
+ attemptCount: job.attemptCount,
848
+ });
849
+ }
850
+
851
+ function assertNativeKernelIdentity(
852
+ identity: NativeEditableArtifactMaterializerIdentity,
853
+ allowUnsandboxedDevelopment = false,
854
+ ): void {
855
+ if (
856
+ identity.kind !== "native" ||
857
+ identity.isolation !== "subprocess" ||
858
+ identity.officeAutomation !== false
859
+ ) {
860
+ throw new Error("Editable artifact materializer requires an isolated native kernel");
861
+ }
862
+ if (identity.processProtocolVersion !== 1) {
863
+ throw new Error("Editable artifact materializer subprocess protocol is not enforced");
864
+ }
865
+ if (identity.sandboxEnforced) {
866
+ if (identity.network !== "denied") {
867
+ throw new Error("Editable artifact materializer sandbox network policy is invalid");
868
+ }
869
+ positiveInteger(identity.memoryLimitBytes, "kernel memory limit");
870
+ positiveInteger(identity.cpuTimeLimitMs, "kernel CPU time limit");
871
+ positiveInteger(identity.fileDescriptorLimit, "kernel file descriptor limit");
872
+ positiveInteger(identity.processLimit, "kernel process limit");
873
+ positiveInteger(identity.fileSizeLimitBytes, "kernel file size limit");
874
+ } else if (
875
+ !allowUnsandboxedDevelopment ||
876
+ identity.network !== "host" ||
877
+ identity.memoryLimitBytes !== 0 ||
878
+ identity.cpuTimeLimitMs !== 0 ||
879
+ identity.fileDescriptorLimit !== 0 ||
880
+ identity.processLimit !== 0 ||
881
+ identity.fileSizeLimitBytes !== 0
882
+ ) {
883
+ throw new Error("Editable artifact materializer subprocess protocol is not enforced");
884
+ }
885
+ positiveInteger(identity.maxOutputBytes, "kernel output limit");
886
+ boundedText(identity.kernelVersion, "kernel version", EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES);
887
+ boundedText(identity.runtimeTarget, "kernel runtime target", 128);
888
+ canonicalHash(identity.fontRegistryHash, "font registry hash");
889
+ canonicalHash(identity.policyHash, "policy hash");
890
+ if (!identity.codecVersions || typeof identity.codecVersions !== "object") {
891
+ throw new Error("Editable artifact materializer codec registry is unavailable");
892
+ }
893
+ for (const [codecId, version] of Object.entries(identity.codecVersions)) {
894
+ boundedText(codecId, "codec id", 128);
895
+ boundedText(version, "codec version", 128);
896
+ }
897
+ for (const [label, values] of [
898
+ ["model schema versions", identity.supportedModelSchemaVersions],
899
+ ["operation protocol versions", identity.supportedOperationProtocolVersions],
900
+ ["snapshot protocol versions", identity.supportedSnapshotProtocolVersions],
901
+ ] as const) {
902
+ if (!Array.isArray(values) || values.length === 0 || values.length > 64) {
903
+ throw new Error(`Editable artifact kernel ${label} are invalid`);
904
+ }
905
+ const unique = new Set<number>();
906
+ for (const value of values) {
907
+ positiveInteger(value, label);
908
+ if (unique.has(value)) throw new Error(`Editable artifact kernel ${label} repeat`);
909
+ unique.add(value);
910
+ }
911
+ }
912
+ }
913
+
914
+ function assertJobKernelCompatibility(
915
+ job: ClaimedEditableArtifactMaterialization,
916
+ identity: NativeEditableArtifactMaterializerIdentity,
917
+ ): void {
918
+ const compatible =
919
+ identity.kernelVersion === job.kernelVersion &&
920
+ identity.codecVersions[job.codecId] === job.codecVersion &&
921
+ identity.fontRegistryHash === job.fontRegistryHash &&
922
+ identity.policyHash === job.policyHash &&
923
+ identity.supportedModelSchemaVersions.includes(job.modelSchemaVersion) &&
924
+ identity.supportedOperationProtocolVersions.includes(job.operationProtocolVersion) &&
925
+ identity.supportedSnapshotProtocolVersions.includes(job.snapshotProtocolVersion);
926
+ if (!compatible) throw new EditableArtifactMaterializerPermanentError("kernel_incompatible");
927
+ }
928
+
929
+ function validateKernelResult(
930
+ job: ClaimedEditableArtifactMaterialization,
931
+ result: NativeEditableArtifactMaterializationResult,
932
+ ): void {
933
+ if (
934
+ result.headSequence !== job.targetHeadSequence ||
935
+ result.stateHash !== job.stateHash ||
936
+ result.format !== job.format ||
937
+ result.mimeType !== mimeTypeForFormat(job.format) ||
938
+ result.codecId !== job.codecId ||
939
+ result.codecVersion !== job.codecVersion ||
940
+ result.kernelVersion !== job.kernelVersion ||
941
+ result.fontRegistryHash !== job.fontRegistryHash ||
942
+ result.policyHash !== job.policyHash ||
943
+ !result.chunks ||
944
+ typeof result.chunks[Symbol.asyncIterator] !== "function"
945
+ ) {
946
+ throw new EditableArtifactMaterializerPermanentError("kernel_result_mismatch");
947
+ }
948
+ if (result.byteSize !== undefined) positiveInteger(result.byteSize, "kernel output bytes");
949
+ if (result.contentHash !== undefined) canonicalHash(result.contentHash, "kernel output hash");
950
+ canonicalHash(result.semanticHash, "kernel semantic hash");
951
+ }
952
+
953
+ function validateIndependentVerification(
954
+ job: ClaimedEditableArtifactMaterialization,
955
+ written: {
956
+ opaqueReference: string;
957
+ byteSize: number;
958
+ contentHash: string;
959
+ contentType: string;
960
+ },
961
+ verified: VerifiedEditableArtifactMaterialization,
962
+ ): void {
963
+ if (
964
+ verified.objectReference !== written.opaqueReference ||
965
+ verified.byteSize !== written.byteSize ||
966
+ verified.contentHash !== written.contentHash ||
967
+ verified.mimeType !== written.contentType ||
968
+ verified.format !== job.format ||
969
+ verified.codecId !== job.codecId ||
970
+ verified.codecVersion !== job.codecVersion
971
+ ) {
972
+ throw new EditableArtifactMaterializerPermanentError("output_verification_failed");
973
+ }
974
+ }
975
+
976
+ function canonicalOptionsBytes(value: string, expectedHash: string): Uint8Array {
977
+ if (typeof value !== "string") {
978
+ throw new EditableArtifactMaterializerPermanentError("invalid_job_manifest");
979
+ }
980
+ const bytes = new TextEncoder().encode(value);
981
+ if (bytes.byteLength > EDITABLE_ARTIFACT_MATERIALIZER_MAX_OPTIONS_BYTES) {
982
+ throw new EditableArtifactMaterializerPermanentError("invalid_job_manifest");
983
+ }
984
+ try {
985
+ const parsed = JSON.parse(value) as unknown;
986
+ if (JSON.stringify(parsed) !== value) {
987
+ throw new Error("non-canonical options");
988
+ }
989
+ } catch {
990
+ throw new EditableArtifactMaterializerPermanentError("invalid_job_manifest");
991
+ }
992
+ if (hashBytes(bytes) !== expectedHash) {
993
+ throw new EditableArtifactMaterializerPermanentError("invalid_job_manifest");
994
+ }
995
+ return bytes;
996
+ }
997
+
998
+ function trackExactStream(
999
+ source: AsyncIterable<Uint8Array>,
1000
+ expectedByteSize: number,
1001
+ expectedContentHash: string,
1002
+ code: EditableArtifactMaterializerDeadLetterCode,
1003
+ diagnostic?: EditableArtifactMaterializerFailureDiagnostic,
1004
+ ): { chunks: AsyncIterable<Uint8Array>; done: Promise<void> } {
1005
+ let settle!: () => void;
1006
+ let reject!: (error: unknown) => void;
1007
+ const done = new Promise<void>((resolve, rejectPromise) => {
1008
+ settle = resolve;
1009
+ reject = rejectPromise;
1010
+ });
1011
+ let claimed = false;
1012
+ const chunks: AsyncIterable<Uint8Array> = Object.freeze({
1013
+ async *[Symbol.asyncIterator](): AsyncIterableIterator<Uint8Array> {
1014
+ if (claimed) {
1015
+ const error = new EditableArtifactMaterializerPermanentError(code, diagnostic);
1016
+ reject(error);
1017
+ throw error;
1018
+ }
1019
+ claimed = true;
1020
+ const digest = createHash("sha256");
1021
+ let byteSize = 0;
1022
+ try {
1023
+ for await (const chunk of source) {
1024
+ if (!(chunk instanceof Uint8Array) || chunk.byteLength === 0) {
1025
+ throw new EditableArtifactMaterializerPermanentError(code, diagnostic);
1026
+ }
1027
+ byteSize += chunk.byteLength;
1028
+ if (byteSize > expectedByteSize) {
1029
+ throw new EditableArtifactMaterializerPermanentError(code, diagnostic);
1030
+ }
1031
+ digest.update(chunk);
1032
+ yield chunk.slice();
1033
+ }
1034
+ if (byteSize !== expectedByteSize) {
1035
+ throw new EditableArtifactMaterializerPermanentError(code, diagnostic);
1036
+ }
1037
+ const contentHash = `sha256:${digest.digest("hex")}`;
1038
+ if (contentHash !== expectedContentHash) {
1039
+ throw new EditableArtifactMaterializerPermanentError(code, diagnostic);
1040
+ }
1041
+ settle();
1042
+ } catch (error) {
1043
+ const diagnosed = diagnoseSourceReaderFailure(error, "stream_identity");
1044
+ reject(diagnosed);
1045
+ throw diagnosed;
1046
+ }
1047
+ },
1048
+ });
1049
+ return { chunks, done };
1050
+ }
1051
+
1052
+ function diagnoseSourceReaderFailure(
1053
+ error: unknown,
1054
+ subcode: Extract<
1055
+ EditableArtifactMaterializerFailureDiagnostic["subcode"],
1056
+ "open" | "stream_identity" | "revalidate"
1057
+ >,
1058
+ ): unknown {
1059
+ const code = permanentDependencyFailure(error);
1060
+ return code
1061
+ ? new EditableArtifactMaterializerPermanentError(code, { stage: "source_reader", subcode })
1062
+ : error;
1063
+ }
1064
+
1065
+ function deterministicResultIds(
1066
+ job: ClaimedEditableArtifactMaterialization,
1067
+ contentHash: string,
1068
+ ): { resultId: string; blobRefId: string } {
1069
+ return {
1070
+ resultId: deterministicStableId("result", job, contentHash),
1071
+ blobRefId: deterministicStableId("blob", job, contentHash),
1072
+ };
1073
+ }
1074
+
1075
+ function deterministicStableId(
1076
+ kind: "result" | "blob",
1077
+ job: ClaimedEditableArtifactMaterialization,
1078
+ contentHash: string,
1079
+ ): string {
1080
+ const digest = createHash("sha256");
1081
+ digest.update(`OpenGeni editable artifact materialization ${kind}\0v1\0`, "utf8");
1082
+ for (const value of [
1083
+ job.scope.accountId,
1084
+ job.scope.workspaceId,
1085
+ job.artifactId,
1086
+ job.jobId,
1087
+ contentHash,
1088
+ ]) {
1089
+ const bytes = Buffer.from(value, "utf8");
1090
+ const length = Buffer.allocUnsafe(4);
1091
+ length.writeUInt32BE(bytes.byteLength);
1092
+ digest.update(length);
1093
+ digest.update(bytes);
1094
+ }
1095
+ const id = digest.digest("hex").slice(0, 32);
1096
+ return /^0+$/u.test(id) ? `1${id.slice(1)}` : id;
1097
+ }
1098
+
1099
+ function hashBytes(bytes: Uint8Array): string {
1100
+ return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
1101
+ }
1102
+
1103
+ function validateFormatForModality(
1104
+ modality: EditableArtifactMaterializationModality,
1105
+ format: EditableArtifactMaterializationFormat,
1106
+ ): void {
1107
+ const allowed: Readonly<Record<EditableArtifactMaterializationModality, readonly string[]>> = {
1108
+ spreadsheet: ["xlsx", "pdf", "png", "webp"],
1109
+ presentation: ["pptx", "pdf", "png", "webp"],
1110
+ document: ["docx", "pdf", "png", "webp"],
1111
+ };
1112
+ if (!allowed[modality]?.includes(format)) {
1113
+ throw new TypeError("materialization format does not match artifact modality");
1114
+ }
1115
+ }
1116
+
1117
+ export function mimeTypeForFormat(
1118
+ format: EditableArtifactMaterializationFormat,
1119
+ ): EditableArtifactMaterializationMimeType {
1120
+ switch (format) {
1121
+ case "xlsx":
1122
+ return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
1123
+ case "pptx":
1124
+ return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
1125
+ case "docx":
1126
+ return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
1127
+ case "pdf":
1128
+ return "application/pdf";
1129
+ case "png":
1130
+ return "image/png";
1131
+ case "webp":
1132
+ return "image/webp";
1133
+ }
1134
+ }
1135
+
1136
+ function validateOwner(value: unknown): string {
1137
+ if (
1138
+ typeof value !== "string" ||
1139
+ value.length < 1 ||
1140
+ value.length > 256 ||
1141
+ value.trim() !== value ||
1142
+ !/^[A-Za-z0-9._:-]+$/u.test(value)
1143
+ ) {
1144
+ throw new TypeError("materializer owner is invalid");
1145
+ }
1146
+ return value;
1147
+ }
1148
+
1149
+ function stableId(value: unknown, label: string): string {
1150
+ if (typeof value !== "string" || !/^[0-9a-f]{32}$/u.test(value) || /^0+$/u.test(value)) {
1151
+ throw new TypeError(`${label} is invalid`);
1152
+ }
1153
+ return value;
1154
+ }
1155
+
1156
+ function canonicalHash(value: unknown, label: string): string {
1157
+ if (typeof value !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(value)) {
1158
+ throw new TypeError(`${label} is invalid`);
1159
+ }
1160
+ return value;
1161
+ }
1162
+
1163
+ function boundedText(value: unknown, label: string, maxBytes: number): string {
1164
+ if (
1165
+ typeof value !== "string" ||
1166
+ value.length === 0 ||
1167
+ new TextEncoder().encode(value).byteLength > maxBytes ||
1168
+ value.trim() !== value ||
1169
+ /[\u0000-\u001f\u007f]/u.test(value)
1170
+ ) {
1171
+ throw new TypeError(`${label} is invalid`);
1172
+ }
1173
+ return value;
1174
+ }
1175
+
1176
+ function positiveInteger(value: unknown, label: string): number {
1177
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
1178
+ throw new TypeError(`${label} must be a positive safe integer`);
1179
+ }
1180
+ return value;
1181
+ }
1182
+
1183
+ function isLeaseFence(error: unknown): boolean {
1184
+ return (
1185
+ error instanceof EditableArtifactMaterializerLeaseLostError ||
1186
+ (typeof error === "object" &&
1187
+ error !== null &&
1188
+ "code" in error &&
1189
+ error.code === "lease_fenced")
1190
+ );
1191
+ }
1192
+
1193
+ function permanentDependencyFailure(
1194
+ error: unknown,
1195
+ ): EditableArtifactMaterializerDeadLetterCode | null {
1196
+ if (error instanceof EditableArtifactMaterializerPermanentError) return error.code;
1197
+ if (error instanceof BoundedObjectReadError) {
1198
+ if (error.code === "size_limit") return "source_size_limit";
1199
+ if (
1200
+ error.code === "object_changed" ||
1201
+ error.code === "truncated" ||
1202
+ error.code === "object_missing" ||
1203
+ error.code === "invalid_request"
1204
+ ) {
1205
+ return "source_identity_mismatch";
1206
+ }
1207
+ }
1208
+ if (error instanceof BoundedObjectWriteError) {
1209
+ if (error.code === "size_limit") return "output_size_limit";
1210
+ if (
1211
+ error.code === "content_hash_mismatch" ||
1212
+ error.code === "readback_mismatch" ||
1213
+ error.code === "truncated" ||
1214
+ error.code === "invalid_request"
1215
+ ) {
1216
+ return "output_verification_failed";
1217
+ }
1218
+ }
1219
+ return null;
1220
+ }
1221
+
1222
+ function isAbortError(error: unknown): boolean {
1223
+ return error instanceof DOMException
1224
+ ? error.name === "AbortError"
1225
+ : error instanceof Error && error.name === "AbortError";
1226
+ }
1227
+
1228
+ function throwIfAborted(signal: AbortSignal): void {
1229
+ if (signal.aborted) throw signal.reason ?? abortError();
1230
+ }
1231
+
1232
+ function abortError(): DOMException {
1233
+ return new DOMException("Operation aborted", "AbortError");
1234
+ }
1235
+
1236
+ function combineAbortSignals(
1237
+ first: AbortSignal | undefined,
1238
+ second: AbortSignal,
1239
+ ): { signal: AbortSignal; dispose(): void } {
1240
+ const controller = new AbortController();
1241
+ const sources = first ? [first, second] : [second];
1242
+ const listeners: Array<readonly [AbortSignal, () => void]> = [];
1243
+ for (const source of sources) {
1244
+ const listener = () => controller.abort(source.reason);
1245
+ if (source.aborted) listener();
1246
+ else {
1247
+ source.addEventListener("abort", listener, { once: true });
1248
+ listeners.push([source, listener]);
1249
+ }
1250
+ }
1251
+ return {
1252
+ signal: controller.signal,
1253
+ dispose() {
1254
+ for (const [source, listener] of listeners) {
1255
+ source.removeEventListener("abort", listener);
1256
+ }
1257
+ },
1258
+ };
1259
+ }
1260
+
1261
+ async function sleepOrAbort(
1262
+ scheduler: EditableArtifactMaterializerSchedulerPort,
1263
+ milliseconds: number,
1264
+ signal: AbortSignal,
1265
+ ): Promise<boolean> {
1266
+ try {
1267
+ await scheduler.sleep(milliseconds, signal);
1268
+ return true;
1269
+ } catch (error) {
1270
+ if (signal.aborted || isAbortError(error)) return false;
1271
+ throw error;
1272
+ }
1273
+ }
1274
+
1275
+ function mutableSummary(): MutableSummary {
1276
+ return {
1277
+ claimed: 0,
1278
+ succeeded: 0,
1279
+ deadLettered: 0,
1280
+ retryDeferred: 0,
1281
+ leaseLost: 0,
1282
+ cancelled: 0,
1283
+ claimFailed: false,
1284
+ };
1285
+ }
1286
+
1287
+ function freezeSummary(summary: MutableSummary): EditableArtifactMaterializerPassSummary {
1288
+ return Object.freeze({ ...summary });
1289
+ }