@fungi.computer/agar 0.0.0-stage → 0.0.1

package/docs/api/files.md

@@ -0,0 +1,91 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / files
+
+# files
+
+## Type Aliases
+
+### AppFileRead
+
+```ts
+type AppFileRead = Disposable & object;
+```
+
+A parent-owned read. Closing it aborts the parent HTTP operation.
+
+#### Type Declaration
+
+| Name         | Type                          | Description                                                     |
+| ------------ | ----------------------------- | --------------------------------------------------------------- |
+| `response()` | () => `Promise`\<`Response`\> | Resolve with the underlying Response once it is available.      |
+| `close()`    | () => `Promise`\<`void`\>     | Release the parent's open read, aborting it if still in flight. |
+
+---
+
+### AppFileWrite
+
+```ts
+type AppFileWrite = Disposable & object;
+```
+
+A parent-owned upload; close requests transport abort, never promises rollback.
+
+#### Type Declaration
+
+| Name      | Type                               | Description                                                     |
+| --------- | ---------------------------------- | --------------------------------------------------------------- |
+| `write()` | (`content`) => `Promise`\<`void`\> | Stream the upload's content to the parent-owned destination.    |
+| `close()` | () => `Promise`\<`void`\>          | Request that the parent abort or finalize the upload transport. |
+
+## Functions
+
+### readAppFile()
+
+```ts
+function readAppFile(read, options): Promise<File>;
+```
+
+Native Response crosses RPC; File is constructed only in the receiving App.
+
+#### Parameters
+
+| Parameter         | Type                                              |
+| ----------------- | ------------------------------------------------- |
+| `read`            | [`AppFileRead`](#appfileread)                     |
+| `options`         | \{ `name`: `string`; `signal?`: `AbortSignal`; \} |
+| `options.name`    | `string`                                          |
+| `options.signal?` | `AbortSignal`                                     |
+
+#### Returns
+
+`Promise`\<`File`\>
+
+---
+
+### writeAppFile()
+
+```ts
+function writeAppFile(write, content, options): Promise<void>;
+```
+
+Stream a Blob's bytes to a parent-owned upload. Aborting `signal` closes the
+upload early; a close failure after a successful write is reported, never
+thrown, since it cannot change an already-acknowledged commit.
+
+#### Parameters
+
+| Parameter         | Type                            |
+| ----------------- | ------------------------------- |
+| `write`           | [`AppFileWrite`](#appfilewrite) |
+| `content`         | `Blob`                          |
+| `options`         | \{ `signal?`: `AbortSignal`; \} |
+| `options.signal?` | `AbortSignal`                   |
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/api/gills.md

@@ -0,0 +1,164 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / gills
+
+# gills
+
+## Type Aliases
+
+### AppBackendGill
+
+```ts
+type AppBackendGill = Readonly<{
+  declaration: AppDeclaredGill;
+  limit: number;
+  input: (selection) => Readonly<{
+    [key: string]: WhistleJsonValue;
+    limit: number;
+  }>;
+  parseCall: (raw) => GillCall;
+  call: (selection, read) => Promise<GillReply>;
+  rows: (output, context) => GillResponse;
+}>;
+```
+
+App-owned projection; methods keep their ordinary domain-shaped output.
+
+## Functions
+
+### decodeGillRefusal()
+
+```ts
+function decodeGillRefusal(
+  raw,
+  declaration,
+):
+  | {
+      viewId: string;
+      title: string;
+      state: "empty";
+      rows: readonly [];
+      next?: string;
+    }
+  | {
+      viewId: string;
+      title: string;
+      state: "error";
+      rows: readonly [];
+      reason?: "exec_isolation_required" | "params_required";
+      error: string;
+      recovery?:
+        | {
+            kind: "configure";
+            param: string;
+          }
+        | {
+            kind: "open";
+          };
+    }
+  | {
+      viewId: string;
+      title: string;
+      state: "full";
+      rows: readonly object[];
+      next?: string;
+    }
+  | undefined;
+```
+
+Decode the App host's strict isolation refusal into its permanent Gill state.
+
+#### Parameters
+
+| Parameter     | Type                                                   |
+| ------------- | ------------------------------------------------------ |
+| `raw`         | `unknown`                                              |
+| `declaration` | `Readonly`\<\{ `id`: `string`; `title`: `string`; \}\> |
+
+#### Returns
+
+##### Type Literal
+
+```ts
+{
+  viewId: string;
+  title: string;
+  state: "empty";
+  rows: readonly [];
+  next?: string;
+}
+```
+
+---
+
+##### Type Literal
+
+```ts
+{
+  viewId: string;
+  title: string;
+  state: "error";
+  rows: readonly [];
+  reason?: "exec_isolation_required" | "params_required";
+  error: string;
+  recovery?:   | {
+     kind: "configure";
+     param: string;
+   }
+     | {
+     kind: "open";
+   };
+}
+```
+
+| Name        | Type                                                                          | Description                                                                       |
+| ----------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `viewId`    | `string`                                                                      | -                                                                                 |
+| `title`     | `string`                                                                      | -                                                                                 |
+| `state`     | `"error"`                                                                     | -                                                                                 |
+| `rows`      | readonly \[\]                                                                 | -                                                                                 |
+| `reason?`   | `"exec_isolation_required"` \| `"params_required"`                            | Host-owned permanent execution refusal; an ordinary error may still be refreshed. |
+| `error`     | `string`                                                                      | -                                                                                 |
+| `recovery?` | \| \{ `kind`: `"configure"`; `param`: `string`; \} \| \{ `kind`: `"open"`; \} | The host supplies the same-placement picker and this App's launch.                |
+
+---
+
+##### Type Literal
+
+```ts
+{
+  viewId: string;
+  title: string;
+  state: "full";
+  rows: readonly object[];
+  next?: string;
+}
+```
+
+---
+
+`undefined`
+
+---
+
+### defineAppGill()
+
+```ts
+function defineAppGill(options): AppBackendGill;
+```
+
+Define a compact view of one of this App's declared read methods.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                         |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `id`: `string`; `title`: `string`; `source`: `string`; `limit`: `number`; `sizes?`: readonly `AppGillDesktopSize`[]; `params?`: readonly `AppGillParam`[]; `watch?`: `AppGillWatch`; `input`: [`AppBackendGill`](#appbackendgill)\[`"input"`\]; `rows`: [`AppBackendGill`](#appbackendgill)\[`"rows"`\]; \}\> |
+
+#### Returns
+
+[`AppBackendGill`](#appbackendgill)

package/docs/api/git-commit.md

@@ -0,0 +1,279 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/agar**](README.md)
+
+---
+
+[@fungi.computer/agar](modules.md) / git-commit
+
+# git-commit
+
+## Type Aliases
+
+### GitCommitStore
+
+```ts
+type GitCommitStore = Pick<GitBinding, "exchange">;
+```
+
+The binding operations these writes use.
+
+---
+
+### GitFileChange
+
+```ts
+type GitFileChange = Readonly<{
+  path: string;
+  content: Uint8Array | null;
+  mode?: "100644" | "100755";
+}>;
+```
+
+One file to write (`content`) or delete (`content: null`), repository-relative.
+
+---
+
+### GitIdentity
+
+```ts
+type GitIdentity = Readonly<{
+  name: string;
+  email: string;
+}>;
+```
+
+Name and email recorded as a commit's author and committer.
+
+---
+
+### CommitFilesRequest
+
+```ts
+type CommitFilesRequest = Readonly<{
+  repository: string;
+  branch: string;
+  expectedHead: string | null;
+  startFrom?: string;
+  changes: readonly GitFileChange[];
+  message: string;
+  author: GitIdentity;
+}>;
+```
+
+A commit of file changes to one branch.
+
+---
+
+### GitWriteOutcome
+
+```ts
+type GitWriteOutcome =
+  | Readonly<{
+      kind: "committed";
+      commit: string;
+    }>
+  | Readonly<{
+      kind: "unchanged";
+      commit: string;
+    }>
+  | Readonly<{
+      kind: "updated";
+    }>
+  | Readonly<{
+      kind: "stale";
+      head: string | null;
+    }>;
+```
+
+What a compare-and-swap write did.
+
+---
+
+### MergeBranchRequest
+
+```ts
+type MergeBranchRequest = Readonly<{
+  target: string;
+  source: string;
+  branch: string;
+  sourceBranch: string;
+  expectedSource: string;
+  expectedTarget?: string;
+  behind?: number;
+  message: string;
+  author: GitIdentity;
+}>;
+```
+
+Merge a branch of `source` (such as a fork) into a branch of `target`.
+
+---
+
+### GitMergeOutcome
+
+```ts
+type GitMergeOutcome =
+  | Readonly<{
+      kind: "merged";
+      before: string;
+      after: string;
+    }>
+  | Readonly<{
+      kind: "up-to-date";
+      head: string;
+    }>
+  | Readonly<{
+      kind: "conflict";
+      head: string;
+      paths: readonly string[];
+    }>
+  | Readonly<{
+      kind: "stale";
+      head: string | null;
+    }>
+  | Readonly<{
+      kind: "source-moved";
+      head: string;
+    }>;
+```
+
+What a merge did. Merges always write a merge commit when there is new work.
+
+---
+
+### MoveRefRequest
+
+```ts
+type MoveRefRequest = Readonly<{
+  repository: string;
+  ref: string;
+  expected: string | null;
+  commit: string;
+  source: string;
+}>;
+```
+
+Point a ref at a commit that is the head of `source`.
+
+---
+
+### MoveRefsRequest
+
+```ts
+type MoveRefsRequest = Readonly<{
+  repository: string;
+  source: string;
+  commit: string;
+  updates: readonly Readonly<{
+    ref: string;
+    expected: string | null;
+  }>[];
+}>;
+```
+
+Ordered ref moves to one fetched source commit; each move has its own CAS guard.
+
+---
+
+### GitRefMovesOutcome
+
+```ts
+type GitRefMovesOutcome =
+  | Readonly<{
+      kind: "updated";
+    }>
+  | Readonly<{
+      kind: "stale";
+      ref: string;
+      head: string | null;
+    }>;
+```
+
+Earlier moves remain accepted if a later ref is stale; this is not an atomic
+push.
+
+## Functions
+
+### commitFiles()
+
+```ts
+function commitFiles(store, request, beforeWrite?): Promise<GitWriteOutcome>;
+```
+
+Commit files using independently resumable, CAS-guarded Git steps.
+
+#### Parameters
+
+| Parameter      | Type                                        |
+| -------------- | ------------------------------------------- |
+| `store`        | [`GitCommitStore`](#gitcommitstore)         |
+| `request`      | [`CommitFilesRequest`](#commitfilesrequest) |
+| `beforeWrite?` | () => `Promise`\<`void`\>                   |
+
+#### Returns
+
+`Promise`\<[`GitWriteOutcome`](#gitwriteoutcome)\>
+
+---
+
+### moveRef()
+
+```ts
+function moveRef(store, request): Promise<GitWriteOutcome>;
+```
+
+Point a ref at the head commit of `source`, compare-and-swap on the ref.
+
+#### Parameters
+
+| Parameter | Type                                |
+| --------- | ----------------------------------- |
+| `store`   | [`GitCommitStore`](#gitcommitstore) |
+| `request` | [`MoveRefRequest`](#moverefrequest) |
+
+#### Returns
+
+`Promise`\<[`GitWriteOutcome`](#gitwriteoutcome)\>
+
+---
+
+### moveRefs()
+
+```ts
+function moveRefs(store, request): Promise<GitRefMovesOutcome>;
+```
+
+Fetch a source once, then move refs in order with separate guarded pushes.
+
+#### Parameters
+
+| Parameter | Type                                  |
+| --------- | ------------------------------------- |
+| `store`   | [`GitCommitStore`](#gitcommitstore)   |
+| `request` | [`MoveRefsRequest`](#moverefsrequest) |
+
+#### Returns
+
+`Promise`\<[`GitRefMovesOutcome`](#gitrefmovesoutcome)\>
+
+---
+
+### mergeBranch()
+
+```ts
+function mergeBranch(store, request): Promise<GitMergeOutcome>;
+```
+
+Merge branches through the same one-exchange step engine as background owners.
+
+#### Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `store`   | [`GitCommitStore`](#gitcommitstore)         |
+| `request` | [`MergeBranchRequest`](#mergebranchrequest) |
+
+#### Returns
+
+`Promise`\<[`GitMergeOutcome`](#gitmergeoutcome)\>