@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/app-builds.d.ts

@@ -19,6 +19,7 @@
 import * as Schema from "effect/Schema";
 import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
 import { type Release } from "@fungi.computer/puffball";
+import { type AppPublisherCoreConfigInput } from "./build/effect.js";
 import { type TeamAppCandidateManifest } from "./build/submission-contract.js";
 import { type ArtifactHeads, type ArtifactStore } from "./release.js";
 import type { PublisherTemplateSeedReceipts } from "./source/seed-receipt.js";
@@ -77,6 +78,19 @@ export declare const oysterBuildSourceSchema: Schema.Struct<{
     readonly buildRecipeDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
 }>;
 export type OysterBuildSource = Schema.Schema.Type<typeof oysterBuildSourceSchema>;
+/** Installation is a build outcome, never a pending consent/approval record. */
+export declare const oysterBuildInstallationSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"pending">;
+    readonly installationId: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["installed", "needs_consent"]>;
+    readonly installationId: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"failed">;
+    readonly installationId: Schema.String;
+    readonly detail: Schema.String;
+}>]>;
+export type OysterBuildInstallation = Schema.Schema.Type<typeof oysterBuildInstallationSchema>;
 /** What an owner sees of one build. */
 export type OysterBuildView = Readonly<{
     jobId: string;
@@ -86,8 +100,42 @@ export type OysterBuildView = Readonly<{
     status: "running" | "succeeded" | "failed" | "revoked";
     detail: string | null;
     release: Release | null;
+    installation: OysterBuildInstallation | null;
+}>;
+/** Known preflight refusals, before a job or Computer run exists. */
+export declare const oysterBuildStartReasonSchema: Schema.Literals<readonly ["invalid_revision", "no_source", "not_template_seed", "no_backend"]>;
+export type OysterBuildStartReason = Schema.Schema.Type<typeof oysterBuildStartReasonSchema>;
+export declare const oysterBuildStartMessages: {
+    invalid_revision: string;
+    no_source: string;
+    no_backend: string;
+    not_template_seed: string;
+};
+declare const OysterBuildStartError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OysterBuildStartError";
+} & Readonly<A>;
+/** Local typed failure. The registry turns it into data before a DO RPC. */
+export declare class OysterBuildStartError extends OysterBuildStartError_base<{
+    readonly reason: OysterBuildStartReason;
+    readonly message: string;
+}> {
+    constructor(reason: OysterBuildStartReason);
+}
+export type OysterBuildStartResult = Readonly<{
+    kind: "started";
+    build: OysterBuildView;
+}> | Readonly<{
+    kind: "refused";
+    reason: OysterBuildStartReason;
+}>;
+export type OysterBuildBackend = Readonly<{
+    kind: "hosted";
+}> | Readonly<{
+    kind: "no_backend";
 }>;
 export type OysterBuildComputer = Readonly<{
+    /** Read the configured hosted route without starting a machine. Local machines never build Apps. */
+    buildBackend(): Promise<OysterBuildBackend>;
     /** Run the fixed build command; the Computer re-admits the job first.
      * A missing `output` means no terminal result was established: the
      * command may still be running, so it is never read as an exit. */
@@ -118,17 +166,28 @@ export type OysterAppBuildOptions = Readonly<{
     templates: Pick<PublisherTemplateSeedReceipts, "read">;
     now?: () => number;
 }>;
-/**
- * The SQLite tables one Oyster build owner keeps. Creation and any carrying
- * forward of retained facts run as one transaction of the owner's storage, so
- * an interrupted conversion leaves the facts as they were for a retry.
- */
+/** Create the current build tables and index atomically; never convert old stores. */
 export declare function migrateOysterAppBuilds(owner: WatchdogSqliteOwner): void;
 /** The build owner over one tenant's SQLite, Computer and artifact store. */
 export declare function createOysterAppBuilds(options: OysterAppBuildOptions): Readonly<{
     /** Record (or replace) an App's build source; the caller is the owner. */
-    registerSource(source: OysterBuildSource): OysterBuildSource;
+    registerSource: (source: OysterBuildSource) => OysterBuildSource;
+    /** Resolve repository identity and replace its current recipe as one transition.
+     * A fork's existing identity wins over the copied manifest's App id. */
+    registerRepositorySource(input: {
+        appId: string;
+        location: Extract<OysterBuildLocation, {
+            kind: "installation";
+        }>;
+        recipe: AppPublisherCoreConfigInput["recipe"];
+    }): {
+        kind: "registered";
+        source: OysterBuildSource;
+    } | {
+        kind: "conflict";
+    };
     readSource: (appId: string) => OysterBuildSource | null;
+    readRepositorySource: (installationId: string, repository: string) => OysterBuildSource | null;
     /**
      * Mint one build job for an App's registered source at one exact commit.
      * A template source builds only a seed revision recorded for its pinned
@@ -136,15 +195,28 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
      * Answers the job and its one run, which the caller keeps alive (the
      * upload grant exists only inside that run's fixed command).
      */
-    start(input: {
+    start: (input: {
         appId: string;
         sourceRevision: string;
         requestedBy: string;
-    }): Promise<Readonly<{
+        /** The Workflow's installation target. Absence leaves manual builds manual. */
+        installAt?: string;
+        /** One host-owned Workflow node reuses its job, including after restart. */
+        requestId?: string;
+    }) => Promise<Readonly<{
         build: OysterBuildView;
         run: () => Promise<OysterBuildView>;
     }>>;
     read(jobId: string): OysterBuildView | null;
+    /** Discover the current source's latest job from the caller's Git owner,
+     * never a job id remembered in a browser or another installation's repo. */
+    latestRepositoryBuild(installationId: string, repository: string): OysterBuildView | null;
+    /** One bounded host installation at a time. Only a verified successful
+     * build may reach the installer; the same existing row owns its outcome.
+     * A Workflow retry may resume a pending decision, never a terminal one. */
+    install(jobId: string, decide: (release: Release, installationId: string) => Promise<Exclude<OysterBuildInstallation, {
+        kind: "pending";
+    }>>): Promise<boolean>;
     /** A built Release by id, for an owner to install or select. */
     release(releaseId: string): Release | null;
     /** May this Computer execute this job now? Re-checked by the Computer. */
@@ -208,3 +280,4 @@ export declare function createOysterAppBuilds(options: OysterAppBuildOptions): R
     submitCandidate(jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string): Promise<Response>;
 }>;
 export type OysterAppBuilds = ReturnType<typeof createOysterAppBuilds>;
+export {};

package/dist/app-builds.js

@@ -17,9 +17,11 @@
  * installed one, and records it; installing it is a separate owner act.
  */
 import * as Schema from "effect/Schema";
+import * as Data from "effect/Data";
+import * as Option from "effect/Option";
 import { parseArtifactRef, parseReleaseId, } from "@fungi.computer/puffball";
 import { appIdSchema, releaseSchema, sha256DigestSchema, sourceRevisionSchema, } from "@fungi.computer/puffball/effect";
-import { capturedPinnedRecipeSchema, digestPinnedRecipe, fitsPinnedRecipe, pinnedRecipeObjectBound, } from "./build/effect.js";
+import { capturedPinnedRecipeSchema, normalizeAppPublisherRecipe, digestPinnedRecipe, fitsPinnedRecipe, pinnedRecipeObjectBound, } from "./build/effect.js";
 import { candidateManifestObjects, decodeCandidateBackend, digestTeamAppCandidateManifest, } from "./build/submission-contract.js";
 import { contentObjectRef } from "./build/content-objects.js";
 import { createTeamBuildPublisher, teamAppBuildCommand, } from "./build/build-jobs.js";
@@ -52,6 +54,42 @@ export const oysterBuildSourceSchema = Schema.Struct({
     recipe: capturedPinnedRecipeSchema,
     buildRecipeDigest: sha256DigestSchema,
 });
+/** Installation is a build outcome, never a pending consent/approval record. */
+export const oysterBuildInstallationSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("pending"),
+        installationId: Schema.String,
+    }),
+    Schema.Struct({
+        kind: Schema.Literals(["installed", "needs_consent"]),
+        installationId: Schema.String,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("failed"),
+        installationId: Schema.String,
+        detail: Schema.String,
+    }),
+]);
+const installationCodec = Schema.fromJsonString(oysterBuildInstallationSchema);
+/** Known preflight refusals, before a job or Computer run exists. */
+export const oysterBuildStartReasonSchema = Schema.Literals([
+    "invalid_revision",
+    "no_source",
+    "not_template_seed",
+    "no_backend",
+]);
+export const oysterBuildStartMessages = {
+    invalid_revision: "Source revision must be git: followed by a full commit hash",
+    no_source: "App has no build source",
+    no_backend: "No hosted build backend is attached to this Computer",
+    not_template_seed: "Revision is not a seed of this App's template",
+};
+/** Local typed failure. The registry turns it into data before a DO RPC. */
+export class OysterBuildStartError extends Data.TaggedError("OysterBuildStartError") {
+    constructor(reason) {
+        super({ reason, message: oysterBuildStartMessages[reason] });
+    }
+}
 /** One Computer as the build owner reaches it. */
 /** The Computer established no terminal result for a build command, for
  * example because its connection to the container dropped mid-command. */
