@molecule/api-deploy-rollout-sandbox 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-10-19T18:03:28.785Z
+-->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @molecule/api-deploy-rollout-sandbox
+
+Sandbox provider bond for the deploy-rollout core.
+
+One adapter over `@molecule/api-code-sandbox`, so E2B, Docker and Fly sandboxes
+share one rolling-deploy implementation. The deploy supplies its launch recipe and
+readiness gate; the bond supplies the lifecycle.
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+## Quick Start
+
+```typescript
+import { runRollout, setProvider } from '@molecule/api-deploy-rollout'
+import { provider } from '@molecule/api-deploy-rollout-default'
+import { createSandboxInstanceProvider } from '@molecule/api-deploy-rollout-sandbox'
+
+setProvider(provider)
+await runRollout({
+  provider: createSandboxInstanceProvider({
+    provider: sandboxProvider,
+    launch: (index) => launchReplica(index),
+    join: (instance) => upsertUpstream(instance.upstreamUrl ?? ''),
+  }),
+  current: oldInstances,
+  policy: { replicas: 2 },
+})
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-deploy-rollout-sandbox @molecule/api-code-sandbox @molecule/api-deploy-rollout
+```
+
+## API
+
+### Interfaces
+
+#### `SandboxInstance`
+
+One sandbox instance plus the address the edge dials.
+
+```typescript
+interface SandboxInstance extends RolloutInstance {
+  /** The live sandbox handle, when this run holds it. */
+  sandbox: Sandbox | null
+}
+```
+
+#### `SandboxInstanceOptions`
+
+How a sandbox rollout reaches and gates one app's instances.
+
+```typescript
+interface SandboxInstanceOptions {
+  /** The sandbox provider (E2B, Docker, Fly — any bonded provider). */
+  provider: SandboxProvider
+
+  /**
+   * Create and start the instance at `index`, resolving once it exists. This is the
+   * deploy's own recipe (tree transfer, env, boot script); the bond never guesses
+   * it.
+   */
+  launch: (index: number) => Promise<{ sandbox: Sandbox; upstreamUrl: string }>
+
+  /**
+   * A BLOCKING readiness gate with the caller's own semantics and budget. When
+   * present, `waitReady` delegates to it. When absent, the bond polls
+   * `readinessProbe` until `readinessTimeoutMs` elapses.
+   */
+  waitReady?: (instance: SandboxInstance) => Promise<boolean>
+
+  /**
+   * One HTTP readiness probe. Default: `GET <upstreamUrl>/health/ready`, falling
+   * back to `GET <upstreamUrl>/health` on 404/405 (an app scaffolded before the
+   * lifecycle bond answers only the latter).
+   */
+  readinessProbe?: (instance: SandboxInstance) => Promise<boolean>
+
+  /** How long the bond's own readiness poll may take. Defaults to 120 s. */
+  readinessTimeoutMs?: number
+
+  /** Probe cadence for the bond's own readiness poll. Defaults to 2000 ms. */
+  readinessPollMs?: number
+
+  /**
+   * The shell command that tells the app to drain. Defaults to a SIGTERM to the
+   * sandbox's node processes ({@link sigtermNodeProcessesCommand}).
+   */
+  drainCommand?: string | ((drainMs: number) => string)
+
+  /** Add a ready instance to the caller's routable set. Default: no-op. */
+  join?: (instance: SandboxInstance) => Promise<void>
+
+  /** Remove an instance from the caller's routable set. Default: no-op. */
+  leave?: (instance: SandboxInstance) => Promise<void>
+
+  /**
+   * Enumerate this deployment's live instances, when the caller can. Used by the
+   * rollout's idempotent resume; omitted means "roll from the caller's set".
+   */
+  list?: () => Promise<SandboxInstance[]>
+}
+```
+
+### Functions
+
+#### `sigtermNodeProcessesCommand(drainMs)`
+
+A drain command that sends SIGTERM to the sandbox's node processes and waits,
+bounded, for them to exit.
+
+The lifecycle bond turns SIGTERM into "flip readiness to 503, finish in-flight
+requests, exit". An app without the bond ignores the signal and the rollout
+destroys it after the same bound — no worse than destroying it without a word.
+
+```typescript
+function sigtermNodeProcessesCommand(drainMs: number): string
+```
+
+- `drainMs` — How long to wait for those processes to exit.
+
+**Returns:** The shell command.
+
+#### `probeSandboxReadiness(instance, timeoutMs)`
+
+One HTTP readiness look at an instance.
+
+`/health/ready` first; a 404 or 405 means the app predates the lifecycle bond, so
+`/health` is asked instead. Any other non-2xx answer is "not ready", and a
+transport failure is "not ready" too (the instance may still be booting).
+
+```typescript
+function probeSandboxReadiness(instance: SandboxInstance, timeoutMs?: number): Promise<boolean>
+```
+
+- `instance` — The instance to probe.
+- `timeoutMs` — Per-request budget. Defaults to 5000 ms.
+
+**Returns:** Whether it answered ready.
+
+#### `createSandboxInstanceProvider(options)`
+
+Create a grow-then-shrink instance provider over a sandbox provider.
+
+```typescript
+function createSandboxInstanceProvider(
+  options: SandboxInstanceOptions,
+): InstanceProvider<SandboxInstance>
+```
+
+- `options` — The provider, the launch recipe and the gate.
+
+**Returns:** An `InstanceProvider` over sandboxes.
+
+### Constants
+
+#### `DEFAULT_SANDBOX_READINESS_TIMEOUT_MS`
+
+The default poll cadence for the bond's own readiness wait.
+
+```typescript
+const DEFAULT_SANDBOX_READINESS_TIMEOUT_MS: 120000
+```
+
+#### `DEFAULT_SANDBOX_READINESS_POLL_MS`
+
+The default per-probe budget.
+
+```typescript
+const DEFAULT_SANDBOX_READINESS_POLL_MS: 2000
+```
+
+## Core Interface
+
+Implements `@molecule/api-deploy-rollout` interface.
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-code-sandbox` ^1.0.0
+- `@molecule/api-deploy-rollout` ^1.0.0
+
+### Runtime Dependencies
+
+- `@molecule/api-code-sandbox`
+- `@molecule/api-deploy-rollout`
+
+- **The launch recipe stays the deploy's.** Building, copying and booting an app
+  inside a sandbox is app knowledge; this bond never guesses it.
+- **Readiness falls back.** `/health/ready` first, `/health` on 404/405, so an app
+  scaffolded before the lifecycle bond still gates correctly.
+- **Drain is a SIGTERM**, bounded, through the sandbox's own exec channel.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-deploy-rollout-sandbox` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-deploy-rollout-sandbox is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Sandbox provider bond for the deploy-rollout core.
+ *
+ * One adapter over `@molecule/api-code-sandbox`, so E2B, Docker and Fly sandboxes
+ * share one rolling-deploy implementation. The deploy supplies its launch recipe and
+ * readiness gate; the bond supplies the lifecycle.
+ *
+ * @example
+ * ```typescript
+ * import { runRollout, setProvider } from '@molecule/api-deploy-rollout'
+ * import { provider } from '@molecule/api-deploy-rollout-default'
+ * import { createSandboxInstanceProvider } from '@molecule/api-deploy-rollout-sandbox'
+ *
+ * setProvider(provider)
+ * await runRollout({
+ *   provider: createSandboxInstanceProvider({
+ *     provider: sandboxProvider,
+ *     launch: (index) => launchReplica(index),
+ *     join: (instance) => upsertUpstream(instance.upstreamUrl ?? ''),
+ *   }),
+ *   current: oldInstances,
+ *   policy: { replicas: 2 },
+ * })
+ * ```
+ *
+ * @remarks
+ * - **The launch recipe stays the deploy's.** Building, copying and booting an app
+ *   inside a sandbox is app knowledge; this bond never guesses it.
+ * - **Readiness falls back.** `/health/ready` first, `/health` on 404/405, so an app
+ *   scaffolded before the lifecycle bond still gates correctly.
+ * - **Drain is a SIGTERM**, bounded, through the sandbox's own exec channel.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './sandbox.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * Sandbox provider bond for the deploy-rollout core.
+ *
+ * One adapter over `@molecule/api-code-sandbox`, so E2B, Docker and Fly sandboxes
+ * share one rolling-deploy implementation. The deploy supplies its launch recipe and
+ * readiness gate; the bond supplies the lifecycle.
+ *
+ * @example
+ * ```typescript
+ * import { runRollout, setProvider } from '@molecule/api-deploy-rollout'
+ * import { provider } from '@molecule/api-deploy-rollout-default'
+ * import { createSandboxInstanceProvider } from '@molecule/api-deploy-rollout-sandbox'
+ *
+ * setProvider(provider)
+ * await runRollout({
+ *   provider: createSandboxInstanceProvider({
+ *     provider: sandboxProvider,
+ *     launch: (index) => launchReplica(index),
+ *     join: (instance) => upsertUpstream(instance.upstreamUrl ?? ''),
+ *   }),
+ *   current: oldInstances,
+ *   policy: { replicas: 2 },
+ * })
+ * ```
+ *
+ * @remarks
+ * - **The launch recipe stays the deploy's.** Building, copying and booting an app
+ *   inside a sandbox is app knowledge; this bond never guesses it.
+ * - **Readiness falls back.** `/health/ready` first, `/health` on 404/405, so an app
+ *   scaffolded before the lifecycle bond still gates correctly.
+ * - **Drain is a SIGTERM**, bounded, through the sandbox's own exec channel.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './sandbox.js';

