@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/build-contract.js

@@ -0,0 +1,4 @@
+/** Provider-neutral App build recipes and candidate orchestration. */
+export * from "./build/effect.js";
+/** Team App candidate wire contract: submission schema and codec. */
+export * from "./build/submission-contract.js";

package/dist/build-jobs.d.ts

@@ -0,0 +1,2 @@
+/** Team build job lifecycle and the fixed builder command; Worker-safe, no Node-only build tooling. */
+export { createTeamBuildPublisher, teamAppBuildCommand, type TeamBuildJob, type BuildCredential, type TeamBuildComputer, } from "./build/build-jobs.js";

package/dist/build-jobs.js

@@ -0,0 +1,2 @@
+/** Team build job lifecycle and the fixed builder command; Worker-safe, no Node-only build tooling. */
+export { createTeamBuildPublisher, teamAppBuildCommand, } from "./build/build-jobs.js";

package/dist/build.d.ts

@@ -0,0 +1,11 @@
+export * from "./build/effect.js";
+export * from "./build/local-build.js";
+export { createDefinitionEmission, type AppBackendOutput, type DefinitionEmission, } from "./build/definition-emission.js";
+export { readBundledHtml } from "./build/bundled-html.js";
+export { bundledHtmlRecipe, boundedBundlePolicy } from "./build/html-recipe.js";
+export { resolveWorkspaceBuild, workspaceBuildPolicySchema, workspaceProjectsArguments, type WorkspaceBuild, type WorkspaceBuildPolicy, } from "./build/workspace-build.js";
+export { workspaceBuildStepSchema, type WorkspaceBuildStep, } from "./build/build-step.js";
+export { frozenSnapshotInstallArguments } from "./build/snapshot-package-store.js";
+export { repositoryEnvironment, artifactsGitEnvironment, hostedArtifactsGitRemote, } from "./build/git-environment.js";
+/** Captured-dependency build program with guarded filesystem access. */
+export declare const dependencyBuildProgram: string;

package/dist/build.js

@@ -0,0 +1,13 @@
+/** Node-only App source capture, compilation and artifact writing. */
+import { dependencyBuildProgram as bundledDependencyBuildProgram } from "#snapshot-program-scripts";
+export * from "./build/effect.js";
+export * from "./build/local-build.js";
+export { createDefinitionEmission, } from "./build/definition-emission.js";
+export { readBundledHtml } from "./build/bundled-html.js";
+export { bundledHtmlRecipe, boundedBundlePolicy } from "./build/html-recipe.js";
+export { resolveWorkspaceBuild, workspaceBuildPolicySchema, workspaceProjectsArguments, } from "./build/workspace-build.js";
+export { workspaceBuildStepSchema, } from "./build/build-step.js";
+export { frozenSnapshotInstallArguments } from "./build/snapshot-package-store.js";
+export { repositoryEnvironment, artifactsGitEnvironment, hostedArtifactsGitRemote, } from "./build/git-environment.js";
+/** Captured-dependency build program with guarded filesystem access. */
+export const dependencyBuildProgram = bundledDependencyBuildProgram;

package/dist/capability-descriptor.d.ts

@@ -0,0 +1,46 @@
+import * as Schema from "effect/Schema";
+/** How an admitted capability method is exposed to the App. */
+export declare const capabilityMethodKindSchema: Schema.Literals<readonly ["json", "transport", "read", "write"]>;
+/** The four supported capability method kinds. */
+export type CapabilityMethodKind = Schema.Schema.Type<typeof capabilityMethodKindSchema>;
+/** The HTTP operation exposed by one capability method on an Oyster page. */
+export declare const capabilityMethodSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"transport">;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "ANY"]>;
+    readonly path: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["json", "read", "write"]>;
+    readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]>;
+    readonly path: Schema.String;
+}>]>;
+/** The serializable part of a capability admitted to an installation's page. */
+export declare const capabilityDescriptorSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly version: Schema.Number;
+    readonly base: Schema.String;
+    readonly methods: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"transport">;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "ANY"]>;
+        readonly path: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["json", "read", "write"]>;
+        readonly method: Schema.Literals<readonly ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]>;
+        readonly path: Schema.String;
+    }>]>>;
+}>;
+/** A page descriptor carries routing, never the authority to use a capability. */
+export type CapabilityDescriptor = Schema.Schema.Type<typeof capabilityDescriptorSchema>;
+/** A UI-only member deputy. Its operation joins the ordinary installation consent owner. */
+export declare const appCallsDescriptor: {
+    readonly id: "apps.call";
+    readonly permission: "apps.call";
+    readonly version: 1;
+    readonly base: "/apps/";
+    readonly methods: {
+        readonly call: {
+            readonly kind: "json";
+            readonly method: "POST";
+            readonly path: ":caller/calls/:appId/:method";
+        };
+    };
+};

