@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/build/local-build.d.ts

@@ -43,6 +43,8 @@ export declare function createFirstPartyAppSourceDistribution(options: {
 /** How one build executor is composed; never part of a recipe or request. */
 export type LocalBuildExecutorOptions = Readonly<{
     packageStoreDirectory?: string;
+    /** Host-hydrated metadata; supplied only for a cache-only pnpm install. */
+    packageCacheDirectory?: string;
     /**
      * `run` executes a dependency's declared `fungi.build.script`. Only the
      * admitted Computer build sets it; every other composition refuses a source

package/dist/build/local-build.js

@@ -11,7 +11,7 @@ import { frozenSnapshotInstallArguments, packageScriptArguments, } from "./snaps
 import { isInsideSnapshot } from "./snapshot-programs/snapshot-path.js";
 import { writeImmutableArtifact, } from "./artifact-writer.js";
 import { assetPathSchema, } from "@fungi.computer/puffball/assets";
-import { resolveWorkspaceBuild, workspaceProjectsArguments, } from "./workspace-build.js";
+import { appBuildRecipe, readBuildManifest, resolveWorkspaceBuild, workspaceProjectsArguments, } from "./workspace-build.js";
 import { readBundledHtml } from "./bundled-html.js";
 import { createHash, randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
@@ -280,9 +280,14 @@ function productionWorkspaceSelectors(build) {
     return ["--filter-prod", `${build.packageName}...`];
 }
 /** Derive the App's page build from the captured tree's own manifests. */
-function capturedWorkspaceBuild(snapshot, entry, run) {
+function capturedWorkspaceBuild(snapshot, entry, run, backendEntry) {
     return Effect.flatMap(run(workspaceProjectsArguments), (projects) => Effect.tryPromise({
-        try: () => resolveWorkspaceBuild({ root: snapshot, entry, projects }),
+        try: () => resolveWorkspaceBuild({
+            root: snapshot,
+            entry,
+            projects,
+            backendEntry,
+        }),
         catch: (error) => error,
     }));
 }
@@ -487,6 +492,23 @@ export function createFirstPartyAppSourceDistribution(options) {
                     await collect(relativePath);
                 for (const relativePath of sourceDistributionRootFiles)
                     await collect(relativePath);
+                // The projected repository is one App, even though its source keeps
+                // workspace-relative paths. Preserve npm metadata and publish that
+                // App's current identity/recipe at the root registration reads.
+                const jsonObject = Schema.Record(Schema.String, Schema.Json);
+                const rootPackage = Schema.decodeUnknownSync(Schema.fromJsonString(jsonObject))(await readFile(join(snapshot, "package.json"), "utf8"));
+                const rootFungi = rootPackage.fungi === undefined
+                    ? {}
+                    : Schema.decodeUnknownSync(jsonObject)(rootPackage.fungi);
+                const manifest = readBuildManifest(await readFile(join(snapshot, appDirectory, "package.json"), "utf8"));
+                collected.set("package.json", Buffer.from(JSON.stringify({
+                    ...rootPackage,
+                    fungi: {
+                        ...rootFungi,
+                        appId,
+                        build: appBuildRecipe(manifest, appDirectory),
+                    },
+                }, null, 2)));
                 await collect("patches");
                 if (collected.has("pnpm-lock.yaml"))
                     collected.set("pnpm-lock.yaml", await prunePnpmLockfile(snapshot, (importerPath) => collected.has(join(importerPath, "package.json"))));
@@ -617,7 +639,7 @@ function rebuildViteSnapshot(sourceSnapshotPath, recipe, options) {
         if ((yield* run(["--version"])).trim() !== "11.24.0") {
             return yield* Effect.fail(new Error("Publisher requires pnpm 11.24.0"));
         }
-        const html = yield* capturedWorkspaceBuild(sourceSnapshotPath, recipe.entry, run);
+        const html = yield* capturedWorkspaceBuild(sourceSnapshotPath, recipe.entry, run, recipe.backend?.entry ?? null);
         yield* Effect.tryPromise({
             try: () => checkPinnedWorkspaceToolchain(sourceSnapshotPath, html, recipe),
             catch: (error) => error,
@@ -628,7 +650,7 @@ function rebuildViteSnapshot(sourceSnapshotPath, recipe, options) {
         const installStarted = performance.now();
         yield* run([
             ...productionWorkspaceSelectors(html),
-            ...frozenSnapshotInstallArguments(options.packageStoreDirectory),
+            ...frozenSnapshotInstallArguments(options.packageStoreDirectory, options.packageCacheDirectory),
         ]);
         const buildStarted = performance.now();
         options.onPhase?.("install", buildStarted - installStarted);
@@ -962,7 +984,7 @@ export function createLocalBuildExecutor(options = {}) {
                             const environment = snapshotBuildEnvironment(source.snapshotPath);
                             if ((yield* runHtmlCommand(["--version"], source.snapshotPath, environment)).trim() !== "11.24.0")
                                 return yield* Effect.fail(new Error("Publisher requires pnpm 11.24.0"));
-                            yield* runHtmlCommand(frozenSnapshotInstallArguments(options.packageStoreDirectory), source.snapshotPath, environment);
+                            yield* runHtmlCommand(frozenSnapshotInstallArguments(options.packageStoreDirectory, options.packageCacheDirectory), source.snapshotPath, environment);
                         }
                     }
                     const ui = yield* recipe.kind === "bundled-html"

package/dist/build/snapshot-package-store.d.ts

@@ -1,5 +1,5 @@
 /** Frozen hydration policy. Cached bytes are verified and copied into each snapshot. */
-export declare function frozenSnapshotInstallArguments(packageStoreDirectory?: string): string[];
+export declare function frozenSnapshotInstallArguments(packageStoreDirectory?: string, packageCacheDirectory?: string): string[];
 /**
  * `pnpm run` for one declared package build script, which follows `--` so
  * pnpm selects that literal name (never an option or a `/pattern/`). pnpm 11

package/dist/build/snapshot-package-store.js

@@ -1,9 +1,11 @@
 import { isAbsolute } from "node:path";
 /** Frozen hydration policy. Cached bytes are verified and copied into each snapshot. */
-export function frozenSnapshotInstallArguments(packageStoreDirectory) {
+export function frozenSnapshotInstallArguments(packageStoreDirectory, packageCacheDirectory) {
     if (packageStoreDirectory !== undefined && !isAbsolute(packageStoreDirectory))
         throw new Error("Publisher package store must be an absolute host path");
-    return [
+    if (packageCacheDirectory !== undefined && !isAbsolute(packageCacheDirectory))
+        throw new Error("Publisher package cache must be an absolute host path");
+    const args = [
         "install",
         "--prod=false",
         "--frozen-lockfile",
@@ -18,6 +20,9 @@ export function frozenSnapshotInstallArguments(packageStoreDirectory) {
         "--config.enable-global-virtual-store=false",
         "--reporter=append-only",
     ];
+    if (packageCacheDirectory !== undefined)
+        args.push("--offline", `--cache-dir=${packageCacheDirectory}`);
+    return args;
 }
 /**
  * `pnpm run` for one declared package build script, which follows `--` so

package/dist/build/workspace-build.d.ts

@@ -1,18 +1,31 @@
 import * as Schema from "effect/Schema";
+import { type AppPublisherCoreConfigInput } from "./effect.js";
 import type { WorkspaceBuildStep } from "./build-step.js";
 /**
  * `package.json#fungi.build`. An App manifest (the manifest nearest the
- * entry) declares how its page builds: `react`, `shellEntry`, the workspace
+ * entry) declares its recipe beside the page policy: `react`, `shellEntry`, the workspace
  * packages whose declared stylesheets compile first (`packageStylesheets`)
  * and its own `stylesheets`, compiled in place, in order. A workspace
  * package declares its build products: extra TypeScript configs compiled
  * after its `tsconfig.build.json`, and its stylesheet input and output; or,
  * instead of TypeScript configs, the one `package.json` script that builds
  * it (`script`), which only an admitted Computer build runs. Every path is
- * relative to the manifest that declares it. Unknown build fields are
+ * relative to the manifest that declares it. Dependency-only metadata needs
+ * no App recipe; App callers require one through appBuildRecipe. Unknown fields are
  * refused, so a builder never silently ignores a policy it does not know.
  */
 export declare const workspaceBuildPolicySchema: Schema.Struct<{
+    readonly entry: Schema.optional<Schema.String>;
+    readonly backend: Schema.optional<Schema.Union<readonly [Schema.Null, Schema.Struct<{
+        readonly entry: Schema.optional<Schema.String>;
+        readonly runtime: Schema.Struct<{
+            readonly kind: Schema.Literal<"durable-facet">;
+            readonly stateSchema: Schema.Number;
+        }>;
+        readonly compatibilityDate: Schema.String;
+        readonly exportName: Schema.String;
+    }>]>>;
+    readonly maxOutputBytes: Schema.optional<Schema.Number>;
     readonly react: Schema.optional<Schema.Boolean>;
     readonly shellEntry: Schema.optional<Schema.String>;
     readonly packageStylesheets: Schema.optional<Schema.$Array<Schema.String>>;
@@ -24,11 +37,81 @@ export declare const workspaceBuildPolicySchema: Schema.Struct<{
         readonly input: Schema.String;
         readonly output: Schema.String;
     }>>;
+    readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+    readonly assets: Schema.optional<Schema.Struct<{
+        readonly maxManifestBytes: Schema.Number;
+        readonly maxObjects: Schema.Number;
+        readonly maxObjectBytes: Schema.Number;
+        readonly maxTotalBytes: Schema.Number;
+    }>>;
+    readonly assetBase: Schema.optionalKey<Schema.String>;
 }>;
 /** The build policy one manifest declares. */
 export type WorkspaceBuildPolicy = Schema.Schema.Type<typeof workspaceBuildPolicySchema>;
+/** Read package metadata once; only fungi.build rejects unknown fields. */
+export declare function readBuildManifest(packageJson: string): {
+    fungi: {
+        build: {
+            readonly kind?: "bundled-html" | "source-html" | undefined;
+            readonly backend?: {
+                readonly runtime: {
+                    readonly kind: "durable-facet";
+                    readonly stateSchema: number;
+                };
+                readonly compatibilityDate: string;
+                readonly exportName: string;
+                readonly entry?: string | undefined;
+            } | null | undefined;
+            readonly assets?: {
+                readonly maxManifestBytes: number;
+                readonly maxObjects: number;
+                readonly maxObjectBytes: number;
+                readonly maxTotalBytes: number;
+            } | undefined;
+            readonly stylesheet?: {
+                readonly input: string;
+                readonly output: string;
+            } | undefined;
+            readonly script?: string | undefined;
+            readonly entry?: string | undefined;
+            readonly assetBase?: string | undefined;
+            readonly maxOutputBytes?: number | undefined;
+            readonly react?: boolean | undefined;
+            readonly typescript?: readonly string[] | undefined;
+            readonly shellEntry?: string | undefined;
+            readonly packageStylesheets?: readonly string[] | undefined;
+            readonly stylesheets?: readonly string[] | undefined;
+        } | undefined;
+        appId?: import("@fungi.computer/puffball").AppId | undefined;
+    };
+    name?: string | undefined;
+    dependencies?: {
+        readonly [x: string]: string;
+    } | undefined;
+    scripts?: {
+        readonly [x: string]: string;
+    } | undefined;
+};
+/** Manifest metadata with the App-owned build policy decoded. */
+export type BuildManifest = ReturnType<typeof readBuildManifest>;
+/** Select an App recipe and root its paths in the captured source tree. */
+export declare function appBuildRecipe(manifest: BuildManifest, directory: string): AppPublisherCoreConfigInput["recipe"];
 /** The pnpm arguments that list a source tree's workspace projects. */
 export declare const workspaceProjectsArguments: readonly string[];
+/** A nested package must own its build graph, never inherit its host's. */
+export declare class WorkspaceBuildError extends Error {
+    /** The nearer package, relative to the captured source root. */
+    readonly directory: string;
+    /** The workspace whose dependencies would otherwise be inherited. */
+    readonly ownerDirectory: string;
+    /** The nearest package is absent from pnpm's workspace inventory. */
+    readonly code = "non_workspace_package";
+    constructor(
+    /** The nearer package, relative to the captured source root. */
+    directory: string, 
+    /** The workspace whose dependencies would otherwise be inherited. */
+    ownerDirectory: string);
+}
 /** One App page build derived from its manifests and package graph. */
 export type WorkspaceBuild = Readonly<{
     /** The pnpm workspace that owns the entry, relative to the source root. */
@@ -37,19 +120,23 @@ export type WorkspaceBuild = Readonly<{
     react: boolean;
     /** A shell module entry, relative to `directory`. */
     shellEntry?: string;
-    /** The workspace's runtime workspace dependencies, dependencies first. */
+    /** Compile dependencies of the App's runtime imports, dependencies first. */
     dependencies: readonly string[];
     steps: readonly WorkspaceBuildStep[];
 }>;
 /**
  * Derive one App's page build from the captured source alone: the manifest
- * nearest `entry` declares the App policy, the owning pnpm workspace's
- * runtime `workspace:` dependencies give the compile order, and each
+ * nearest `entry` must be the owning pnpm workspace (or standalone repository
+ * root). It declares the App policy, its
+ * runtime imports select its compile roots; their `workspace:` dependencies
+ * give the compile order, and each
  * dependency's manifest declares its own extra build products.
  */
 export declare function resolveWorkspaceBuild(options: {
     readonly root: string;
     readonly entry: string;
+    /** The selected recipe's backend, if it differs from the manifest recipe. */
+    readonly backendEntry?: string | null | undefined;
     /** `pnpm ls -r --depth -1 --json` output for the same source tree. */
     readonly projects: string;
 }): Promise<WorkspaceBuild>;

package/dist/build/workspace-build.js

@@ -1,25 +1,28 @@
 import { access, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import * as Schema from "effect/Schema";
-const manifestPathSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((path) => path.length > 0 &&
-    !path.startsWith("/") &&
-    !path.includes("\\") &&
-    path
-        .split("/")
-        .every((part) => part !== "" && part !== "." && part !== ".."))));
+import { appIdSchema } from "@fungi.computer/puffball/effect";
+import { pinnedRecipeSchema, } from "./effect.js";
+import { appRuntimeImports } from "./app-imports.js";
+const manifestPathSchema = pinnedRecipeSchema.fields.entry;
 /**
  * `package.json#fungi.build`. An App manifest (the manifest nearest the
- * entry) declares how its page builds: `react`, `shellEntry`, the workspace
+ * entry) declares its recipe beside the page policy: `react`, `shellEntry`, the workspace
  * packages whose declared stylesheets compile first (`packageStylesheets`)
  * and its own `stylesheets`, compiled in place, in order. A workspace
  * package declares its build products: extra TypeScript configs compiled
  * after its `tsconfig.build.json`, and its stylesheet input and output; or,
  * instead of TypeScript configs, the one `package.json` script that builds
  * it (`script`), which only an admitted Computer build runs. Every path is
- * relative to the manifest that declares it. Unknown build fields are
+ * relative to the manifest that declares it. Dependency-only metadata needs
+ * no App recipe; App callers require one through appBuildRecipe. Unknown fields are
  * refused, so a builder never silently ignores a policy it does not know.
  */
 export const workspaceBuildPolicySchema = Schema.Struct({
+    ...pinnedRecipeSchema.fields,
+    entry: Schema.optional(pinnedRecipeSchema.fields.entry),
+    backend: Schema.optional(pinnedRecipeSchema.fields.backend),
+    maxOutputBytes: Schema.optional(pinnedRecipeSchema.fields.maxOutputBytes),
     react: Schema.optional(Schema.Boolean),
     shellEntry: Schema.optional(manifestPathSchema),
     packageStylesheets: Schema.optional(Schema.Array(Schema.String)),
@@ -33,16 +36,45 @@ const manifestSchema = Schema.fromJsonString(Schema.Struct({
     name: Schema.optional(Schema.String),
     dependencies: Schema.optional(Schema.Record(Schema.String, Schema.String)),
     scripts: Schema.optional(Schema.Record(Schema.String, Schema.String)),
-    fungi: Schema.optional(Schema.Struct({ build: Schema.optional(Schema.Unknown) })),
+    fungi: Schema.optional(Schema.Struct({
+        appId: Schema.optional(appIdSchema),
+        build: Schema.optional(Schema.Unknown),
+    })),
 }));
-/** A manifest's build policy; only `fungi.build` itself is held strict. */
-function policyOf(manifest) {
+/** Read package metadata once; only fungi.build rejects unknown fields. */
+export function readBuildManifest(packageJson) {
+    const manifest = Schema.decodeUnknownSync(manifestSchema)(packageJson);
     const build = manifest.fungi?.build;
-    return build === undefined
-        ? {}
-        : Schema.decodeUnknownSync(workspaceBuildPolicySchema, {
-            onExcessProperty: "error",
-        })(build);
+    return {
+        ...manifest,
+        fungi: {
+            ...manifest.fungi,
+            build: build === undefined
+                ? undefined
+                : Schema.decodeUnknownSync(workspaceBuildPolicySchema, {
+                    onExcessProperty: "error",
+                })(build),
+        },
+    };
+}
+/** Select an App recipe and root its paths in the captured source tree. */
+export function appBuildRecipe(manifest, directory) {
+    const recipe = Schema.decodeUnknownSync(pinnedRecipeSchema)(manifest.fungi.build);
+    if (directory === "")
+        return Schema.encodeSync(pinnedRecipeSchema)(recipe);
+    const root = Schema.decodeUnknownSync(manifestPathSchema)(directory);
+    const backend = recipe.backend;
+    return Schema.encodeSync(pinnedRecipeSchema)({
+        ...recipe,
+        entry: root + "/" + recipe.entry,
+        backend: backend?.entry === undefined
+            ? backend
+            : { ...backend, entry: root + "/" + backend.entry },
+    });
+}
+/** The same policy drives dependency products and the App page. */
+function policyOf(manifest) {
+    return manifest.fungi.build ?? {};
 }
 /** One pnpm workspace project, as `pnpm ls -r --depth -1 --json` lists it. */
 const workspaceProjectsSchema = Schema.fromJsonString(Schema.Array(Schema.Struct({
@@ -57,6 +89,23 @@ export const workspaceProjectsArguments = Object.freeze([
     "-1",
     "--json",
 ]);
+/** A nested package must own its build graph, never inherit its host's. */
+export class WorkspaceBuildError extends Error {
+    directory;
+    ownerDirectory;
+    /** The nearest package is absent from pnpm's workspace inventory. */
+    code = "non_workspace_package";
+    constructor(
+    /** The nearer package, relative to the captured source root. */
+    directory, 
+    /** The workspace whose dependencies would otherwise be inherited. */
+    ownerDirectory) {
+        super(`${directory} has its own package.json but is not a workspace member; refusing to inherit ${ownerDirectory || "the repository root"}'s build dependencies`);
+        this.directory = directory;
+        this.ownerDirectory = ownerDirectory;
+        this.name = "WorkspaceBuildError";
+    }
+}
 function within(root, path) {
     const relativePath = relative(root, resolve(root, path));
     if (relativePath === ".." ||
@@ -70,8 +119,10 @@ async function exists(path) {
 }
 /**
  * Derive one App's page build from the captured source alone: the manifest
- * nearest `entry` declares the App policy, the owning pnpm workspace's
- * runtime `workspace:` dependencies give the compile order, and each
+ * nearest `entry` must be the owning pnpm workspace (or standalone repository
+ * root). It declares the App policy, its
+ * runtime imports select its compile roots; their `workspace:` dependencies
+ * give the compile order, and each
  * dependency's manifest declares its own extra build products.
  */
 export async function resolveWorkspaceBuild(options) {
@@ -82,7 +133,7 @@ export async function resolveWorkspaceBuild(options) {
         const known = manifests.get(directory);
         if (known)
             return known;
-        const decoded = Schema.decodeUnknownSync(manifestSchema)(await readFile(join(root, directory, "package.json"), "utf8"));
+        const decoded = readBuildManifest(await readFile(join(root, directory, "package.json"), "utf8"));
         manifests.set(directory, decoded);
         return decoded;
     };
@@ -118,15 +169,38 @@ export async function resolveWorkspaceBuild(options) {
     while (appDirectory !== directory &&
         !(await exists(join(root, appDirectory, "package.json"))))
         appDirectory = parent(appDirectory);
+    if (appDirectory !== directory)
+        throw new WorkspaceBuildError(appDirectory, directory);
     const policy = policyOf(await manifest(appDirectory));
     if (policy.script !== undefined)
         throw new Error(`${appDirectory} is the App; its page builds with the recipe, not a script`);
+    const runtimeImports = await appRuntimeImports({
+        root,
+        entry,
+        backendEntry: options.backendEntry === undefined
+            ? policy.backend?.entry === undefined
+                ? undefined
+                : join(appDirectory, policy.backend.entry)
+            : (options.backendEntry ?? undefined),
+        shellEntry: policy.shellEntry === undefined
+            ? undefined
+            : join(appDirectory, policy.shellEntry),
+    });
+    const imported = (name) => runtimeImports.has(name) ||
+        [...runtimeImports].some((path) => path.startsWith(`${name}/`));
     const dependencies = [];
     const visiting = new Set([directory]);
     const visit = async (from) => {
         for (const [name, range] of Object.entries((await manifest(from)).dependencies ?? {})) {
             if (!range.startsWith("workspace:"))
                 continue;
+            // A package still builds its complete declared products. Only the App
+            // roots are narrowed: erased types and authoring-only imports do not
+            // compile the host runtime. Explicit stylesheet products remain roots.
+            if (from === directory &&
+                !imported(name) &&
+                !policy.packageStylesheets?.includes(name))
+                continue;
             const dependency = projects.get(name);
             if (dependency === undefined)
                 throw new Error(`${from} depends on an unlisted workspace ${name}`);

package/dist/build.d.ts

@@ -3,7 +3,7 @@ export * from "./build/local-build.js";
 export { createDefinitionEmission, type AppBackendOutput, type DefinitionEmission, } from "./build/definition-emission.js";
 export { readBundledHtml } from "./build/bundled-html.js";
 export { bundledHtmlRecipe, boundedBundlePolicy } from "./build/html-recipe.js";
-export { resolveWorkspaceBuild, workspaceBuildPolicySchema, workspaceProjectsArguments, type WorkspaceBuild, type WorkspaceBuildPolicy, } from "./build/workspace-build.js";
+export { resolveWorkspaceBuild, readBuildManifest, appBuildRecipe, type BuildManifest, WorkspaceBuildError, workspaceBuildPolicySchema, workspaceProjectsArguments, type WorkspaceBuild, type WorkspaceBuildPolicy, } from "./build/workspace-build.js";
 export { workspaceBuildStepSchema, type WorkspaceBuildStep, } from "./build/build-step.js";
 export { frozenSnapshotInstallArguments } from "./build/snapshot-package-store.js";
 export { repositoryEnvironment, artifactsGitEnvironment, hostedArtifactsGitRemote, } from "./build/git-environment.js";

package/dist/build.js

@@ -5,7 +5,7 @@ export * from "./build/local-build.js";
 export { createDefinitionEmission, } from "./build/definition-emission.js";
 export { readBundledHtml } from "./build/bundled-html.js";
 export { bundledHtmlRecipe, boundedBundlePolicy } from "./build/html-recipe.js";
-export { resolveWorkspaceBuild, workspaceBuildPolicySchema, workspaceProjectsArguments, } from "./build/workspace-build.js";
+export { resolveWorkspaceBuild, readBuildManifest, appBuildRecipe, WorkspaceBuildError, workspaceBuildPolicySchema, workspaceProjectsArguments, } from "./build/workspace-build.js";
 export { workspaceBuildStepSchema, } from "./build/build-step.js";
 export { frozenSnapshotInstallArguments } from "./build/snapshot-package-store.js";
 export { repositoryEnvironment, artifactsGitEnvironment, hostedArtifactsGitRemote, } from "./build/git-environment.js";

package/dist/catalog-frame.js

@@ -1,6 +1,6 @@
 import * as Schema from "effect/Schema";
 import { appIdSchema } from "@fungi.computer/puffball/effect";
-import { appCatalogResponseSchema, } from "./shell/app-directory.js";
+import { appCatalogResponseSchema, } from "@fungi.computer/nacre/app-directory";
 /** Guest input for `APPS.fork`: the platform App to fork and a chosen label. */
 export const appForkInputSchema = Schema.Struct({
     platformAppId: appIdSchema,

package/dist/cloudflare.d.ts

@@ -4,12 +4,18 @@ export type { BackgroundFrameState } from "./invocation.js";
 import { WorkerEntrypoint } from "cloudflare:workers";
 import { type GuestLimits } from "./guest-policy.js";
 export type { GuestLimits } from "./guest-policy.js";
+import type { ArtifactHeads, ArtifactStore, ArtifactStreams } from "./release.js";
 import { type AppBackendBindingName } from "@fungi.computer/puffball/app";
 import { type InvocationFrame, type InvocationGate } from "./invocation.js";
 import * as Schema from "effect/Schema";
 import { z } from "zod";
+import type { Release } from "@fungi.computer/puffball";
+import { type UiBootCheckOutcome } from "./boot-gate.js";
+export { checkBackendConstruction } from "./boot-construction.js";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
-import { type AppInstance, type InstancePorts } from "./index.js";
+import { AppInstanceError, type AppInstance, type InstancePorts } from "./index.js";
+/** Store Release artifacts without loading the Worker ownership barrel. */
+export declare function r2ArtifactStore(bucket: R2Bucket): ArtifactStore & ArtifactHeads & ArtifactStreams;
 /** Encode supervisor refusals before native RPC can discard Error properties. */
 export declare function captureFrameBindingReply<Value>(run: () => Promise<Value>): Promise<FrameBindingReply<Value>>;
 /** Retained shard reply ceiling; replies settle before the frame aborts its facet. */
@@ -50,7 +56,7 @@ export declare const backgroundFrameMethods: {
 };
 /** The shared RPC boundary decoder for host-minted invocation binding props. */
 export declare const frameBindingPropsSchema: Schema.Struct<{
-    readonly instanceId: Schema.Codec<import("./index.js").InstanceId, string, never, never>;
+    readonly instanceId: Schema.Codec<import("./instance-id.js").InstanceId, string, never, never>;
     readonly frameId: Schema.String;
     readonly binding: Schema.refine<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", Schema.String>;
 }>;
@@ -85,6 +91,8 @@ export type AppInstanceContext<FacetClass> = Readonly<{
         abort: (name: string, reason: Error) => void;
         /** Delete the named facet and its storage. */
         delete: (name: string) => void;
+        /** Native same-supervisor copy; absence refuses initialized-state probes. */
+        clone?: (source: string, destination: string) => void;
     }>;
 }>;
 /** The module set the Worker Loader runs for one App backend. */
@@ -118,6 +126,8 @@ export declare function createCloudflareInvocationGate<Host, FacetClass>(ctx: Pi
  * @param loader - The Worker Loader binding; without it backend execution is unavailable.
  * @param resolve - Resolves a Release ID to its verified durable backend.
  * @param guestEnv - Mints loopbacks bound to the captured invocation frame.
+ * @param bootUi - Host-owned UI check, or `null` when this executor deliberately skips it (for example, after the signed host already checked).
  * @param limits - Guest CPU and subrequest budgets; omitted fields use safe defaults.
+ * @param onAbort - Close the host's existing invocation frame after its state is fenced.
  */
-export declare function createCloudflareAppInstance<FacetClass, Host>(ctx: AppInstanceContext<FacetClass>, loader: AppInstanceLoader<FacetClass> | undefined, resolve: InstancePorts<Host>["resolve"], guestEnv: (frame: InvocationFrame<Host>) => object, limits?: Partial<GuestLimits>): AppInstance<Host>;
+export declare function createCloudflareAppInstance<FacetClass, Host>(ctx: AppInstanceContext<FacetClass>, loader: AppInstanceLoader<FacetClass> | undefined, resolve: InstancePorts<Host>["resolve"], guestEnv: (frame: InvocationFrame<Host>) => object, bootUi: (release: Release) => Promise<UiBootCheckOutcome | null>, limits?: Partial<GuestLimits>, onAbort?: (reason: AppInstanceError) => Promise<void>): AppInstance<Host>;