@fungi.computer/puffball 0.0.0-stage → 0.0.1

package/docs/api/app-method-context.md

@@ -0,0 +1,166 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/puffball**](README.md)
+
+---
+
+[@fungi.computer/puffball](README.md) / app-method-context
+
+# app-method-context
+
+## Variables
+
+### appMethodCallContextSchema
+
+```ts
+const appMethodCallContextSchema: declareConstructor<
+  {
+    computerId: string | null;
+    actor:
+      | {
+          kind: "member";
+          memberId: string;
+        }
+      | {
+          kind: "agent";
+          agentId: string;
+        }
+      | {
+          kind: "team-key";
+          keyId: string;
+        };
+    backgroundLane?: string;
+    backgroundOrigin?: {
+      method: string;
+      seal: string;
+    };
+    role?: "member" | "owner";
+    soleMember?: true;
+    workflow?: {
+      workflowId: string;
+      runId: string;
+      nodeId: string;
+      armedBy:
+        | {
+            kind: "member";
+            memberId: string;
+          }
+        | {
+            kind: "agent";
+            agentId: string;
+          }
+        | {
+            kind: "team-key";
+            keyId: string;
+          };
+    };
+    idempotencyKey?: string;
+  },
+  {
+    computerId: string | null;
+    actor:
+      | {
+          kind: "member";
+          memberId: string;
+        }
+      | {
+          kind: "agent";
+          agentId: string;
+        }
+      | {
+          kind: "team-key";
+          keyId: string;
+        };
+    backgroundLane?: string;
+    backgroundOrigin?: {
+      method: string;
+      seal: string;
+    };
+    role?: "member" | "owner";
+    soleMember?: true;
+    workflow?: {
+      workflowId: string;
+      runId: string;
+      nodeId: string;
+      armedBy:
+        | {
+            kind: "member";
+            memberId: string;
+          }
+        | {
+            kind: "agent";
+            agentId: string;
+          }
+        | {
+            kind: "team-key";
+            keyId: string;
+          };
+    };
+    idempotencyKey?: string;
+  },
+  readonly [],
+  {
+    computerId: string | null;
+    actor:
+      | {
+          kind: "member";
+          memberId: string;
+        }
+      | {
+          kind: "agent";
+          agentId: string;
+        }
+      | {
+          kind: "team-key";
+          keyId: string;
+        };
+    backgroundLane?: string;
+    backgroundOrigin?: {
+      method: string;
+      seal: string;
+    };
+    role?: "member" | "owner";
+    soleMember?: true;
+    workflow?: {
+      workflowId: string;
+      runId: string;
+      nodeId: string;
+      armedBy:
+        | {
+            kind: "member";
+            memberId: string;
+          }
+        | {
+            kind: "agent";
+            agentId: string;
+          }
+        | {
+            kind: "team-key";
+            keyId: string;
+          };
+    };
+    idempotencyKey?: string;
+  }
+>;
+```
+
+Host attribution, including paired sealed enqueue origin, uses the sole
+lightweight caller grammar.
+
+## References
+
+### AppMethodCallContext
+
+Re-exports [AppMethodCallContext](app-method-runtime.md#appmethodcallcontext)
+
+---
+
+### HostActor
+
+Re-exports [HostActor](app-method-runtime.md#hostactor)
+
+---
+
+### WorkflowAttestation
+
+Re-exports [WorkflowAttestation](app-method-runtime.md#workflowattestation)

package/docs/api/app-method-runtime.md

@@ -0,0 +1,330 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/puffball**](README.md)
+
+---
+
+[@fungi.computer/puffball](README.md) / app-method-runtime
+
+# app-method-runtime
+
+## Type Aliases
+
+### HostActor
+
+```ts
+type HostActor = z.output<typeof hostActorSchema>;
+```
+
+The host's verified member, Agent or Team-key identity.
+
+---
+
+### WorkflowAttestation
+
+```ts
+type WorkflowAttestation = z.output<typeof workflowAttestationSchema>;
+```
+
+Workflow attribution shared by invocation frames and Git writers.
+
+---
+
+### AppMethodCallContext
+
+```ts
+type AppMethodCallContext = z.output<typeof appMethodCallerSchema>;
+```
+
+Trusted attribution delivered separately from App method arguments.
+
+## Variables
+
+### appApiReservedMethodNames
+
+```ts
+const appApiReservedMethodNames: Readonly<{
+  intrinsic: readonly [
+    "constructor",
+    "toString",
+    "valueOf",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toLocaleString",
+  ];
+  rpc: readonly ["then", "dup", "connect", "id", "name"];
+  instance: readonly ["ctx", "env"];
+  lifecycle: readonly [
+    "gill",
+    "onGitPush",
+    "syncRefused",
+    "authorizeGitPush",
+    "fetch",
+    "alarm",
+    "queue",
+    "scheduled",
+    "tail",
+    "trace",
+    "email",
+    "test",
+    "tailStream",
+    "webSocketMessage",
+    "webSocketClose",
+    "webSocketError",
+  ];
+}>;
+```
+
+Reserved JavaScript, RPC and lifecycle names are never App method names.
+
+---
+
+### hostActorSchema
+
+```ts
+const hostActorSchema: ZodMiniDiscriminatedUnion<
+  [
+    ZodMiniObject<
+      {
+        kind: ZodMiniLiteral<"member">;
+        memberId: ZodMiniString<string>;
+      },
+      $strip
+    >,
+    ZodMiniObject<
+      {
+        kind: ZodMiniLiteral<"agent">;
+        agentId: ZodMiniString<string>;
+      },
+      $strip
+    >,
+    ZodMiniObject<
+      {
+        kind: ZodMiniLiteral<"team-key">;
+        keyId: ZodMiniString<string>;
+      },
+      $strip
+    >,
+  ],
+  "kind"
+>;
+```
+
+Actor identity attested by the host, shared by calls and Workflow arming.
+
+---
+
+### workflowAttestationSchema
+
+```ts
+const workflowAttestationSchema: ZodMiniObject<
+  {
+    workflowId: ZodMiniString<string>;
+    runId: ZodMiniString<string>;
+    nodeId: ZodMiniString<string>;
+    armedBy: ZodMiniDiscriminatedUnion<
+      [
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"member">;
+            memberId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"agent">;
+            agentId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"team-key">;
+            keyId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+      ],
+      "kind"
+    >;
+  },
+  $strip
+>;
+```
+
+Host-held Workflow attribution, delivered separately from guest input.
+
+---
+
+### appMethodCallerSchema
+
+```ts
+const appMethodCallerSchema: ZodMiniObject<
+  {
+    computerId: ZodMiniNullable<ZodMiniString<string>>;
+    actor: ZodMiniDiscriminatedUnion<
+      [
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"member">;
+            memberId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"agent">;
+            agentId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+        ZodMiniObject<
+          {
+            kind: ZodMiniLiteral<"team-key">;
+            keyId: ZodMiniString<string>;
+          },
+          $strip
+        >,
+      ],
+      "kind"
+    >;
+    backgroundLane: ZodMiniOptional<ZodMiniString<string>>;
+    backgroundOrigin: ZodMiniOptional<
+      ZodMiniObject<
+        {
+          method: ZodMiniString<string>;
+          seal: ZodMiniString<string>;
+        },
+        $strict
+      >
+    >;
+    role: ZodMiniOptional<
+      ZodMiniEnum<{
+        member: "member";
+        owner: "owner";
+      }>
+    >;
+    soleMember: ZodMiniOptional<ZodMiniLiteral<true>>;
+    workflow: ZodMiniOptional<
+      ZodMiniObject<
+        {
+          workflowId: ZodMiniString<string>;
+          runId: ZodMiniString<string>;
+          nodeId: ZodMiniString<string>;
+          armedBy: ZodMiniDiscriminatedUnion<
+            [
+              ZodMiniObject<
+                {
+                  kind: ZodMiniLiteral<"member">;
+                  memberId: ZodMiniString<string>;
+                },
+                $strip
+              >,
+              ZodMiniObject<
+                {
+                  kind: ZodMiniLiteral<"agent">;
+                  agentId: ZodMiniString<string>;
+                },
+                $strip
+              >,
+              ZodMiniObject<
+                {
+                  kind: ZodMiniLiteral<"team-key">;
+                  keyId: ZodMiniString<string>;
+                },
+                $strip
+              >,
+            ],
+            "kind"
+          >;
+        },
+        $strip
+      >
+    >;
+    idempotencyKey: ZodMiniOptional<ZodMiniString<string>>;
+  },
+  $strip
+>;
+```
+
+Sole grammar for the host-minted Computer pin and actor attribution.
+
+## Functions
+
+### parseAppMethodCallContext()
+
+```ts
+function parseAppMethodCallContext(value, rejectUnknownKeys?): object;
+```
+
+Decode trusted host attribution through the sole runtime-neutral grammar.
+
+#### Parameters
+
+| Parameter           | Type      | Default value |
+| ------------------- | --------- | ------------- |
+| `value`             | `unknown` | `undefined`   |
+| `rejectUnknownKeys` | `boolean` | `false`       |
+
+#### Returns
+
+| Name                      | Type                                                                                                                                                  | Default value     | Description                                                                                                                                                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `computerId`              | `string` \| `null`                                                                                                                                    | -                 | -                                                                                                                                                                                                                         |
+| `actor`                   | \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \} | `hostActorSchema` | -                                                                                                                                                                                                                         |
+| `backgroundLane?`         | `string`                                                                                                                                              | -                 | Host-attested enqueue eligibility for this ordinary write; absent otherwise.                                                                                                                                              |
+| `backgroundOrigin?`       | `object`                                                                                                                                              | -                 | Host-sealed foreground method for durable jobs; paired with backgroundLane.                                                                                                                                               |
+| `backgroundOrigin.method` | `string`                                                                                                                                              | -                 | -                                                                                                                                                                                                                         |
+| `backgroundOrigin.seal`   | `string`                                                                                                                                              | -                 | -                                                                                                                                                                                                                         |
+| `role?`                   | `"member"` \| `"owner"`                                                                                                                               | -                 | Team role attested by the host, never selected by App method input.                                                                                                                                                       |
+| `soleMember?`             | `true`                                                                                                                                                | -                 | The host attests that this member is currently the Team's only member. Present only on a member's own call; never on an Agent, Team key or Workflow node, and never selected by App method input.                         |
+| `workflow?`               | `object`                                                                                                                                              | -                 | Present only on a Workflow node invocation admitted by its host.                                                                                                                                                          |
+| `workflow.workflowId`     | `string`                                                                                                                                              | `identity`        | Published Workflow selected by the run owner.                                                                                                                                                                             |
+| `workflow.runId`          | `string`                                                                                                                                              | `identity`        | Run identity held by the run owner.                                                                                                                                                                                       |
+| `workflow.nodeId`         | `string`                                                                                                                                              | `identity`        | Node selected by the stored published Workflow.                                                                                                                                                                           |
+| `workflow.armedBy`        | \| \{ `kind`: `"member"`; `memberId`: `string`; \} \| \{ `kind`: `"agent"`; `agentId`: `string`; \} \| \{ `kind`: `"team-key"`; `keyId`: `string`; \} | `hostActorSchema` | Actor that armed the run, re-admitted by the host at dispatch.                                                                                                                                                            |
+| `idempotencyKey?`         | `string`                                                                                                                                              | -                 | The host's stable key for this logical call (for example one Workflow node), the same on every retry. A method with side effects uses it to do its work at most once. Absent when the caller supplies its own request id. |
+
+---
+
+### isAppApiMethodName()
+
+```ts
+function isAppApiMethodName(name): boolean;
+```
+
+Shared domain grammar for generated RPC method names.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `name`    | `string` |
+
+#### Returns
+
+`boolean`
+
+---
+
+### backgroundSyncAllowed()
+
+```ts
+function backgroundSyncAllowed(api, sync): boolean;
+```
+
+A continuation must cover every write method's requirements, and itself be a
+write.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                               |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`     | \| `Readonly`\<\{ `methods`: `Readonly`\<`Record`\<`string`, `Pick`\<[`AppApi`](index.md#appapi)\[`"methods"`\]\[`string`\], `"effect"` \| `"requires"`\>\>\>; \}\> \| `undefined` |
+| `sync`    | \| `Readonly`\<\{ `method`: `string`; \}\> \| `undefined`                                                                                                                          |
+
+#### Returns
+
+`boolean`

package/docs/api/backend.md

@@ -0,0 +1,108 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/puffball**](README.md)
+
+---
+
+[@fungi.computer/puffball](README.md) / backend
+
+# backend
+
+## Variables
+
+### durableBackendSchema
+
+```ts
+const durableBackendSchema: Struct<{
+  runtime: Struct<{
+    kind: Literal<"durable-facet">;
+    stateSchema: Number;
+  }>;
+  compatibilityDate: String;
+  exportName: String;
+  code: String;
+}>;
+```
+
+This immutable descriptor is stored inside the verified Release artifact.
+
+---
+
+### backendMediaType
+
+```ts
+const backendMediaType: "application/vnd.fungi.app-backend+json";
+```
+
+Content type separating executable backend artifacts from website HTML.
+
+---
+
+### backendJsonSchema
+
+```ts
+const backendJsonSchema: fromJsonString<
+  Struct<{
+    runtime: Struct<{
+      kind: Literal<"durable-facet">;
+      stateSchema: Number;
+    }>;
+    compatibilityDate: String;
+    exportName: String;
+    code: String;
+  }>
+>;
+```
+
+Maintained JSON codec for immutable backend bytes.
+
+## Functions
+
+### resolveDurableBackend()
+
+```ts
+function resolveDurableBackend(
+  catalog,
+  releaseId,
+): Effect<
+  {
+    release: Release;
+    digest: Sha256Digest;
+    backend: Readonly<{
+      runtime: Readonly<{
+        kind: "durable-facet";
+        stateSchema: number;
+      }>;
+      compatibilityDate: string;
+      exportName: string;
+      code: string;
+    }>;
+  },
+  AppReleaseCoreFailure,
+  never
+>;
+```
+
+Resolve through catalog eligibility and digest verification before decoding
+code.
+
+#### Parameters
+
+| Parameter   | Type                                                                           |
+| ----------- | ------------------------------------------------------------------------------ |
+| `catalog`   | `Pick`\<[`AppReleaseCore`](effect.md#appreleasecore), `"resolveEligibleApp"`\> |
+| `releaseId` | [`ReleaseId`](index.md#releaseid)                                              |
+
+#### Returns
+
+`Effect`\<\{ `release`: [`Release`](index.md#release); `digest`:
+[`Sha256Digest`](index.md#sha256digest); `backend`: `Readonly`\<\{ `runtime`:
+`Readonly`\<\{ `kind`: `"durable-facet"`; `stateSchema`: `number`; \}\>;
+`compatibilityDate`: `string`; `exportName`: `string`; `code`: `string`; \}\>;
+\}, [`AppReleaseCoreFailure`](effect.md#appreleasecorefailure), `never`\>
+
+## References
+
+### DurableBackend
+
+Re-exports [DurableBackend](index.md#durablebackend)