@opengeni/worker-bundle 0.16.29 → 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 (168) hide show
  1. package/dist/activities/agent-turn.d.ts +85 -19
  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 +1 -0
  8. package/dist/activities/documents.d.ts +3 -2
  9. package/dist/activities/environment.d.ts +11 -8
  10. package/dist/activities/expiring-material-renewal.d.ts +1 -1
  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 +1 -1
  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 +2 -2
  25. package/dist/activities/retained-screenshots.d.ts +36 -0
  26. package/dist/activities/rig-verification.d.ts +82 -5
  27. package/dist/activities/run-credential-renewal.d.ts +1 -1
  28. package/dist/activities/run-input.d.ts +3 -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 +10 -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 -150
  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/concurrency.d.ts +108 -5
  64. package/dist/editable-artifact-hint-broker.d.ts +49 -0
  65. package/dist/editable-artifact-materializer-launcher.d.ts +49 -0
  66. package/dist/editable-artifact-materializer-service.d.ts +108 -0
  67. package/dist/editable-artifact-materializer-storage.d.ts +12 -0
  68. package/dist/editable-artifact-materializer-subprocess.d.ts +50 -0
  69. package/dist/editable-artifact-materializer.d.ts +262 -0
  70. package/dist/editable-artifact-outbox-dispatcher.d.ts +44 -0
  71. package/dist/editable-artifact-outbox-service.d.ts +70 -0
  72. package/dist/host-export.d.ts +1 -1
  73. package/dist/index.d.ts +176 -10
  74. package/dist/index.js +662 -17374
  75. package/dist/index.js.map +1 -1
  76. package/dist/memory-pressure-guard.d.ts +57 -0
  77. package/dist/model-checkpoint-memory-collector.d.ts +22 -0
  78. package/dist/observability-metrics.d.ts +33 -0
  79. package/dist/sandbox-reaper-contract.d.ts +40 -0
  80. package/dist/sandbox-reaper-timeout.d.ts +14 -0
  81. package/dist/sandbox-resume.d.ts +34 -7
  82. package/dist/sandbox-routing.d.ts +2 -0
  83. package/dist/worker-service-lifecycle.d.ts +6 -2
  84. package/dist/workflow-bundle.js +1043 -363
  85. package/dist/workflows/activities.d.ts +7 -1
  86. package/dist/workflows/document-index.d.ts +1 -1
  87. package/dist/workflows/knowledge-source-sync.d.ts +13 -0
  88. package/dist/workflows/rig-verification.d.ts +1 -1
  89. package/dist/workflows/sandbox-reaper.d.ts +8 -0
  90. package/dist/workflows/scheduled-tasks.d.ts +1 -1
  91. package/dist/workflows/session.d.ts +2 -2
  92. package/dist/workflows/video-generation.d.ts +10 -0
  93. package/dist/workflows/workflow-wake.d.ts +1 -1
  94. package/dist/workflows.d.ts +9 -7
  95. package/package.json +34 -15
  96. package/src/activities/agent-turn.ts +1470 -246
  97. package/src/activities/api-integrations.ts +138 -0
  98. package/src/activities/codemode-dispatcher.ts +335 -0
  99. package/src/activities/codemode-token-renewal.ts +64 -0
  100. package/src/activities/codex-capacity.ts +6 -6
  101. package/src/activities/codex-image-generation.ts +56 -0
  102. package/src/activities/context-compaction.ts +38 -3
  103. package/src/activities/documents.ts +14 -4
  104. package/src/activities/environment.ts +45 -42
  105. package/src/activities/expiring-material-renewal.ts +1 -1
  106. package/src/activities/file-upload-reaper.ts +34 -3
  107. package/src/activities/gateway-image-generation.ts +146 -0
  108. package/src/activities/gateway-video-generation.ts +298 -0
  109. package/src/activities/generated-images.ts +860 -0
  110. package/src/activities/goals.ts +6 -2
  111. package/src/activities/google-drive-changes.ts +454 -0
  112. package/src/activities/image-generation-operation.ts +333 -0
  113. package/src/activities/image-generation-references.ts +118 -0
  114. package/src/activities/knowledge-source-sync-driver.ts +27 -0
  115. package/src/activities/knowledge-source-sync.ts +2840 -0
  116. package/src/activities/mcp-credentials.ts +1 -0
  117. package/src/activities/packs.ts +55 -55
  118. package/src/activities/retained-screenshot-reaper.ts +2 -2
  119. package/src/activities/retained-screenshots.ts +453 -28
  120. package/src/activities/rig-verification.ts +554 -43
  121. package/src/activities/run-input.ts +22 -6
  122. package/src/activities/sandbox-images.ts +167 -0
  123. package/src/activities/sandbox-lease.ts +1065 -483
  124. package/src/activities/scheduled-tasks.ts +77 -4
  125. package/src/activities/session-state.ts +4 -4
  126. package/src/activities/streaming.ts +42 -3
  127. package/src/activities/types.ts +87 -5
  128. package/src/activities/video-generation-admission.ts +270 -0
  129. package/src/activities/video-generation-credential.ts +34 -0
  130. package/src/activities/video-generation-reconciliation.ts +578 -0
  131. package/src/activities/video-media-validation.ts +326 -0
  132. package/src/activities/video-output-retention.ts +314 -0
  133. package/src/activities/video-reference-staging.ts +263 -0
  134. package/src/activities/workflow-wake.ts +2 -2
  135. package/src/activities/workspace-capture.ts +44 -10
  136. package/src/activities-control.ts +54 -0
  137. package/src/activities-turn.ts +40 -0
  138. package/src/activities.ts +48 -124
  139. package/src/activity-services.ts +62 -0
  140. package/src/artifact-materializer-entry.ts +35 -0
  141. package/src/artifact-outbox-entry.ts +29 -0
  142. package/src/concurrency.ts +484 -6
  143. package/src/editable-artifact-hint-broker.ts +235 -0
  144. package/src/editable-artifact-materializer-launcher.ts +515 -0
  145. package/src/editable-artifact-materializer-service.ts +787 -0
  146. package/src/editable-artifact-materializer-storage.ts +413 -0
  147. package/src/editable-artifact-materializer-subprocess.ts +956 -0
  148. package/src/editable-artifact-materializer.ts +1289 -0
  149. package/src/editable-artifact-outbox-dispatcher.ts +244 -0
  150. package/src/editable-artifact-outbox-service.ts +438 -0
  151. package/src/index.ts +277 -72
  152. package/src/memory-pressure-guard.ts +489 -0
  153. package/src/model-checkpoint-memory-collector.ts +116 -0
  154. package/src/observability-metrics.ts +199 -4
  155. package/src/sandbox-reaper-contract.ts +73 -0
  156. package/src/sandbox-reaper-timeout.ts +79 -0
  157. package/src/sandbox-resume.ts +294 -153
  158. package/src/sandbox-routing.ts +19 -24
  159. package/src/worker-service-lifecycle.ts +80 -14
  160. package/src/workflows/activities.ts +30 -0
  161. package/src/workflows/file-upload-reaper.ts +3 -1
  162. package/src/workflows/knowledge-source-sync.ts +83 -0
  163. package/src/workflows/sandbox-reaper.ts +183 -21
  164. package/src/workflows/scheduled-tasks.ts +42 -6
  165. package/src/workflows/video-generation.ts +36 -0
  166. package/src/workflows.ts +17 -1
  167. package/dist/activities/toolspace-token-renewal.d.ts +0 -23
  168. package/src/activities/toolspace-token-renewal.ts +0 -64