package/dist/capability-descriptor.js

@@ -0,0 +1,51 @@
+import * as Schema from "effect/Schema";
+/** How an admitted capability method is exposed to the App. */
+export const capabilityMethodKindSchema = Schema.Literals([
+    "json",
+    "transport",
+    "read",
+    "write",
+]);
+const httpMethods = [
+    "GET",
+    "POST",
+    "PUT",
+    "DELETE",
+    "PATCH",
+    "HEAD",
+    "OPTIONS",
+];
+/** The HTTP operation exposed by one capability method on an Oyster page. */
+export const capabilityMethodSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("transport"),
+        method: Schema.Literals([...httpMethods, "ANY"]),
+        path: Schema.String,
+    }),
+    Schema.Struct({
+        kind: Schema.Literals(["json", "read", "write"]),
+        method: Schema.Literals(httpMethods),
+        path: Schema.String,
+    }),
+]);
+/** The serializable part of a capability admitted to an installation's page. */
+export const capabilityDescriptorSchema = Schema.Struct({
+    id: Schema.String,
+    version: Schema.Number,
+    base: Schema.String,
+    methods: Schema.Record(Schema.String, capabilityMethodSchema),
+});
+/** A UI-only member deputy. Its operation joins the ordinary installation consent owner. */
+export const appCallsDescriptor = {
+    id: "apps.call",
+    permission: "apps.call",
+    version: 1,
+    base: "/apps/",
+    methods: {
+        call: {
+            kind: "json",
+            method: "POST",
+            path: ":caller/calls/:appId/:method",
+        },
+    },
+};

package/dist/catalog-frame.d.ts

@@ -0,0 +1,39 @@
+import * as Schema from "effect/Schema";
+import type { OysterRootDirectory } from "./root-data.js";
+import type { OysterBindingResult } from "./workers.js";
+/** Guest input for `APPS.fork`: the platform App to fork and a chosen label. */
+export declare const appForkInputSchema: Schema.Struct<{
+    readonly platformAppId: Schema.refine<import("@fungi.computer/puffball").AppId, Schema.String>;
+    readonly name: Schema.String;
+}>;
+export type AppForkInput = Schema.Schema.Type<typeof appForkInputSchema>;
+/** The closed result union `forkAppSource` already returns. */
+export declare const appForkResultSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"forked">;
+    readonly appId: Schema.String;
+    readonly repository: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["unauthorized", "conflict", "provider_unavailable"]>;
+}>]>;
+/** Canonical read-only App metadata, projected from the existing root
+ * directory. Typed as the binding's own result, so every consumer --
+ * in this package or across one -- gets the real return type directly. */
+export declare function oysterAppCatalog(directory: OysterRootDirectory): OysterBindingResult;
+/** The plain host exposes only `catalog`; a Git-capable host also wires `fork`. */
+export declare const catalogFrameMethods: {
+    APPS: {
+        catalog: {
+            decodeArgs: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => readonly [{}];
+            decodeResult: (raw: unknown) => OysterBindingResult;
+            requiredOperations: () => string[];
+        };
+        fork: {
+            decodeArgs: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => readonly [{
+                readonly platformAppId: import("@fungi.computer/puffball").AppId;
+                readonly name: string;
+            }];
+            decodeResult: (raw: unknown) => OysterBindingResult;
+            requiredOperations: () => string[];
+        };
+    };
+};

package/dist/catalog-frame.js

