@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/app-storage.js

@@ -0,0 +1,281 @@
+/**
+ * `env.APP_STORAGE`: the App's own key/value store, as its backend receives
+ * it. One contract for every Oyster host (standalone and the Fungi Hub).
+ *
+ * - **Same handle everywhere.** Method handlers and lifecycle handlers (such
+ *   as `onGitPush`) run in the same facet and receive the same `env`. When the
+ *   Release declares the `APP_STORAGE` binding, both get this handle with the
+ *   same operations.
+ * - **Who writes.** In a method call, a member writes their own `member`
+ *   layer; an admitted owner may also write the `team` layer, as from the UI.
+ *   A lifecycle handler has no
+ *   member, so it writes the installation's shared `team` layer; a `member`
+ *   write from a lifecycle handler is rejected with `owner_required`.
+ * - **Visible to watchers.** Every accepted write or reset is committed by the
+ *   host's storage owner, bumps the key's revision and is published to
+ *   `appStorage.watch` subscribers, exactly like a write from the App's UI.
+ *   A push that writes a key therefore refreshes every open UI watching it.
+ * - **Same limits.** Declared keys, scopes, per-key size and quotas, and
+ *   `basedOn` compare-and-set apply unchanged; rejections use Agar's
+ *   `AppStorageError` codes.
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { appStorageScopes } from "@fungi.computer/puffball";
+import * as Stream from "effect/Stream";
+import * as Queue from "effect/Queue";
+import { AppStorageError, } from "@fungi.computer/agar/storage";
+/** Whether `writer` may mutate `scope`; anything else is `owner_required`. */
+export function appStorageWritable(writer, scope) {
+    return writer.kind === "member"
+        ? scope === "member" || writer.isOwner
+        : scope === "team";
+}
+const unavailable = (cause) => cause instanceof AppStorageError
+    ? cause
+    : new AppStorageError("unavailable", { cause });
+const revision = Schema.Int.check(Schema.isGreaterThan(0));
+// Team layers and installation rate counters use the existing non-member SQL partition.
+const writerIdentity = (admission) => "memberId" in admission
+    ? {
+        memberId: admission.memberId,
+        membershipVersion: admission.membershipVersion,
+    }
+    : { memberId: "", membershipVersion: 0 };
+/** SQLite tables, indexes and initial revision state used by the App storage owner. */
+export const appStorageSchemaStatements = [
+    `CREATE TABLE IF NOT EXISTS hub_app_storage (
+    address TEXT NOT NULL, app_id TEXT NOT NULL, key TEXT NOT NULL,
+    scope TEXT NOT NULL CHECK(scope IN ('team','member')), member_id TEXT NOT NULL, membership_version INTEGER NOT NULL,
+    value TEXT NOT NULL, revision INTEGER NOT NULL, bytes INTEGER NOT NULL,
+    PRIMARY KEY(address,app_id,key,scope,member_id,membership_version),
+    CHECK((scope='team' AND member_id='' AND membership_version=0) OR (scope='member' AND member_id<>'' AND membership_version>0))) STRICT`,
+    `CREATE INDEX IF NOT EXISTS hub_app_storage_member ON hub_app_storage(member_id) WHERE scope='member'`,
+    `CREATE TABLE IF NOT EXISTS hub_app_storage_clock (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL) STRICT`,
+    `INSERT OR IGNORE INTO hub_app_storage_clock VALUES(1,0)`,
+    `CREATE TABLE IF NOT EXISTS hub_app_storage_writes (address TEXT NOT NULL, member_id TEXT NOT NULL, membership_version INTEGER NOT NULL, started_at INTEGER NOT NULL, count INTEGER NOT NULL, PRIMARY KEY(address,member_id,membership_version)) STRICT`,
+];
+/** Called only inside the installation owner's delete transaction. */
+export function purgeAppStorageInCommit(sql, address) {
+    sql.exec("DELETE FROM hub_app_storage WHERE address=?", address);
+    sql.exec("DELETE FROM hub_app_storage_writes WHERE address=?", address);
+}
+/** Called only inside the membership owner's removal transaction. */
+export function purgeAppMemberStorageInCommit(sql, memberId, throughVersion) {
+    sql.exec("DELETE FROM hub_app_storage WHERE scope='member' AND member_id=? AND membership_version<=?", memberId, throughVersion);
+    sql.exec("DELETE FROM hub_app_storage_writes WHERE member_id=? AND membership_version<=?", memberId, throughVersion);
+}
+const storedLayer = Schema.Struct({
+    scope: Schema.Literals(appStorageScopes),
+    value: Schema.fromJsonString(Schema.Json),
+    revision,
+    bytes: Schema.Int,
+});
+const usageSchema = Schema.Struct({ bytes: Schema.Int, app_bytes: Schema.Int });
+const clockSchema = Schema.Struct({ revision });
+const appQuotaBytes = 1024 * 1024;
+const teamQuotaBytes = 16 * appQuotaBytes;
+const isJsonPrimitive = Schema.is(Schema.Union([Schema.String, Schema.Number, Schema.Boolean, Schema.Null]));
+function withinDepth(value, depth = 0) {
+    if (isJsonPrimitive(value))
+        return true;
+    if (depth >= 32)
+        return false;
+    return Object.values(value).every((child) => withinDepth(child, depth + 1));
+}
+/** One SQLite owner for scoped App values; its views bind the admitted member. */
+export function createAppStorage(options) {
+    const { sql } = options;
+    const listeners = new Set();
+    const publish = (admission, input, result) => {
+        const notice = {
+            address: admission.address,
+            appId: admission.appId,
+            memberId: writerIdentity(admission).memberId,
+            key: input.key,
+            scope: input.scope,
+            revision: result.revision,
+        };
+        for (const listener of listeners)
+            listener(notice);
+    };
+    for (const statement of appStorageSchemaStatements)
+        sql.exec(statement);
+    const layers = (admission, key) => sql
+        .exec("SELECT scope,value,revision,bytes FROM hub_app_storage WHERE address=? AND app_id=? AND key=? AND (scope='team' OR (member_id=? AND membership_version=?))", admission.address, admission.appId, key, writerIdentity(admission).memberId, writerIdentity(admission).membershipVersion)
+        .toArray()
+        .map((row) => Schema.decodeUnknownSync(storedLayer)(row));
+    const declare = (admission, key) => {
+        const declared = admission.keys.find((entry) => entry.key === key);
+        if (declared === undefined)
+            throw new AppStorageError("undeclared_key");
+        admission.assertCurrent();
+        return declared;
+    };
+    const nextRevision = () => {
+        sql.exec("UPDATE hub_app_storage_clock SET revision=revision+1 WHERE id=1");
+        const row = sql
+            .exec("SELECT revision FROM hub_app_storage_clock WHERE id=1")
+            .toArray()[0];
+        return Schema.decodeUnknownSync(clockSchema)(row).revision;
+    };
+    const consumeWrite = (admission) => {
+        const now = (options.now ?? Date.now)();
+        const row = sql
+            .exec("SELECT started_at,count FROM hub_app_storage_writes WHERE address=? AND member_id=? AND membership_version=?", admission.address, writerIdentity(admission).memberId, writerIdentity(admission).membershipVersion)
+            .toArray()[0];
+        const saved = row === undefined
+            ? null
+            : Schema.decodeUnknownSync(Schema.Struct({ started_at: Schema.Int, count: Schema.Int }))(row);
+        const current = saved !== null && now < saved.started_at + 60000;
+        if (current && saved.count >= 60)
+            throw new AppStorageError("quota_exceeded");
+        sql.exec("INSERT INTO hub_app_storage_writes(address,member_id,membership_version,started_at,count) VALUES(?,?,?,?,?) ON CONFLICT(address,member_id,membership_version) DO UPDATE SET started_at=excluded.started_at,count=excluded.count", admission.address, writerIdentity(admission).memberId, writerIdentity(admission).membershipVersion, current ? saved.started_at : now, current ? saved.count + 1 : 1);
+    };
+    const mutate = (admission, input, value) => {
+        const writer = "memberId" in admission
+            ? {
+                kind: "member",
+                memberId: admission.memberId,
+                isOwner: admission.isOwner,
+            }
+            : { kind: "lifecycle", handler: "installation" };
+        if (!appStorageWritable(writer, input.scope))
+            throw new AppStorageError("owner_required");
+        const declared = declare(admission, input.key);
+        if (!declared.scopes.includes(input.scope))
+            throw new AppStorageError("scope_not_declared");
+        const current = layers(admission, input.key).find((row) => row.scope === input.scope);
+        if ((current?.revision ?? null) !== input.basedOn)
+            throw new AppStorageError("conflict");
+        const memberId = input.scope === "member" ? writerIdentity(admission).memberId : "";
+        const membershipVersion = input.scope === "member"
+            ? writerIdentity(admission).membershipVersion
+            : 0;
+        if (value === undefined) {
+            consumeWrite(admission);
+            sql.exec("DELETE FROM hub_app_storage WHERE address=? AND app_id=? AND key=? AND scope=? AND member_id=? AND membership_version=?", admission.address, admission.appId, input.key, input.scope, memberId, membershipVersion);
+            return { revision: nextRevision() };
+        }
+        if (!withinDepth(value))
+            throw new AppStorageError("invalid");
+        const encoded = JSON.stringify(value);
+        const bytes = new TextEncoder().encode(encoded).byteLength;
+        if (bytes > declared.maxBytes)
+            throw new AppStorageError("too_large");
+        const usage = Schema.decodeUnknownSync(usageSchema)(sql
+            .exec("SELECT COALESCE(SUM(bytes),0) AS bytes, COALESCE(SUM(CASE WHEN address=? THEN bytes ELSE 0 END),0) AS app_bytes FROM hub_app_storage", admission.address)
+            .toArray()[0]);
+        const delta = bytes - (current?.bytes ?? 0);
+        if (usage.bytes + delta > teamQuotaBytes ||
+            usage.app_bytes + delta > appQuotaBytes)
+            throw new AppStorageError("quota_exceeded");
+        consumeWrite(admission);
+        const revision = nextRevision();
+        sql.exec("INSERT INTO hub_app_storage(address,app_id,key,scope,member_id,membership_version,value,revision,bytes) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(address,app_id,key,scope,member_id,membership_version) DO UPDATE SET value=excluded.value,revision=excluded.revision,bytes=excluded.bytes", admission.address, admission.appId, input.key, input.scope, memberId, membershipVersion, encoded, revision, bytes);
+        return { revision };
+    };
+    const resolveStorage = (admission, key) => {
+        const declared = declare(admission, key);
+        const rows = layers(admission, key);
+        const team = declared.scopes.includes("team")
+            ? rows.find((row) => row.scope === "team")
+            : undefined;
+        if (!("memberId" in admission) && !declared.scopes.includes("team"))
+            throw new AppStorageError("owner_required");
+        const member = "memberId" in admission && declared.scopes.includes("member")
+            ? rows.find((row) => row.scope === "member")
+            : undefined;
+        const project = (row) => row === undefined ? null : { value: row.value, revision: row.revision };
+        return {
+            value: member !== undefined
+                ? member.value
+                : team !== undefined
+                    ? team.value
+                    : null,
+            source: member !== undefined ? "member" : team !== undefined ? "team" : "none",
+            team: project(team),
+            member: project(member),
+            canWriteTeam: "isOwner" in admission ? admission.isOwner : true,
+        };
+    };
+    const commitMutation = (admission, input, value) => Effect.uninterruptible(options
+        .commit(() => mutate(admission, input, value))
+        .pipe(Effect.tap((result) => Effect.sync(() => {
+        publish(admission, input, result);
+    }))));
+    return {
+        /** Remove an installation's values and write counters inside its delete transaction. */
+        purgeInstallation: (address) => {
+            purgeAppStorageInCommit(sql, address);
+        },
+        /** Remove a member's private values and counters through the revoked membership version. */
+        purgeMember: (memberId, throughVersion) => {
+            purgeAppMemberStorageInCommit(sql, memberId, throughVersion);
+        },
+        /** Bind a lifecycle view to fresh installation admission; only declared team layers are accessible. */
+        openInstallation(authorize) {
+            const mutation = (input, value) => authorize().pipe(Effect.flatMap((admission) => commitMutation(admission, input, value)), Effect.mapError(unavailable));
+            return {
+                /** Read the declared team layer without exposing any member's private value. */
+                read: (key) => authorize().pipe(Effect.flatMap((admission) => Effect.try({
+                    try: () => resolveStorage(admission, key),
+                    catch: unavailable,
+                })), Effect.mapError(unavailable)),
+                /** Commit a declared team-layer write and publish its new revision to watchers. */
+                write: (input) => mutation(input, input.value),
+                /** Reset a declared team layer; member scope is rejected with owner_required. */
+                reset: (input) => mutation(input, undefined),
+            };
+        },
+        /** Bind a member view to live admission, declared keys and the current membership version. */
+        open(authorize) {
+            const admitted = () => authorize().pipe(Effect.mapError(unavailable));
+            return {
+                /** Resolve declared member and team layers under current live admission. */
+                read: (key) => admitted().pipe(Effect.flatMap((admission) => Effect.try({
+                    try: () => {
+                        return resolveStorage(admission, key);
+                    },
+                    catch: unavailable,
+                }))),
+                /** Commit an admitted layer write with revision and quota checks, then notify watchers. */
+                write: (input) => admitted().pipe(Effect.flatMap((admission) => commitMutation(admission, input, input.value)), Effect.mapError(unavailable)),
+                /** Remove an admitted layer at its expected revision and notify watchers. */
+                reset: (input) => admitted().pipe(Effect.flatMap((admission) => commitMutation(admission, input, undefined)), Effect.mapError(unavailable)),
+                /** One bounded invalidation stream. Null marks an armed subscription. */
+                events: (key) => Stream.unwrap(Effect.gen(function* () {
+                    const admission = yield* admitted();
+                    const declared = yield* Effect.try({
+                        try: () => declare(admission, key),
+                        catch: unavailable,
+                    });
+                    const queue = yield* Queue.sliding(1);
+                    const listener = (notice) => {
+                        if (notice.address !== admission.address ||
+                            notice.appId !== admission.appId ||
+                            notice.key !== key ||
+                            !declared.scopes.includes(notice.scope) ||
+                            (notice.scope === "member" &&
+                                notice.memberId !== admission.memberId))
+                            return;
+                        Queue.offerUnsafe(queue, {
+                            appId: notice.appId,
+                            key: notice.key,
+                            scope: notice.scope,
+                            revision: notice.revision,
+                        });
+                    };
+                    yield* Effect.acquireRelease(Effect.sync(() => listeners.add(listener)), () => Effect.sync(() => {
+                        listeners.delete(listener);
+                        Queue.shutdownUnsafe(queue);
+                    }));
+                    return Stream.concat(Stream.succeed(null), Stream.fromQueue(queue)).pipe(Stream.tap(() => admitted().pipe(Effect.flatMap((current) => Effect.try({
+                        try: () => declare(current, key),
+                        catch: unavailable,
+                    })))));
+                })),
+            };
+        },
+    };
+}