@@ -1,14 +1,36 @@
1
1
  import type { Settings } from "@opengeni/config";
2
- import type { WorkerOptions } from "@temporalio/worker";
2
+ import type { Observability } from "@opengeni/observability";
3
+ import type { ActivitySlotInfo, CustomSlotSupplier, SlotMarkUsedContext, SlotPermit, SlotReleaseContext, SlotReserveContext, WorkerOptions, WorkerTuner } from "@temporalio/worker";
4
+ /**
5
+ * Default fixed/HPA turn-worker admission contract. The configured fixed-mode
6
+ * ceiling may be lower, but every live Temporal permit reserves the complete
7
+ * hard budget until the runAgentTurn activity promise physically completes.
8
+ */
9
+ export declare const TURN_WORKER_MAX_CONCURRENT_TURNS = 16;
10
+ export declare const TURN_WORKER_HARD_MEMORY_BYTES_PER_TURN: number;
11
+ export declare const TURN_WORKER_NATIVE_HEADROOM_BYTES: number;
3
12
  export type TurnWorkerConcurrencySettings = Pick<Settings, "turnWorkerConcurrencyMode" | "turnWorkerMaxConcurrentTurns" | "turnWorkerTargetCpuUsage" | "turnWorkerTargetMemoryUsage">;
4
13
  export type TurnWorkerConcurrencyOptions = Pick<WorkerOptions, "maxConcurrentActivityTaskExecutions" | "tuner">;
5
14
  /**
6
- * Ordinary multi-worker deployments keep a fixed per-process ceiling so HPA or
7
- * an operator owns horizontal capacity. The single-machine profile selects the
8
- * resource tuner instead: Temporal admits activity slots while whole-system CPU
9
- * and memory remain below the configured targets, then stops polling more work.
15
+ * Fixed profiles keep a per-process ceiling. Resource-aware profiles retain a
16
+ * hard per-process maximum while Temporal meters new activity admission against
17
+ * cgroup/host CPU and memory. The ramp lets usage become visible before a burst
18
+ * can reserve the entire ceiling.
10
19
  */
11
20
  export declare function turnWorkerConcurrencyOptions(settings: TurnWorkerConcurrencySettings): TurnWorkerConcurrencyOptions;