package/dist/sandbox.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Sandbox adapter for the deploy-rollout core.
+ *
+ * Implements the grow-then-shrink instance provider over
+ * `@molecule/api-code-sandbox`'s `SandboxProvider` — the seam molecule.dev's
+ * production deploy already uses (`requireProductionSandboxProvider()`), so ONE
+ * bond covers every sandbox backend: E2B, Docker, Fly, and any future provider.
+ *
+ * What the bond owns is the provider-independent lifecycle: create through the
+ * caller's launch recipe, gate on an HTTP readiness probe, join/leave the routable
+ * set, drain by SIGTERM through `sandbox.exec`, destroy through the provider. What
+ * it does NOT own is how the app is built and booted inside the sandbox — that is
+ * the deploy's recipe, passed in as `launch`.
+ *
+ * @module
+ */
+import type { Sandbox, SandboxProvider } from '@molecule/api-code-sandbox';
+import type { InstanceProvider, RolloutInstance } from '@molecule/api-deploy-rollout';
+/** One sandbox instance plus the address the edge dials. */
+export interface SandboxInstance extends RolloutInstance {
+    /** The live sandbox handle, when this run holds it. */
+    sandbox: Sandbox | null;
+}
+/** How a sandbox rollout reaches and gates one app's instances. */
+export interface SandboxInstanceOptions {
+    /** The sandbox provider (E2B, Docker, Fly — any bonded provider). */
+    provider: SandboxProvider;
+    /**
+     * Create and start the instance at `index`, resolving once it exists. This is the
+     * deploy's own recipe (tree transfer, env, boot script); the bond never guesses
+     * it.
+     */
+    launch: (index: number) => Promise<{
+        sandbox: Sandbox;
+        upstreamUrl: string;
+    }>;
+    /**
+     * A BLOCKING readiness gate with the caller's own semantics and budget. When
+     * present, `waitReady` delegates to it. When absent, the bond polls
+     * `readinessProbe` until `readinessTimeoutMs` elapses.
+     */
+    waitReady?: (instance: SandboxInstance) => Promise<boolean>;
+    /**
+     * One HTTP readiness probe. Default: `GET <upstreamUrl>/health/ready`, falling
+     * back to `GET <upstreamUrl>/health` on 404/405 (an app scaffolded before the
+     * lifecycle bond answers only the latter).
+     */
+    readinessProbe?: (instance: SandboxInstance) => Promise<boolean>;
+    /** How long the bond's own readiness poll may take. Defaults to 120 s. */
+    readinessTimeoutMs?: number;
+    /** Probe cadence for the bond's own readiness poll. Defaults to 2000 ms. */
+    readinessPollMs?: number;
+    /**
+     * The shell command that tells the app to drain. Defaults to a SIGTERM to the
+     * sandbox's node processes ({@link sigtermNodeProcessesCommand}).
+     */
+    drainCommand?: string | ((drainMs: number) => string);
+    /** Add a ready instance to the caller's routable set. Default: no-op. */
+    join?: (instance: SandboxInstance) => Promise<void>;
+    /** Remove an instance from the caller's routable set. Default: no-op. */
+    leave?: (instance: SandboxInstance) => Promise<void>;
+    /**
+     * Enumerate this deployment's live instances, when the caller can. Used by the
+     * rollout's idempotent resume; omitted means "roll from the caller's set".
+     */
+    list?: () => Promise<SandboxInstance[]>;
+}
+/**
+ * A drain command that sends SIGTERM to the sandbox's node processes and waits,
+ * bounded, for them to exit.
+ *
+ * The lifecycle bond turns SIGTERM into "flip readiness to 503, finish in-flight
+ * requests, exit". An app without the bond ignores the signal and the rollout
+ * destroys it after the same bound — no worse than destroying it without a word.
+ *
+ * @param drainMs - How long to wait for those processes to exit.
+ * @returns The shell command.
+ */
+export declare const sigtermNodeProcessesCommand: (drainMs: number) => string;
+/**
+ * One HTTP readiness look at an instance.
+ *
+ * `/health/ready` first; a 404 or 405 means the app predates the lifecycle bond, so
+ * `/health` is asked instead. Any other non-2xx answer is "not ready", and a
+ * transport failure is "not ready" too (the instance may still be booting).
+ *
+ * @param instance - The instance to probe.
+ * @param timeoutMs - Per-request budget. Defaults to 5000 ms.
+ * @returns Whether it answered ready.
+ */
+export declare const probeSandboxReadiness: (instance: SandboxInstance, timeoutMs?: number) => Promise<boolean>;
+/** The default poll cadence for the bond's own readiness wait. */
+export declare const DEFAULT_SANDBOX_READINESS_TIMEOUT_MS = 120000;
+/** The default per-probe budget. */
+export declare const DEFAULT_SANDBOX_READINESS_POLL_MS = 2000;
+/**
+ * Create a grow-then-shrink instance provider over a sandbox provider.
+ *
+ * @param options - The provider, the launch recipe and the gate.
+ * @returns An `InstanceProvider` over sandboxes.
+ */
+export declare const createSandboxInstanceProvider: (options: SandboxInstanceOptions) => InstanceProvider<SandboxInstance>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAc,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAErF,4DAA4D;AAC5D,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,uDAAuD;IACvD,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,qEAAqE;IACrE,QAAQ,EAAE,eAAe,CAAA;IAEzB;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAE7E;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAE3D;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhE,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IAErD,yEAAyE;IACzE,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnD,yEAAyE;IACzE,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpD;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;CACxC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,SAAS,MAAM,KAAG,MAuB7D,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAChC,UAAU,eAAe,EACzB,kBAAiB,KAChB,OAAO,CAAC,OAAO,CAkBjB,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,oCAAoC,SAAU,CAAA;AAE3D,oCAAoC;AACpC,eAAO,MAAM,iCAAiC,OAAQ,CAAA;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,GACxC,SAAS,sBAAsB,KAC9B,gBAAgB,CAAC,eAAe,CAsDlC,CAAA"}

