@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/storage-wire.d.ts

@@ -0,0 +1,167 @@
+import * as Schema from "effect/Schema";
+import { appStorageKeyNameSchema } from "@fungi.computer/puffball/app";
+export { appStorageKeyNameSchema };
+/**
+ * Storage error codes the host and client agree on: invalid input, an
+ * undeclared key, a scope this App never declared, a member-only action
+ * tried without a member, a value or quota that is too large, a write
+ * conflict, or a transient host failure.
+ */
+export declare const appStorageErrorCodes: readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"];
+/** Validates that a value is one of the known storage error codes. */
+export declare const appStorageErrorCodeSchema: Schema.Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+/**
+ * Thrown by the storage client when a read, write, reset, or watch is
+ * rejected by the host; `code` identifies why.
+ */
+export declare class AppStorageError extends Error {
+    readonly code: typeof appStorageErrorCodeSchema.Type;
+    constructor(code: typeof appStorageErrorCodeSchema.Type, options?: ErrorOptions);
+}
+/**
+ * Validates the resolved shape of a storage key: its merged value, which
+ * layer it came from, the raw team and member layers it was merged from,
+ * and whether this App may write to the team layer.
+ */
+export declare const resolvedAppStorageSchema: Schema.Struct<{
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly source: Schema.Literals<readonly ["member", "team", "none"]>;
+    readonly team: Schema.NullOr<Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly revision: Schema.Int;
+    }>>;
+    readonly member: Schema.NullOr<Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly revision: Schema.Int;
+    }>>;
+    readonly canWriteTeam: Schema.Boolean;
+}>;
+/**
+ * The resolved value for a storage key, as returned by `read`: the merged
+ * value, which layer it came from, the raw team/member layers, and whether
+ * this App may write to the team layer.
+ */
+export type ResolvedAppStorage = typeof resolvedAppStorageSchema.Type;
+/**
+ * Validates a write request: the key, scope, value to store, and the
+ * revision it's conditioned on (`null` to write unconditionally).
+ */
+export declare const appStorageWriteSchema: Schema.Struct<{
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly key: Schema.String;
+    readonly scope: Schema.Literals<readonly ["team", "member"]>;
+    readonly basedOn: Schema.NullOr<Schema.Int>;
+}>;
+/**
+ * Validates a reset request: the key, scope, and the revision it's
+ * conditioned on (`null` to reset unconditionally).
+ */
+export declare const appStorageResetSchema: Schema.Struct<{
+    key: Schema.String;
+    scope: Schema.Literals<readonly ["team", "member"]>;
+    basedOn: Schema.NullOr<Schema.Int>;
+}>;
+/** A validated write request for one storage key. */
+export type AppStorageWrite = typeof appStorageWriteSchema.Type;
+/** A validated reset request for one storage key. */
+export type AppStorageReset = typeof appStorageResetSchema.Type;
+/** Validates a bare revision number returned after a write or reset. */
+export declare const appStorageRevisionSchema: Schema.Struct<{
+    readonly revision: Schema.Int;
+}>;
+/**
+ * Validates a change-event payload pushed when a storage key's value
+ * changes, naming the App, key, scope, and resulting revision.
+ */
+export declare const appStorageEventSchema: Schema.Struct<{
+    readonly appId: Schema.String;
+    readonly key: Schema.String;
+    readonly scope: Schema.Literals<readonly ["team", "member"]>;
+    readonly revision: Schema.Int;
+}>;
+/**
+ * A change-event payload identifying which App, key, scope, and
+ * resulting revision changed.
+ */
+export type AppStorageEvent = typeof appStorageEventSchema.Type;
+/**
+ * The wire-level outcome of a storage operation: either an accepted
+ * value or a rejection carrying an {@link AppStorageError} code.
+ */
+export type AppStorageResult<A> = Readonly<{
+    kind: "accepted";
+    value: A;
+}> | Readonly<{
+    kind: "rejected";
+    code: AppStorageError["code"];
+}>;
+/**
+ * Validates the wire result of a read: either an accepted resolved
+ * value or a rejection code.
+ */
+export declare const appStorageReadResultSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"accepted">;
+    readonly value: Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly source: Schema.Literals<readonly ["member", "team", "none"]>;
+        readonly team: Schema.NullOr<Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly revision: Schema.Int;
+        }>>;
+        readonly member: Schema.NullOr<Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly revision: Schema.Int;
+        }>>;
+        readonly canWriteTeam: Schema.Boolean;
+    }>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"rejected">;
+    readonly code: Schema.Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+}>]>;
+/**
+ * Validates the wire result of a write or reset: either an accepted
+ * revision or a rejection code.
+ */
+export declare const appStorageMutationResultSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"accepted">;
+    readonly value: Schema.Struct<{
+        readonly revision: Schema.Int;
+    }>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"rejected">;
+    readonly code: Schema.Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+}>]>;
+/** The read result at a host broker, retaining its existing admission/failure reply. */
+export declare const appStorageBrokerReadResultSchema: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"accepted">;
+    readonly value: Schema.Struct<{
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly source: Schema.Literals<readonly ["member", "team", "none"]>;
+        readonly team: Schema.NullOr<Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly revision: Schema.Int;
+        }>>;
+        readonly member: Schema.NullOr<Schema.Struct<{
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly revision: Schema.Int;
+        }>>;
+        readonly canWriteTeam: Schema.Boolean;
+    }>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"rejected">;
+    readonly code: Schema.Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+}>]>, Schema.Struct<{
+    readonly error: Schema.String;
+}>]>;
+/** The shared write/reset result at a host broker, including its existing failure reply. */
+export declare const appStorageBrokerMutationResultSchema: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"accepted">;
+    readonly value: Schema.Struct<{
+        readonly revision: Schema.Int;
+    }>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"rejected">;
+    readonly code: Schema.Literals<readonly ["invalid", "undeclared_key", "scope_not_declared", "owner_required", "too_large", "quota_exceeded", "conflict", "unavailable"]>;
+}>]>, Schema.Struct<{
+    readonly error: Schema.String;
+}>]>;