package/dist/apps/gate.d.ts

@@ -0,0 +1,105 @@
+import * as z from "zod";
+import { type AppApi, type AppDeclaration, type HostActor } from "@fungi.computer/puffball/app";
+import { type AppToolAccess } from "./tools.js";
+import { type DeclaredOperations, type Installation, type ApprovedGrant } from "./installation.js";
+/** Attested by the host, never authenticated by decoding request JSON. */
+export type HostPrincipal = Readonly<{
+    actor: HostActor | Readonly<{
+        kind: "visitor";
+    }>;
+    role: "owner" | "member" | null;
+}>;
+/** Requests select existing SDK methods, opaque backend calls and derived operation identities. */
+export declare const gateRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"method">;
+    name: z.ZodString;
+    input: z.ZodUnknown;
+    via: z.ZodEnum<{
+        ui: "ui";
+        agent: "agent";
+        mcp: "mcp";
+        workflow: "workflow";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"capability-route">;
+    capability: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"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", unknown>>;
+    operation: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"binding">;
+    binding: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", unknown>>;
+    operation: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"list-tools">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"backend">;
+}, z.core.$strict>], "kind">;
+/** One decoded method, route, binding or catalog admission request. */
+export type GateRequest = z.output<typeof gateRequestSchema>;
+/** Immutable values the host already read; resource/grantor freshness remains host-owned. */
+export type GateFacts = Readonly<{
+    principal: HostPrincipal;
+    installation: Installation;
+    declaration: AppDeclaration;
+    declaredOperations: DeclaredOperations;
+    api: AppApi | null;
+    access: AppToolAccess | null;
+    pins?: Readonly<{
+        authorityVersion: number;
+        artifactDigest: string;
+    }>;
+}>;
+/** Binding grants have the exact S2 InvocationFacts shape and its maintained registry grammar. */
+export declare const invocationGrantsSchema: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    binding: z.ZodPipe<z.ZodUnknown, z.ZodTransform<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", unknown>>;
+    operations: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>>;
+/** The explicit binding ceiling passed to an invocation frame. */
+export type InvocationGrants = z.output<typeof invocationGrantsSchema>;
+/** A declared method from the canonical Puffball API grammar. */
+export type AppMethodDeclaration = AppApi["methods"][string];
+/** Ordered, closed refusal vocabulary; external methods always require approval. */
+export declare const gateRefusalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    code: z.ZodEnum<{
+        unavailable: "unavailable";
+        stale_authority: "stale_authority";
+        not_declared: "not_declared";
+        not_approved: "not_approved";
+        level_too_low: "level_too_low";
+        approval_required: "approval_required";
+        requires_not_granted: "requires_not_granted";
+        invalid_input: "invalid_input";
+        visitor_read_only: "visitor_read_only";
+    }>;
+}, z.core.$strict>;
+/** Either an admitted scoped ceiling or one closed refusal code. */
+export type GateDecision = Readonly<{
+    kind: "admitted";
+    grants: InvocationGrants;
+    method?: AppMethodDeclaration;
+}> | z.output<typeof gateRefusalSchema>;
+/** Intersect stored approvals with the current verified Release without widening resource selectors. */
+export declare function grantsFor(installation: Installation, declaration: AppDeclaration, snapshot: DeclaredOperations, capability: ApprovedGrant["capability"]): ApprovedGrant | null;
+/** Approved binding operations from an already verified declaration. Hosts still pin
+ * the selection/version/artifact and compare running frame grants as a subset. */
+export declare function approvedBindingGrants(installation: Installation, declaration: AppDeclaration): InvocationGrants;
+/** Narrow captured binding operations to the method's verified requirements and effect.
+ * The captured set is the ceiling; this never adds an operation or resource authority. */
+export declare function scopedBindings(captured: InvocationGrants, method?: AppMethodDeclaration, ceiling?: "read" | "write"): InvocationGrants;
+/** Principal ceiling for invocation and metadata capture. Captures must pass this
+ * to scopedBindings; its default write ceiling does not encode caller access. */
+export declare function appInvocationCeiling(facts: Pick<GateFacts, "principal" | "access">): "read" | "write";
+/** Permission metadata only: this is neither an invocation grant nor input admission. */
+export type AppMethodMetadataDecision = Readonly<{
+    kind: "admitted";
+    method: AppMethodDeclaration;
+}> | z.output<typeof gateRefusalSchema>;
+/** Check a verified method's Release, principal, effect and real capability consent.
+ * Captures have no mapped runtime input yet. This result cannot authorize execution:
+ * dispatch must still use admits, including its ordinary input validation.
+ * Input schemas are not compiled here; execution may still refuse invalid_input.
+ * Project captured bindings with appInvocationCeiling(facts).
+ */
+export declare function admitMethodMetadata(facts: GateFacts, name: string): AppMethodMetadataDecision;
+/** Ordered admission only. Host freshness/resource admission and effect execution stay outside this pure gate. */
+export declare function admits(facts: GateFacts, rawRequest: GateRequest): GateDecision;

