@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import { type BackgroundSyncRefusal } from "@fungi.computer/puffball/background-replay";
+import { type AppGitPushFact, type GitPushQuestion, type GitPushVerdict } from "@fungi.computer/agar/git";
+import { type CairnId } from "@fungi.computer/cairn/id";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { DurableBackend } from "@fungi.computer/puffball/backend";
+import type { Release, Sha256Digest } from "@fungi.computer/puffball";
+import type { AppMethodReply } from "@fungi.computer/agar/backend";
+import type { AppApi } from "@fungi.computer/puffball";
+import type { InvocationFrame } from "./invocation.js";
+import type { Installation } from "./apps/installation.js";
+import { type GillCall, type GillReply } from "@fungi.computer/gills";
+/** The Cairn ID family that mints and recognizes App Instance IDs (`instance_…`). */
+export declare const instanceIds: Readonly<{
+    readonly instance: import("@fungi.computer/cairn").IdCodec<"app-instance", "instance", 1>;
+}>;
+/** A stable App Instance ID minted by {@link instanceIds}. */
+export type InstanceId = CairnId<"app-instance", "instance">;
+/** Decodes a string into an {@link InstanceId}, rejecting any other ID family. */
+export declare const instanceIdSchema: Schema.Codec<InstanceId, string>;
+/**
+ * The owner that issues authority for an Instance: an `installation` of an App
+ * or a `deployment`. Owner identity never changes for the life of an Instance.
+ */
+export declare const ownerSchema: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
+    readonly id: Schema.NonEmptyString;
+}>;
+/**
+ * An owner-issued selection: which Instance, owner, App and Release a request
+ * runs against, at a positive authority version.
+ */
+export declare const selectionSchema: Schema.Struct<{
+    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly owner: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly releaseId: Schema.refine<import("@fungi.computer/puffball").ReleaseId, Schema.String>;
+    readonly authorityVersion: Schema.Number;
+}>;
+/** A complete owner-issued state: a selection plus `enabled`, `disabled` or `deleted`. */
+export declare const ownerStateSchema: Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["enabled", "disabled", "deleted"]>;
+    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly owner: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly releaseId: Schema.refine<import("@fungi.computer/puffball").ReleaseId, Schema.String>;
+    readonly authorityVersion: Schema.Number;
+}>;
+/** A decoded {@link ownerStateSchema} value, the input to `apply`. */
+export type OwnerState = Schema.Schema.Type<typeof ownerStateSchema>;
+/**
+ * The persisted Instance record: the last applied selection, its state-schema
+ * version, the owner's desired status and the runtime's own status.
+ */
+export declare const instanceSchema: Schema.Struct<{
+    readonly stateSchema: Schema.NullOr<Schema.Number>;
+    readonly desiredStatus: Schema.Literals<readonly ["enabled", "disabled", "deleted"]>;
+    readonly status: Schema.Literals<readonly ["active", "disabled", "deleting", "deleted"]>;
+    readonly instanceId: Schema.Codec<InstanceId, string, never, never>;
+    readonly owner: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["installation", "deployment"]>;
+        readonly id: Schema.NonEmptyString;
+    }>;
+    readonly appId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly releaseId: Schema.refine<import("@fungi.computer/puffball").ReleaseId, Schema.String>;
+    readonly authorityVersion: Schema.Number;
+}>;
+/** A decoded {@link selectionSchema} value, the authority for `fetch` and `call`. */
+export type Selection = Schema.Schema.Type<typeof selectionSchema>;
+/** The admitted selection for an installation's Instance. */
+export declare function selectionOf(installation: Installation): Selection;
+/** A decoded {@link instanceSchema} record, as returned by `apply` and `inspect`. */
+export type Instance = Schema.Schema.Type<typeof instanceSchema>;
+/** A resolved, verified durable backend: its Release, artifact digest and code. */
+export type Backend = Readonly<{
+    release: Release;
+    digest: Sha256Digest;
+    backend: DurableBackend;
+}>;
+/** The runtime owns the bounded rejection grammar, including across RPC. */
+export declare const appInstanceErrorCodeSchema: Schema.Literals<readonly ["invalid_owner_state", "invalid_invocation_facts", "revoked", "binding_not_granted", "binding_unavailable", "expired", "reentrant", "instance_identity_mismatch", "instance_owner_mismatch", "conflicting_owner_state", "stale_authority", "instance_deleted", "release_app_mismatch", "state_schema_migration_unsupported", "instance_inactive", "instance_authority_version_mismatch", "release_no_longer_matches_instance", "instance_release_mismatch", "installation_tenant_mismatch"]>;
+/** One of the bounded {@link appInstanceErrorCodeSchema} rejection codes. */
+export type AppInstanceErrorCode = typeof appInstanceErrorCodeSchema.Type;
+/** Stable runtime failure identity; message remains presentation only. */
+export declare class AppInstanceError extends Error {
+    readonly code: AppInstanceErrorCode;
+    readonly name = "AppInstanceError";
+    constructor(code: AppInstanceErrorCode, options?: ErrorOptions);
+}
+/** Supervisor schema checks do not open guest authority; execution carries a frame. */
+export type BackendResolution<Host> = Readonly<{
+    kind: "metadata";
+}> | Readonly<{
+    kind: "invocation";
+    frame: InvocationFrame<Host>;
+}>;
+/** Host storage, verified artifact resolution, and frame-bound execution ports. */
+export type InstancePorts<Host> = Readonly<{
+    /** The stable ID every owner state and selection must name. */
+    instanceId: string;
+    /** Read the persisted Instance record, or `null` before the first apply. */
+    read: () => Effect.Effect<Instance | null, Error>;
+    /** Persist the Instance record. */
+    write: (instance: Instance) => Effect.Effect<void, Error>;
+    /** Resolve a Release ID to its verified durable backend. */
+    resolve: (release: Selection["releaseId"], scope: BackendResolution<Host>) => Effect.Effect<Backend, Error>;
+    /** Abort in-flight backend work and invalidate existing connections. */
+    abort: () => Effect.Effect<void, Error>;
+    /** Delete the backend's own state. */
+    purge: () => Effect.Effect<void, Error>;
+    /**
+     * Acquire a connection to the backend under admission. A later `abort` must
+     * invalidate connections acquired before it.
+     */
+    connect: (backend: Backend, frame: InvocationFrame<Host>) => Effect.Effect<AppBackendConnection, Error>;
+}>;
+/** One admitted connection to a running App backend. */
+export type AppBackendConnection = Readonly<{
+    /** Ask the App about the whole external push under this admitted connection. */
+    authorizeGitPush?: (question: GitPushQuestion) => Effect.Effect<GitPushVerdict, Error>;
+    /** Handle an accepted Git push under the same selected Instance authority. */
+    onGitPush?: (fact: AppGitPushFact) => Effect.Effect<void, Error>;
+    /** Settle the refused member lane, without binding authority. */
+    syncRefused?: (refusal: BackgroundSyncRefusal) => Effect.Effect<void, Error>;
+    /** Send an HTTP request to the backend. */
+    fetch: (request: Request) => Effect.Effect<Response, Error>;
+    /** Invoke a declared backend method under the connection's immutable frame;
+     * the App's typed refusal is a reply, not a failure. */
+    call: (name: string, input: Schema.Json) => Effect.Effect<AppMethodReply, Error>;
+    /** Invoke the generated Gill entry under the connection's immutable frame. */
+    gill: (cargo: Schema.Json) => Effect.Effect<Schema.Json, Error>;
+}>;
+/** The lifecycle and admission operations of one App Instance. */
+export type AppInstance<Host> = Readonly<{
+    /**
+     * Apply a complete owner state. Exact retries return the recorded result;
+     * changed input at the same version conflicts and older versions are stale.
+     */
+    apply: (input: OwnerState) => Effect.Effect<Instance, Error>;
+    /** Admit the frame's selection and forward an HTTP request to the active backend. */
+    fetch: (frame: InvocationFrame<Host>, request: Request) => Effect.Effect<Response, Error>;
+    /** Admit the frame and invoke a method declared by the Release's App API. */
+    call: (frame: InvocationFrame<Host>, api: AppApi, name: string, input: Schema.Json) => Effect.Effect<AppMethodReply, Error>;
+    /** Invoke a Gill's generated entry under its declared source read's frame. */
+    gill: (frame: InvocationFrame<Host>, api: AppApi, source: string, input: GillCall) => Effect.Effect<GillReply, Error>;
+    /** Authorize a whole external push through the same frame-bound connection. */
+    authorizeGitPush: (frame: InvocationFrame<Host>, question: GitPushQuestion) => Effect.Effect<GitPushVerdict, Error>;
+    /** Deliver a host-admitted Git push under exact live Instance selection. */
+    onGitPush: (frame: InvocationFrame<Host>, fact: AppGitPushFact) => Effect.Effect<void, Error>;
+    /** Deliver a zero-grant refusal to an active, freshly selected backend. */
+    syncRefused: (frame: InvocationFrame<Host>, refusal: BackgroundSyncRefusal) => Effect.Effect<void, Error>;
+    /** Read the current Instance record, resuming an interrupted purge. */
+    inspect: () => Effect.Effect<Instance | null, Error>;
+}>;
+/**
+ * Create the resource-local lifecycle for one App Instance over host ports.
+ * This is not admission: the host must obtain real authority from its owner
+ * before calling `apply`, `fetch` or `call`.
+ */
+export declare function createAppInstance<Host>(ports: InstancePorts<Host>): AppInstance<Host>;