package/dist/storage-wire.js

@@ -0,0 +1,115 @@
+import * as Schema from "effect/Schema";
+import { appStorageScopes, appStorageKeyNameSchema, } from "@fungi.computer/puffball/app";
+export { appStorageKeyNameSchema };
+/**
+ * Storage error codes the host and client agree on: invalid input, an
+ * undeclared key, a scope this App never declared, a member-only action
+ * tried without a member, a value or quota that is too large, a write
+ * conflict, or a transient host failure.
+ */
+export const appStorageErrorCodes = [
+    "invalid",
+    "undeclared_key",
+    "scope_not_declared",
+    "owner_required",
+    "too_large",
+    "quota_exceeded",
+    "conflict",
+    "unavailable",
+];
+/** Validates that a value is one of the known storage error codes. */
+export const appStorageErrorCodeSchema = Schema.Literals(appStorageErrorCodes);
+/**
+ * Thrown by the storage client when a read, write, reset, or watch is
+ * rejected by the host; `code` identifies why.
+ */
+export class AppStorageError extends Error {
+    code;
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+    }
+}
+const revision = Schema.Int.check(Schema.isGreaterThan(0));
+const layer = Schema.Struct({ value: Schema.Json, revision });
+/**
+ * Validates the resolved shape of a storage key: its merged value, which
+ * layer it came from, the raw team and member layers it was merged from,
+ * and whether this App may write to the team layer.
+ */
+export const resolvedAppStorageSchema = Schema.Struct({
+    value: Schema.Json,
+    source: Schema.Literals(["member", "team", "none"]),
+    team: Schema.NullOr(layer),
+    member: Schema.NullOr(layer),
+    canWriteTeam: Schema.Boolean,
+});
+const mutation = {
+    key: appStorageKeyNameSchema,
+    scope: Schema.Literals(appStorageScopes),
+    basedOn: Schema.NullOr(revision),
+};
+/**
+ * Validates a write request: the key, scope, value to store, and the
+ * revision it's conditioned on (`null` to write unconditionally).
+ */
+export const appStorageWriteSchema = Schema.Struct({
+    ...mutation,
+    value: Schema.Json,
+});
+/**
+ * Validates a reset request: the key, scope, and the revision it's
+ * conditioned on (`null` to reset unconditionally).
+ */
+export const appStorageResetSchema = Schema.Struct(mutation);
+/** Validates a bare revision number returned after a write or reset. */
+export const appStorageRevisionSchema = Schema.Struct({ revision });
+/**
+ * Validates a change-event payload pushed when a storage key's value
+ * changes, naming the App, key, scope, and resulting revision.
+ */
+export const appStorageEventSchema = Schema.Struct({
+    appId: Schema.String,
+    key: appStorageKeyNameSchema,
+    scope: Schema.Literals(appStorageScopes),
+    revision,
+});
+/**
+ * Validates the wire result of a read: either an accepted resolved
+ * value or a rejection code.
+ */
+export const appStorageReadResultSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("accepted"),
+        value: resolvedAppStorageSchema,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("rejected"),
+        code: appStorageErrorCodeSchema,
+    }),
+]);
+/**
+ * Validates the wire result of a write or reset: either an accepted
+ * revision or a rejection code.
+ */
+export const appStorageMutationResultSchema = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("accepted"),
+        value: appStorageRevisionSchema,
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("rejected"),
+        code: appStorageErrorCodeSchema,
+    }),
+]);
+const brokerRefusal = Schema.Struct({ error: Schema.String });
+/** The read result at a host broker, retaining its existing admission/failure reply. */
+export const appStorageBrokerReadResultSchema = Schema.Union([
+    appStorageReadResultSchema,
+    brokerRefusal,
+]);
+/** The shared write/reset result at a host broker, including its existing failure reply. */
+export const appStorageBrokerMutationResultSchema = Schema.Union([
+    appStorageMutationResultSchema,
+    brokerRefusal,
+]);

