@superblocksteam/workspace-sync 0.0.0-stage → 2.0.0-SNAPSHOT.e3d0ac5dd38ba62e

package/LICENSE.txt

@@ -0,0 +1,87 @@
+Superblocks Community Software License
+
+This Superblocks Community License Agreement (the “Agreement”) sets forth the terms on which DayZero
+Software, Inc. d/b/a Superblocks (“Superblocks”) makes available certain software made available by Superblocks
+under this Agreement (the “Software”). BY INSTALLING, DOWNLOADING, ACCESSING, USING OR
+DISTRIBUTING ANY OF THE SOFTWARE, YOU AGREE TO THE TERMS AND CONDITIONS OF THIS
+AGREEMENT.IF YOU DO NOT AGREE TO SUCH TERMS AND CONDITIONS, YOU MUST NOT USE THE
+SOFTWARE. IF YOU ARE RECEIVING THE SOFTWARE ON BEHALF OF A LEGAL ENTITY, YOU
+REPRESENT AND WARRANT THAT YOU HAVE THE ACTUAL AUTHORITY TO AGREE TO THE
+TERMS AND CONDITIONS OF THIS AGREEMENT ON BEHALF OF SUCH ENTITY. “Licensee” means you,
+an individual, or the entity on whose behalf you are receiving the Software.
+
+1. LICENSE GRANT AND CONDITIONS.
+
+1.1 License. Subject to the terms and conditions of this Agreement, Superblocks hereby grants to Licensee a
+non-exclusive, royalty-free, worldwide, non-transferable, non-sublicenseable license during the term of this
+Agreement to: (a) use the Software; (b) prepare modifications and derivative works of the Software; (c)
+distribute the Software (including without limitation in source code or object code form); and (d) reproduce
+copies of the Software (the “License”). Licensee is not granted the right to, and Licensee shall not, exercise the
+License for an Excluded Purpose. For purposes of this Agreement, “Excluded Purpose” means making
+available any software-as-a-service, platform-as-a-service, infrastructure-as-a-service or other similar online
+service that competes with Superblocks’ products or services.
+
+1.2 Conditions. In consideration of the License, Licensee’s distribution of the Software is subject to the
+following conditions:
+
+  a. Licensee must cause any Software modified by Licensee to carry prominent notices stating that Licensee
+  modified the Software.
+  b. On each Software copy, Licensee shall reproduce and not remove or alter all Superblocks or third party
+  copyright or other proprietary notices contained in the Software, and Licensee must provide the notice
+  below with each copy.
+
+  “This software is made available by DayZero Software, Inc. d/b/a Superblocks, under the terms of the
+  Superblocks Community License Agreement. © 2022 DayZero Software, Inc.”
+
+1.3 Licensee Modifications. Licensee may add its own copyright notices to modifications made by Licensee
+and may provide additional or different license terms and conditions for use, reproduction, or distribution of
+Licensee’s modifications. While redistributing the Software or modifications thereof, Licensee may choose to
+offer, for a fee or free of charge, support, warranty, indemnity, or other obligations. Licensee, and not
+Superblocks, will be responsible for any such obligations.
+
+1.4 No Sublicensing. The License does not include the right to sublicense the Software, however, each recipient
+to which Licensee provides the Software may exercise the Licenses so long as such recipient agrees to the terms
+and conditions of this Agreement.
+
+2. TERM AND TERMINATION. This Agreement will continue unless and until earlier terminated as set forth
+herein. If Licensee breaches any of its conditions or obligations under this Agreement, this Agreement will
+terminate automatically and the License will terminate automatically and permanently.
+
+3. INTELLECTUAL PROPERTY. As between the parties, Superblocks will retain all right, title, and interest in
+the Software, and all intellectual property rights therein. Superblocks hereby reserves all rights not expressly
+granted to Licensee in this Agreement. Superblocks hereby reserves all rights in its trademarks and service
+marks, and no licenses therein are granted in this Agreement.
+
+4. DISCLAIMER. SUPERBLOCKS HEREBY DISCLAIMS ANY AND ALL WARRANTIES AND
+CONDITIONS, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SPECIFICALLY
+DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE, WITH RESPECT TO THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY. SUPERBLOCKS WILL NOT BE LIABLE FOR ANY DAMAGES OF
+ANY KIND, INCLUDING BUT NOT LIMITED TO, LOST PROFITS OR ANY CONSEQUENTIAL,
+SPECIAL, INCIDENTAL, INDIRECT, OR DIRECT DAMAGES, HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, ARISING OUT OF THIS AGREEMENT. THE FOREGOING SHALL APPLY TO
+THE EXTENT PERMITTED BY APPLICABLE LAW.
+
+6. GENERAL.
+
+6.1  Governing Law. This Agreement will be governed by and interpreted in accordance with the laws of the
+state of California, without reference to its conflict of laws principles. If Licensee is located within the United
+States, all disputes arising out of this Agreement are subject to the exclusive jurisdiction of courts located in San
+Mateo County, California. USA. If Licensee is located outside of the United States, any dispute, controversy or
+claim arising out of or relating to this Agreement will be referred to and finally determined by arbitration in
+accordance with the JAMS International Arbitration Rules. The tribunal will consist of one neutral arbitrator.
+The place of arbitration will be Palo Alto, California. The language to be used in the arbitral proceedings will be
+English. Judgment upon the award rendered by the arbitrator may be entered in any court having jurisdiction
+thereof.
+
+6.2.  Assignment. Licensee may not assign its rights under this Agreement to any third party. Superblocks may
+freely assign its rights under this Agreement to any third party.
+
+6.3.  Other.  This Agreement is the entire agreement between the parties regarding the subject matter hereof.
+No amendment or modification of this Agreement will be valid or binding upon the parties unless made in
+writing and signed by the duly authorized representatives of both parties. In the event that any provision,
+including without limitation any condition, of this Agreement is held to be unenforceable, this Agreement and
+all licenses and rights granted hereunder will immediately terminate. Waiver by Superblocks of a breach of any
+provision of this Agreement or the failure by Superblocks to exercise any right hereunder will not be construed
+as a waiver of any subsequent breach of that right or as a waiver of any other right.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @superblocksteam/workspace-sync
 