package/dist/index.js

@@ -0,0 +1,320 @@
+import { backgroundSyncRefusalSchema, } from "@fungi.computer/puffball/background-replay";
+import { appGitPushFactSchema, gitPushQuestionSchema, gitPushVerdictSchema, } from "@fungi.computer/agar/git";
+import * as Semaphore from "effect/Semaphore";
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { releaseIdSchema, appIdSchema } from "@fungi.computer/puffball/effect";
+import { appFacetRequest, appFacetResponse } from "./backend-request.js";
+import { appApiSchema } from "@fungi.computer/puffball/app";
+import { gillCallSchema, gillReplySchema, } from "@fungi.computer/gills";
+/** The Cairn ID family that mints and recognizes App Instance IDs (`instance_…`). */
+export const instanceIds = defineIdFamily({
+    family: "app-instance",
+    version: 1,
+    kinds: { instance: { prefix: "instance" } },
+});
+/** Decodes a string into an {@link InstanceId}, rejecting any other ID family. */
+export const instanceIdSchema = Schema.String.pipe(Schema.refine((value) => instanceIds.instance.is(value)));
+/**
+ * The owner that issues authority for an Instance: an `installation` of an App
+ * or a `deployment`. Owner identity never changes for the life of an Instance.
+ */
+export const ownerSchema = Schema.Struct({
+    kind: Schema.Literals(["installation", "deployment"]),
+    id: Schema.NonEmptyString,
+});
+/**
+ * An owner-issued selection: which Instance, owner, App and Release a request
+ * runs against, at a positive authority version.
+ */
+export const selectionSchema = Schema.Struct({
+    instanceId: instanceIdSchema,
+    owner: ownerSchema,
+    appId: appIdSchema,
+    releaseId: releaseIdSchema,
+    authorityVersion: Schema.Number.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+});
+/** A complete owner-issued state: a selection plus `enabled`, `disabled` or `deleted`. */
+export const ownerStateSchema = Schema.Struct({
+    ...selectionSchema.fields,
+    status: Schema.Literals(["enabled", "disabled", "deleted"]),
+});
+/**
+ * The persisted Instance record: the last applied selection, its state-schema
+ * version, the owner's desired status and the runtime's own status.
+ */
+export const instanceSchema = Schema.Struct({
+    ...selectionSchema.fields,
+    stateSchema: Schema.NullOr(Schema.Number),
+    desiredStatus: ownerStateSchema.fields.status,
+    status: Schema.Literals(["active", "disabled", "deleting", "deleted"]),
+});
+/** The admitted selection for an installation's Instance. */
+export function selectionOf(installation) {
+    if (installation.instanceId === null)
+        throw new Error("Installation has no Instance");
+    return {
+        instanceId: installation.instanceId,
+        owner: { kind: "installation", id: installation.installationId },
+        appId: installation.release.appId,
+        releaseId: installation.release.releaseId,
+        authorityVersion: installation.authorityVersion,
+    };
+}
+/** The runtime owns the bounded rejection grammar, including across RPC. */
+export const appInstanceErrorCodeSchema = Schema.Literals([
+    "invalid_owner_state",
+    "invalid_invocation_facts",
+    "revoked",
+    "binding_not_granted",
+    "binding_unavailable",
+    "expired",
+    "reentrant",
+    "instance_identity_mismatch",
+    "instance_owner_mismatch",
+    "conflicting_owner_state",
+    "stale_authority",
+    "instance_deleted",
+    "release_app_mismatch",
+    "state_schema_migration_unsupported",
+    "instance_inactive",
+    "instance_authority_version_mismatch",
+    "release_no_longer_matches_instance",
+    "instance_release_mismatch",
+    "installation_tenant_mismatch",
+]);
+const APP_INSTANCE_ERROR_MESSAGES = {
+    invalid_owner_state: "Invalid owner state",
+    invalid_invocation_facts: "Invalid invocation facts",
+    revoked: "Invocation authority revoked",
+    binding_not_granted: "Binding operation not granted",
+    binding_unavailable: "Binding operation unavailable on this host",
+    expired: "Invocation deadline exceeded",
+    reentrant: "Invocation would re-enter an active Instance",
+    instance_identity_mismatch: "Instance identity mismatch",
+    instance_owner_mismatch: "Instance owner mismatch",
+    conflicting_owner_state: "Conflicting owner state",
+    stale_authority: "Stale authority",
+    instance_deleted: "Instance deleted",
+    release_app_mismatch: "Release belongs to another App",
+    state_schema_migration_unsupported: "State schema migration not supported",
+    instance_inactive: "Instance inactive",
+    instance_authority_version_mismatch: "Instance authority version mismatch",
+    release_no_longer_matches_instance: "Release no longer matches Instance",
+    instance_release_mismatch: "Instance release mismatch",
+    installation_tenant_mismatch: "Installation tenant mismatch",
+};
+/** Stable runtime failure identity; message remains presentation only. */
+export class AppInstanceError extends Error {
+    code;
+    name = "AppInstanceError";
+    constructor(code, options) {
+        super(APP_INSTANCE_ERROR_MESSAGES[code], options);
+        this.code = code;
+    }
+}
+const failure = (code) => Effect.fail(new AppInstanceError(code));
+const sameOwner = (a, b) => a.instanceId === b.instanceId &&
+    a.owner.kind === b.owner.kind &&
+    a.owner.id === b.owner.id &&
+    a.appId === b.appId;
+/**
+ * Create the resource-local lifecycle for one App Instance over host ports.
+ * This is not admission: the host must obtain real authority from its owner
+ * before calling `apply`, `fetch` or `call`.
+ */
+export function createAppInstance(ports) {
+    const lock = Semaphore.makeUnsafe(1);
+    const read = Effect.gen(function* () {
+        const current = yield* ports.read();
+        if (current?.status === "deleting") {
+            yield* ports.purge();
+            const deleted = { ...current, status: "deleted" };
+            yield* ports.write(deleted);
+            return deleted;
+        }
+        return current;
+    });
+    const apply = (input) => lock.withPermits(1)(Effect.gen(function* () {
+        const desired = yield* Schema.decodeUnknownEffect(ownerStateSchema)(input).pipe(Effect.mapError(() => new AppInstanceError("invalid_owner_state")));
+        if (desired.instanceId !== ports.instanceId)
+            return yield* failure("instance_identity_mismatch");
+        const current = yield* read;
+        if (current && !sameOwner(current, desired))
+            return yield* failure("instance_owner_mismatch");
+        const retry = current !== null &&
+            current.authorityVersion === desired.authorityVersion;
+        if (retry &&
+            (current.releaseId !== desired.releaseId ||
+                current.desiredStatus !== desired.status))
+            return yield* failure("conflicting_owner_state");
+        if (current && desired.authorityVersion < current.authorityVersion)
+            return yield* failure("stale_authority");
+        if (current?.status === "deleted") {
+            if (retry && desired.status === "deleted")
+                return current;
+            return yield* failure("instance_deleted");
+        }
+        if (retry && current.status === "active")
+            return current;
+        let stateSchema = current?.stateSchema ?? null;
+        if (desired.status === "enabled") {
+            const resolved = yield* ports.resolve(desired.releaseId, {
+                kind: "metadata",
+            });
+            if (resolved.release.appId !== desired.appId)
+                return yield* failure("release_app_mismatch");
+            if (stateSchema !== null &&
+                stateSchema !== resolved.backend.runtime.stateSchema)
+                return yield* failure("state_schema_migration_unsupported");
+            stateSchema = resolved.backend.runtime.stateSchema;
+        }
+        const next = {
+            ...desired,
+            desiredStatus: desired.status,
+            stateSchema,
+            status: desired.status === "deleted"
+                ? "deleting"
+                : "disabled",
+        };
+        // Persist the exact owner fact before stopping runtime; no resource-issued version.
+        yield* ports.write(next);
+        yield* ports.abort();
+        if (desired.status === "deleted")
+            yield* ports.purge();
+        const receipt = {
+            ...next,
+            status: desired.status === "enabled"
+                ? "active"
+                : desired.status === "deleted"
+                    ? "deleted"
+                    : "disabled",
+        };
+        yield* ports.write(receipt);
+        return receipt;
+    }));
+    const connect = (frame) => lock.withPermits(1)(Effect.gen(function* () {
+        yield* Effect.try({
+            try: () => {
+                frame.signal.throwIfAborted();
+            },
+            catch: () => new AppInstanceError("revoked"),
+        });
+        if (frame.facts.deadlineAt <= Date.now())
+            return yield* failure("expired");
+        const authority = frame.facts.selection;
+        if (frame.facts.instanceId !== ports.instanceId)
+            return yield* failure("instance_identity_mismatch");
+        const current = yield* read;
+        if (current?.status !== "active")
+            return yield* failure("instance_inactive");
+        if (!sameOwner(current, authority))
+            return yield* failure("instance_owner_mismatch");
+        if (current.authorityVersion !== authority.authorityVersion)
+            return yield* failure("instance_authority_version_mismatch");
+        const scope = { kind: "invocation", frame };
+        const storedBackend = yield* ports.resolve(current.releaseId, scope);
+        if (storedBackend.release.appId !== current.appId ||
+            storedBackend.backend.runtime.stateSchema !== current.stateSchema)
+            return yield* failure("release_no_longer_matches_instance");
+        const backend = authority.releaseId === current.releaseId
+            ? storedBackend
+            : yield* ports.resolve(authority.releaseId, scope);
+        if (backend.release.appId !== authority.appId ||
+            backend.backend.runtime.stateSchema !== current.stateSchema)
+            return yield* failure("release_no_longer_matches_instance");
+        if (backend.digest !== storedBackend.digest)
+            return yield* failure("instance_release_mismatch");
+        if (backend.digest !== frame.facts.artifactDigest)
+            return yield* failure("instance_release_mismatch");
+        yield* Effect.try({
+            try: () => {
+                frame.signal.throwIfAborted();
+            },
+            catch: () => new AppInstanceError("revoked"),
+        });
+        if (frame.facts.deadlineAt <= Date.now())
+            return yield* failure("expired");
+        return yield* ports.connect(backend, frame);
+    }));
+    const fetch = (frame, request) => connect(frame).pipe(Effect.flatMap((connection) => connection
+        .fetch(appFacetRequest(request))
+        .pipe(Effect.map(appFacetResponse))));
+    const call = (frame, api, name, input) => frame.facts.subject.kind !== "call"
+        ? failure("invalid_invocation_facts")
+        : Schema.decodeUnknownEffect(appApiSchema)(api).pipe(Effect.mapError((cause) => new Error("App method declaration invalid", { cause })), Effect.flatMap((declaration) => {
+            if (!Object.hasOwn(declaration.methods, name))
+                return Effect.fail(new Error("App method not declared"));
+            const subject = frame.facts.subject;
+            if (subject.kind !== "call" ||
+                (subject.method !== undefined &&
+                    (subject.method.name !== name ||
+                        subject.method.effect !== declaration.methods[name]?.effect)))
+                return failure("invalid_invocation_facts");
+            return connect(frame).pipe(Effect.flatMap((connection) => connection.call(name, input)));
+        }), Effect.mapError((cause) => cause instanceof Error
+            ? cause
+            : new Error("App method context invalid", { cause })));
+    const gill = (frame, api, source, input) => Effect.gen(function* () {
+        if (frame.facts.subject.kind !== "call")
+            return yield* failure("invalid_invocation_facts");
+        const declaration = yield* Schema.decodeUnknownEffect(appApiSchema)(api);
+        if (!Object.hasOwn(declaration.methods, source) ||
+            declaration.methods[source]?.effect !== "read")
+            return yield* Effect.fail(new Error("Gill source must be a declared read method"));
+        const selected = yield* Schema.decodeUnknownEffect(gillCallSchema)(input, { onExcessProperty: "error" });
+        const cargo = yield* Schema.decodeUnknownEffect(Schema.Json)(selected);
+        const connection = yield* connect(frame);
+        const result = yield* connection.gill(cargo);
+        return yield* Schema.decodeUnknownEffect(gillReplySchema)(result, {
+            onExcessProperty: "error",
+        });
+    }).pipe(Effect.mapError((cause) => cause instanceof Error
+        ? cause
+        : new Error("App Gill context invalid", { cause })));
+    const authorizeGitPush = (frame, raw) => Effect.try({
+        try: () => gitPushQuestionSchema.parse(raw),
+        catch: (cause) => new Error("Git push question invalid", { cause }),
+    }).pipe(Effect.flatMap((question) => connect(frame).pipe(Effect.flatMap((connection) => connection.authorizeGitPush === undefined
+        ? Effect.fail(new Error("App Git push authorizer unavailable"))
+        : connection.authorizeGitPush(question)))), Effect.flatMap((verdict) => Effect.try({
+        try: () => gitPushVerdictSchema.parse(verdict),
+        catch: (cause) => new Error("Git push verdict invalid", { cause }),
+    })));
+    const onGitPush = (frame, raw) => Effect.try({
+        try: () => appGitPushFactSchema.parse(raw),
+        catch: (cause) => new Error("Git push fact invalid", { cause }),
+    }).pipe(Effect.flatMap((fact) => frame.facts.subject.kind !== "lifecycle" ||
+        frame.facts.subject.name !== "onGitPush" ||
+        frame.facts.subject.eventId !== fact.eventId
+        ? failure("invalid_invocation_facts")
+        : connect(frame).pipe(Effect.flatMap((connection) => connection.onGitPush === undefined
+            ? Effect.fail(new Error("App Git push handler unavailable"))
+            : connection.onGitPush(fact)))));
+    const syncRefused = (frame, raw) => Effect.try({
+        try: () => backgroundSyncRefusalSchema.parse(raw),
+        catch: (cause) => new Error("Background refusal invalid", { cause }),
+    }).pipe(Effect.flatMap((refusal) => {
+        const subject = frame.facts.subject;
+        if (subject.kind !== "lifecycle" ||
+            subject.name !== "syncRefused" ||
+            frame.facts.grants.length !== 0 ||
+            subject.lane !== refusal.lane ||
+            subject.code !== refusal.code)
+            return failure("invalid_invocation_facts");
+        return connect(frame).pipe(Effect.flatMap((connection) => connection.syncRefused === undefined
+            ? Effect.fail(new Error("App background refusal handler unavailable"))
+            : connection.syncRefused(refusal)));
+    }));
+    return {
+        syncRefused,
+        apply,
+        fetch,
+        call,
+        gill,
+        authorizeGitPush,
+        onGitPush,
+        inspect: () => lock.withPermits(1)(read),
+    };
+}