package/dist/sandbox.js

@@ -0,0 +1,146 @@
+/**
+ * Sandbox adapter for the deploy-rollout core.
+ *
+ * Implements the grow-then-shrink instance provider over
+ * `@molecule/api-code-sandbox`'s `SandboxProvider` — the seam molecule.dev's
+ * production deploy already uses (`requireProductionSandboxProvider()`), so ONE
+ * bond covers every sandbox backend: E2B, Docker, Fly, and any future provider.
+ *
+ * What the bond owns is the provider-independent lifecycle: create through the
+ * caller's launch recipe, gate on an HTTP readiness probe, join/leave the routable
+ * set, drain by SIGTERM through `sandbox.exec`, destroy through the provider. What
+ * it does NOT own is how the app is built and booted inside the sandbox — that is
+ * the deploy's recipe, passed in as `launch`.
+ *
+ * @module
+ */
+/**
+ * A drain command that sends SIGTERM to the sandbox's node processes and waits,
+ * bounded, for them to exit.
+ *
+ * The lifecycle bond turns SIGTERM into "flip readiness to 503, finish in-flight
+ * requests, exit". An app without the bond ignores the signal and the rollout
+ * destroys it after the same bound — no worse than destroying it without a word.
+ *
+ * @param drainMs - How long to wait for those processes to exit.
+ * @returns The shell command.
+ */
+export const sigtermNodeProcessesCommand = (drainMs) => {
+    const seconds = Math.max(1, Math.ceil(drainMs / 1000));
+    return [
+        'for p in /proc/[0-9]*; do',
+        '  c=$(tr "\\0" " " < "$p/cmdline" 2>/dev/null) || continue',
+        '  case "$c" in',
+        '    *node*) kill -TERM "${p#/proc/}" 2>/dev/null;;',
+        '  esac',
+        'done',
+        'end=$(( $(date +%s) + ' + seconds + ' ))',
+        'while [ "$(date +%s)" -lt "$end" ]; do',
+        '  alive=0',
+        '  for p in /proc/[0-9]*; do',
+        '    c=$(tr "\\0" " " < "$p/cmdline" 2>/dev/null) || continue',
+        '    case "$c" in',
+        '      *node*) alive=1;;',
+        '    esac',
+        '  done',
+        '  [ "$alive" = 0 ] && break',
+        '  sleep 1',
+        'done',
+        'exit 0',
+    ].join('\n');
+};
+/**
+ * One HTTP readiness look at an instance.
+ *
+ * `/health/ready` first; a 404 or 405 means the app predates the lifecycle bond, so
+ * `/health` is asked instead. Any other non-2xx answer is "not ready", and a
+ * transport failure is "not ready" too (the instance may still be booting).
+ *
+ * @param instance - The instance to probe.
+ * @param timeoutMs - Per-request budget. Defaults to 5000 ms.
+ * @returns Whether it answered ready.
+ */
+export const probeSandboxReadiness = async (instance, timeoutMs = 5_000) => {
+    if (!instance.upstreamUrl)
+        return false;
+    const base = instance.upstreamUrl.replace(/\/+$/, '');
+    for (const path of ['/health/ready', '/health']) {
+        try {
+            const response = await fetch(`${base}${path}`, {
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (response.ok)
+                return true;
+            if (path === '/health/ready' && (response.status === 404 || response.status === 405))
+                continue;
+            return false;
+        }
+        catch (_error) {
+            // A transport failure is "not ready yet", never a crash: the instance is
+            // booting and the next poll is the health look that settles it.
+            return false;
+        }
+    }
+    return false;
+};
+/** The default poll cadence for the bond's own readiness wait. */
+export const DEFAULT_SANDBOX_READINESS_TIMEOUT_MS = 120_000;
+/** The default per-probe budget. */
+export const DEFAULT_SANDBOX_READINESS_POLL_MS = 2_000;
+/**
+ * Create a grow-then-shrink instance provider over a sandbox provider.
+ *
+ * @param options - The provider, the launch recipe and the gate.
+ * @returns An `InstanceProvider` over sandboxes.
+ */
+export const createSandboxInstanceProvider = (options) => {
+    const readinessProbe = options.readinessProbe ??
+        ((instance) => probeSandboxReadiness(instance));
+    const provider = {
+        name: `sandbox:${options.provider.name}`,
+        create: async (index) => {
+            const launched = await options.launch(index);
+            return {
+                id: launched.sandbox.id,
+                upstreamUrl: launched.upstreamUrl,
+                sandbox: launched.sandbox,
+            };
+        },
+        waitReady: async (instance, timeoutMs) => {
+            if (options.waitReady)
+                return options.waitReady(instance);
+            const budget = Math.max(0, timeoutMs ?? options.readinessTimeoutMs ?? DEFAULT_SANDBOX_READINESS_TIMEOUT_MS);
+            const pollMs = Math.max(1, options.readinessPollMs ?? DEFAULT_SANDBOX_READINESS_POLL_MS);
+            for (let waited = 0; waited <= budget; waited += pollMs) {
+                if (await readinessProbe(instance))
+                    return true;
+                await new Promise((resolve) => {
+                    setTimeout(resolve, pollMs);
+                });
+            }
+            return false;
+        },
+        isServing: (instance) => readinessProbe(instance),
+        join: async (instance) => options.join?.(instance),
+        leave: async (instance) => options.leave?.(instance),
+        drain: async (instance, drainMs) => {
+            if (drainMs <= 0 || !instance.sandbox)
+                return;
+            const command = typeof options.drainCommand === 'function'
+                ? options.drainCommand(drainMs)
+                : (options.drainCommand ?? sigtermNodeProcessesCommand(drainMs));
+            const result = await instance.sandbox.exec(command, {
+                timeout: drainMs + 15_000,
+            });
+            if (result.exitCode !== 0) {
+                throw new Error(`drain command exited ${result.exitCode}: ${result.stderr.trim().slice(0, 200)}`);
+            }
+        },
+        destroy: async (instance) => {
+            await options.provider.destroy(instance.id);
+        },
+    };
+    if (options.list)
+        provider.list = options.list;
+    return provider;
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@molecule/api-deploy-rollout-sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Sandbox provider bond for @molecule/api-deploy-rollout: grow-then-shrink rolling deploys over any @molecule/api-code-sandbox provider (E2B, Docker, Fly).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "molecule",
+    "deploy",
+    "rollout",
+    "sandbox",
+    "e2b",
+    "docker"
+  ],
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@molecule/api-code-sandbox": "^1.0.0",
+    "@molecule/api-deploy-rollout": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-code-sandbox": "1.4.0",
+    "@molecule/api-deploy-rollout": "1.1.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/deploy-rollout/sandbox"
+  },
+  "homepage": "https://www.molecule.dev/packages/api-deploy-rollout-sandbox",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}