@@ -76,10 +114,12 @@ const jobRow = Schema.Struct({
     requested_by: Schema.String,
     credential_id: Schema.String,
     upload_grant_digest: Schema.String,
+    request_id: Schema.NullOr(Schema.String),
     status: Schema.Literals(["running", "succeeded", "failed", "revoked"]),
     artifact_digest: Schema.NullOr(Schema.String),
     artifact_bytes: Schema.NullOr(Schema.Number),
     detail: Schema.NullOr(Schema.String),
+    installation: Schema.NullOr(installationCodec),
     issued_at: Schema.Number,
     expires_at: Schema.Number,
     executable_until: Schema.Number,
@@ -107,48 +147,21 @@ function sameDigest(left, right) {
         difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
     return difference === 0;
 }
-/**
- * The SQLite tables one Oyster build owner keeps. Creation and any carrying
- * forward of retained facts run as one transaction of the owner's storage, so
- * an interrupted conversion leaves the facts as they were for a retry.
- */
+/** Create the current build tables and index atomically; never convert old stores. */
 export function migrateOysterAppBuilds(owner) {
     const { sql } = owner;
     owner.transactionSync(() => {
         sql.exec("CREATE TABLE IF NOT EXISTS oyster_build_sources (app_id TEXT PRIMARY KEY, source TEXT NOT NULL) STRICT");
-        // Sources recorded before the location union named only an installation
-        // repository; carry each forward once, in place.
-        sql.exec(`UPDATE oyster_build_sources SET source = json_set(
-       json_remove(source, '$.installationId', '$.repository'), '$.location',
-       json_object('kind', 'installation',
-         'installationId', json_extract(source, '$.installationId'),
-         'repository', json_extract(source, '$.repository')))
-     WHERE json_type(source, '$.location') IS NULL`);
         const jobColumns = `
       job_id TEXT PRIMARY KEY, app_id TEXT NOT NULL, release_id TEXT NOT NULL UNIQUE,
       source_revision TEXT NOT NULL, location TEXT NOT NULL,
       recipe TEXT NOT NULL, recipe_digest TEXT NOT NULL, requested_by TEXT NOT NULL,
       credential_id TEXT NOT NULL, upload_grant_digest TEXT NOT NULL,
       status TEXT NOT NULL, artifact_digest TEXT, artifact_bytes INTEGER, detail TEXT,
+      installation TEXT, request_id TEXT,
       issued_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, executable_until INTEGER NOT NULL`;
         sql.exec(`CREATE TABLE IF NOT EXISTS oyster_build_jobs (${jobColumns}) STRICT`);
-        // Jobs recorded before the location union named an installation repository
-        // in two columns; carry each into the one location column, once.
-        if (sql
-            .exec("SELECT name FROM pragma_table_info('oyster_build_jobs') WHERE name='installation_id'")
-            .toArray().length > 0) {
-            sql.exec(`CREATE TABLE oyster_build_jobs_current (${jobColumns}) STRICT`);
-            sql.exec(`INSERT INTO oyster_build_jobs_current SELECT job_id, app_id, release_id,
-         source_revision,
-         json_object('kind', 'installation', 'installationId', installation_id,
-           'repository', repository),
-         recipe, recipe_digest, requested_by, credential_id, upload_grant_digest,
-         status, artifact_digest, artifact_bytes, detail, issued_at, expires_at,
-         executable_until
-       FROM oyster_build_jobs`);
-            sql.exec("DROP TABLE oyster_build_jobs");
-            sql.exec("ALTER TABLE oyster_build_jobs_current RENAME TO oyster_build_jobs");
-        }
+        sql.exec("CREATE UNIQUE INDEX IF NOT EXISTS oyster_build_request ON oyster_build_jobs(request_id)");
         sql.exec("CREATE TABLE IF NOT EXISTS oyster_build_releases (release_id TEXT PRIMARY KEY, job_id TEXT NOT NULL UNIQUE, release TEXT NOT NULL) STRICT");
     });
 }
@@ -172,7 +185,10 @@ export function createOysterAppBuilds(options) {
     // job, so an owner restart must not fail it. A job that reaches its expiry
     // without a result can never settle, so it fails then instead of reading
     // as running for as long as anyone asks.
-    const expire = () => owner.sql.exec("UPDATE oyster_build_jobs SET status='failed', detail=? WHERE status='running' AND expires_at<=?", "Build expired without a result", now());
+    const failedInstallation = `CASE WHEN installation IS NULL THEN NULL ELSE
+    json_object('kind', 'failed', 'installationId', json_extract(installation, '$.installationId'),
+      'detail', COALESCE(?, 'Build did not succeed')) END`;
+    const expire = () => owner.sql.exec(`UPDATE oyster_build_jobs SET installation=${failedInstallation}, status='failed', detail=? WHERE status='running' AND expires_at<=?`, "Build expired without a result", "Build expired without a result", now());
     expire();
     const decodeRecipe = (recipe) => Schema.decodeUnknownSync(recipeCodec)(recipe);
     const grantAdmits = async (job, grant) => sameDigest(job.upload_grant_digest, await sha256Hex(new TextEncoder().encode(grant)));
@@ -209,7 +225,8 @@ export function createOysterAppBuilds(options) {
         detail: job.detail,
     });
     const settle = (jobId, status, detail) => {
-        owner.sql.exec("UPDATE oyster_build_jobs SET status=?, detail=?, expires_at=MIN(expires_at, ?) WHERE job_id=? AND status='running'", status, detail, now(), jobId);
+        owner.sql.exec(`UPDATE oyster_build_jobs SET installation=CASE WHEN ?='succeeded' THEN installation ELSE ${failedInstallation} END,
+        status=?, detail=?, expires_at=MIN(expires_at, ?) WHERE job_id=? AND status='running'`, status, detail, status, detail, now(), jobId);
     };
     const required = (jobId) => {
         const job = readJob(jobId);
@@ -293,16 +310,128 @@ export function createOysterAppBuilds(options) {
         status: job.status,
         detail: job.detail,
         release: readRelease(job.job_id),
+        installation: job.installation,
     });
+    const registerSource = (source) => {
+        if (digestPinnedRecipe(source.recipe) !== source.buildRecipeDigest)
+            throw new Error("Build recipe digest does not match its recipe");
+        owner.sql.exec("INSERT INTO oyster_build_sources(app_id, source) VALUES(?, ?) ON CONFLICT(app_id) DO UPDATE SET source=excluded.source", source.appId, Schema.encodeUnknownSync(sourceCodec)(source));
+        return source;
+    };
+    const readRepositorySource = (installationId, repository) => {
+        const [row] = owner.sql
+            .exec("SELECT source FROM oyster_build_sources WHERE json_extract(source, '$.location.kind')='installation' AND json_extract(source, '$.location.installationId')=? AND json_extract(source, '$.location.repository')=? LIMIT 1", installationId, repository)
+            .toArray();
+        return row === undefined
+            ? null
+            : Schema.decodeUnknownSync(sourceCodec)(Schema.decodeUnknownSync(sourceRow)(row).source);
+    };
+    async function start(input) {
+        const revision = Schema.decodeUnknownOption(sourceRevisionSchema)(input.sourceRevision);
+        if (Option.isNone(revision))
+            throw new OysterBuildStartError("invalid_revision");
+        const sourceRevision = revision.value;
+        const source = readSource(input.appId);
+        if (source === null)
+            throw new OysterBuildStartError("no_source");
+        if (source.location.kind === "template") {
+            const receipt = await options.templates.read(source.appId, sourceRevision);
+            if (receipt?.buildRecipeDigest !== source.buildRecipeDigest)
+                throw new OysterBuildStartError("not_template_seed");
+        }
+        const reusedRequest = () => {
+            if (input.requestId !== undefined) {
+                const [row] = owner.sql
+                    .exec("SELECT * FROM oyster_build_jobs WHERE request_id=?", input.requestId)
+                    .toArray();
+                if (row !== undefined) {
+                    const existing = decodeJob(row);
+                    if (existing.app_id !== source.appId ||
+                        existing.source_revision !== sourceRevision)
+                        throw new Error("Build request identity conflict");
+                    return existing.job_id;
+                }
+            }
+            return null;
+        };
+        const existing = reusedRequest();
+        if (existing !== null)
+            return {
+                build: view(required(existing)),
+                run: () => Promise.resolve(view(required(existing))),
+            };
+        if ((await options.computer.port.buildBackend()).kind === "no_backend")
+            throw new OysterBuildStartError("no_backend");
+        const jobId = `build_${randomHex(16)}`;
+        const releaseId = parseReleaseId(`rel_${sourceRevision.slice("git:".length, "git:".length + 12)}${randomHex(4)}`);
+        const uploadGrant = randomHex(32);
+        const issuedAt = now();
+        const uploadGrantDigest = await sha256Hex(new TextEncoder().encode(uploadGrant));
+        const reused = owner.transactionSync(() => {
+            const existing = reusedRequest();
+            if (existing !== null)
+                return existing;
+            owner.sql.exec(`INSERT INTO oyster_build_jobs(job_id, app_id, release_id, source_revision, location,
+          recipe, recipe_digest, requested_by, credential_id, upload_grant_digest,
+          status, artifact_digest, artifact_bytes, detail, installation, request_id, issued_at, expires_at, executable_until)
+        VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL, NULL, NULL, ?, ?, ?, ?, 0)`, jobId, source.appId, releaseId, sourceRevision, Schema.encodeUnknownSync(locationCodec)(source.location), Schema.encodeUnknownSync(recipeCodec)(source.recipe), source.buildRecipeDigest, input.requestedBy, randomHex(32), uploadGrantDigest, input.installAt === undefined
+                ? null
+                : Schema.encodeUnknownSync(installationCodec)({
+                    kind: "pending",
+                    installationId: input.installAt,
+                }), input.requestId ?? null, issuedAt, issuedAt + jobTtlMs);
+            return null;
+        });
+        if (reused !== null)
+            return {
+                build: view(required(reused)),
+                run: () => Promise.resolve(view(required(reused))),
+            };
+        // The grant leaves this owner only inside the fixed command.
+        const command = teamAppBuildCommand({ appId: source.appId, sourceRevision, source }, uploadGrant);
+        return { build: view(required(jobId)), run: () => run(jobId, command) };
+    }
+    let installationBusy = false;
+    function recordInstallationOutcome(jobId, outcome) {
+        return owner.transactionSync(() => {
+            const job = readJob(jobId);
+            if (job?.status !== "succeeded" ||
+                readRelease(jobId) === null ||
+                job.installation?.kind !== "pending" ||
+                job.installation.installationId !== outcome.installationId)
+                return false;
+            owner.sql.exec("UPDATE oyster_build_jobs SET installation=? WHERE job_id=?", Schema.encodeUnknownSync(installationCodec)(outcome), jobId);
+            return true;
+        });
+    }
     return Object.freeze({
         /** Record (or replace) an App's build source; the caller is the owner. */
-        registerSource(source) {
-            if (digestPinnedRecipe(source.recipe) !== source.buildRecipeDigest)
-                throw new Error("Build recipe digest does not match its recipe");
-            owner.sql.exec("INSERT INTO oyster_build_sources(app_id, source) VALUES(?, ?) ON CONFLICT(app_id) DO UPDATE SET source=excluded.source", source.appId, Schema.encodeUnknownSync(sourceCodec)(source));
-            return source;
+        registerSource,
+        /** Resolve repository identity and replace its current recipe as one transition.
+         * A fork's existing identity wins over the copied manifest's App id. */
+        registerRepositorySource(input) {
+            return owner.transactionSync(() => {
+                const existing = readRepositorySource(input.location.installationId, input.location.repository);
+                const appId = Schema.decodeUnknownSync(appIdSchema)(existing?.appId ?? input.appId);
+                if (existing === null && readSource(appId) !== null)
+                    return { kind: "conflict" };
+                const pinned = normalizeAppPublisherRecipe({
+                    appId,
+                    recipe: input.recipe,
+                });
+                return {
+                    kind: "registered",
+                    source: registerSource({
+                        appId,
+                        location: input.location,
+                        recipe: pinned.recipe,
+                        buildRecipeDigest: pinned.buildRecipeDigest,
+                    }),
+                };
+            });
         },
         readSource,
+        readRepositorySource,
         /**
          * Mint one build job for an App's registered source at one exact commit.
          * A template source builds only a seed revision recorded for its pinned
@@ -310,33 +439,54 @@ export function createOysterAppBuilds(options) {
          * Answers the job and its one run, which the caller keeps alive (the
          * upload grant exists only inside that run's fixed command).
          */
-        async start(input) {
-            const sourceRevision = Schema.decodeUnknownSync(sourceRevisionSchema)(input.sourceRevision);
-            const source = readSource(input.appId);
-            if (source === null)
-                throw new Error("App has no build source");
-            if (source.location.kind === "template") {
-                const receipt = await options.templates.read(source.appId, sourceRevision);
-                if (receipt?.buildRecipeDigest !== source.buildRecipeDigest)
-                    throw new Error("Revision is not a seed of this App's template");
-            }
-            const jobId = `build_${randomHex(16)}`;
-            const releaseId = parseReleaseId(`rel_${sourceRevision.slice("git:".length, "git:".length + 12)}${randomHex(4)}`);
-            const uploadGrant = randomHex(32);
-            const issuedAt = now();
-            owner.sql.exec(`INSERT INTO oyster_build_jobs(job_id, app_id, release_id, source_revision, location,
-          recipe, recipe_digest, requested_by, credential_id, upload_grant_digest,
-          status, artifact_digest, artifact_bytes, detail, issued_at, expires_at, executable_until)
-        VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', NULL, NULL, NULL, ?, ?, 0)`, jobId, source.appId, releaseId, sourceRevision, Schema.encodeUnknownSync(locationCodec)(source.location), Schema.encodeUnknownSync(recipeCodec)(source.recipe), source.buildRecipeDigest, input.requestedBy, randomHex(32), await sha256Hex(new TextEncoder().encode(uploadGrant)), issuedAt, issuedAt + jobTtlMs);
-            // The grant leaves this owner only inside the fixed command.
-            const command = teamAppBuildCommand({ appId: source.appId, sourceRevision, source }, uploadGrant);
-            return { build: view(required(jobId)), run: () => run(jobId, command) };
-        },
+        start,
         read(jobId) {
             expire();
             const job = readJob(jobId);
             return job === null ? null : view(job);
         },
+        /** Discover the current source's latest job from the caller's Git owner,
+         * never a job id remembered in a browser or another installation's repo. */
+        latestRepositoryBuild(installationId, repository) {
+            expire();
+            const source = readRepositorySource(installationId, repository);
+            if (source === null)
+                return null;
+            const [row] = owner.sql
+                .exec("SELECT * FROM oyster_build_jobs WHERE app_id=? AND json_extract(location, '$.kind')='installation' AND json_extract(location, '$.installationId')=? AND json_extract(location, '$.repository')=? ORDER BY rowid DESC LIMIT 1", source.appId, installationId, repository)
+                .toArray();
+            return row === undefined ? null : view(decodeJob(row));
+        },
+        /** One bounded host installation at a time. Only a verified successful
+         * build may reach the installer; the same existing row owns its outcome.
+         * A Workflow retry may resume a pending decision, never a terminal one. */
+        async install(jobId, decide) {
+            const job = readJob(jobId);
+            const release = readRelease(jobId);
+            if (installationBusy ||
+                job?.status !== "succeeded" ||
+                release === null ||
+                job.installation?.kind !== "pending")
+                return false;
+            installationBusy = true;
+            try {
+                let outcome;
+                try {
+                    outcome = await decide(release, job.installation.installationId);
+                }
+                catch {
+                    outcome = {
+                        kind: "failed",
+                        installationId: job.installation.installationId,
+                        detail: "Automatic installation unavailable",
+                    };
+                }
+                return recordInstallationOutcome(jobId, outcome);
+            }
+            finally {
+                installationBusy = false;
+            }
+        },
         /** A built Release by id, for an owner to install or select. */
         release(releaseId) {
             const [row] = owner.sql

package/dist/app-storage.d.ts

@@ -86,7 +86,7 @@ export declare function createAppStorage(options: {
         /** Read the declared team layer without exposing any member's private value. */
         read: (key: string) => Effect.Effect<{
             readonly value: Schema.Json;
-            readonly source: "team" | "member" | "none";
+            readonly source: "member" | "team" | "none";
             readonly team: {
                 readonly value: Schema.Json;
                 readonly revision: number;
@@ -111,7 +111,7 @@ export declare function createAppStorage(options: {
         /** Resolve declared member and team layers under current live admission. */
         read: (key: string) => Effect.Effect<{
             readonly value: Schema.Json;
-            readonly source: "team" | "member" | "none";
+            readonly source: "member" | "team" | "none";
             readonly team: {
                 readonly value: Schema.Json;
                 readonly revision: number;
@@ -134,7 +134,7 @@ export declare function createAppStorage(options: {
         events: (key: string) => Stream.Stream<{
             readonly appId: string;
             readonly key: string;
-            readonly scope: "team" | "member";
+            readonly scope: "member" | "team";
             readonly revision: number;
         } | null, AppStorageError, never>;
     };

package/dist/approval-capability.d.ts

@@ -0,0 +1,5 @@
+import { type Approvals } from "@fungi.computer/approvals";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import type { OysterCapability } from "./host.js";
+/** Ordinary capability routes; the outer App gate supplies identity and consent. */
+export declare function approvalCapability(control: (actor: HostActor) => Approvals): OysterCapability;

package/dist/approval-capability.js

@@ -0,0 +1,46 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { causeClass } from "./cause-class.js";
+import * as Schema from "effect/Schema";
+import { ApprovalListInputSchema, ApprovalGetInputSchema, ApprovalAnswerInputSchema, AutoApproveInputSchema, } from "@fungi.computer/approvals";
+/** Ordinary capability routes; the outer App gate supplies identity and consent. */
+export function approvalCapability(control) {
+    const routes = new Hono();
+    routes.use("*", bodyLimit({ maxSize: 4096 }));
+    routes.use("*", async (context, next) => {
+        if (context.env.principal.actor.kind !== "member")
+            return context.json({ kind: "refused", reason: "not-eligible" }, 403);
+        await next();
+        return undefined;
+    });
+    routes.onError((cause, context) => {
+        if (cause instanceof SyntaxError || cause instanceof Schema.SchemaError)
+            return context.json({ error: "Invalid approval request" }, 400);
+        console.warn("Native approval control failed", {
+            causeClass: causeClass(cause),
+        });
+        return context.json({ error: "Approval home unavailable" }, 503);
+    });
+    const strict = { onExcessProperty: "error" };
+    routes.post("/list", async (c) => c.json(await control(c.env.principal.actor).list(Schema.decodeUnknownSync(ApprovalListInputSchema, strict)(await c.req.json()))));
+    routes.post("/get", async (c) => c.json(await control(c.env.principal.actor).get(Schema.decodeUnknownSync(ApprovalGetInputSchema, strict)(await c.req.json()))));
+    routes.post("/answer", async (c) => c.json(await control(c.env.principal.actor).answer(Schema.decodeUnknownSync(ApprovalAnswerInputSchema, strict)(await c.req.json()))));
+    routes.post("/set-auto-approve", async (c) => c.json(await control(c.env.principal.actor).setAutoApprove(Schema.decodeUnknownSync(AutoApproveInputSchema, strict)(await c.req.json()))));
+    return {
+        id: "approvals",
+        version: 1,
+        permission: "approvals",
+        base: "/approvals/",
+        routes,
+        methods: {
+            list: { kind: "json", method: "POST", path: "list" },
+            get: { kind: "json", method: "POST", path: "get" },
+            answer: { kind: "json", method: "POST", path: "answer" },
+            setAutoApprove: {
+                kind: "json",
+                method: "POST",
+                path: "set-auto-approve",
+            },
+        },
+    };
+}

package/dist/approval-home.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { ApprovalLedger, type Approvals, type PendingApproval, type ApprovalApplyResult } from "@fungi.computer/approvals";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type OysterHost } from "./host.js";
+import type { HostActor } from "@fungi.computer/puffball/app";
+import type { TenantScope } from "./tenant.js";
+declare const callSchema: z.ZodObject<{
+    actor: import("zod/mini").ZodMiniDiscriminatedUnion<[import("zod/mini").ZodMiniObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"member">;
+        memberId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strip>, import("zod/mini").ZodMiniObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"agent">;
+        agentId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strip>, import("zod/mini").ZodMiniObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+        keyId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strip>], "kind">;
+    installationId: z.ZodString;
+    sessionId: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    access: z.ZodEnum<{
+        write: "write";
+        external: "external";
+    }>;
+    authorityFence: z.ZodString;
+    idempotencyKey: z.ZodString;
+    input: z.ZodJSONSchema;
+}, z.core.$strict>;
+/** Host-generated App call metadata; the operation's input contains no actor or approval choice. */
+export type OysterApprovalCall = z.output<typeof callSchema>;
+/** The registry's durable App effect home. Mycelium still owns operation/schema invocation. */
+export declare class OysterApprovalHome {
+    private readonly host;
+    readonly ledger: ApprovalLedger;
+    constructor(host: Readonly<{
+        owner: WatchdogSqliteOwner;
+        scope: TenantScope;
+        current: () => Promise<OysterHost>;
+        /** Commit only intent state and its wake, never an App effect. */
+        commit: <T>(write: () => Promise<T>, nextWakeAt: () => number | null) => Promise<T>;
+    }>);
+    private createLedger;
+    submit(raw: OysterApprovalCall): Promise<PendingApproval | ApprovalApplyResult>;
+    /** Bind each read/decision to current membership, not the renderer's actor bytes. */
+    capability(rawActor: HostActor): Approvals;
+    /** One native alarm quantum; apply owns the fresh grant/fence check and single claim. */
+    reconcile(): Promise<number | null>;
+    private resolve;
+    private execution;
+}
+export {};