package/dist/installation-consent.d.ts

@@ -0,0 +1,79 @@
+import * as Schema from "effect/Schema";
+/** Private view projection. The installation reducer decodes all submitted grants. */
+export declare const installationConsentSchema: Schema.Struct<{
+    readonly installationId: Schema.String;
+    readonly appId: Schema.String;
+    readonly appName: Schema.String;
+    readonly authorityVersion: Schema.Int;
+    readonly artifactDigest: Schema.refine<import("@fungi.computer/puffball").Sha256Digest, Schema.String>;
+    readonly capabilities: Schema.$Array<Schema.Struct<{
+        readonly request: Schema.Struct<{
+            readonly capability: Schema.Literals<readonly ["agent.list", "agent.manage", "agent.rename", "agent.toolPolicy", "agent.read", "agent.send", "computer.list", "computer.readFile", "computer.writeFile", "computer.execute", "llm.generation", "media.generation", "games:servers", "git.repository", "apps.open", "apps.call", "app.storage", "app.events.emit", "team.workbenchHost", "marketplace.browse", "marketplace.purchase", "workflow.run", "workflow.publish", "workflow.arm", "world", "channels.read", "channels.personal.manage"]>;
+            readonly operations: Schema.$Array<Schema.String>;
+            readonly resources: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>;
+        readonly approved: Schema.Boolean;
+        readonly description: Schema.String;
+        readonly scope: Schema.String;
+    }>>;
+}>;
+/** Human consent copy; these labels never decide authority or operation mappings. */
+export declare const capabilityLabels: {
+    "agent.list": string;
+    "agent.manage": string;
+    "agent.rename": string;
+    "agent.toolPolicy": string;
+    "agent.read": string;
+    "agent.send": string;
+    "computer.list": string;
+    "computer.readFile": string;
+    "computer.writeFile": string;
+    "computer.execute": string;
+    "llm.generation": string;
+    "media.generation": string;
+    "games:servers": string;
+    "git.repository": string;
+    "apps.open": string;
+    "apps.call": string;
+    "app.storage": string;
+    "app.events.emit": string;
+    "team.workbenchHost": string;
+    "marketplace.browse": string;
+    "marketplace.purchase": string;
+    "workflow.run": string;
+    "workflow.publish": string;
+    "workflow.arm": string;
+    world: string;
+    "channels.read": string;
+    "channels.personal.manage": string;
+};
+/** Plain descriptions of the declared capability; copy never infers extra access. */
+export declare const capabilityDescriptions: {
+    "agent.list": string;
+    "agent.manage": string;
+    "agent.rename": string;
+    "agent.toolPolicy": string;
+    "agent.read": string;
+    "agent.send": string;
+    "computer.list": string;
+    "computer.readFile": string;
+    "computer.writeFile": string;
+    "computer.execute": string;
+    "llm.generation": string;
+    "media.generation": string;
+    "games:servers": string;
+    "git.repository": string;
+    "apps.open": string;
+    "apps.call": string;
+    "app.storage": string;
+    "app.events.emit": string;
+    "team.workbenchHost": string;
+    "marketplace.browse": string;
+    "marketplace.purchase": string;
+    "workflow.run": string;
+    "workflow.publish": string;
+    "workflow.arm": string;
+    world: string;
+    "channels.read": string;
+    "channels.personal.manage": string;
+};

package/dist/installation-consent.js

@@ -0,0 +1,82 @@
+import * as Schema from "effect/Schema";
+import { sha256DigestSchema } from "@fungi.computer/puffball/effect";
+import { appCapabilityIdSchema, } from "@fungi.computer/puffball/app";
+/** Private view projection. The installation reducer decodes all submitted grants. */
+export const installationConsentSchema = Schema.Struct({
+    installationId: Schema.String,
+    appId: Schema.String,
+    appName: Schema.String,
+    authorityVersion: Schema.Int,
+    artifactDigest: sha256DigestSchema,
+    capabilities: Schema.Array(Schema.Struct({
+        request: Schema.Struct({
+            capability: appCapabilityIdSchema,
+            operations: Schema.Array(Schema.String),
+            // Preserve the owner's resource selector as JSON; this view cannot mint authority.
+            resources: Schema.Json,
+        }),
+        approved: Schema.Boolean,
+        description: Schema.String,
+        scope: Schema.String,
+    })),
+});
+/** Human consent copy; these labels never decide authority or operation mappings. */
+export const capabilityLabels = {
+    "agent.list": "List Agents",
+    "agent.manage": "Create and manage Agents",
+    "agent.rename": "Rename Agents",
+    "agent.toolPolicy": "Allow Agents to use Apps",
+    "agent.read": "Read Agent conversations",
+    "agent.send": "Send messages to Agents",
+    "computer.list": "List Computers",
+    "computer.readFile": "Read files",
+    "computer.writeFile": "Change files",
+    "computer.execute": "Run commands",
+    "llm.generation": "Generate text",
+    "media.generation": "Generate images and videos",
+    "games:servers": "Use game servers",
+    "git.repository": "Use Git repositories",
+    "apps.open": "Open Apps",
+    "apps.call": "Call declared App methods",
+    "app.storage": "Store App data",
+    "app.events.emit": "Send events",
+    "team.workbenchHost": "Arrange the workbench",
+    "marketplace.browse": "Browse the marketplace",
+    "marketplace.purchase": "Purchase from the marketplace",
+    "workflow.run": "Run Workflows",
+    "workflow.publish": "Publish Workflows",
+    "workflow.arm": "Arm Workflow triggers",
+    world: "Connect to external services",
+    "channels.read": "Read channels",
+    "channels.personal.manage": "Manage personal channels",
+};
+/** Plain descriptions of the declared capability; copy never infers extra access. */
+export const capabilityDescriptions = {
+    "agent.list": "see which Agents are available.",
+    "agent.manage": "create Agents and manage their sessions.",
+    "agent.rename": "rename Agents you created.",
+    "agent.toolPolicy": "approve Agents to use your installed Apps.",
+    "agent.read": "read Agent conversations.",
+    "agent.send": "send messages to Agents.",
+    "computer.list": "see which Computers are available.",
+    "computer.readFile": "read files on your Computers.",
+    "computer.writeFile": "create and change files on your Computers.",
+    "computer.execute": "run commands on your Computers.",
+    "llm.generation": "ask AI models to generate text.",
+    "media.generation": "ask AI models to generate images and videos.",
+    "games:servers": "connect to game servers.",
+    "git.repository": "work with Git repositories.",
+    "apps.open": "open other Apps.",
+    "apps.call": "call the listed methods in other Apps as you. Renamed target methods need approval again.",
+    "app.storage": "save its App data on your Oyster.",
+    "app.events.emit": "tell your Workflows when something happens.",
+    "team.workbenchHost": "arrange Apps on your workbench.",
+    "marketplace.browse": "browse Apps in the marketplace.",
+    "marketplace.purchase": "purchase Apps from the marketplace.",
+    "workflow.run": "start Workflows.",
+    "workflow.publish": "publish Workflow definitions.",
+    "workflow.arm": "enable Workflow triggers.",
+    world: "connect to external services.",
+    "channels.read": "read messages from channels.",
+    "channels.personal.manage": "manage personal channels.",
+};

package/dist/internal/background-origins.d.ts

@@ -0,0 +1,3 @@
+import { type GateFacts } from "../apps/gate.js";
+/** Project only write origins admitted by this frame's fresh canonical gate. */
+export declare function admittedBackgroundOrigins(gate: GateFacts): readonly string[];

package/dist/internal/background-origins.js

@@ -0,0 +1,8 @@
+import { admitMethodMetadata } from "../apps/gate.js";
+/** Project only write origins admitted by this frame's fresh canonical gate. */
+export function admittedBackgroundOrigins(gate) {
+    return Object.entries(gate.api?.methods ?? {})
+        .filter(([name, method]) => method.effect === "write" &&
+        admitMethodMetadata(gate, name).kind === "admitted")
+        .map(([name]) => name);
+}