@@ -0,0 +1,72 @@
+import * as Schema from "effect/Schema";
+import { appIdSchema } from "@fungi.computer/puffball/effect";
+import { appCatalogResponseSchema, } from "./shell/app-directory.js";
+/** Guest input for `APPS.fork`: the platform App to fork and a chosen label. */
+export const appForkInputSchema = Schema.Struct({
+    platformAppId: appIdSchema,
+    name: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(63))),
+});
+/** The closed result union `forkAppSource` already returns. */
+export const appForkResultSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("forked"),
+        appId: Schema.String,
+        repository: Schema.String,
+    }),
+    Schema.Struct({
+        kind: Schema.Literals(["unauthorized", "conflict", "provider_unavailable"]),
+    }),
+]);
+/** Canonical read-only App metadata, projected from the existing root
+ * directory. Typed as the binding's own result, so every consumer --
+ * in this package or across one -- gets the real return type directly. */
+export function oysterAppCatalog(directory) {
+    const roles = {};
+    if (directory.roles.inbox !== undefined)
+        roles.inbox = directory.roles.inbox;
+    return appCatalogResponseSchema.parse({
+        apps: directory.apps
+            .filter((app) => app.availability === "available" &&
+            app.surface !== null &&
+            app.releaseId !== null &&
+            !app.roles.includes("dashboard"))
+            .map((app) => {
+            const entry = {
+                surfaceId: app.surfaceId,
+                appId: app.appId,
+                gills: app.gills.map((gill) => {
+                    const metadata = {
+                        id: gill.id,
+                        title: gill.title,
+                    };
+                    if (gill.desktop !== undefined)
+                        metadata.desktop = { sizes: [...gill.desktop.sizes] };
+                    return metadata;
+                }),
+            };
+            if (app.displayName !== undefined)
+                entry.displayName = app.displayName;
+            return entry;
+        }),
+        roles,
+    });
+}
+/** The plain host exposes only `catalog`; a Git-capable host also wires `fork`. */
+export const catalogFrameMethods = {
+    APPS: {
+        catalog: {
+            decodeArgs: Schema.decodeUnknownSync(Schema.Tuple([Schema.Struct({})]), {
+                onExcessProperty: "error",
+            }),
+            decodeResult: (raw) => appCatalogResponseSchema.parse(raw),
+            requiredOperations: () => ["catalog"],
+        },
+        fork: {
+            decodeArgs: Schema.decodeUnknownSync(Schema.Tuple([appForkInputSchema]), {
+                onExcessProperty: "error",
+            }),
+            decodeResult: (raw) => Schema.decodeUnknownSync(appForkResultSchema)(raw),
+            requiredOperations: () => ["fork"],
+        },
+    },
+};

package/dist/cause-class.d.ts

@@ -0,0 +1,19 @@
+/** Never copy a guest-controlled name, message or stack into host diagnostics. */
+export declare function causeClass(cause: unknown): "TypeError" | "RangeError" | "SyntaxError" | "AbortError" | "TimeoutError" | "Other" | "Error";
+/** Mark a failure that came back through the App facet so host logs keep only its class. */
+export declare function guestFailure<E extends Error>(cause: E): E;
+declare const platformFlags: readonly ["remote", "retryable", "overloaded", "durableObjectReset"];
+export type PlatformFlag = (typeof platformFlags)[number];
+/** A host-owned failure diagnostic; see {@link failureDiagnostic}. */
+export type FailureDiagnostic = {
+    causeClass: ReturnType<typeof causeClass>;
+    platform?: PlatformFlag[];
+    message?: string;
+};
+/**
+ * One host-owned failure diagnostic: the closed cause class, the workerd
+ * platform flags that are `true`, and, only when no guest produced the failure,
+ * its first message line bounded to {@link maxDiagnosticMessage} characters.
+ */
+export declare function failureDiagnostic(cause: unknown): FailureDiagnostic;
+export {};

package/dist/cause-class.js