package/dist/storage.d.ts

@@ -0,0 +1,72 @@
+import { type CapabilityContract } from "./capabilities.js";
+import type { ReadonlyStore } from "./store.js";
+import { type AppStorageResult, type AppStorageWrite, type AppStorageReset, type ResolvedAppStorage } from "./storage-wire.js";
+export * from "./storage-wire.js";
+/**
+ * A live subscription to one storage key's resolved value: read the
+ * current value, subscribe to changes, and close when done watching.
+ */
+export type AppStorageWatch = ReadonlyStore<ResolvedAppStorage> & Disposable & {
+    /** Stop watching and release the underlying event subscription. */
+    close(): void;
+};
+/** This App's storage client, scoped to its declared member/team data. */
+export type AppStorage = Readonly<{
+    /** Read the resolved value for `key`, merging team and member layers. */
+    read(key: string): Promise<ResolvedAppStorage>;
+    /**
+     * Write a value for a key and scope, optionally conditioned on
+     * `basedOn` revision; resolves with the resulting revision.
+     */
+    write(input: AppStorageWrite): Promise<{
+        revision: number;
+    }>;
+    /**
+     * Clear a key's value for a scope, optionally conditioned on
+     * `basedOn` revision; resolves with the resulting revision.
+     */
+    reset(input: AppStorageReset): Promise<{
+        revision: number;
+    }>;
+    /** Resolves after the first admitted snapshot; close when the consumer leaves. */
+    watch(key: string): Promise<AppStorageWatch>;
+}>;
+/**
+ * A live object capability backing one key's change-event stream,
+ * adapted to Fetch so it can drive an `EventSource`.
+ */
+export type AppStorageEventHandle = Disposable & {
+    /** Forward one `EventSource` request to the host's event stream. */
+    fetch(request: Request): Promise<Response>;
+    /** Release the change-event stream's underlying object capability. */
+    close(): Promise<void>;
+};
+/**
+ * The raw wire contract this capability negotiates with the host,
+ * before client-side input validation and error unwrapping.
+ */
+export type AppStorageWire = {
+    /**
+     * Read a key's resolved value over the wire; resolves with an
+     * accepted value or a rejection code.
+     */
+    read(key: string): Promise<AppStorageResult<ResolvedAppStorage>>;
+    /**
+     * Write a key's value over the wire; resolves with the accepted
+     * revision or a rejection code.
+     */
+    write(input: AppStorageWrite): Promise<AppStorageResult<{
+        revision: number;
+    }>>;
+    /**
+     * Reset a key's value over the wire; resolves with the accepted
+     * revision or a rejection code.
+     */
+    reset(input: AppStorageReset): Promise<AppStorageResult<{
+        revision: number;
+    }>>;
+    /** Open the change-event stream for a key, as a Fetch-adapted handle. */
+    openEvents(key: string): Promise<AppStorageEventHandle>;
+};
+/** This App's own declared data. The host seals App and member identities. */
+export declare const appStorage: CapabilityContract<AppStorage>;

