@fungi.computer/oyster 0.0.0-stage → 0.1.0

package/docs/api/index.md

@@ -0,0 +1,430 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/oyster**](README.md)
+
+---
+
+[@fungi.computer/oyster](modules.md) / index
+
+# index
+
+## Classes
+
+### AppInstanceError
+
+Stable runtime failure identity; message remains presentation only.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new AppInstanceError(code, options?): AppInstanceError;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code`     | \| `"stale_authority"` \| `"invalid_owner_state"` \| `"invalid_invocation_facts"` \| `"revoked"` \| `"binding_not_granted"` \| `"binding_unavailable"` \| `"expired"` \| `"reentrant"` \| `"instance_identity_mismatch"` \| `"instance_owner_mismatch"` \| `"conflicting_owner_state"` \| `"instance_deleted"` \| `"release_app_mismatch"` \| `"state_schema_migration_unsupported"` \| `"instance_inactive"` \| `"instance_authority_version_mismatch"` \| `"release_no_longer_matches_instance"` \| `"instance_release_mismatch"` \| `"installation_tenant_mismatch"` |
+| `options?` | `ErrorOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+###### Returns
+
+[`AppInstanceError`](#appinstanceerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "AppInstanceError" = "AppInstanceError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### code
+
+```ts
+readonly code:
+  | "stale_authority"
+  | "invalid_owner_state"
+  | "invalid_invocation_facts"
+  | "revoked"
+  | "binding_not_granted"
+  | "binding_unavailable"
+  | "expired"
+  | "reentrant"
+  | "instance_identity_mismatch"
+  | "instance_owner_mismatch"
+  | "conflicting_owner_state"
+  | "instance_deleted"
+  | "release_app_mismatch"
+  | "state_schema_migration_unsupported"
+  | "instance_inactive"
+  | "instance_authority_version_mismatch"
+  | "release_no_longer_matches_instance"
+  | "instance_release_mismatch"
+  | "installation_tenant_mismatch";
+```
+
+## Type Aliases
+
+### InstanceId
+
+```ts
+type InstanceId = CairnId<"app-instance", "instance">;
+```
+
+A stable App Instance ID minted by [instanceIds](#instanceids).
+
+---
+
+### OwnerState
+
+```ts
+type OwnerState = Schema.Schema.Type<typeof ownerStateSchema>;
+```
+
+A decoded [ownerStateSchema](#ownerstateschema) value, the input to `apply`.
+
+---
+
+### Selection
+
+```ts
+type Selection = Schema.Schema.Type<typeof selectionSchema>;
+```
+
+A decoded [selectionSchema](#selectionschema) value, the authority for `fetch`
+and `call`.
+
+---
+
+### Instance
+
+```ts
+type Instance = Schema.Schema.Type<typeof instanceSchema>;
+```
+
+A decoded [instanceSchema](#instanceschema) record, as returned by `apply` and
+`inspect`.
+
+---
+
+### Backend
+
+```ts
+type Backend = Readonly<{
+  release: Release;
+  digest: Sha256Digest;
+  backend: DurableBackend;
+}>;
+```
+
+A resolved, verified durable backend: its Release, artifact digest and code.
+
+---
+
+### AppInstanceErrorCode
+
+```ts
+type AppInstanceErrorCode = typeof appInstanceErrorCodeSchema.Type;
+```
+
+One of the bounded [appInstanceErrorCodeSchema](#appinstanceerrorcodeschema)
+rejection codes.
+
+---
+
+### BackendResolution
+
+```ts
+type BackendResolution<Host> =
+  | Readonly<{
+      kind: "metadata";
+    }>
+  | Readonly<{
+      kind: "invocation";
+      frame: InvocationFrame<Host>;
+    }>;
+```
+
+Supervisor schema checks do not open guest authority; execution carries a frame.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Host`         |
+
+---
+
+### InstancePorts
+
+```ts
+type InstancePorts<Host> = Readonly<{
+  instanceId: string;
+  read: () => Effect.Effect<Instance | null, Error>;
+  write: (instance) => Effect.Effect<void, Error>;
+  resolve: (release, scope) => Effect.Effect<Backend, Error>;
+  abort: () => Effect.Effect<void, Error>;
+  purge: () => Effect.Effect<void, Error>;
+  connect: (backend, frame) => Effect.Effect<AppBackendConnection, Error>;
+}>;
+```
+
+Host storage, verified artifact resolution, and frame-bound execution ports.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Host`         |
+
+---
+
+### AppBackendConnection
+
+```ts
+type AppBackendConnection = Readonly<{
+  authorizeGitPush?: (question) => Effect.Effect<GitPushVerdict, Error>;
+  onGitPush?: (fact) => Effect.Effect<void, Error>;
+  syncRefused?: (refusal) => Effect.Effect<void, Error>;
+  fetch: (request) => Effect.Effect<Response, Error>;
+  call: (name, input) => Effect.Effect<AppMethodReply, Error>;
+  gill: (cargo) => Effect.Effect<Schema.Json, Error>;
+}>;
+```
+
+One admitted connection to a running App backend.
+
+---
+
+### AppInstance
+
+```ts
+type AppInstance<Host> = Readonly<{
+  apply: (input) => Effect.Effect<Instance, Error>;
+  fetch: (frame, request) => Effect.Effect<Response, Error>;
+  call: (frame, api, name, input) => Effect.Effect<AppMethodReply, Error>;
+  gill: (frame, api, source, input) => Effect.Effect<GillReply, Error>;
+  authorizeGitPush: (frame, question) => Effect.Effect<GitPushVerdict, Error>;
+  onGitPush: (frame, fact) => Effect.Effect<void, Error>;
+  syncRefused: (frame, refusal) => Effect.Effect<void, Error>;
+  inspect: () => Effect.Effect<Instance | null, Error>;
+}>;
+```
+
+The lifecycle and admission operations of one App Instance.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Host`         |
+
+## Variables
+
+### instanceIds
+
+```ts
+const instanceIds: Readonly<{
+  instance: IdCodec<"app-instance", "instance", 1>;
+}>;
+```
+
+The Cairn ID family that mints and recognizes App Instance IDs (`instance_…`).
+
+---
+
+### instanceIdSchema
+
+```ts
+const instanceIdSchema: Schema.Codec<InstanceId, string>;
+```
+
+Decodes a string into an [InstanceId](#instanceid), rejecting any other ID
+family.
+
+---
+
+### ownerSchema
+
+```ts
+const ownerSchema: Struct<{
+  kind: Literals<readonly ["installation", "deployment"]>;
+  id: NonEmptyString;
+}>;
+```
+
+The owner that issues authority for an Instance: an `installation` of an App or
+a `deployment`. Owner identity never changes for the life of an Instance.
+
+---
+
+### selectionSchema
+
+```ts
+const selectionSchema: Struct<{
+  instanceId: Codec<InstanceId, string, never, never>;
+  owner: Struct<{
+    kind: Literals<readonly ["installation", "deployment"]>;
+    id: NonEmptyString;
+  }>;
+  appId: refine<AppId, String>;
+  releaseId: refine<ReleaseId, String>;
+  authorityVersion: Number;
+}>;
+```
+
+An owner-issued selection: which Instance, owner, App and Release a request runs
+against, at a positive authority version.
+
+---
+
+### ownerStateSchema
+
+```ts
+const ownerStateSchema: Struct<{
+  instanceId: Codec<InstanceId, string, never, never>;
+  owner: Struct<{
+    kind: Literals<readonly ["installation", "deployment"]>;
+    id: NonEmptyString;
+  }>;
+  appId: refine<AppId, String>;
+  releaseId: refine<ReleaseId, String>;
+  authorityVersion: Number;
+  status: Literals<readonly ["enabled", "disabled", "deleted"]>;
+}>;
+```
+
+A complete owner-issued state: a selection plus `enabled`, `disabled` or
+`deleted`.
+
+---
+
+### instanceSchema
+
+```ts
+const instanceSchema: Struct<{
+  instanceId: Codec<InstanceId, string, never, never>;
+  owner: Struct<{
+    kind: Literals<readonly ["installation", "deployment"]>;
+    id: NonEmptyString;
+  }>;
+  appId: refine<AppId, String>;
+  releaseId: refine<ReleaseId, String>;
+  authorityVersion: Number;
+  stateSchema: NullOr<Number>;
+  desiredStatus: Literals<readonly ["enabled", "disabled", "deleted"]>;
+  status: Literals<readonly ["active", "disabled", "deleting", "deleted"]>;
+}>;
+```
+
+The persisted Instance record: the last applied selection, its state-schema
+version, the owner's desired status and the runtime's own status.
+
+---
+
+### appInstanceErrorCodeSchema
+
+```ts
+const appInstanceErrorCodeSchema: Literals<
+  readonly [
+    "invalid_owner_state",
+    "invalid_invocation_facts",
+    "revoked",
+    "binding_not_granted",
+    "binding_unavailable",
+    "expired",
+    "reentrant",
+    "instance_identity_mismatch",
+    "instance_owner_mismatch",
+    "conflicting_owner_state",
+    "stale_authority",
+    "instance_deleted",
+    "release_app_mismatch",
+    "state_schema_migration_unsupported",
+    "instance_inactive",
+    "instance_authority_version_mismatch",
+    "release_no_longer_matches_instance",
+    "instance_release_mismatch",
+    "installation_tenant_mismatch",
+  ]
+>;
+```
+
+The runtime owns the bounded rejection grammar, including across RPC.
+
+## Functions
+
+### selectionOf()
+
+```ts
+function selectionOf(installation): object;
+```
+
+The admitted selection for an installation's Instance.
+
+#### Parameters
+
+| Parameter      | Type                                   |
+| -------------- | -------------------------------------- |
+| `installation` | [`Installation`](apps.md#installation) |
+
+#### Returns
+
+`object`
+
+| Name               | Type                               | Default value           |
+| ------------------ | ---------------------------------- | ----------------------- |
+| `instanceId`       | [`InstanceId`](#instanceid)        | `instanceIdSchema`      |
+| `owner`            | `object`                           | `ownerSchema`           |
+| `owner.kind`       | `"installation"` \| `"deployment"` | -                       |
+| `owner.id`         | `string`                           | `Schema.NonEmptyString` |
+| `appId`            | `AppId`                            | `appIdSchema`           |
+| `releaseId`        | `ReleaseId`                        | `releaseIdSchema`       |
+| `authorityVersion` | `number`                           | -                       |
+
+---
+
+### createAppInstance()
+
+```ts
+function createAppInstance<Host>(ports): AppInstance<Host>;
+```
+
+Create the resource-local lifecycle for one App Instance over host ports. This
+is not admission: the host must obtain real authority from its owner before
+calling `apply`, `fetch` or `call`.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `Host`         |
+
+#### Parameters
+
+| Parameter | Type                                        |
+| --------- | ------------------------------------------- |
+| `ports`   | [`InstancePorts`](#instanceports)\<`Host`\> |
+
+#### Returns
+
+[`AppInstance`](#appinstance)\<`Host`\>