@@ -0,0 +1,54 @@
+/** Never copy a guest-controlled name, message or stack into host diagnostics. */
+export function causeClass(cause) {
+    if (cause instanceof TypeError)
+        return "TypeError";
+    if (cause instanceof RangeError)
+        return "RangeError";
+    if (cause instanceof SyntaxError)
+        return "SyntaxError";
+    if (cause instanceof DOMException) {
+        if (cause.name === "AbortError")
+            return "AbortError";
+        if (cause.name === "TimeoutError")
+            return "TimeoutError";
+        return "Other";
+    }
+    return cause instanceof Error ? "Error" : "Other";
+}
+/** Failures that crossed the App facet boundary; their text may be guest-authored. */
+const guestCrossed = new WeakSet();
+/** Mark a failure that came back through the App facet so host logs keep only its class. */
+export function guestFailure(cause) {
+    guestCrossed.add(cause);
+    return cause;
+}
+const maxDiagnosticMessage = 240;
+const platformFlags = [
+    "remote",
+    "retryable",
+    "overloaded",
+    "durableObjectReset",
+];
+/**
+ * One host-owned failure diagnostic: the closed cause class, the workerd
+ * platform flags that are `true`, and, only when no guest produced the failure,
+ * its first message line bounded to {@link maxDiagnosticMessage} characters.
+ */
+export function failureDiagnostic(cause) {
+    const diagnostic = { causeClass: causeClass(cause) };
+    if (!(cause instanceof Error))
+        return diagnostic;
+    const flags = platformFlags.filter((flag) => Object.getOwnPropertyDescriptor(cause, flag)?.value === true);
+    if (flags.length > 0)
+        diagnostic.platform = flags;
+    if (!guestCrossed.has(cause)) {
+        const [line = ""] = cause.message.split("\n", 1);
+        // Control characters become spaces so one failure stays one log line.
+        const message = line
+            .replace(/\p{Cc}/gu, " ")
+            .slice(0, maxDiagnosticMessage);
+        if (message.length > 0)
+            diagnostic.message = message;
+    }
+    return diagnostic;
+}

package/dist/cloudflare.d.ts