package/dist/storage.js

@@ -0,0 +1,143 @@
+import * as Schema from "effect/Schema";
+import * as z from "zod";
+import { EventSource } from "eventsource";
+import { defineCapability } from "./capabilities.js";
+import { rpcHandleSchema, rpcDataSchema, rpcMethod, rpcFetchHandleSchema, } from "./internal/rpc-contract.js";
+import { createReadonlyStore } from "./internal/store.js";
+import { reportCatchFailure } from "./failure.js";
+import { AppStorageError, appStorageKeyNameSchema, appStorageWriteSchema, appStorageResetSchema, appStorageReadResultSchema, appStorageMutationResultSchema, appStorageEventSchema, } from "./storage-wire.js";
+export * from "./storage-wire.js";
+const data = (schema) => rpcDataSchema(z
+    .unknown()
+    .transform((value) => Schema.decodeUnknownSync(schema, { onExcessProperty: "error" })(value)));
+const rawSchema = rpcHandleSchema({
+    read: rpcMethod(data(appStorageReadResultSchema)),
+    write: rpcMethod(data(appStorageMutationResultSchema)),
+    reset: rpcMethod(data(appStorageMutationResultSchema)),
+    openEvents: rpcMethod(rpcFetchHandleSchema),
+});
+const unwrap = (result) => {
+    if (result.kind === "rejected")
+        throw new AppStorageError(result.code);
+    return result.value;
+};
+const parseInput = (schema, value) => {
+    const parsed = Schema.decodeUnknownResult(schema, {
+        onExcessProperty: "error",
+    })(value);
+    if (parsed._tag === "Failure")
+        throw new AppStorageError("invalid", { cause: parsed.failure });
+    return parsed.success;
+};
+const parseKey = (key) => parseInput(appStorageKeyNameSchema, key);
+function client(raw) {
+    const read = async (key) => unwrap(await raw.read(parseKey(key)));
+    return {
+        read,
+        write: async (input) => unwrap(await raw.write(parseInput(appStorageWriteSchema, input))),
+        reset: async (input) => unwrap(await raw.reset(parseInput(appStorageResetSchema, input))),
+        async watch(input) {
+            const key = parseKey(input);
+            const handle = await raw.openEvents(key);
+            let closed = false;
+            const isClosed = () => closed;
+            let loading;
+            let dirty = false;
+            const shouldRead = () => dirty && !isClosed();
+            let store;
+            let resolveInitial = () => undefined;
+            let rejectInitial = () => undefined;
+            const initial = new Promise((resolve, reject) => {
+                resolveInitial = resolve;
+                rejectInitial = reject;
+            });
+            const events = new EventSource("https://app-storage.fungi.invalid/events", {
+                fetch: async (url, init) => {
+                    const response = await handle.fetch(new Request(url, init));
+                    if (!response.ok) {
+                        const parsed = Schema.decodeUnknownResult(appStorageReadResultSchema)(await response.json());
+                        const failure = new AppStorageError(parsed._tag === "Success" && parsed.success.kind === "rejected"
+                            ? parsed.success.code
+                            : "unavailable");
+                        fail(failure);
+                        throw failure;
+                    }
+                    return response;
+                },
+            });
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                events.close();
+                rejectInitial(new AppStorageError("unavailable"));
+                void handle
+                    .close()
+                    .catch((cause) => {
+                    reportCatchFailure("storage.watch.close", cause);
+                })
+                    .finally(() => {
+                    handle[Symbol.dispose]();
+                });
+            };
+            const fail = (cause) => {
+                rejectInitial(cause instanceof AppStorageError
+                    ? cause
+                    : new AppStorageError("unavailable", { cause }));
+                if (!closed && store !== undefined)
+                    reportCatchFailure("storage.watch", cause);
+                close();
+            };
+            const refresh = () => {
+                dirty = true;
+                if (loading !== undefined || closed)
+                    return;
+                loading = (async () => {
+                    while (shouldRead()) {
+                        dirty = false;
+                        const next = await read(key);
+                        if (isClosed())
+                            return;
+                        if (store === undefined) {
+                            const first = createReadonlyStore(next);
+                            store = first;
+                            resolveInitial({
+                                get: () => first.get(),
+                                subscribe: (listener) => first.subscribe(listener),
+                                close,
+                                [Symbol.dispose]: close,
+                            });
+                        }
+                        else
+                            store.update(next);
+                    }
+                })()
+                    .catch(fail)
+                    .finally(() => {
+                    loading = undefined;
+                    if (dirty && !closed)
+                        refresh();
+                });
+            };
+            // The owner emits ready only after registering the subscription. Reading
+            // then closes the initial-read/subscription race and every reconnect gap.
+            events.addEventListener("ready", refresh);
+            events.addEventListener("changed", (event) => {
+                const changed = Schema.decodeUnknownResult(Schema.fromJsonString(appStorageEventSchema), { onExcessProperty: "error" })(event.data);
+                if (changed._tag === "Failure")
+                    fail(changed.failure);
+                else if (changed.success.key !== key)
+                    fail(new AppStorageError("invalid"));
+                else
+                    refresh();
+            });
+            events.onerror = (cause) => {
+                if (store === undefined || events.readyState === EventSource.CLOSED)
+                    fail(cause);
+            };
+            return initial;
+        },
+    };
+}
+/** This App's own declared data. The host seals App and member identities. */
+export const appStorage = defineCapability("app.storage", 1, rawSchema.transform(client));

