@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/dist/build/content-objects.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A build's uploaded objects in an R2-shaped store: content addressed
+ * (`artifact:sha256-<hex>`), written once from a stream with the store
+ * itself verifying the digest, and described by `head()` without a read.
+ * The bytes never pass through an isolate's memory as a whole.
+ */
+import { type ArtifactRef, type Sha256Digest } from "@fungi.computer/puffball";
+import type { ArtifactHead } from "../release.js";
+import type { CandidateObject, CandidateObjectMediaType } from "./submission-contract.js";
+/** The parts of an R2 bucket a content-object store uses. */
+export type ContentObjectBucket = Readonly<{
+    /** Describe the object at `key` without its body, or `null` when absent. */
+    head(key: string): Promise<Readonly<{
+        size: number;
+        checksums: Readonly<{
+            sha256?: ArrayBuffer;
+        }>;
+    }> | null>;
+    /** Store `value` at `key`; the bucket refuses bytes whose SHA-256 differs. */
+    put(key: string, value: ReadableStream<Uint8Array> | Uint8Array, options: Readonly<{
+        sha256: string;
+        httpMetadata: Readonly<{
+            contentType: CandidateObjectMediaType;
+        }>;
+    }>): Promise<object | null>;
+}>;
+/** The store key of one content-addressed object. */
+export declare function contentObjectRef(digest: Sha256Digest): ArtifactRef;
+/** Describe a stored object by its size and the SHA-256 the store verified. */
+export declare function headContentObject(bucket: ContentObjectBucket, artifactRef: ArtifactRef): Promise<ArtifactHead | null>;
+/**
+ * Stream one object into the store under its digest. The store refuses a
+ * body whose SHA-256 differs; an object already stored with the same
+ * verified digest and size is kept (write-once: a stored version may be
+ * pinned by a Release) and the body is discarded, never stored.
+ */
+export declare function putContentObject(bucket: ContentObjectBucket, object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType): Promise<"stored" | "refused">;

package/dist/build/content-objects.js