-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.
+DBFS sync primitives for an app workspace: listing and snapshotting the local
+tree, uploading a snapshot, downloading a tree, draft markers, and the native
+draft journal.
+
+This is a leaf package. It depends on `@superblocksteam/shared` and
+`@superblocksteam/util`, never on `vite-plugin-file-sync`, the CLI or the
+server, so it can run outside the dev-server pod.
+
+`vite-plugin-file-sync` binds its logger with `setSyncLoggerProvider`. Until a
+host binds one, messages go to the console.
+
+## Native draft journal stores
+
+`NativeDraftJournal` persists through a `DraftJournalStore`:
+
+- `FileDraftJournalStore` (the default) writes one base64 JSON file to
+  `<root>/../.superblocks-native-drafts/<sha256(root)>.json`. This is the
+  live-edit layout.
+- `SessionDraftJournalStore` writes a small pointer record to a session state
+  directory and keeps file contents as DBFS blobs referenced by content hash.
+  A fresh process over the same directory can still reconcile, accept or
+  discard a killed session's drafts.
+
+## Sync engine
+
+`createWorkspaceSyncEngine` runs a workspace without the live-edit
+`SyncService`, for the AgentCore microVM. DBFS is the commit point and the
+session state directory is a cache, so the engine survives a kill at any step.
+
+- `interimFlush()` uploads blobs only and never moves the branch hash.
+  `createFlushScheduler` runs it on the live-edit cadence (10s trailing, 30s
+  cap).
+- `commit(source)` reconciles the draft journal, reports a drafted tree
+  (after asking the `BranchWriteGuard` and before the hash, so the server
+  files the turn as a draft), snapshots the tree, uploads what DBFS lacks,
+  asks the guard again, moves the branch hash, then writes the state store and
+  retires the journal. Only a `checkpoint` commit (accept or reject) clears
+  the server's draft flag, and only after its hash moves, so a failed accept
+  or reject leaves the server in draft. Every draft-state report asks the
+  guard first. An accept, reject or clear passes its marker step as
+  `settle`, which runs inside the commit queue after the draft journal is
+  dropped, so no other commit interleaves. Draft checks fail closed: only a
+  missing `.superblocks/drafts` directory counts as no drafts.
+- `rehydrate()` compares the server hash, the stored hash and the local tree
+  on boot and returns `fresh`, `resumed`, `replayed` or `reloaded`. A
+  `reloaded` tree keeps the local diff under `<stateDir>/orphaned/`.
+
+It talks to the server only through a `DbfsTransport`. `SocketDbfsTransport`
+wraps the existing socket RPCs; `FakeDbfs` from
+`@superblocksteam/workspace-sync/testing` is an in-memory stand-in for tests.