@@ -0,0 +1,123 @@
+import { type FrameBindingReply } from "./frame-binding-wire.js";
+export type { FrameBindingReply, FrameBindingWire, } from "./frame-binding-wire.js";
+export type { BackgroundFrameState } from "./invocation.js";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { type GuestLimits } from "./guest-policy.js";
+export type { GuestLimits } from "./guest-policy.js";
+import { type AppBackendBindingName } from "@fungi.computer/puffball/app";
+import { type InvocationFrame, type InvocationGate } from "./invocation.js";
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type AppInstance, type InstancePorts } from "./index.js";
+/** Encode supervisor refusals before native RPC can discard Error properties. */
+export declare function captureFrameBindingReply<Value>(run: () => Promise<Value>): Promise<FrameBindingReply<Value>>;
+/** Retained shard reply ceiling; replies settle before the frame aborts its facet. */
+export declare const MAX_APP_REPLY_BYTES: number;
+/** Host-minted caller-frame routing props; never supplied by the App. */
+export type FrameBindingProps = Readonly<{
+    instanceId: string;
+    binding: AppBackendBindingName;
+    frameId: string;
+}>;
+/** The host's maintained positional argument/result codecs and operation policy. */
+export type FrameBindingMethod<Result> = Readonly<{
+    /** Decode the guest's positional arguments with the maintained method grammar. */
+    decodeArgs: (raw: readonly unknown[]) => readonly unknown[];
+    decodeResult: z.ZodType<Result>["parse"];
+    /** Determine the declared operations needed for these decoded arguments. */
+    requiredOperations: (args: readonly unknown[]) => readonly string[];
+}>;
+/** Method descriptors for the closed App binding vocabulary. */
+export type FrameBindingMethods<Result> = Readonly<Partial<Record<AppBackendBindingName, Readonly<Record<string, FrameBindingMethod<Result>>>>>>;
+/** Shared replay-only port codecs. Origin input is verified by the host and fails with a typed refusal. */
+export declare const backgroundFrameMethods: {
+    BACKGROUND: {
+        admit: {
+            /** Malformed arity supplies invalid origin evidence for the host's typed refusal. */
+            decodeArgs: (raw: readonly unknown[]) => [unknown] | undefined[];
+            /** Preserve the host's closed admitted/refused result. */
+            decodeResult: (raw: unknown) => {
+                kind: "admitted";
+            } | {
+                kind: "refused";
+                code: "access_changed";
+            };
+            /** Only the host-minted replay grant supplies this operation. */
+            requiredOperations: () => string[];
+        };
+    };
+};
+/** The shared RPC boundary decoder for host-minted invocation binding props. */
+export declare const frameBindingPropsSchema: Schema.Struct<{
+    readonly instanceId: Schema.Codec<import("./index.js").InstanceId, string, never, never>;
+    readonly frameId: Schema.String;
+    readonly binding: Schema.refine<"BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS", Schema.String>;
+}>;
+/** Decode a host routing packet or refuse it before any Instance lookup. */
+export declare function decodeFrameBindingProps(raw: unknown): FrameBindingProps;
+/** One native binding factory for both Hub and standalone, preserving RPC values. */
+export declare function frameBindingEntrypoint<Env, Result>(methods: FrameBindingMethods<Result>, dispatch: (env: Env, props: FrameBindingProps, method: string, args: readonly unknown[]) => Promise<FrameBindingReply<unknown>>): typeof WorkerEntrypoint<Env, FrameBindingProps>;
+/** Native facet handle; method RPCs are decoded at the invocation boundary. */
+export type AppFacetStub = Readonly<{
+    /** Issue an HTTP request through the native facet handle. */
+    fetch: (request: Request) => Promise<Response>;
+}>;
+/**
+ * Only the native storage and facet capabilities used by an App Instance.
+ * `FacetClass` is the host's Durable Object class type (`DurableObjectClass`
+ * on workerd, celld and Cloudflare); Oyster passes it through unopened.
+ */
+export type AppInstanceContext<FacetClass> = Readonly<{
+    /** The Durable Object's ID; its `name` is the Instance ID. */
+    id: Readonly<{
+        name?: string | undefined;
+    }>;
+    /** The Durable Object's SQLite storage, used for supervisor state only. */
+    storage: WatchdogSqliteOwner;
+    /** The Durable Object's facets; the App backend runs in the `app` facet. */
+    facets: Readonly<{
+        /** Get or create the named facet from the class `prepare` returns. */
+        get: (name: string, prepare: () => {
+            class: FacetClass;
+        }) => AppFacetStub;
+        /** Abort the named facet's in-flight work with `reason`. */
+        abort: (name: string, reason: Error) => void;
+        /** Delete the named facet and its storage. */
+        delete: (name: string) => void;
+    }>;
+}>;
+/** The module set the Worker Loader runs for one App backend. */
+export type AppWorkerCode = Readonly<{
+    compatibilityDate: string;
+    mainModule: string;
+    modules: Readonly<Record<string, string>>;
+    env: object;
+    globalOutbound: null;
+    /** Per-invocation guest budgets, enforced by the Worker Loader. */
+    limits: GuestLimits;
+}>;
+/** Loader memoization and class lookup; entrypoint access is not required. */
+export type AppInstanceLoader<FacetClass> = Readonly<{
+    /** Get or load the Worker for `id`, calling `configure` only on a cache miss. */
+    get: (id: string, configure: () => AppWorkerCode) => Readonly<{
+        /** Look up the Durable Object class the backend exports as `exportName`. */
+        getDurableObjectClass: (exportName: string) => FacetClass;
+    }>;
+}>;
+/** End the native App facet before shared frame admission releases its permit. */
+export declare function createCloudflareInvocationGate<Host, FacetClass>(ctx: Pick<AppInstanceContext<FacetClass>, "facets">, close: (frame: InvocationFrame<Host>) => Promise<void>): InvocationGate<Host>;
+/**
+ * Run an App Instance inside a SQLite-backed Durable Object on workerd, celld
+ * or Cloudflare. Supervisor state lives in the Durable Object's own SQLite; the
+ * App backend runs in a named `app` facet loaded through the Worker Loader, so
+ * its database survives Release replacement and stays separate from the
+ * supervisor. Guest code gets only host gatekeeper bindings and no ambient outbound access.
+ *
+ * @param ctx - The Durable Object's name, storage and facets.
+ * @param loader - The Worker Loader binding; without it backend execution is unavailable.
+ * @param resolve - Resolves a Release ID to its verified durable backend.
+ * @param guestEnv - Mints loopbacks bound to the captured invocation frame.
+ * @param limits - Guest CPU and subrequest budgets; omitted fields use safe defaults.
+ */
+export declare function createCloudflareAppInstance<FacetClass, Host>(ctx: AppInstanceContext<FacetClass>, loader: AppInstanceLoader<FacetClass> | undefined, resolve: InstancePorts<Host>["resolve"], guestEnv: (frame: InvocationFrame<Host>) => object, limits?: Partial<GuestLimits>): AppInstance<Host>;