@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/build/build-step.js

@@ -0,0 +1,20 @@
+import * as Schema from "effect/Schema";
+/**
+ * One captured dependency build step. Paths are relative to the captured
+ * snapshot root. A TypeScript step compiles one config; a Tailwind step
+ * compiles one stylesheet input into its output (the same path for an App's
+ * own stylesheet, which compiles in place).
+ */
+export const workspaceBuildStepSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("typescript"),
+        config: Schema.String,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("tailwind"),
+        input: Schema.String,
+        output: Schema.String,
+    }),
+]);
+/** The steps one dependency-build process runs, encoded as one argument. */
+export const workspaceBuildStepsJsonSchema = Schema.fromJsonString(Schema.Array(workspaceBuildStepSchema));

package/dist/build/bundled-html.d.ts

@@ -0,0 +1,7 @@
+import type { PinnedRecipe, RawBuildOutput } from "./effect.js";
+/** Read only regular files under the captured entry's directory. No scripts,
+ * dependency hydration, URL rewriting, or access to the producer's live build.
+ */
+export declare function readBundledHtml(snapshot: string, recipe: PinnedRecipe): Promise<Extract<RawBuildOutput, {
+    kind: "assets";
+}>>;

package/dist/build/bundled-html.js

@@ -0,0 +1,64 @@
+import { lstat, opendir, readFile } from "node:fs/promises";
+import { dirname, extname, join } from "node:path";
+import * as Schema from "effect/Schema";
+import { assetPathSchema } from "@fungi.computer/puffball/assets";
+import { boundedBundlePolicy, bundledHtmlRecipe } from "./html-recipe.js";
+/** Read only regular files under the captured entry's directory. No scripts,
+ * dependency hydration, URL rewriting, or access to the producer's live build.
+ */
+export async function readBundledHtml(snapshot, recipe) {
+    const policy = recipe.assets;
+    if (!policy ||
+        !recipe.assetBase ||
+        !recipe.entry.endsWith("/index.html") ||
+        !boundedBundlePolicy(policy, recipe.maxOutputBytes))
+        throw new Error("Invalid bundled HTML policy");
+    // Check every ancestor before descending: a symlink is not a bundle root.
+    const parts = dirname(recipe.entry).split("/");
+    let root = snapshot;
+    for (const part of parts) {
+        if (!part || part === "." || part === ".." || part.includes("\\"))
+            throw new Error("Invalid bundle directory");
+        root = join(root, part);
+        if (!(await lstat(root)).isDirectory())
+            throw new Error("Bundle directory must be a captured directory");
+    }
+    const assets = [];
+    let total = 0;
+    let entries = 0;
+    const visit = async (directory, prefix) => {
+        const children = await opendir(directory);
+        for await (const child of children) {
+            // Bound traversal too, including empty directories.
+            if (++entries > policy.maxObjects * 2)
+                throw new Error("Bundle directory count exceeds policy");
+            const path = Schema.decodeUnknownSync(assetPathSchema)(`${prefix}/${child.name}`);
+            const source = join(directory, child.name);
+            if (child.isDirectory()) {
+                await visit(source, path);
+                continue;
+            }
+            if (!child.isFile() ||
+                !bundledHtmlRecipe.extensions.includes(extname(child.name)))
+                throw new Error("Bundle contains an unsupported file type");
+            if (assets.length >= policy.maxObjects)
+                throw new Error("Bundle file count exceeds policy");
+            const stat = await lstat(source);
+            total += stat.size;
+            if (!stat.isFile() ||
+                stat.size > policy.maxObjectBytes ||
+                !Number.isSafeInteger(total) ||
+                total > policy.maxTotalBytes)
+                throw new Error("Bundle bytes exceed policy");
+            const bytes = await readFile(source);
+            if (bytes.byteLength !== stat.size)
+                throw new Error("Bundle changed during capture");
+            assets.push({ path, bytes });
+        }
+    };
+    await visit(root, "");
+    if (!assets.some((asset) => asset.path === "/index.html"))
+        throw new Error("Bundle is missing its HTML entry");
+    assets.sort((a, b) => a.path.localeCompare(b.path));
+    return { kind: "assets", base: recipe.assetBase, assets };
+}

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,231 @@
+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";
+/** 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;
+}>;
+/** 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;
+}>;
+/** 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;