Skip to content
Oyster0.6.0
API reference

oyster

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/oyster";

Exports

Section titled “Exports”
Kind Export Description
class AppInstanceError Stable runtime failure identity; message remains presentation only.
type alias AgentAvatarStore One owner-local store of chosen Agent avatars.
type alias UiBootCheckOutcome A UI check result recorded on an installation operation, never installation authority.
type alias OwnerState A decoded ownerStateSchema value, the input to apply.
type alias Selection A decoded selectionSchema value, the authority for fetch and call.
type alias Instance A decoded instanceSchema record, as returned by apply and inspect.
type alias Backend A resolved, verified durable backend: its Release, artifact digest and code.
type alias AppInstanceErrorCode One of the bounded appInstanceErrorCodeSchema rejection codes.
type alias BackendResolution Supervisor schema checks do not open guest authority; execution carries a frame.
type alias InstancePorts Host storage, verified artifact resolution, and frame-bound execution ports.
type alias AppBackendConnection One admitted connection to a running App backend.
type alias AppInstance The lifecycle and admission operations of one App Instance.
type alias InstanceId A stable App Instance ID minted by instanceIds.
constant agentAvatarSchema The catalog-valid avatar an owner may choose for an Agent.
constant agentAvatarProjectionSchema The avatar as a closed record, for contracts that refuse open maps (Hub projections): each character’s appearance names only its own controls, then the catalog refines it exactly as agentAvatarSchema does.
constant uiBootCheckOutcomeSchema A UI check recorded on an installation operation, never installation authority.
constant ownerSchema 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.
constant selectionSchema An owner-issued selection: which Instance, owner, App and Release a request runs against, at a positive authority version.
constant ownerStateSchema A complete owner-issued state: a selection plus enabled, disabled or deleted.
constant instanceSchema The persisted Instance record: the last applied selection, its state-schema version, the owner’s desired status and the runtime’s own status.
constant appInstanceErrorCodeSchema The runtime owns the bounded rejection grammar, including across RPC.
constant instanceIds The Cairn ID family that mints and recognizes App Instance IDs (instance_…).
constant instanceIdSchema Decodes a string into an InstanceId, rejecting any other ID family.
function avatarFromProjection() A projected avatar as the Avatar descriptor Sprite draws.
function createAgentAvatarStore() Open the chosen-avatar table in the Agent directory’s own SQLite.
function selectionOf() The admitted selection for an installation’s Instance.
function createAppInstance() 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.

AppInstanceErrorclass

Section titled “AppInstanceError”

Stable runtime failure identity; message remains presentation only.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new AppInstanceError(code, options?): AppInstanceError;
Parameters
Section titled “Parameters”
Parameter Type
code | "disabled" | "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" | "backend_load_failed" | "backend_construction_failed" | "ui_mount_failed" | "boot_runner_unavailable" | "boot_browser_binding_missing" | "boot_clone_unavailable" | "boot_timeout" | "boot_cleanup_failed"
options? ErrorOptions
Returns
Section titled “Returns”

AppInstanceError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

name

Section titled “name”
Signature
readonly name: "AppInstanceError" = "AppInstanceError";
Overrides
Section titled “Overrides”
Signature
Error.name;

code

Section titled “code”
Signature
readonly code:
  | "disabled"
  | "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"
  | "backend_load_failed"
  | "backend_construction_failed"
  | "ui_mount_failed"
  | "boot_runner_unavailable"
  | "boot_browser_binding_missing"
  | "boot_clone_unavailable"
  | "boot_timeout"
  | "boot_cleanup_failed";

AgentAvatarStoretype alias

Section titled “AgentAvatarStore”
Signature
type AgentAvatarStore = Readonly<{
  read: {
    v: z.ZodLiteral<1>;
    character: z.ZodEnum<{
      mushroom: "mushroom";
      cat: "cat";
      burger: "burger";
    }>;
    appearance: z.ZodRecord<
      z.ZodString,
      z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>
    >;
    expression: z.ZodString;
    renderStyle: z.ZodEnum<{
      plain: "plain";
      pencil: "pencil";
      manga: "manga";
      riso: "riso";
      halftone: "halftone";
      blueprint: "blueprint";
      crt: "crt";
      watercolor: "watercolor";
    }>;
  };
  write: void;
  remove: void;
}>;

One owner-local store of chosen Agent avatars.

UiBootCheckOutcometype alias

Section titled “UiBootCheckOutcome”
Signature
type UiBootCheckOutcome = z.output<typeof uiBootCheckOutcomeSchema>;

A UI check result recorded on an installation operation, never installation authority.

OwnerStatetype alias

Section titled “OwnerState”
Signature
type OwnerState = Schema.Schema.Type<typeof ownerStateSchema>;

A decoded ownerStateSchema value, the input to apply.

Selectiontype alias

Section titled “Selection”
Signature
type Selection = Schema.Schema.Type<typeof selectionSchema>;

A decoded selectionSchema value, the authority for fetch and call.

Instancetype alias

Section titled “Instance”
Signature
type Instance = Schema.Schema.Type<typeof instanceSchema>;