@@ -0,0 +1,53 @@
+/**
+ * A build's uploaded objects in an R2-shaped store: content addressed
+ * (`artifact:sha256-<hex>`), written once from a stream with the store
+ * itself verifying the digest, and described by `head()` without a read.
+ * The bytes never pass through an isolate's memory as a whole.
+ */
+import { parseArtifactRef, parseSha256Digest, } from "@fungi.computer/puffball";
+/** The store key of one content-addressed object. */
+export function contentObjectRef(digest) {
+    return parseArtifactRef(`artifact:sha256-${digest.slice("sha256:".length)}`);
+}
+function hex(bytes) {
+    return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Describe a stored object by its size and the SHA-256 the store verified. */
+export async function headContentObject(bucket, artifactRef) {
+    const object = await bucket.head(artifactRef);
+    if (object === null)
+        return null;
+    const sha256 = object.checksums.sha256;
+    return {
+        byteLength: object.size,
+        digest: sha256 === undefined ? null : parseSha256Digest(`sha256:${hex(sha256)}`),
+    };
+}
+/**
+ * Stream one object into the store under its digest. The store refuses a
+ * body whose SHA-256 differs; an object already stored with the same
+ * verified digest and size is kept (write-once: a stored version may be
+ * pinned by a Release) and the body is discarded, never stored.
+ */
+export async function putContentObject(bucket, object, body, mediaType) {
+    const artifactRef = contentObjectRef(object.digest);
+    const existing = await headContentObject(bucket, artifactRef);
+    if (existing !== null &&
+        existing.digest === object.digest &&
+        existing.byteLength === object.byteLength) {
+        // Read the body through (discarding it) rather than cancel it: a
+        // cancelled request body resets the uploader's connection mid-send.
+        await body?.pipeTo(new WritableStream());
+        return "stored";
+    }
+    try {
+        await bucket.put(artifactRef, body ?? new Uint8Array(0), {
+            sha256: object.digest.slice("sha256:".length),
+            httpMetadata: { contentType: mediaType },
+        });
+    }
+    catch {
+        return "refused";
+    }
+    return "stored";
+}

package/dist/build/definition-emission.d.ts

@@ -0,0 +1,34 @@
+import type * as esbuild from "esbuild";
+import type { AppDeclaration } from "@fungi.computer/puffball";
+import type { CapturedSource, PinnedRecipe } from "./effect.js";
+/** Package entry policy pinned only by the captured source recipes that need it. */
+export declare function appBackendPackageMainFields(recipe: PinnedRecipe): string[] | undefined;
+/** The checked Worker output of one App backend build. */
+export type AppBackendOutput = Readonly<{
+    file: esbuild.OutputFile;
+    /** Source inputs contributing to the Worker bundle. */
+    inputs: readonly string[];
+}>;
+/**
+ * Build one App backend and derive its declaration from that same build.
+ *
+ * A declared `fungi.backendDefinition` adds a second, build-only entry that
+ * derives the declaration with `buildAppDeclaration(appBackend, fungi.app)`.
+ * esbuild loads every path and resolves every import once per build, so the
+ * Worker serves exactly the definition bytes and module resolution the
+ * declaration describes. The Worker output is then checked to include that
+ * definition and no build-only declaration code, and the declaration output to
+ * import nothing at runtime.
+ */
+export declare function createDefinitionEmission(source: CapturedSource, recipe: PinnedRecipe): Promise<{
+    /** Entries for the one backend build: the Worker and, if defined, its declaration. */
+    entryPoints: (entry: string) => Record<string, string>;
+    outdir: string;
+    plugins: esbuild.Plugin[];
+    /** Check one finished backend build and return its Worker output. */
+    worker(result: esbuild.BuildResult): AppBackendOutput;
+    /** Evaluate the declaration derived in the checked backend build. */
+    declare(signal: AbortSignal): Promise<AppDeclaration>;
+}>;
+/** One App backend build and the declaration derived from it. */
+export type DefinitionEmission = Awaited<ReturnType<typeof createDefinitionEmission>>;

package/dist/build/definition-emission.js

@@ -0,0 +1,201 @@
+import { execFile } from "node:child_process";
+import { access, readFile, realpath, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import * as Schema from "effect/Schema";
+import { appDeclarationSchema } from "@fungi.computer/puffball/app";
+import { emptyAppDeclaration } from "@fungi.computer/puffball";
+const packageSchema = Schema.fromJsonString(Schema.Struct({
+    fungi: Schema.optional(Schema.Struct({
+        app: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+        backendDefinition: Schema.optional(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256))),
+    })),
+}));
+// The Computer VM is the customer-code sandbox. These rules enforce the SDK's
+// runtime-neutral definition convention; they are not a Node security sandbox.
+const evaluateDefinition = `
+import { registerHooks } from 'node:module';
+const entry = process.argv[1];
+const write = process.stdout.write.bind(process.stdout);
+const writeError = process.stderr.write.bind(process.stderr);
+const exit = process.exit.bind(process);
+registerHooks({ resolve(specifier, context, next) {
+  if (specifier !== entry) throw new Error('App backend definition imports ' + specifier + '. Move runtime-specific imports into the Worker composition; keep the definition runtime-neutral.');
+  return next(specifier, context);
+}});
+globalThis.fetch = () => { throw new Error('App backend definition attempted network access. Move network calls into method handlers; evaluation must be runtime-neutral.'); };
+globalThis.WebSocket = undefined;
+globalThis.process = undefined;
+try {
+const { appDeclaration } = await import(entry);
+write(JSON.stringify(appDeclaration));
+} catch (error) {
+  writeError((error instanceof Error ? error.message : "App definition evaluation failed").split("\\n")[0] + "\\n");
+  exit(1);
+}
+`;
+const evaluationFailureSchema = Schema.Struct({ stderr: Schema.String });
+const evaluationFailure = (cause) => {
+    if (Schema.is(evaluationFailureSchema)(cause)) {
+        const message = cause.stderr.trim().split("\n")[0];
+        if (message)
+            return new Error(message);
+    }
+    return new Error("App definition evaluation failed before emitting a declaration");
+};
+async function appPackage(source, recipe) {
+    let directory = dirname(join(source.snapshotPath, recipe.entry));
+    for (;;) {
+        const file = join(directory, "package.json");
+        const present = await access(file).then(() => true, () => false);
+        if (present)
+            return {
+                directory,
+                metadata: Schema.decodeUnknownSync(packageSchema)(await readFile(file, "utf8")),
+            };
+        if (directory === source.snapshotPath)
+            return { directory, metadata: {} };
+        const parent = dirname(directory);
+        const path = relative(source.snapshotPath, parent);
+        if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+            throw new Error("App entry is outside its captured source");
+        directory = parent;
+    }
+}
+/** Package entry policy pinned only by the captured source recipes that need it. */
+export function appBackendPackageMainFields(recipe) {
+    return recipe.toolchain.packageResolution ===
+        "captured-browser-module-main-v1"
+        ? ["browser", "module", "main"]
+        : undefined;
+}
+/** Output directory naming the Worker and declaration bundles of one build. */
+const backendOutputDirectory = ".fungi-backend";
+const declarationEntry = "fungi:app-declaration";
+const declarationNamespace = "fungi-app-declaration";
+const buildOnlySdk = "@fungi.computer/agar/backend-declaration";
+const buildOnlySdkFile = /(?:^|\/)agar\/(?:src|dist)\/backend-declaration\.(?:js|ts)$/;
+/** Metafile paths are relative to the build's working directory, with `/`. */
+const metafilePath = (source, path) => relative(source.snapshotPath, path).split(sep).join("/");
+/**
+ * Build one App backend and derive its declaration from that same build.
+ *
+ * A declared `fungi.backendDefinition` adds a second, build-only entry that
+ * derives the declaration with `buildAppDeclaration(appBackend, fungi.app)`.
+ * esbuild loads every path and resolves every import once per build, so the
+ * Worker serves exactly the definition bytes and module resolution the
+ * declaration describes. The Worker output is then checked to include that
+ * definition and no build-only declaration code, and the declaration output to
+ * import nothing at runtime.
+ */
+export async function createDefinitionEmission(source, recipe) {
+    const { directory, metadata } = await appPackage(source, recipe);
+    const app = metadata.fungi?.app;
+    const packageDeclaration = app === undefined
+        ? emptyAppDeclaration
+        : Schema.decodeUnknownSync(appDeclarationSchema)({
+            handlers: [],
+            roles: [],
+            ...app,
+        });
+    const definition = metadata.fungi?.backendDefinition;
+    let definitionPath = null;
+    if (definition !== undefined) {
+        definitionPath = await realpath(join(directory, definition));
+        const path = relative(await realpath(source.snapshotPath), definitionPath);
+        if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path))
+            throw new Error("App backend definition must be inside its captured source");
+        if (recipe.backend === null)
+            throw new Error("An App backend definition requires a backend build recipe");
+    }
+    const workerPath = join(source.snapshotPath, backendOutputDirectory, "worker.js");
+    const declarationPath = join(source.snapshotPath, backendOutputDirectory, "declaration.js");
+    let declarationCode;
+    const declarationPlugin = {
+        name: "derived-app-declaration",
+        setup(build) {
+            // Only the build's own declaration entry may load the derivation.
+            build.onResolve({ filter: /^fungi:app-declaration$/ }, (args) => args.kind === "entry-point"
+                ? { path: "app-declaration.js", namespace: declarationNamespace }
+                : undefined);
+            build.onLoad({ filter: /.*/, namespace: declarationNamespace }, () => ({
+                contents: `import { appBackend } from ${JSON.stringify(definitionPath)}; import { buildAppDeclaration } from ${JSON.stringify(buildOnlySdk)}; export const appDeclaration = buildAppDeclaration(appBackend, ${JSON.stringify(packageDeclaration)});`,
+                resolveDir: directory,
+                loader: "js",
+            }));
+        },
+    };
+    return {
+        /** Entries for the one backend build: the Worker and, if defined, its declaration. */
+        entryPoints: (entry) => definitionPath === null
+            ? { worker: entry }
+            : { worker: entry, declaration: declarationEntry },
+        outdir: backendOutputDirectory,
+        plugins: definitionPath === null ? [] : [declarationPlugin],
+        /** Check one finished backend build and return its Worker output. */
+        worker(result) {
+            const metafile = result.metafile;
+            if (metafile === undefined)
+                throw new Error("App backend build did not return its metafile");
+            const outputs = result.outputFiles ?? [];
+            const expected = definitionPath === null ? [workerPath] : [workerPath, declarationPath];
+            const file = outputs.find((output) => output.path === workerPath);
+            if (file === undefined ||
+                outputs.length !== expected.length ||
+                !outputs.every((output) => expected.includes(output.path)))
+                throw new Error("App backend build must emit exactly its Worker and declaration");
+            const workerMeta = metafile.outputs[metafilePath(source, workerPath)];
+            if (workerMeta === undefined)
+                throw new Error("App backend build did not describe its Worker");
+            const inputs = Object.keys(workerMeta.inputs);
+            if (definitionPath === null)
+                return { file, inputs };
+            if (!inputs.includes(metafilePath(source, definitionPath)))
+                throw new Error("The Worker must import its declared fungi.backendDefinition; the declaration is derived from the definition it serves");
+            if (inputs.some((input) => input.startsWith(`${declarationNamespace}:`) ||
+                buildOnlySdkFile.test(input) ||
+                metafile.inputs[input]?.imports.some((imported) => imported.original === buildOnlySdk) === true))
+                throw new Error("The Worker must not import build-only App declaration code");
+            const declaration = outputs.find((output) => output.path === declarationPath);
+            const declarationMeta = metafile.outputs[metafilePath(source, declarationPath)];
+            if (declaration === undefined || declarationMeta === undefined)
+                throw new Error("App backend build did not derive its declaration");
+            const external = declarationMeta.imports.find((imported) => imported.external === true);
+            if (external !== undefined)
+                throw new Error(`App backend definition imports ${external.path}. Move runtime-specific imports into the Worker composition; keep the definition runtime-neutral.`);
+            if (declaration.contents.byteLength > recipe.maxOutputBytes)
+                throw new Error("App backend definition exceeds its pinned build bound");
+            declarationCode = declaration.text;
+            return { file, inputs };
+        },
+        /** Evaluate the declaration derived in the checked backend build. */
+        async declare(signal) {
+            if (definitionPath === null) {
+                if (packageDeclaration.api &&
+                    Object.keys(packageDeclaration.api.methods).length > 0)
+                    throw new Error("App API methods require fungi.backendDefinition; the build derives them from its methods instead of a handwritten table");
+                return packageDeclaration;
+            }
+            if (declarationCode === undefined)
+                throw new Error("The App declaration is derived from a checked backend build");
+            const file = join(source.snapshotPath, ".fungi-built-definition.mjs");
+            await writeFile(file, declarationCode, { flag: "wx", mode: 0o600 });
+            const result = await promisify(execFile)(process.execPath, [
+                "--input-type=module",
+                "--eval",
+                evaluateDefinition,
+                pathToFileURL(file).href,
+            ], {
+                cwd: source.snapshotPath,
+                env: {},
+                maxBuffer: 1024 * 1024,
+                timeout: 30_000,
+                signal,
+            }).catch((cause) => {
+                throw evaluationFailure(cause);
+            });
+            return Schema.decodeUnknownSync(Schema.fromJsonString(appDeclarationSchema), { onExcessProperty: "error" })(result.stdout);
+        },
+    };
+}