package/dist/store.d.ts

@@ -0,0 +1,11 @@
+/** Releases a subscription or other held resource. Call once; further
+ * calls are a no-op. */
+export type Disposer = () => void;
+/** A retained SDK-owned snapshot. */
+export type ReadonlyStore<T> = {
+    /** The current value; always available, even before any subscription. */
+    get(): T;
+    /** Call `listener` on every change until the returned Disposer runs.
+     * Does not emit the current value immediately on subscribe. */
+    subscribe(listener: (value: T) => void): Disposer;
+};

package/dist/store.js

@@ -0,0 +1 @@
+export {};

package/dist/test-kit/git.d.ts

@@ -0,0 +1,31 @@
+import type { GitCommit, GitRepositoryInfo } from "../git.js";
+/** Real smart HTTP writes and git plumbing reads in one disposable bare repository. */
+export declare function realGit(): {
+    git: Readonly<{
+        create(name: string, options?: {
+            description?: string;
+            defaultBranch?: string;
+        }): Promise<GitRepositoryInfo>;
+        fork(source: string, target: string, options?: {
+            description?: string;
+        }): Promise<GitRepositoryInfo>;
+        cloneUrl(name: string): Promise<string>;
+        info(name: string): Promise<GitRepositoryInfo | null>;
+        delete(name: string): Promise<boolean>;
+        log(name: string, options: {
+            ref: string;
+            limit?: number;
+            offset?: number;
+        }): Promise<GitCommit[]>;
+        readCommit(name: string, hash: string): Promise<GitCommit | null>;
+        readTree(name: string, hash: string): Promise<import("../git.js").GitTreeEntry[] | null>;
+        readBlob(name: string, hash: string): Promise<Uint8Array | null>;
+        refs(name: string): Promise<{
+            name: string;
+            hash: string;
+        }[]>;
+        exchange(name: string, request: import("../git.js").GitExchangeRequest): Promise<import("../git.js").GitExchangeResponse>;
+    }>;
+    run: (name: string, ...args: string[]) => string;
+    close: () => void;
+};