21
+ export type TurnWorkerConcurrencyPlan = {
22
+ options: TurnWorkerConcurrencyOptions;
23
+ admission: MemoryAwareTurnSlotSupplier | null;
24
+ };
25
+ /**
26
+ * Build the runtime concurrency policy for a turn worker.
27
+ *
28
+ * Fixed/HPA deployments use the hard-reservation supplier below. The explicit
29
+ * non-HA single-machine profile keeps Temporal's native CPU/memory resource
30
+ * tuner because it controls whole-machine load rather than a pod cgroup; that
31
+ * profile documents that its configured maximum is not a per-turn reservation.
32
+ */
33
+ export declare function createTurnWorkerConcurrencyPlan(settings: TurnWorkerConcurrencySettings, options?: Omit<TurnAdmissionOptions, "maximumTurns">): TurnWorkerConcurrencyPlan;
12
34
  export declare function turnWorkerConcurrencyLogFields(settings: TurnWorkerConcurrencySettings): {
13
35
  concurrencyMode: "fixed" | "resource-based";
14
36
  maxConcurrentTurns: number;
@@ -17,3 +39,84 @@ export declare function turnWorkerConcurrencyLogFields(settings: TurnWorkerConcu
17
39
  };
18
40
  export declare const CONTROL_WORKER_MAX_CONCURRENT_ACTIVITIES = 32;
19
41
  export declare const CONTROL_WORKER_MAX_CONCURRENT_WORKFLOW_TASKS = 40;
42
+ export type CgroupMemorySnapshot = {
43
+ currentBytes: number;
44
+ limitBytes: number | null;
45
+ source: "cgroup-v1" | "cgroup-v2" | "process";
46
+ };
47
+ export type TurnAdmissionSnapshot = {
48
+ baselineBytes: number;
49
+ currentBytes: number;
50
+ limitBytes: number | null;
51
+ hardBytesPerTurn: number;
52
+ nativeHeadroomBytes: number;
53
+ maximumTurns: number;
54
+ memoryBoundCapacity: number;
55
+ reservedSlots: number;
56
+ usedSlots: number;
57
+ availableSlots: number;
58
+ };
59
+ export type TurnAdmissionOptions = {
60
+ maximumTurns?: number;
61
+ hardBytesPerTurn?: number;
62
+ nativeHeadroomBytes?: number;
63
+ memorySnapshot?: () => CgroupMemorySnapshot;
64
+ retryDelayMs?: number;
65
+ observability?: Observability;
66
+ };
67
+ /**
68
+ * Temporal custom activity-slot supplier for turn workers.
69
+ *
70
+ * A permit is required before Temporal polls a task. Reservation is allowed
71
+ * only when both independent safety checks pass:
72
+ *
73
+ * baseline + reserved-after × hard-turn-budget + native headroom <= limit
74
+ * current + reserved-after × hard-turn-budget + native headroom <= limit
75
+ *
76
+ * The first check enforces the release contract even when current RSS happens
77
+ * to be low. The second accounts for native/retained memory observed after
78
+ * startup and keeps the complete hard budget reserved for every live permit.
79
+ * A used permit is not evidence that its allocation is already visible in the
80
+ * cgroup, and unrelated native growth cannot safely be attributed to a turn.
81
+ * Kubernetes OOM is never an admission mechanism.
82
+ */
83
+ export declare class MemoryAwareTurnSlotSupplier implements CustomSlotSupplier<ActivitySlotInfo> {
84
+ readonly type: "custom";
85
+ private readonly owner;
86
+ private readonly permits;
87
+ private baselineBytes;
88
+ private readonly maximumTurns;
89
+ private readonly hardBytesPerTurn;
90
+ private readonly nativeHeadroomBytes;
91
+ private readonly memorySnapshot;
92
+ private readonly retryDelayMs;
93
+ private readonly observability;
94
+ constructor(options?: TurnAdmissionOptions);
95
+ reserveSlot(_ctx: SlotReserveContext, abortSignal: AbortSignal): Promise<SlotPermit>;
96
+ tryReserveSlot(_ctx: SlotReserveContext): SlotPermit | null;
97
+ markSlotUsed(ctx: SlotMarkUsedContext<ActivitySlotInfo>): void;
98
+ releaseSlot(ctx: SlotReleaseContext<ActivitySlotInfo>): void;
99
+ snapshot(memory?: CgroupMemorySnapshot): TurnAdmissionSnapshot;
100
+ /**
101
+ * Finalize the admission baseline after Temporal/native construction.
102
+ * Worker.create can retain memory after the constructor's provisional
103
+ * sample. That initialization delta must remain in the baseline for every
104
+ * later projection rather than competing with turn reservations.
105
+ */
106
+ finalizeStartupBaseline(): void;
107
+ private reserveIfSafe;
108
+ private memoryAllowsAnother;
109
+ private availableSlots;
110
+ private memoryBoundCapacity;
111
+ private usedSlots;
112
+ private ownedPermit;
113
+ private refreshMetrics;
114
+ }
115
+ export declare function createTurnWorkerTuner(options?: TurnAdmissionOptions): {
116
+ tuner: WorkerTuner;
117
+ admission: MemoryAwareTurnSlotSupplier;
118
+ };
119
+ export declare function readCgroupMemorySnapshot(): CgroupMemorySnapshot;
120
+ export declare function parseCgroupLimitValue(value: string): number | null;
121
+ export declare function parseCgroupCurrentValue(value: string): number;
122
+ export declare const CONTROL_WORKER_MAX_CACHED_WORKFLOWS = 64;
@@ -0,0 +1,49 @@
1
+ import { type EditableArtifactHintBrokerPort } from "@opengeni/core";
2
+ import { type NatsConnection } from "@opengeni/events";
3
+ export type EditableArtifactHintNatsAuth = Readonly<{
4
+ kind: "user-password";
5
+ user: string;
6
+ pass: string;
7
+ }> | Readonly<{
8
+ kind: "token";
9
+ token: string;
10
+ }> | Readonly<{
11
+ kind: "anonymous";
12
+ }>;
13
+ export type EditableArtifactHintNatsBrokerOptions = Readonly<{
14
+ maxHintBytes?: number;
15
+ }>;
16
+ export type EditableArtifactHintNatsConnection = Pick<NatsConnection, "publish" | "flush" | "drain" | "close" | "closed" | "isClosed" | "isDraining">;
17
+ /**
18
+ * Core-NATS adapter for the durable outbox. A publish resolves only after a
19
+ * server round-trip flush ACK. Reconnect buffering may create duplicates after
20
+ * a timeout; hints are intentionally idempotent wakeups for durable gap-fill.
21
+ */
22
+ export declare class ConfirmedNatsEditableArtifactHintBroker implements EditableArtifactHintBrokerPort {
23
+ private readonly connection;
24
+ private readonly maxHintBytes;
25
+ constructor(connection: EditableArtifactHintNatsConnection, options?: EditableArtifactHintNatsBrokerOptions);
26
+ publish(input: Readonly<{
27
+ subject: string;
28
+ payload: Uint8Array;
29
+ signal: AbortSignal;
30
+ }>): Promise<void>;
31
+ /**
32
+ * A readiness probe must prove the server is reachable, not merely that the
33
+ * client object has not observed closure yet. `flush()` is a bounded NATS
34
+ * round trip and has the same acknowledgement semantics as publication.
35
+ */
36
+ check(signal?: AbortSignal): Promise<void>;
37
+ close(drainTimeoutMs?: number): Promise<void>;
38
+ }
39
+ export declare class EditableArtifactNatsHintPublishError extends Error {
40
+ readonly code: "broker_unavailable" | "broker_backpressure";
41
+ constructor(code: "broker_unavailable" | "broker_backpressure", message: string, options?: ErrorOptions);
42
+ }
43
+ /** Opens one resilient dispatcher identity; callers own `broker.close()`. */
44
+ export declare function connectEditableArtifactHintBroker(input: Readonly<{
45
+ natsUrl: string;
46
+ auth: EditableArtifactHintNatsAuth;
47
+ name?: string;
48
+ maxHintBytes?: number;
49
+ }>): Promise<ConfirmedNatsEditableArtifactHintBroker>;
@@ -0,0 +1,49 @@
1
+ import type { VerifiedEditableArtifactProcessLauncher } from "./editable-artifact-materializer-subprocess.js";
2
+ export type LinuxEditableArtifactLauncherOptions = Readonly<{
3
+ materializerExecutable: string;
4
+ bubblewrapExecutable: string;
5
+ prlimitExecutable: string;
6
+ runtimeRoot: string;
7
+ memoryLimitBytes: number;
8
+ cpuTimeLimitMs: number;
9
+ fileDescriptorLimit: number;
10
+ processLimit: number;
11
+ fileSizeLimitBytes: number;
12
+ probeExecutable?: string;
13
+ }>;
14
+ export type DevelopmentEditableArtifactLauncherOptions = Readonly<{
15
+ materializerExecutable: string;
16
+ explicitlyEnabled: boolean;
17
+ nodeEnvironment: string | undefined;
18
+ }>;
19
+ /**
20
+ * Current-host local development only. This deliberately reports that no OS
21
+ * sandbox, network namespace, or process resource limit is enforced. The
22
+ * caller must surface that degraded capability and can never select this path
23
+ * in production.
24
+ */
25
+ export declare function createDevelopmentEditableArtifactProcessLauncher(options: DevelopmentEditableArtifactLauncherOptions): Promise<VerifiedEditableArtifactProcessLauncher>;
26
+ /**
27
+ * Concrete production launcher for Linux. Isolation facts are established by
28
+ * a parent-run behavioral probe of the actual bwrap+prlimit command, never by
29
+ * the untrusted codec child. macOS/Windows require their own native launcher
30
+ * implementation and therefore fail closed in production today.
31
+ */
32
+ export declare function createLinuxEditableArtifactProcessLauncher(options: LinuxEditableArtifactLauncherOptions): Promise<VerifiedEditableArtifactProcessLauncher>;
33
+ export declare function linuxEditableArtifactSandboxArguments(input: Readonly<{
34
+ executable: string;
35
+ args: readonly string[];
36
+ runtimeRoot: string;
37
+ scratchLimitBytes: number;
38
+ }>): readonly string[];
39
+ export declare function linuxEditableArtifactPrlimitArguments(input: Readonly<{
40
+ memoryLimitBytes: number;
41
+ cpuSeconds: number;
42
+ fileDescriptorLimit: number;
43
+ processLimit: number;
44
+ fileSizeLimitBytes: number;
45
+ }>): readonly string[];
46
+ export declare function linuxEditableArtifactSandboxRootEntries(input: Readonly<{
47
+ executable: string;
48
+ runtimeRoot: string;
49
+ }>): readonly string[];
@@ -0,0 +1,108 @@
1
+ import { type Settings } from "@opengeni/config";
2
+ import { type Database } from "@opengeni/db";
3
+ import { type Observability } from "@opengeni/observability";
4
+ import { type ObjectStorage } from "@opengeni/storage";
5
+ import { EditableArtifactMaterializer, type EditableArtifactMaterializerPassSummary } from "./editable-artifact-materializer.js";
6
+ export type EditableArtifactRuntimeAuthority = Readonly<{
7
+ mode: "production";
8
+ environmentVariable: "OPENGENI_ARTIFACT_RUNTIME_MANIFEST";
9
+ manifestPath: string;
10
+ }> | Readonly<{
11
+ mode: "development-current-host";
12
+ environmentVariable: "OPENGENI_ARTIFACT_DEVELOPMENT_RUNTIME_MANIFEST";
13
+ manifestPath: string;
14
+ }>;
15
+ export type EditableArtifactMaterializerServiceState = "starting" | "ready" | "draining" | "stopped" | "failed";
16
+ export type EditableArtifactMaterializerService = Readonly<{
17
+ state(): EditableArtifactMaterializerServiceState;
18
+ run(): Promise<void>;
19
+ drain(reason?: string): boolean;
20
+ close(): Promise<void>;
21
+ dispatchOnce(signal?: AbortSignal): Promise<EditableArtifactMaterializerPassSummary>;
22
+ fetch(request: Request): Promise<Response>;
23
+ }>;
24
+ export type CreateEditableArtifactMaterializerServiceInput = Readonly<{
25
+ materializer: EditableArtifactMaterializer;
26
+ db: Database;
27
+ closeDatabase: () => Promise<void>;
28
+ observability: Observability;
29
+ serviceName: string;
30
+ environment: string;
31
+ deploymentRevision?: string;
32
+ readinessTimeoutMs?: number;
33
+ runtimeCapability?: Readonly<{
34
+ mode: EditableArtifactRuntimeAuthority["mode"];
35
+ sandboxEnforced: boolean;
36
+ }>;
37
+ }>;
38
+ export type ProductionEditableArtifactMaterializerServiceOptions = Readonly<{
39
+ settings: Settings;
40
+ /** Dedicated DSN; never defaults to settings.databaseUrl. */
41
+ databaseUrl: string;
42
+ declaredDatabaseRole: string;
43
+ executable: string;
44
+ bubblewrapExecutable: string | null;
45
+ prlimitExecutable: string | null;
46
+ runtimeAuthority: EditableArtifactRuntimeAuthority;
47
+ /** Explicit exception selected only by the validated local-dev sidecar config. */
48
+ allowUnsandboxedLocalDevelopment?: boolean;
49
+ skillFacadeEntrypoint: string;
50
+ owner: string;
51
+ objectStorage?: ObjectStorage;
52
+ batchSize?: number;
53
+ concurrency?: number;
54
+ leaseDurationMs?: number;
55
+ leaseRenewIntervalMs?: number;
56
+ pollIntervalMs?: number;
57
+ maxAttempts?: number;
58
+ memoryLimitBytes: number;
59
+ cpuTimeLimitMs: number;
60
+ fileDescriptorLimit: number;
61
+ processLimit: number;
62
+ fileSizeLimitBytes: number;
63
+ wallTimeoutMs: number;
64
+ nodeEnvironment?: string;
65
+ maxSourceBytes?: number;
66
+ maxOutputBytes?: number;
67
+ }>;
68
+ /**
69
+ * Compose the distinct production sidecar. It creates its own connection pool
70
+ * from the dedicated DSN and never reuses a control/turn worker handle.
71
+ */
72
+ export declare function createProductionEditableArtifactMaterializerService(options: ProductionEditableArtifactMaterializerServiceOptions): Promise<EditableArtifactMaterializerService>;
73
+ export declare function createEditableArtifactMaterializerService(input: CreateEditableArtifactMaterializerServiceInput): EditableArtifactMaterializerService;
74
+ export declare function assertDedicatedMaterializerDatabaseRole(db: Database): Promise<void>;
75
+ export type EditableArtifactMaterializerSidecarEnvironment = Readonly<{
76
+ databaseUrl: string;
77
+ declaredDatabaseRole: string;
78
+ executable: string;
79
+ bubblewrapExecutable: string | null;
80
+ prlimitExecutable: string | null;
81
+ runtimeAuthority: EditableArtifactRuntimeAuthority;
82
+ skillFacadeEntrypoint: string;
83
+ owner: string;
84
+ httpHostname: string;
85
+ httpPort: number;
86
+ batchSize: number;
87
+ concurrency: number;
88
+ leaseDurationMs: number;
89
+ leaseRenewIntervalMs: number;
90
+ pollIntervalMs: number;
91
+ maxAttempts: number;
92
+ memoryLimitBytes: number;
93
+ cpuTimeLimitMs: number;
94
+ fileDescriptorLimit: number;
95
+ processLimit: number;
96
+ fileSizeLimitBytes: number;
97
+ wallTimeoutMs: number;
98
+ maxSourceBytes: number;
99
+ maxOutputBytes: number;
100
+ allowUnsandboxedLocalDevelopment: boolean;
101
+ nodeEnvironment?: string;
102
+ }>;
103
+ export declare function readEditableArtifactMaterializerSidecarEnvironment(environment?: NodeJS.ProcessEnv): EditableArtifactMaterializerSidecarEnvironment | null;
104
+ export declare function createMaterializerSidecarFromEnvironment(environment?: NodeJS.ProcessEnv): Promise<Readonly<{
105
+ service: EditableArtifactMaterializerService;
106
+ httpHostname: string;
107
+ httpPort: number;
108
+ }> | null>;
@@ -0,0 +1,12 @@
1
+ import { type BoundedImmutableObjectWritePort, type BoundedObjectReadPort, type ObjectStorage } from "@opengeni/storage";
2
+ import { type EditableArtifactMaterializationSemanticVerifierPort, type EditableArtifactMaterializationVerifierPort } from "./editable-artifact-materializer.js";
3
+ /** Provider-versioned, immutable range reader. No whole-object fallback. */
4
+ export declare function createEditableArtifactObjectStorageReader(storage: ObjectStorage): BoundedObjectReadPort;
5
+ /** Conditional-create digest writer with independent version-pinned readback. */
6
+ export declare function createEditableArtifactObjectStorageWriter(storage: ObjectStorage): BoundedImmutableObjectWritePort;
7
+ /**
8
+ * Independent immutable readback + structural parser. When the native source
9
+ * projection supplies a semantic digest, a second isolated codec process must
10
+ * re-import the published Office bytes and prove that digest before success.
11
+ */
12
+ export declare function createEditableArtifactObjectStorageVerifier(storage: ObjectStorage, semanticVerifier: EditableArtifactMaterializationSemanticVerifierPort): EditableArtifactMaterializationVerifierPort;
@@ -0,0 +1,50 @@
1
+ import type { ChildProcessWithoutNullStreams } from "node:child_process";
2
+ import { type NativeEditableArtifactMaterializerPort } from "./editable-artifact-materializer.js";
3
+ export type NativeEditableArtifactSubprocessOptions = Readonly<{
4
+ /** Absolute path to the exact codec executable. Isolation belongs to launcher. */
5
+ executable: string;
6
+ launcher: VerifiedEditableArtifactProcessLauncher;
7
+ childEnvironment?: Readonly<Record<string, string>>;
8
+ /** Explicitly permits the current-host local-dev launcher; never set in production. */
9
+ allowUnsandboxedDevelopment?: boolean;
10
+ wallTimeoutMs: number;
11
+ maxSourceBytes: number;
12
+ maxOutputBytes: number;
13
+ probeTimeoutMs?: number;
14
+ }>;
15
+ export type VerifiedEditableArtifactProcessLauncher = Readonly<{
16
+ identity: Readonly<{
17
+ platform: string;
18
+ isolation: "subprocess";
19
+ network: "denied" | "host";
20
+ officeAutomation: false;
21
+ sandboxEnforced: boolean;
22
+ memoryLimitBytes: number;
23
+ cpuTimeLimitMs: number;
24
+ fileDescriptorLimit: number;
25
+ processLimit: number;
26
+ fileSizeLimitBytes: number;
27
+ }>;
28
+ spawn(input: {
29
+ executable: string;
30
+ args: readonly string[];
31
+ environment: Readonly<Record<string, string>>;
32
+ }): ChildProcessWithoutNullStreams;
33
+ }>;
34
+ export type NativeEditableArtifactSubprocessPort = NativeEditableArtifactMaterializerPort & Readonly<{
35
+ verifyMaterialization(input: {
36
+ format: string;
37
+ codecId: string;
38
+ codecVersion: string;
39
+ expectedSemanticHash: string;
40
+ byteSize: number;
41
+ chunks: AsyncIterable<Uint8Array>;
42
+ signal: AbortSignal;
43
+ }): Promise<void>;
44
+ }>;
45
+ /**
46
+ * Probe exact codec/kernel capabilities and combine them with independently
47
+ * verified parent-launcher isolation. The child is never trusted to attest its
48
+ * own network namespace, resource limits, or platform sandbox.
49
+ */
50
+ export declare function createNativeEditableArtifactSubprocessPort(options: NativeEditableArtifactSubprocessOptions): Promise<NativeEditableArtifactSubprocessPort>;
@@ -0,0 +1,262 @@
1
+ import type { BoundedImmutableObjectWritePort, BoundedObjectReadPort } from "@opengeni/storage";
2
+ /**
3
+ * The database role allowed to poll the cross-tenant materialization queue.
4
+ * It owns no table privileges; @opengeni/db exposes only fenced SECURITY
5
+ * DEFINER functions to this role.
6
+ */
7
+ export declare const EDITABLE_ARTIFACT_MATERIALIZER_DATABASE_ROLE: "opengeni_artifact_materializer";
8
+ export declare const EDITABLE_ARTIFACT_MATERIALIZER_MAX_SOURCE_BYTES: number;
9
+ export declare const EDITABLE_ARTIFACT_MATERIALIZER_MAX_OUTPUT_BYTES: number;
10
+ export declare const EDITABLE_ARTIFACT_MATERIALIZER_MAX_OPTIONS_BYTES: number;
11
+ export declare const EDITABLE_ARTIFACT_MATERIALIZER_MAX_ATTEMPTS = 20;
12
+ export type EditableArtifactMaterializationFormat = "xlsx" | "pptx" | "docx" | "pdf" | "png" | "webp";
13
+ export type EditableArtifactMaterializationModality = "spreadsheet" | "presentation" | "document";
14
+ export type EditableArtifactMaterializationMimeType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/pdf" | "image/png" | "image/webp";
15
+ export type EditableArtifactMaterializationScope = Readonly<{
16
+ accountId: string;
17
+ workspaceId: string;
18
+ }>;
19
+ /**
20
+ * One immutable, self-contained input manifest returned by the global claim
21
+ * function. The source snapshot covers exactly targetHeadSequence. There is
22
+ * deliberately no "current" lookup after claim and no unbounded DB tail read.
23
+ */
24
+ export type ClaimedEditableArtifactMaterialization = Readonly<{
25
+ scope: EditableArtifactMaterializationScope;
26
+ artifactId: string;
27
+ jobId: string;
28
+ versionId: string | null;
29
+ modality: EditableArtifactMaterializationModality;
30
+ inputSnapshotId: string;
31
+ targetHeadSequence: number;
32
+ stateHash: string;
33
+ sourceObjectReference: string;
34
+ sourceByteSize: number;
35
+ sourceContentHash: string;
36
+ sourceMimeType: string;
37
+ modelSchemaVersion: number;
38
+ operationProtocolVersion: number;
39
+ snapshotProtocolVersion: number;
40
+ format: EditableArtifactMaterializationFormat;
41
+ codecId: string;
42
+ /** Canonical UTF-8 JSON, bounded and hashed by optionsHash. */
43
+ normalizedOptions: string;
44
+ optionsHash: string;
45
+ codecVersion: string;
46
+ kernelVersion: string;
47
+ fontRegistryHash: string;
48
+ policyHash: string;
49
+ attemptCount: number;
50
+ leaseOwner: string;
51
+ leaseExpiresAt: string;
52
+ }>;
53
+ export type EditableArtifactMaterializationLease = Readonly<{
54
+ scope: EditableArtifactMaterializationScope;
55
+ artifactId: string;
56
+ jobId: string;
57
+ owner: string;
58
+ attemptCount: number;
59
+ }>;
60
+ export interface EditableArtifactMaterializationStorePort {
61
+ claim(input: {
62
+ owner: string;
63
+ leaseDurationMs: number;
64
+ limit: number;
65
+ }): Promise<readonly ClaimedEditableArtifactMaterialization[]>;
66
+ renew(input: EditableArtifactMaterializationLease & {
67
+ leaseDurationMs: number;
68
+ }): Promise<string>;
69
+ succeed(input: EditableArtifactMaterializationLease & {
70
+ resultId: string;
71
+ blobRefId: string;
72
+ objectReference: string;
73
+ byteSize: number;
74
+ contentHash: string;
75
+ mimeType: EditableArtifactMaterializationMimeType;
76
+ verifiedAt: string;
77
+ }): Promise<unknown>;
78
+ fail(input: EditableArtifactMaterializationLease & {
79
+ errorCode: string;
80
+ }): Promise<unknown>;
81
+ }
82
+ export type NativeEditableArtifactMaterializerIdentity = Readonly<{
83
+ kind: "native";
84
+ /** Parent-owned launcher facts, never copied from the codec child. */
85
+ isolation: "subprocess";
86
+ network: "denied" | "host";
87
+ officeAutomation: false;
88
+ processProtocolVersion: 1;
89
+ sandboxEnforced: boolean;
90
+ memoryLimitBytes: number;
91
+ cpuTimeLimitMs: number;
92
+ fileDescriptorLimit: number;
93
+ processLimit: number;
94
+ fileSizeLimitBytes: number;
95
+ maxOutputBytes: number;
96
+ kernelVersion: string;
97
+ codecVersions: Readonly<Record<string, string>>;
98
+ fontRegistryHash: string;
99
+ policyHash: string;
100
+ runtimeTarget: string;
101
+ supportedModelSchemaVersions: readonly number[];
102
+ supportedOperationProtocolVersions: readonly number[];
103
+ supportedSnapshotProtocolVersions: readonly number[];
104
+ }>;
105
+ export type NativeEditableArtifactMaterializationResult = Readonly<{
106
+ headSequence: number;
107
+ stateHash: string;
108
+ format: EditableArtifactMaterializationFormat;
109
+ mimeType: EditableArtifactMaterializationMimeType;
110
+ codecId: string;
111
+ codecVersion: string;
112
+ kernelVersion: string;
113
+ fontRegistryHash: string;
114
+ policyHash: string;
115
+ /** Optional precomputed facts; the independent writer/verifier still checks. */
116
+ byteSize?: number;
117
+ contentHash?: string;
118
+ /** Canonical semantics projected by the authoritative native source kernel. */
119
+ semanticHash: string;
120
+ chunks: AsyncIterable<Uint8Array>;
121
+ }>;
122
+ /**
123
+ * Production implementations must be a native Rust subprocess adapter. The
124
+ * adapter consumes a version-pinned stream, reconstructs and validates the
125
+ * canonical snapshot, and exports without Office/COM or network access.
126
+ */
127
+ export interface NativeEditableArtifactMaterializerPort {
128
+ readonly identity: NativeEditableArtifactMaterializerIdentity;
129
+ materialize(input: {
130
+ job: ClaimedEditableArtifactMaterialization;
131
+ normalizedOptions: Uint8Array;
132
+ snapshot: AsyncIterable<Uint8Array>;
133
+ signal: AbortSignal;
134
+ }): Promise<NativeEditableArtifactMaterializationResult>;
135
+ }
136
+ export type VerifiedEditableArtifactMaterialization = Readonly<{
137
+ objectReference: string;
138
+ byteSize: number;
139
+ contentHash: string;
140
+ mimeType: EditableArtifactMaterializationMimeType;
141
+ format: EditableArtifactMaterializationFormat;
142
+ codecId: string;
143
+ codecVersion: string;
144
+ }>;
145
+ /** Independent reader/parser. It must not reuse the exporting codec process. */
146
+ export interface EditableArtifactMaterializationVerifierPort {
147
+ verify(input: {
148
+ objectReference: string;
149
+ expectedByteSize: number;
150
+ expectedContentHash: string;
151
+ expectedMimeType: EditableArtifactMaterializationMimeType;
152
+ format: EditableArtifactMaterializationFormat;
153
+ codecId: string;
154
+ codecVersion: string;
155
+ expectedSemanticHash: string;
156
+ maxBytes: number;
157
+ signal: AbortSignal;
158
+ }): Promise<VerifiedEditableArtifactMaterialization>;
159
+ }
160
+ export interface EditableArtifactMaterializationSemanticVerifierPort {
161
+ verify(input: {
162
+ format: EditableArtifactMaterializationFormat;
163
+ codecId: string;
164
+ codecVersion: string;
165
+ expectedSemanticHash: string;
166
+ byteSize: number;
167
+ chunks: AsyncIterable<Uint8Array>;
168
+ signal: AbortSignal;
169
+ }): Promise<void>;
170
+ }
171
+ export interface EditableArtifactMaterializerSchedulerPort {
172
+ sleep(milliseconds: number, signal: AbortSignal): Promise<void>;
173
+ }
174
+ export interface EditableArtifactMaterializerClockPort {
175
+ now(): Date;
176
+ }
177
+ export interface EditableArtifactMaterializerLoggerPort {
178
+ warn(message: string, attributes: Readonly<Record<string, unknown>>): void;
179
+ }
180
+ export type EditableArtifactMaterializerMetricOutcome = "claimed" | "succeeded" | "dead_lettered" | "retry_deferred" | "lease_lost" | "cancelled" | "claim_failed";
181
+ export interface EditableArtifactMaterializerMetricsPort {
182
+ increment(outcome: EditableArtifactMaterializerMetricOutcome, count?: number): void;
183
+ }
184
+ export type EditableArtifactMaterializerOptions = Readonly<{
185
+ owner: string;
186
+ batchSize?: number;
187
+ concurrency?: number;
188
+ leaseDurationMs?: number;
189
+ leaseRenewIntervalMs?: number;
190
+ pollIntervalMs?: number;
191
+ claimBackoffMs?: number;
192
+ maxAttempts?: number;
193
+ maxSourceBytes?: number;
194
+ maxOutputBytes?: number;
195
+ }>;
196
+ export type EditableArtifactMaterializerDependencies = Readonly<{
197
+ store: EditableArtifactMaterializationStorePort;
198
+ sourceReader: BoundedObjectReadPort;
199
+ outputWriter: BoundedImmutableObjectWritePort;
200
+ outputVerifier: EditableArtifactMaterializationVerifierPort;
201
+ kernel: NativeEditableArtifactMaterializerPort;
202
+ scheduler: EditableArtifactMaterializerSchedulerPort;
203
+ clock: EditableArtifactMaterializerClockPort;
204
+ logger?: EditableArtifactMaterializerLoggerPort;
205
+ metrics?: EditableArtifactMaterializerMetricsPort;
206
+ }>;
207
+ export type EditableArtifactMaterializerPassSummary = Readonly<{
208
+ claimed: number;
209
+ succeeded: number;
210
+ deadLettered: number;
211
+ retryDeferred: number;
212
+ leaseLost: number;
213
+ cancelled: number;
214
+ claimFailed: boolean;
215
+ }>;
216
+ /** Closed, diagnostics-free terminal failure codes persisted in Postgres. */
217
+ export type EditableArtifactMaterializerDeadLetterCode = "invalid_job_manifest" | "source_identity_mismatch" | "source_size_limit" | "kernel_incompatible" | "kernel_result_mismatch" | "unsupported_semantics" | "output_size_limit" | "output_verification_failed" | "retry_exhausted";
218
+ export type EditableArtifactMaterializerFailureDiagnostic = Readonly<{
219
+ stage: "source_reader" | "native";
220
+ subcode: "open" | "content_type" | "stream_identity" | "revalidate" | "input_framing" | "snapshot_open" | "state_mismatch";
221
+ }>;
222
+ export declare class EditableArtifactMaterializerPermanentError extends Error {
223
+ readonly code: EditableArtifactMaterializerDeadLetterCode;
224
+ readonly diagnostic?: EditableArtifactMaterializerFailureDiagnostic | undefined;
225
+ constructor(code: EditableArtifactMaterializerDeadLetterCode, diagnostic?: EditableArtifactMaterializerFailureDiagnostic | undefined);
226
+ }
227
+ export declare class EditableArtifactMaterializerLeaseLostError extends Error {
228
+ constructor();
229
+ }
230
+ /**
231
+ * At-least-once materialization loop. Immutable content-addressed output makes
232
+ * recomputation safe; owner + attemptCount fences make DB settlement exact.
233
+ */
234
+ export declare class EditableArtifactMaterializer {
235
+ #private;
236
+ private readonly dependencies;
237
+ constructor(dependencies: EditableArtifactMaterializerDependencies, options: EditableArtifactMaterializerOptions, securityPolicy?: Readonly<{
238
+ allowUnsandboxedDevelopment?: boolean;
239
+ }>);
240
+ run(signal: AbortSignal): Promise<void>;
241
+ /** Concurrent triggers share one bounded claim pass. */
242
+ dispatchOnce(signal?: AbortSignal): Promise<EditableArtifactMaterializerPassSummary>;
243
+ drain(): Promise<void>;
244
+ }
245
+ export type ConfiguredEditableArtifactMaterializerInput = Readonly<{
246
+ enabled: boolean;
247
+ databaseRole: string | null | undefined;
248
+ objectStorageConfigured: boolean;
249
+ dependencies?: Partial<EditableArtifactMaterializerDependencies>;
250
+ options?: EditableArtifactMaterializerOptions;
251
+ /** Explicit local-development exception; production callers must omit it. */
252
+ allowUnsandboxedDevelopment?: boolean;
253
+ }>;
254
+ /**
255
+ * Production gate. Disabled is the default. Once enabled, every privileged
256
+ * dependency and the dedicated database role are mandatory—there is no
257
+ * reference-kernel, mutable-storage, or tenant-role fallback.
258
+ */
259
+ export declare function createConfiguredEditableArtifactMaterializer(input: ConfiguredEditableArtifactMaterializerInput): EditableArtifactMaterializer | null;
260
+ export declare const systemEditableArtifactMaterializerScheduler: EditableArtifactMaterializerSchedulerPort;
261
+ export declare const systemEditableArtifactMaterializerClock: EditableArtifactMaterializerClockPort;
262
+ export declare function mimeTypeForFormat(format: EditableArtifactMaterializationFormat): EditableArtifactMaterializationMimeType;