package/dist/atomic-write.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Replaces `file` with `contents` so a reader sees the old or the new bytes,
+ * never a torn write: write a temporary sibling, fsync it, rename it over the
+ * target, then fsync the directory so the rename survives a crash.
+ */
+export declare function writeFileAtomic(file: string, contents: string | Buffer, options?: {
+    mode?: number;
+    preserveMode?: number;
+}): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/atomic-write.js

@@ -0,0 +1,35 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Replaces `file` with `contents` so a reader sees the old or the new bytes,
+ * never a torn write: write a temporary sibling, fsync it, rename it over the
+ * target, then fsync the directory so the rename survives a crash.
+ */
+export async function writeFileAtomic(file, contents, options = {}) {
+    const temporary = path.join(path.dirname(file), `.${randomUUID()}.tmp`);
+    const handle = await fs.open(temporary, "wx", options.preserveMode ?? options.mode ?? 0o600);
+    try {
+        try {
+            await handle.writeFile(contents);
+            if (options.preserveMode !== undefined)
+                await handle.chmod(options.preserveMode);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+        const directory = await fs.open(path.dirname(file), "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,QAAyB,EACzB,OAAO,GAA6C,EAAE;IAEtD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAC1B,SAAS,EACT,IAAI,EACJ,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,IAAI,IAAI,KAAK,CAC9C,CAAC;IACF,IAAI,CAAC;QACH,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YACjC,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS;gBACpC,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC3C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QACD,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACjC,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACzD,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC;gBAAS,CAAC;YACT,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/branch-write-guard.d.ts

@@ -0,0 +1,32 @@
+import type { DbfsTransport } from "./dbfs-transport.js";
+export type BranchWriteRejection = "lock_not_held" | "server_moved";
+/** A commit was refused before the branch hash moved. */
+export declare class BranchWriteRejectedError extends Error {
+    readonly reason: BranchWriteRejection;
+    constructor(reason: BranchWriteRejection, message: string);
+}
+/**
+ * Decides whether this workspace may move the branch hash on top of
+ * `baseHash`. Throws {@link BranchWriteRejectedError} to refuse.
+ */
+export interface BranchWriteGuard {
+    assertCanCommit(baseHash: string | undefined): Promise<void>;
+}
+/**
+ * The interim guard: the edge must hold the app branch lock (the host toggles
+ * {@link setLockHeld} from the edge's state snapshots), and the server hash
+ * must still equal the base. The compare and the set are two calls, so this
+ * races a concurrent writer; the branching work (#22956) replaces it with a
+ * server compare-and-set behind the same interface.
+ */
+export declare class ServerHashGuard implements BranchWriteGuard {
+    private readonly transport;
+    private held;
+    constructor(transport: Pick<DbfsTransport, "getServerHash">, options?: {
+        lockHeld?: boolean;
+    });
+    get lockHeld(): boolean;
+    setLockHeld(held: boolean): void;
+    assertCanCommit(baseHash: string | undefined): Promise<void>;
+}
+//# sourceMappingURL=branch-write-guard.d.ts.map

package/dist/branch-write-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-write-guard.d.ts","sourceRoot":"","sources":["../src/branch-write-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,cAAc,CAAC;AAEpE,yDAAyD;AACzD,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,MAAM,EAAE,oBAAoB;IADvC,YACW,MAAM,EAAE,oBAAoB,EACrC,OAAO,EAAE,MAAM,EAIhB;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IAIpD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAH5B,OAAO,CAAC,IAAI,CAAU;IAEtB,YACmB,SAAS,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,CAAC,EAChE,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,EAGrC;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE/B;IAEK,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAYjE;CACF"}

package/dist/branch-write-guard.js

@@ -0,0 +1,38 @@
+/** A commit was refused before the branch hash moved. */
+export class BranchWriteRejectedError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "BranchWriteRejectedError";
+    }
+}
+/**
+ * The interim guard: the edge must hold the app branch lock (the host toggles
+ * {@link setLockHeld} from the edge's state snapshots), and the server hash
+ * must still equal the base. The compare and the set are two calls, so this
+ * races a concurrent writer; the branching work (#22956) replaces it with a
+ * server compare-and-set behind the same interface.
+ */
+export class ServerHashGuard {
+    transport;
+    held;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.held = options.lockHeld ?? false;
+    }
+    get lockHeld() {
+        return this.held;
+    }
+    setLockHeld(held) {
+        this.held = held;
+    }
+    async assertCanCommit(baseHash) {
+        if (!this.held)
+            throw new BranchWriteRejectedError("lock_not_held", "The application branch lock is not held");
+        const serverHash = await this.transport.getServerHash();
+        if (serverHash !== baseHash)
+            throw new BranchWriteRejectedError("server_moved", "The application branch moved since this workspace last synced");
+    }
+}
+//# sourceMappingURL=branch-write-guard.js.map

package/dist/branch-write-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-write-guard.js","sourceRoot":"","sources":["../src/branch-write-guard.ts"],"names":[],"mappings":"AAIA,yDAAyD;AACzD,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAEtC,MAAM;IADjB,YACW,MAA4B,EACrC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;sBAHN,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAUD;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAIP,SAAS;IAHpB,IAAI,CAAU;IAEtB,YACmB,SAA+C,EAChE,OAAO,GAA2B,EAAE;yBADnB,SAAS;QAG1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IACxC,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,WAAW,CAAC,IAAa;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,QAA4B;QAChD,IAAI,CAAC,IAAI,CAAC,IAAI;YACZ,MAAM,IAAI,wBAAwB,CAChC,eAAe,EACf,yCAAyC,CAC1C,CAAC;QACJ,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC;QACxD,IAAI,UAAU,KAAK,QAAQ;YACzB,MAAM,IAAI,wBAAwB,CAChC,cAAc,EACd,+DAA+D,CAChE,CAAC;IACN,CAAC;CACF"}

package/dist/control.d.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+/**
+ * The port the VM's ingress listens on. The builder runtime's `allowedPorts`
+ * must include it (AgentCore allows 8000-12000).
+ */
+export declare const WORKSPACE_INGRESS_PORT = 8090;
+/**
+ * Every control path on either side lives under this prefix. The edge never
+ * forwards a browser request under it to the VM: forwarded requests carry the
+ * workspace token, so a forwarded control path would be authorized.
+ */
+export declare const WORKSPACE_CONTROL_PREFIX = "/_sb_workspace/";
+/** VM ingress, edge → VM: replace the VM's copy of the edge's state. */
+export declare const WORKSPACE_STATE_PATH = "/_sb_workspace/state";
+/** VM ingress, edge → VM: commit the tree to DBFS now and report the result. */
+export declare const WORKSPACE_COMMIT_PATH = "/_sb_workspace/commit";
+/** Edge, AI service → edge: the VM's current session endpoint. */
+export declare const WORKSPACE_ENDPOINT_PATH = "/_sb_workspace/endpoint";
+/** Edge, VM → edge: read-only package registry proxy (prefix). */
+export declare const WORKSPACE_REGISTRY_PATH = "/_sb_workspace/registry/";
+/**
+ * Carries the workspace token on every request between the parties. Not
+ * `Authorization`: SigV4 owns that header on the edge → VM hop.
+ */
+export declare const WORKSPACE_TOKEN_HEADER = "x-sb-workspace-token";
+/**
+ * The browser's Host. The edge → VM hop must send the session endpoint's own
+ * Host (it is signed), so the edge moves the original here and the VM ingress
+ * restores it before Vite sees the request.
+ */
+export declare const WORKSPACE_ORIGINAL_HOST_HEADER = "x-sb-original-host";
+/**
+ * The browser's `Authorization`. SigV4 owns `Authorization` on the edge → VM
+ * hop, so the edge moves the browser's value here (dropping any inbound copy)
+ * and the VM ingress restores it before the workspace host checks it.
+ */
+export declare const WORKSPACE_ORIGINAL_AUTHORIZATION_HEADER = "x-sb-original-authorization";
+/** True when `pathname` is a control path that must not be forwarded. */
+export declare function isWorkspaceControlPath(pathname: string): boolean;
+/**
+ * The bearer token for one workspace session: the hex HMAC-SHA256 of
+ * `sessionKey` keyed by `secret`. Every party that holds the secret derives
+ * the same token, and a token derived for one session opens no other.
+ */
+export declare function deriveWorkspaceToken(secret: string, sessionKey: string): string;
+/**
+ * The token that authorizes endpoint reports (`PUT`
+ * {@link WORKSPACE_ENDPOINT_PATH}) for one session. Only parties outside the
+ * VM derive it: the VM holds the {@link deriveWorkspaceToken workspace
+ * token}, and that token must not be able to retarget the edge.
+ */
+export declare function deriveWorkspaceEndpointToken(secret: string, sessionKey: string): string;
+/**
+ * True when `url` is an AgentCore session endpoint in `region`: https on the
+ * default port, no credentials, and a host under
+ * `runtime.bedrock-agentcore.<region>.on.aws`.
+ */
+export declare function isAgentCoreSessionEndpoint(url: string, region: string): boolean;
+/**
+ * Constant-time string comparison. Both sides are hashed first so inputs of
+ * different lengths compare in constant time too.
+ */
+export declare function tokensEqual(a: string, b: string): boolean;
+/**
+ * Whether `headers` carry exactly `expected` in {@link WORKSPACE_TOKEN_HEADER}.
+ * A missing, repeated or empty header is rejected.
+ */
+export declare function hasWorkspaceToken(headers: Record<string, string | string[] | undefined>, expected: string): boolean;
+export declare const workspaceSyncCredentialSchema: z.ZodObject<{
+    token: z.ZodString;
+    /** Epoch milliseconds after which the server rejects the token. */
+    expiresAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    token: string;
+    expiresAt: number;
+}, {
+    token: string;
+    expiresAt: number;
+}>;
+export type WorkspaceSyncCredential = z.infer<typeof workspaceSyncCredentialSchema>;
+/**
+ * Everything the VM needs from the edge, sent whole every time
+ * (`PUT` {@link WORKSPACE_STATE_PATH}). The edge sends it on every change and
+ * on a timer, so a VM that restarted inside the same session is back in sync
+ * within one interval without the edge noticing the restart. The VM replaces
+ * its copy; it never merges.
+ */
+export declare const workspaceStateSchema: z.ZodObject<{
+    /** The edge holds the branch lock; without it the VM must not commit. */
+    lockHeld: z.ZodBoolean;
+    /** A user was recently active in the editor (feeds the VM's busy policy). */
+    userActive: z.ZodBoolean;
+    /** The edge is shutting down; going quiet after this is not a failure. */
+    draining: z.ZodBoolean;
+    /**
+     * Absent until the edge has minted one. A snapshot without one leaves the
+     * VM's last credential in place; the server enforces its expiry.
+     */
+    credential: z.ZodOptional<z.ZodObject<{
+        token: z.ZodString;
+        /** Epoch milliseconds after which the server rejects the token. */
+        expiresAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+        expiresAt: number;
+    }, {
+        token: string;
+        expiresAt: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    lockHeld: boolean;
+    userActive: boolean;
+    draining: boolean;
+    credential?: {
+        token: string;
+        expiresAt: number;
+    } | undefined;
+}, {
+    lockHeld: boolean;
+    userActive: boolean;
+    draining: boolean;
+    credential?: {
+        token: string;
+        expiresAt: number;
+    } | undefined;
+}>;
+export type WorkspaceState = z.infer<typeof workspaceStateSchema>;
+/**
+ * The VM's answer to a state snapshot. `bootId` is random per VM process, for
+ * logs and metrics; the edge does not branch on it.
+ */
+export declare const workspaceStatusSchema: z.ZodObject<{
+    bootId: z.ZodString;
+    devServer: z.ZodEnum<["booting", "ready", "failed"]>;
+    /** Local changes not yet committed to DBFS. */
+    unsynced: z.ZodBoolean;
+    dbfsHash: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bootId: string;
+    devServer: "booting" | "failed" | "ready";
+    unsynced: boolean;
+    dbfsHash?: string | undefined;
+}, {
+    bootId: string;
+    devServer: "booting" | "failed" | "ready";
+    unsynced: boolean;
+    dbfsHash?: string | undefined;
+}>;
+export type WorkspaceStatus = z.infer<typeof workspaceStatusSchema>;
+/**
+ * The response body of `POST` {@link WORKSPACE_COMMIT_PATH}, always with
+ * status 200 so the edge reads one shape. `not_ready` means the workspace is
+ * not open or has no state snapshot yet; the edge reports it like an error.
+ */
+export declare const workspaceCommitResultSchema: z.ZodDiscriminatedUnion<"outcome", [z.ZodObject<{
+    outcome: z.ZodLiteral<"committed">;
+    dbfsHash: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    outcome: "committed";
+    dbfsHash?: string | undefined;
+}, {
+    outcome: "committed";
+    dbfsHash?: string | undefined;
+}>, z.ZodObject<{
+    outcome: z.ZodLiteral<"not_ready">;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    outcome: "not_ready";
+    reason: string;
+}, {
+    outcome: "not_ready";
+    reason: string;
+}>, z.ZodObject<{
+    outcome: z.ZodLiteral<"error">;
+    error: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    outcome: "error";
+    error: string;
+}, {
+    outcome: "error";
+    error: string;
+}>]>;
+export type WorkspaceCommitResult = z.infer<typeof workspaceCommitResultSchema>;
+/**
+ * Where the VM's ingress is reachable and how the edge authenticates to it
+ * (`PUT` {@link WORKSPACE_ENDPOINT_PATH}). Each `workspace.open` that returns
+ * a new URL sends a new one; the edge then pushes its state there.
+ *
+ * - `sigv4`: an AgentCore session endpoint. The edge signs each request and
+ *   WebSocket handshake for `bedrock-agentcore` in `region`.
+ * - `none`: a local builder runtime reached directly, for development.
+ */
+export declare const workspaceEndpointSchema: z.ZodDiscriminatedUnion<"auth", [z.ZodObject<{
+    auth: z.ZodLiteral<"sigv4">;
+    url: z.ZodEffects<z.ZodString, string, string>;
+    region: z.ZodString;
+    sessionKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    auth: "sigv4";
+    url: string;
+    region: string;
+    sessionKey: string;
+}, {
+    auth: "sigv4";
+    url: string;
+    region: string;
+    sessionKey: string;
+}>, z.ZodObject<{
+    auth: z.ZodLiteral<"none">;
+    url: z.ZodEffects<z.ZodString, string, string>;
+    sessionKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    auth: "none";
+    url: string;
+    sessionKey: string;
+}, {
+    auth: "none";
+    url: string;
+    sessionKey: string;
+}>]>;
+export type WorkspaceEndpoint = z.infer<typeof workspaceEndpointSchema>;
+/**
+ * The edge's view of the VM, reported in its health response as
+ * `workspace.ingress`. The AI service reopens the workspace when it stays
+ * `unreachable`.
+ *
+ * - `waiting`: no endpoint yet.
+ * - `reachable`: the last state push succeeded and the VM reports a booting
+ *   or ready workspace host.
+ * - `unreachable`: pushes to the current endpoint are failing, or the VM
+ *   answers them but reports its workspace host `failed` (it cannot serve
+ *   until the workspace is reopened).
+ * - `closed`: the edge is shutting down.
+ */
+export declare const workspaceIngressStateSchema: z.ZodEnum<["waiting", "reachable", "unreachable", "closed"]>;
+export type WorkspaceIngressState = z.infer<typeof workspaceIngressStateSchema>;
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AACjE,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,gCACrB,CAAC;AAEhC,yEAAyE;AACzE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhE;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,MAAM,CAQR;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAeT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,QAAQ,EAAE,MAAM,GACf,OAAO,CAIT;AAMD,eAAO,MAAM,6BAA6B;;IAExC,mEAAmE;;;;;;;;EAEnE,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B,yEAAyE;;IAEzE,6EAA6E;;IAE7E,0EAA0E;;IAE1E;;;OAGG;;;QAxBH,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;EA0BnE,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;IAGhC,+CAA+C;;;;;;;;;;;;;EAG/C,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;IAatC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAWhF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;IAYlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,8DAKtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}