package/dist/build/effect.d.ts

@@ -0,0 +1,249 @@
+import { type AppId, type ArtifactRef, type AppReleaseCatalog, type Release, type ReleaseId, type Sha256Digest, type SourceRevision } from "@fungi.computer/puffball";
+import type { AppDeclaration } from "@fungi.computer/puffball";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+import type { CandidateOutputManifest } from "./submission-contract.js";
+/** Canonical recipe policy shared by core and the local adapter. */
+export declare const pinnedRecipeSchema: Schema.Struct<{
+    readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+    readonly entry: Schema.String;
+    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>;
+    readonly backend: 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.Number;
+}>;
+/** Core configuration contains only immutable App identity and recipe policy. */
+export declare const AppPublisherCoreConfigSchema: Schema.Struct<{
+    readonly appId: Schema.refine<AppId, Schema.String>;
+    readonly recipe: Schema.Struct<{
+        readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+        readonly entry: Schema.String;
+        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>;
+        readonly backend: 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.Number;
+    }>;
+}>;
+/** App identity and caller-selected recipe inputs before normalization. */
+export type AppPublisherCoreConfigInput = Schema.Codec.Encoded<typeof AppPublisherCoreConfigSchema>;
+/** Package-export conditions used by the pinned Workers builder. */
+export declare const appBackendExportConditions: readonly string[];
+/** Persisted, fully resolved recipe including its code-owned toolchain. */
+export declare const capturedPinnedRecipeSchema: Schema.Struct<{
+    readonly kind: Schema.optional<Schema.Literals<readonly ["bundled-html", "source-html"]>>;
+    readonly bundle: Schema.Literal<true>;
+    readonly entry: Schema.String;
+    readonly format: Schema.Literals<readonly ["html", "esm", "assets"]>;
+    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>;
+    readonly toolchain: Schema.$Record<Schema.String, Schema.String>;
+    readonly maxOutputBytes: Schema.Number;
+    readonly platform: Schema.Literals<readonly ["browser", "neutral"]>;
+    readonly backend: 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 target: Schema.Tuple<readonly [Schema.Literal<"es2022">]>;
+}>;
+/** Fully resolved recipe with its pinned toolchain. */
+export type PinnedRecipe = Schema.Schema.Type<typeof capturedPinnedRecipeSchema>;
+/** A source tree captured into a scoped local snapshot directory. */
+export type CapturedSource = Readonly<{
+    readonly sourceRevision: SourceRevision;
+    readonly sourceTreeDigest: Sha256Digest;
+    readonly snapshotPath: string;
+}>;
+/** Compiler bytes or a bounded collection of emitted UI assets. */
+export type RawBuildOutput = Readonly<{
+    readonly kind: "bytes";
+    readonly bytes: Uint8Array;
+}> | Readonly<{
+    readonly kind: "assets";
+    readonly base: string;
+    readonly assets: readonly {
+        readonly path: string;
+        readonly bytes: Uint8Array;
+    }[];
+}>;
+/** A complete HTML document or an asset collection. */
+export type UiBuildOutput = Readonly<{
+    readonly kind: "html";
+    readonly bytes: Uint8Array;
+}> | Extract<RawBuildOutput, {
+    readonly kind: "assets";
+}>;
+/** Raw executor result before the recipe owner assigns App surface meaning. */
+export type BuildExecutorOutput = RawBuildOutput | Readonly<{
+    readonly kind: "app";
+    readonly ui: PreparedUiOutput | null;
+    readonly backend: Uint8Array | null;
+}>;
+/** UI output paired with its immutable artifact media type. */
+export type PreparedUiOutput = Readonly<{
+    readonly content: Extract<UiBuildOutput, {
+        readonly kind: "html";
+    }>;
+    readonly mediaType: "text/html; charset=utf-8";
+}> | Readonly<{
+    readonly content: Extract<UiBuildOutput, {
+        readonly kind: "assets";
+    }>;
+    readonly mediaType: "application/vnd.fungi.app-assets+json";
+}>;
+/** Complete, non-empty App content accepted by immutable artifact writers. */
+export type BuildOutput = (Readonly<{
+    readonly kind: "ui";
+    readonly ui: PreparedUiOutput;
+}> | Readonly<{
+    readonly kind: "backend";
+    readonly backend: Uint8Array;
+}> | Readonly<{
+    readonly kind: "app";
+    readonly ui: PreparedUiOutput;
+    readonly backend: Uint8Array;
+}>) & Readonly<{
+    /** The source's declared request; absent means the App asks for nothing. */
+    readonly declaration?: AppDeclaration;
+}>;
+/** Reference and digest of the persisted App build root. */
+export type StoredArtifact = Readonly<{
+    readonly artifactRef: ArtifactRef;
+    readonly artifactDigest: Sha256Digest;
+}>;
+/** A locally captured and built candidate awaiting native artifact/catalog custody. */
+export type PreparedCandidate = Readonly<{
+    readonly appId: AppId;
+    readonly releaseId: ReleaseId;
+    readonly output: BuildOutput;
+    readonly provenance: Readonly<{
+        readonly sourceRevision: SourceRevision;
+        readonly sourceTreeDigest: Sha256Digest;
+        readonly buildRecipeDigest: Sha256Digest;
+    }>;
+}>;
+/** Four structural roles used by the private composition. */
+export type SourceCapture = {
+    /** Acquire a snapshot whose cleanup follows the Effect scope. */
+    readonly capture: () => Effect.Effect<CapturedSource, unknown, Scope.Scope>;
+};
+/** Compiles captured source and reads its matching declaration. */
+export type BuildExecutor = {
+    /** Compile only the captured source under its pinned recipe. */
+    readonly build: (source: CapturedSource, recipe: PinnedRecipe) => Effect.Effect<BuildExecutorOutput, unknown, Scope.Scope>;
+    /**
+     * Read the App's declaration from the same captured tree. Every App, a fork
+     * included, declares through its own source; there is no other source.
+     */
+    readonly declaration?: (source: CapturedSource, recipe: PinnedRecipe) => Effect.Effect<AppDeclaration, unknown>;
+};
+/** Persists one complete App build as immutable artifacts. */
+export type ArtifactWriter = {
+    /** Persist the App root and return its reference and digest. */
+    readonly write: (output: BuildOutput) => Effect.Effect<StoredArtifact, unknown>;
+};
+/** Release catalog role needed to record a built candidate. */
+export type ReleaseCreator = Pick<AppReleaseCatalog, "createRelease">;
+/** Captured build inputs and the resource owners used to publish a candidate. */
+export type AppPublisherOptions = Readonly<{
+    readonly config: AppPublisherCoreConfigInput;
+    readonly releaseCatalog: ReleaseCreator;
+    readonly sourceCapture: SourceCapture;
+    readonly buildExecutor: BuildExecutor;
+    readonly artifactWriter: ArtifactWriter;
+}>;
+/** Builds and records immutable App Release candidates. */
+export type AppPublisher = Readonly<{
+    /** Capture, build, store, attest, and create exactly one candidate. */
+    readonly createCandidate: (releaseId: ReleaseId) => Effect.Effect<Release, AppPublisherError>;
+}>;
+/** Builds a candidate before artifact storage and catalog publication. */
+export type AppCandidatePreparer = Readonly<{
+    /** Capture and build once; persistence remains with the resource-native host. */
+    readonly prepareCandidate: (releaseId: ReleaseId) => Effect.Effect<PreparedCandidate, AppPublisherError>;
+}>;
+/** The bounded stages reported by AppPublisherError. */
+export type AppPublisherStage = "configuration" | "source" | "build" | "artifact" | "release";
+/** Closed failure boundary for the four private composition stages. */
+export declare class AppPublisherError extends Error {
+    readonly stage: AppPublisherStage;
+    readonly _tag: "AppPublisherError";
+    constructor(stage: AppPublisherStage, options?: ErrorOptions);
+}
+/** App identity and normalized recipe with its digest. */
+export type CapturedConfig = Readonly<{
+    readonly appId: AppId;
+    readonly recipe: PinnedRecipe;
+    readonly buildRecipeDigest: Sha256Digest;
+}>;
+/**
+ * Whether a pinned recipe pins this Publisher's current toolchain (its build
+ * policy included). An executor refuses any other: a recipe pinned under
+ * another policy describes a build this code does not perform.
+ */
+export declare function pinsCurrentToolchain(recipe: PinnedRecipe): boolean;
+/** Hash every captured build and output-policy input in the Publisher recipe. */
+export declare function digestPinnedRecipe(recipe: PinnedRecipe): Sha256Digest;
+/** Decode and normalize Publisher-owned recipe policy for durable seed proof. */
+export declare function normalizeAppPublisherRecipe(input: {
+    appId: string;
+    recipe: AppPublisherCoreConfigInput["recipe"];
+}): Readonly<{
+    recipe: PinnedRecipe;
+    buildRecipeDigest: Sha256Digest;
+}>;
+/**
+ * The largest single object a build under this recipe may upload: no larger
+ * than the largest output bound the recipe could assign it under.
+ */
+export declare function pinnedRecipeObjectBound(recipe: PinnedRecipe): number;
+/**
+ * Whether output built elsewhere (a Computer's candidate manifest) is one
+ * this recipe could assign: the same surfaces and `maxOutputBytes` bound the
+ * preparer applies here. Asset sizes stay the artifact writer's policy.
+ */
+export declare function fitsPinnedRecipe(output: CandidateOutputManifest, recipe: PinnedRecipe): boolean;
+/** Construct one private App Publisher with copied core configuration and roles. */
+export declare function createAppCandidatePreparer(options: Pick<AppPublisherOptions, "config" | "sourceCapture" | "buildExecutor">): AppCandidatePreparer;
+/** Prepare a candidate from a previously captured recipe. */
+export declare function createCapturedCandidatePreparer(config: CapturedConfig, options: Pick<AppPublisherOptions, "sourceCapture" | "buildExecutor">): AppCandidatePreparer;
+/** Persist a prepared build through the native artifact and App Release owners. */
+export declare function commitPreparedCandidate(prepared: PreparedCandidate, options: Pick<AppPublisherOptions, "artifactWriter" | "releaseCatalog">): Effect.Effect<Release, AppPublisherError>;
+/** Compose capture, compilation, immutable writing and Release recording. */
+export declare function createAppPublisher(options: AppPublisherOptions): AppPublisher;