package/dist/apps/gate.js

@@ -0,0 +1,273 @@
+import { AppInstanceError } from "../index.js";
+import { appMethodSchemas } from "@fungi.computer/forage";
+import { bindingOperationKey } from "./operations.js";
+import * as z from "zod";
+import * as Schema from "effect/Schema";
+import { appBackendBindingKinds, appBackendBindingOperation, scopeOperationToMethod, appApiMethodNameSchema, appBackendBindingsSchema, appCapabilityIdSchema, } from "@fungi.computer/puffball/app";
+import { appToolAccessSchema } from "./tools.js";
+import { ownerCodec, } from "./installation.js";
+const bindingNameSchema = ownerCodec(Schema.Literals(Object.values(appBackendBindingKinds).map((kind) => kind.name)));
+/** Requests select existing SDK methods, opaque backend calls and derived operation identities. */
+export const gateRequestSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("method"),
+        name: z.string(),
+        input: z.unknown(),
+        via: z.enum(["ui", "agent", "mcp", "workflow"]),
+    }),
+    z.strictObject({
+        kind: z.literal("capability-route"),
+        capability: ownerCodec(appCapabilityIdSchema),
+        operation: z.string().min(1),
+    }),
+    z.strictObject({
+        kind: z.literal("binding"),
+        binding: bindingNameSchema,
+        operation: z.string().min(1),
+    }),
+    z.strictObject({ kind: z.literal("list-tools") }),
+    z.strictObject({ kind: z.literal("backend") }),
+]);
+/** Binding grants have the exact S2 InvocationFacts shape and its maintained registry grammar. */
+export const invocationGrantsSchema = z
+    .array(z.strictObject({
+    binding: bindingNameSchema,
+    operations: z.array(z.string().min(1)).readonly(),
+}))
+    .refine((grants) => Schema.is(appBackendBindingsSchema)(grants.map((grant) => ({
+    name: grant.binding,
+    operations: grant.operations,
+}))), "Invalid declared binding operations")
+    .readonly();
+/** Ordered, closed refusal vocabulary; external methods always require approval. */
+export const gateRefusalSchema = z.strictObject({
+    kind: z.literal("refused"),
+    code: z.enum([
+        "unavailable",
+        "stale_authority",
+        "not_declared",
+        "not_approved",
+        "level_too_low",
+        "approval_required",
+        "requires_not_granted",
+        "invalid_input",
+        "visitor_read_only",
+    ]),
+});
+/** Intersect stored approvals with the current verified Release without widening resource selectors. */
+export function grantsFor(installation, declaration, snapshot, capability) {
+    if (installation.status !== "enabled" ||
+        snapshot.digest !== installation.declaredOperationsDigest ||
+        snapshot.artifactDigest !== installation.release.artifact.artifactDigest ||
+        !declaration.capabilities.includes(capability))
+        return null;
+    const approved = installation.approvedGrants.find((grant) => grant.capability === capability);
+    const declared = snapshot.capabilities.find((row) => row.capability === capability)
+        ?.operations ?? [];
+    if (!approved?.capabilityApproved ||
+        (approved.resources !== "tenant-scope" && approved.resources.length === 0))
+        return null;
+    const operations = approved.operations.filter((operation) => declared.includes(operation));
+    return { ...approved, operations };
+}
+/** Approved binding operations from an already verified declaration. Hosts still pin
+ * the selection/version/artifact and compare running frame grants as a subset. */
+export function approvedBindingGrants(installation, declaration) {
+    if (installation.status !== "enabled")
+        return [];
+    const bindings = [];
+    for (const binding of declaration.backend?.bindings ?? []) {
+        const operations = binding.operations.filter((name) => {
+            const operation = appBackendBindingOperation(binding.name, name);
+            return (operation !== undefined &&
+                operation.requires.length > 0 &&
+                operation.requires.every((capability) => {
+                    const approved = installation.approvedGrants.find((grant) => grant.capability === capability);
+                    return (declaration.capabilities.includes(capability) &&
+                        approved?.capabilityApproved &&
+                        (approved.resources === "tenant-scope" ||
+                            approved.resources.length > 0) &&
+                        approved.operations.includes(bindingOperationKey(binding.name, name)));
+                }));
+        });
+        if (operations.length > 0)
+            bindings.push({ binding: binding.name, operations });
+    }
+    return bindings;
+}
+/** Narrow captured binding operations to the method's verified requirements and effect.
+ * The captured set is the ceiling; this never adds an operation or resource authority. */
+export function scopedBindings(captured, method, ceiling = "write") {
+    return captured.flatMap((binding) => {
+        const operations = binding.operations.filter((name) => {
+            const operation = appBackendBindingOperation(binding.binding, name);
+            if (operation === undefined)
+                throw new AppInstanceError("invalid_invocation_facts");
+            return scopeOperationToMethod(operation, method, ceiling);
+        });
+        return operations.length > 0
+            ? [{ binding: binding.binding, operations }]
+            : [];
+    });
+}
+/** Principal ceiling for invocation and metadata capture. Captures must pass this
+ * to scopedBindings; its default write ceiling does not encode caller access. */
+export function appInvocationCeiling(facts) {
+    return facts.access?.level === "read" ||
+        facts.principal.actor.kind === "visitor"
+        ? "read"
+        : "write";
+}
+function admittedBindings(facts, method) {
+    return scopedBindings(approvedBindingGrants(facts.installation, facts.declaration), method, appInvocationCeiling(facts));
+}
+const refusal = (code) => ({ kind: "refused", code });
+function admissionRefusal(facts) {
+    const { installation, principal } = facts;
+    const visitor = principal.actor.kind === "visitor";
+    if (installation.status !== "enabled" ||
+        (visitor && installation.visibility !== "public"))
+        return refusal("unavailable");
+    if (facts.declaredOperations.digest !== installation.declaredOperationsDigest ||
+        facts.declaredOperations.artifactDigest !==
+            installation.release.artifact.artifactDigest ||
+        (facts.pins !== undefined &&
+            (facts.pins.authorityVersion !== installation.authorityVersion ||
+                facts.pins.artifactDigest !==
+                    installation.release.artifact.artifactDigest)))
+        return refusal("stale_authority");
+    if ((principal.actor.kind === "agent" || principal.actor.kind === "team-key") &&
+        !Schema.is(appToolAccessSchema)(facts.access))
+        return refusal("not_approved");
+    return null;
+}
+function methodMetadata(facts, name) {
+    const { installation, principal } = facts;
+    const visitor = principal.actor.kind === "visitor";
+    if (installation.instanceId === null)
+        return refusal("unavailable");
+    if (!Schema.is(appApiMethodNameSchema)(name) ||
+        facts.api === null ||
+        !Object.hasOwn(facts.api.methods, name))
+        return refusal("not_declared");
+    const method = facts.api.methods[name];
+    if (method === undefined)
+        return refusal("not_declared");
+    if (method.effect === "external")
+        return refusal("approval_required");
+    if (visitor && method.effect !== "read")
+        return refusal("visitor_read_only");
+    if (method.effect === "write" && facts.access?.level === "read")
+        return refusal("level_too_low");
+    return { kind: "admitted", method };
+}
+function methodGrantRefusal(facts, method) {
+    const { installation } = facts;
+    if (method.requires.some((capability) => grantsFor(installation, facts.declaration, facts.declaredOperations, capability) === null))
+        return refusal("requires_not_granted");
+    return null;
+}
+/** Check a verified method's Release, principal, effect and real capability consent.
+ * Captures have no mapped runtime input yet. This result cannot authorize execution:
+ * dispatch must still use admits, including its ordinary input validation.
+ * Input schemas are not compiled here; execution may still refuse invalid_input.
+ * Project captured bindings with appInvocationCeiling(facts).
+ */
+export function admitMethodMetadata(facts, name) {
+    const denied = admissionRefusal(facts);
+    if (denied !== null)
+        return denied;
+    const metadata = methodMetadata(facts, name);
+    if (metadata.kind === "refused")
+        return metadata;
+    return methodGrantRefusal(facts, metadata.method) ?? metadata;
+}
+/** Ordered admission only. Host freshness/resource admission and effect execution stay outside this pure gate. */
+export function admits(facts, rawRequest) {
+    const parsed = gateRequestSchema.safeParse(rawRequest);
+    if (!parsed.success)
+        return refusal("invalid_input");
+    const request = parsed.data;
+    const { installation, principal } = facts;
+    const visitor = principal.actor.kind === "visitor";
+    const denied = admissionRefusal(facts);
+    if (denied !== null)
+        return denied;
+    switch (request.kind) {
+        case "backend":
+            // Opaque App requests have no verified method selector; they require write authority.
+            if (visitor)
+                return refusal("visitor_read_only");
+            if (installation.instanceId === null)
+                return refusal("unavailable");
+            if (facts.access?.level === "read")
+                return refusal("level_too_low");
+            return { kind: "admitted", grants: admittedBindings(facts) };
+        case "method": {
+            const metadata = methodMetadata(facts, request.name);
+            if (metadata.kind === "refused")
+                return metadata;
+            const { method } = metadata;
+            // The maintained JSON-Schema compiler can reject unsupported declared schemas.
+            // Return the typed input refusal; never leak compiler diagnostics or throw from admission.
+            try {
+                const input = appMethodSchemas({ methods: { [request.name]: method } })[request.name]?.input;
+                if (!input?.safeParse(request.input).success)
+                    return refusal("invalid_input");
+                if (new TextEncoder().encode(JSON.stringify(request.input)).byteLength >
+                    64 * 1024)
+                    return refusal("invalid_input");
+            }
+            catch {
+                return refusal("invalid_input");
+            }
+            const grantDenied = methodGrantRefusal(facts, method);
+            if (grantDenied !== null)
+                return grantDenied;
+            return {
+                kind: "admitted",
+                grants: admittedBindings(facts, method),
+                method,
+            };
+        }
+        case "capability-route": {
+            if (visitor)
+                return refusal("visitor_read_only");
+            if (!request.operation.startsWith("route:") ||
+                !facts.declaration.capabilities.includes(request.capability) ||
+                facts.declaredOperations.capabilities
+                    .find((row) => row.capability === request.capability)
+                    ?.operations.includes(request.operation) !== true)
+                return refusal("not_declared");
+            if (grantsFor(installation, facts.declaration, facts.declaredOperations, request.capability)?.operations.includes(request.operation) !== true)
+                return refusal("not_approved");
+            return { kind: "admitted", grants: [] };
+        }
+        case "binding": {
+            if (visitor)
+                return refusal("visitor_read_only");
+            if (installation.instanceId === null)
+                return refusal("unavailable");
+            const operation = appBackendBindingOperation(request.binding, request.operation);
+            if (operation === undefined ||
+                facts.declaration.backend?.bindings
+                    .find((binding) => binding.name === request.binding)
+                    ?.operations.includes(request.operation) !== true ||
+                !operation.requires.every((capability) => facts.declaration.capabilities.includes(capability)))
+                return refusal("not_declared");
+            if (operation.effect === "write" && facts.access?.level === "read")
+                return refusal("level_too_low");
+            if (operation.requires.length < 1 ||
+                !operation.requires.every((capability) => grantsFor(installation, facts.declaration, facts.declaredOperations, capability)?.operations.includes(bindingOperationKey(request.binding, request.operation)) === true))
+                return refusal("not_approved");
+            return {
+                kind: "admitted",
+                grants: [{ binding: request.binding, operations: [request.operation] }],
+            };
+        }
+        case "list-tools":
+            return facts.api === null || installation.instanceId === null
+                ? refusal("unavailable")
+                : { kind: "admitted", grants: admittedBindings(facts) };
+    }
+}

package/dist/apps/index.d.ts

@@ -0,0 +1,5 @@
+/** Installation records and pure admission rules; tenant state and commits stay host-owned. */
+export { applyInstallationCommand, approvedGrantSchema, declaredOperationsSchema, installationCommandSchema, installationIdSchema, installationRefusalSchema, installationSchema, type Approval, type ApprovedGrant, type CapabilityOperationDescriptor, type DeclaredOperations, type GrantRequest, type Installation, type InstallationCommand, type InstallationContext, type InstallationReader, type InstallationRefusal, type InstallationUpdate, type ResourceRef, } from "./installation.js";
+export { admits, admitMethodMetadata, appInvocationCeiling, approvedBindingGrants, scopedBindings, grantsFor, gateRefusalSchema, gateRequestSchema, invocationGrantsSchema, type AppMethodDeclaration, type AppMethodMetadataDecision, type GateDecision, type GateFacts, type GateRequest, type HostPrincipal, type InvocationGrants, } from "./gate.js";
+export { deriveDeclaredOperations, appCallOperation } from "./operations.js";
+export { appToolPolicySchema, type AppToolAccess, type AppToolEntry, type AppToolPolicy, } from "./tools.js";