A decoded instanceSchema record, as returned by apply and inspect.

Backendtype alias

Section titled “Backend”
Signature
type Backend = Readonly<{
  release: Release;
  digest: Sha256Digest;
  backend: DurableBackend;
}>;

A resolved, verified durable backend: its Release, artifact digest and code.

AppInstanceErrorCodetype alias

Section titled “AppInstanceErrorCode”
Signature
type AppInstanceErrorCode = typeof appInstanceErrorCodeSchema.Type;

One of the bounded appInstanceErrorCodeSchema rejection codes.

BackendResolutiontype alias

Section titled “BackendResolution”
Signature
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

Section titled “Type Parameters”
Type Parameter
Host

InstancePortstype alias

Section titled “InstancePorts”
Signature
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>;
  boot: (
    backend,
    priorStateSchema,
    uiCheck,
  ) => Effect.Effect<UiBootCheckOutcome | null, Error>;
  abort: (reason) => 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

Section titled “Type Parameters”
Type Parameter
Host

AppBackendConnectiontype alias

Section titled “AppBackendConnection”
Signature
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.

AppInstancetype alias

Section titled “AppInstance”
Signature
type AppInstance<Host> = Readonly<{
  apply: (input) => Effect.Effect<Instance, Error>;
  prepare: (input) => Effect.Effect<UiBootCheckOutcome | null, 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

Section titled “Type Parameters”
Type Parameter
Host

InstanceIdtype alias

Section titled “InstanceId”
Signature
type InstanceId = CairnId<"app-instance", "instance">;

A stable App Instance ID minted by instanceIds.

agentAvatarSchemaconstant

Section titled “agentAvatarSchema”
Signature
const agentAvatarSchema: ZodObject<
  {
    v: ZodLiteral<1>;
    character: ZodEnum<{
      mushroom: "mushroom";
      cat: "cat";
      burger: "burger";
    }>;
    appearance: ZodRecord<
      ZodString,
      ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
    >;
    expression: ZodString;
    renderStyle: ZodEnum<{
      plain: "plain";
      pencil: "pencil";
      manga: "manga";
      riso: "riso";
      halftone: "halftone";
      blueprint: "blueprint";
      crt: "crt";
      watercolor: "watercolor";
    }>;
  },
  $strict
> = avatarSchema;

The catalog-valid avatar an owner may choose for an Agent.

agentAvatarProjectionSchemaconstant

Section titled “agentAvatarProjectionSchema”
Signature
const agentAvatarProjectionSchema: ZodDiscriminatedUnion<
  [
    ZodObject<
      {
        v: ZodLiteral<1>;
        character: ZodLiteral<"mushroom">;
        appearance: ZodObject<
          {
            [key: string]: ZodOptional<
              ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
            >;
          },
          $strict
        >;
        expression: ZodString;
        renderStyle: ZodEnum<{
          plain: "plain";
          pencil: "pencil";
          manga: "manga";
          riso: "riso";
          halftone: "halftone";
          blueprint: "blueprint";
          crt: "crt";
          watercolor: "watercolor";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        v: ZodLiteral<1>;
        character: ZodLiteral<"cat">;
        appearance: ZodObject<
          {
            [key: string]: ZodOptional<
              ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
            >;
          },
          $strict
        >;
        expression: ZodString;
        renderStyle: ZodEnum<{
          plain: "plain";
          pencil: "pencil";
          manga: "manga";
          riso: "riso";
          halftone: "halftone";
          blueprint: "blueprint";
          crt: "crt";
          watercolor: "watercolor";
        }>;
      },
      $strict
    >,
    ZodObject<
      {
        v: ZodLiteral<1>;
        character: ZodLiteral<"burger">;
        appearance: ZodObject<
          {
            [key: string]: ZodOptional<
              ZodUnion<readonly [ZodString, ZodNumber, ZodBoolean]>
            >;
          },
          $strict
        >;
        expression: ZodString;
        renderStyle: ZodEnum<{
          plain: "plain";
          pencil: "pencil";
          manga: "manga";
          riso: "riso";
          halftone: "halftone";
          blueprint: "blueprint";
          crt: "crt";
          watercolor: "watercolor";
        }>;
      },
      $strict
    >,
  ],
  "character"
>;

The avatar as a closed record, for contracts that refuse open maps (Hub projections): each character’s appearance names only its own controls, then the catalog refines it exactly as agentAvatarSchema does.

uiBootCheckOutcomeSchemaconstant

Section titled “uiBootCheckOutcomeSchema”
Signature
const uiBootCheckOutcomeSchema: ZodDiscriminatedUnion<[ZodObject<{
  kind: ZodLiteral<"passed">;
}, $strict>, ZodObject<{
  kind: ZodLiteral<"failed">;
  code: ZodLiteral<"ui_mount_failed">;
  diagnostics: ZodOptional<ZodObject<{
     failedPredicate: ZodEnum<{
        unexpected_candidate_request: "unexpected_candidate_request";
        response_status: "response_status";
        request_failed: "request_failed";
        page_error: "page_error";
        candidate_not_mounted: "candidate_not_mounted";
     }>;
     errorName: ZodOptional<ZodEnum<{
        TypeError: "TypeError";
        RangeError: "RangeError";
        SyntaxError: "SyntaxError";
        AbortError: "AbortError";
        TimeoutError: "TimeoutError";
        Other: "Other";
        Error: "Error";
     }>>;
     finalUrlPath: ZodString;
     consoleErrors: ZodArray<ZodPipe<ZodPipe<ZodString, ZodTransform<..., ...>>, ZodString>>;
     pageErrors: ZodArray<ZodPipe<ZodPipe<ZodString, ZodTransform<..., ...>>, ZodString>>;
     failedRequests: ZodArray<ZodObject<{
        path: ZodString;
        status: ZodOptional<...>;
        failureKind: ZodOptional<...>;
     }, $strict>>;
     droppedCount: ZodNumber;
  }, $strict>>;
}, $strict>, ZodObject<{
  kind: ZodLiteral<"not_checked">;
  code: ZodEnum<{
     boot_runner_unavailable: "boot_runner_unavailable";
     boot_browser_binding_missing: "boot_browser_binding_missing";
     boot_clone_unavailable: "boot_clone_unavailable";
     boot_timeout: "boot_timeout";
     boot_cleanup_failed: "boot_cleanup_failed";
     ui_check_not_run_on_host: "ui_check_not_run_on_host";
  }>;
}, $strict>], "kind">;

A UI check recorded on an installation operation, never installation authority.

ownerSchemaconstant

Section titled “ownerSchema”
Signature
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.

selectionSchemaconstant

Section titled “selectionSchema”
Signature
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.

ownerStateSchemaconstant

Section titled “ownerStateSchema”
Signature
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.

instanceSchemaconstant

Section titled “instanceSchema”
Signature
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.

appInstanceErrorCodeSchemaconstant

Section titled “appInstanceErrorCodeSchema”
Signature
const appInstanceErrorCodeSchema: Literals<
  readonly [
    "invalid_owner_state",
    "invalid_invocation_facts",
    "revoked",
    "disabled",
    "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",
    (
      | "backend_load_failed"
      | "backend_construction_failed"
      | "ui_mount_failed"
      | "boot_runner_unavailable"
      | "boot_browser_binding_missing"
      | "boot_clone_unavailable"
      | "boot_timeout"
      | "boot_cleanup_failed"
    ),
  ]
>;

The runtime owns the bounded rejection grammar, including across RPC.

instanceIdsconstant

Section titled “instanceIds”
Signature
const instanceIds: Readonly<{
  instance: IdCodec<"app-instance", "instance", 1>;
}>;

The Cairn ID family that mints and recognizes App Instance IDs (instance_…).

instanceIdSchemaconstant

Section titled “instanceIdSchema”
Signature
const instanceIdSchema: Schema.Codec<InstanceId, string>;

Decodes a string into an InstanceId, rejecting any other ID family.

avatarFromProjection()function

Section titled “avatarFromProjection()”
Signature
function avatarFromProjection(projected): object;

A projected avatar as the Avatar descriptor Sprite draws.

Parameters

Section titled “Parameters”
Parameter Type
projected | { v: 1; character: "mushroom"; appearance: Record<string, string | number | boolean | undefined>; expression: string; renderStyle: | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"; } | { v: 1; character: "cat"; appearance: Record<string, string | number | boolean | undefined>; expression: string; renderStyle: | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"; } | { v: 1; character: "burger"; appearance: Record<string, string | number | boolean | undefined>; expression: string; renderStyle: | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"; }

Returns

Section titled “Returns”

object

Name Type
v 1
character "mushroom" | "cat" | "burger"
appearance z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>
expression string
renderStyle | "plain" | "pencil" | "manga" | "riso" | "halftone" | "blueprint" | "crt" | "watercolor"

createAgentAvatarStore()function

Section titled “createAgentAvatarStore()”
Signature
function createAgentAvatarStore(sql): AgentAvatarStore;

Open the chosen-avatar table in the Agent directory’s own SQLite.

Parameters

Section titled “Parameters”
Parameter Type
sql Readonly<{ exec: (statement, …bindings) => WatchdogSqliteCursor; }>

Returns

Section titled “Returns”

AgentAvatarStore

selectionOf()function

Section titled “selectionOf()”
Signature
function selectionOf(installation): object;

The admitted selection for an installation’s Instance.

Parameters

Section titled “Parameters”
Parameter Type
installation Installation

Returns

Section titled “Returns”

object

Name Type Default value
instanceId InstanceId instanceIdSchema
owner object ownerSchema
owner.kind "installation" | "deployment" -
owner.id string Schema.NonEmptyString
appId AppId appIdSchema
releaseId ReleaseId releaseIdSchema
authorityVersion number -

createAppInstance()function

Section titled “createAppInstance()”
Signature
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

Section titled “Type Parameters”
Type Parameter
Host

Parameters

Section titled “Parameters”
Parameter Type
ports InstancePorts<Host>

Returns

Section titled “Returns”

AppInstance<Host>