Skip to content
Oyster0.6.0
API reference

invocation

Import

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

Exports

Section titled “Exports”
Kind Export Description
type alias InvocationFacts The immutable authority and attribution supplied at host admission.
type alias InvocationMethod Method name/effect taken from a verified API; raw backend requests have no method.
type alias InvocationAgentPolicy Captured policy identity; the Agent id remains on the canonical call actor.
type alias InvocationFrame A live frame stays inside its Instance; host state and signals never cross RPC.
type alias BackgroundFrameState One mutable origin latch on the host state of one invocation, never shared across frames.
type alias InvocationGatePorts The host’s native guest-abort and authority-close hooks.
type alias InvocationGate One invocation owner shared by Hub shards and standalone Instances.
type alias InvocationAuthority Verified selection, artifact and binding grants before caller attribution.
type alias InvocationDeadline The host supplies both deadlines; the frame cannot outlive either.
constant APP_INVOCATION_CEILING_MS One App invocation may hold authority for at most the Hub grant’s lifetime.
constant invocationFactsSchema Host-admitted facts; shape decoding does not establish host authority.
constant invocationFrameIdSchema Decode only identities minted from the invocation-frame ID family.
constant invocationFacts Shared host-held caller/Workflow fact builders, never guest argument decoders.
function assertBackgroundBinding() Block replay capability effects before job-origin admission; storage permits claiming/settling.
function admitBackgroundFrame() Consume this frame’s one origin check before awaiting verification, then retain only its decision.
function createInvocationGate() Admit frames against one guest. Verified foreground reads share it, up to eight at once; writes, raw backend requests, Gills and replay run alone. Every guest binding packet names its frame, so a finished frame’s leftover timers cannot borrow a later frame’s authority and a normal finish keeps the guest warm. Closing authority early (revocation, expiry, a write preempting replay) aborts the guest and so every frame sharing it; replay only yields to a verified write.
function invocationCallerContext() Project an admitted principal into App attribution; only the host chooses the fixed Computer context. The App caller grammar has no visitor actor, so the anonymous public reader is attributed as the reserved visitor key without a Computer. Host admission reads the principal, never this projection.
function invocationAuthorityOf() Authority comes from the admitted installation and its verified backend bytes.
function admittedCallerFacts() Mint standalone facts only after host caller and Release admission.
function admittedMethodCallerFacts() Seal the host-verified named method after its current admission checks.

InvocationFactstype alias

Section titled “InvocationFacts”
Signature
type InvocationFacts = typeof invocationFactsSchema.Type;

The immutable authority and attribution supplied at host admission.

InvocationMethodtype alias

Section titled “InvocationMethod”
Signature
type InvocationMethod = NonNullable<
  Extract<
    InvocationFacts["subject"],
    {
      kind: "call";
    }
  >["method"]
>;

Method name/effect taken from a verified API; raw backend requests have no method.

InvocationAgentPolicytype alias

Section titled “InvocationAgentPolicy”
Signature
type InvocationAgentPolicy = NonNullable<
  Extract<
    InvocationFacts["subject"],
    {
      kind: "call";
    }
  >["agentPolicy"]
>;

Captured policy identity; the Agent id remains on the canonical call actor.

InvocationFrametype alias

Section titled “InvocationFrame”
Signature
type InvocationFrame<Host> = Readonly<{
  frameId: string;
  facts: InvocationFacts;
  host: Host;
  signal: AbortSignal;
}>;

A live frame stays inside its Instance; host state and signals never cross RPC.

Type Parameters

Section titled “Type Parameters”
Type Parameter Default type
Host unknown

BackgroundFrameStatetype alias

Section titled “BackgroundFrameState”
Signature
type BackgroundFrameState = object;

One mutable origin latch on the host state of one invocation, never shared across frames.

Properties

Section titled “Properties”

origin

Section titled “origin”
Signature
origin: "unchecked" | "admitted" | "refused";

This frame’s one claimed-origin decision; never carried into another frame.

InvocationGatePortstype alias

Section titled “InvocationGatePorts”
Signature
type InvocationGatePorts<Host> = Readonly<{
  abortGuest: () => Promise<void>;
  close: (frame) => Promise<void>;
  now?: () => number;
}>;

The host’s native guest-abort and authority-close hooks.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Host

InvocationGatetype alias

Section titled “InvocationGate”
Signature
type InvocationGate<Host> = Readonly<{
  run: <A>(facts, host, work) => Promise<A>;
  active: (frameId) => InvocationFrame<Host>;
  revoke: (reason?, target?) => Promise<void>;
  exclusive: <A>(work) => Promise<A>;
}>;

One invocation owner shared by Hub shards and standalone Instances.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Host

InvocationAuthoritytype alias

Section titled “InvocationAuthority”
Signature
type InvocationAuthority = Omit<InvocationFacts, "subject" | "deadlineAt">;

Verified selection, artifact and binding grants before caller attribution.

InvocationDeadlinetype alias

Section titled “InvocationDeadline”
Signature
type InvocationDeadline = Readonly<{
  deadlineAt: number;
  grantExpiresAt: number;
}>;

The host supplies both deadlines; the frame cannot outlive either.

APP_INVOCATION_CEILING_MSconstant

Section titled “APP_INVOCATION_CEILING_MS”
Signature
const APP_INVOCATION_CEILING_MS: 60000 = 60_000;

One App invocation may hold authority for at most the Hub grant’s lifetime.

invocationFactsSchemaconstant

Section titled “invocationFactsSchema”
Signature
const invocationFactsSchema: Struct<{
  instanceId: Codec<InstanceId, string, never, never>;
  selection: 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;
  }>;
  artifactDigest: refine<Sha256Digest, String>;
  subject: Union<readonly [Struct<{
     kind: Literal<"call">;
     context: 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: ... | ... | ...;
        };
        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: ... | ... | ...;
        };
        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: ... | ... | ...;
        };
        idempotencyKey?: string;
     }>;
     sessionId: optionalKey<String>;
     agentPolicy: optionalKey<Struct<{
        policyRevision: NonEmptyString;
        grantorMemberId: NonEmptyString;
     }>>;
     method: optionalKey<Struct<{
        name: String;
        effect: Literals<readonly [..., ..., ...]>;
     }>>;
     replay: optionalKey<Struct<{
        lane: NonEmptyString;
        epoch: Number;
        admitted: $Array<String>;
     }>>;
   }>, Struct<{
     kind: Literal<"lifecycle">;
     name: Literal<"onGitPush">;
     eventId: NonEmptyString;
   }>, Struct<{
     kind: Literal<"lifecycle">;
     name: Literal<"syncRefused">;
     lane: String;
     code: Literals<("access_changed" | "installation_unavailable")[]>;
  }>]>;
  grants: $Array<Struct<{
     binding: refine<
        | "BACKGROUND"
        | "GIT"
        | "EVENTS"
        | "APPS"
        | "WORKFLOWS"
        | "APP_STORAGE"
        | "MEDIA"
        | "COMPUTER"
        | "INBOX"
       | "AGENTS", String>;
     operations: $Array<NonEmptyString>;
  }>>;
  deadlineAt: Number;
  ancestry: $Array<Codec<InstanceId, string, never, never>>;
}>;

Host-admitted facts; shape decoding does not establish host authority.

invocationFrameIdSchemaconstant

Section titled “invocationFrameIdSchema”
Signature
const invocationFrameIdSchema: String;

Decode only identities minted from the invocation-frame ID family.

invocationFactsconstant

Section titled “invocationFacts”
Signature
const invocationFacts: object;

Shared host-held caller/Workflow fact builders, never guest argument decoders.

Type Declaration

Section titled “Type Declaration”
Name Type Description
fromCaller() (authority, context, deadline, method?, sessionId?, agentPolicy?) => object Combine host-admitted caller facts with the invocation and grant deadlines.
fromWorkflowNode() (authority, input, deadline) => object Attribute an already host-admitted published node to its retained arming actor.

assertBackgroundBinding()function

Section titled “assertBackgroundBinding()”
Signature
function assertBackgroundBinding(frame, binding): void;

Block replay capability effects before job-origin admission; storage permits claiming/settling.

Parameters

Section titled “Parameters”
Parameter Type
frame InvocationFrame<BackgroundFrameState>
binding | "BACKGROUND" | "GIT" | "EVENTS" | "APPS" | "WORKFLOWS" | "APP_STORAGE" | "MEDIA" | "COMPUTER" | "INBOX" | "AGENTS"

Returns

Section titled “Returns”

void

admitBackgroundFrame()function

Section titled “admitBackgroundFrame()”
Signature
function admitBackgroundFrame(
  key,
  frame,
  raw,
): Promise<
  | {
      kind: "admitted";
    }
  | {
      kind: "refused";
      code: "access_changed";
    }
>;

Consume this frame’s one origin check before awaiting verification, then retain only its decision.

Parameters

Section titled “Parameters”
Parameter Type
key CryptoKey
frame InvocationFrame<BackgroundFrameState>
raw unknown

Returns

Section titled “Returns”

Promise< | { kind: "admitted"; } | { kind: "refused"; code: "access_changed"; }>

createInvocationGate()function

Section titled “createInvocationGate()”
Signature
function createInvocationGate<Host>(ports): InvocationGate<Host>;

Admit frames against one guest. Verified foreground reads share it, up to eight at once; writes, raw backend requests, Gills and replay run alone. Every guest binding packet names its frame, so a finished frame’s leftover timers cannot borrow a later frame’s authority and a normal finish keeps the guest warm. Closing authority early (revocation, expiry, a write preempting replay) aborts the guest and so every frame sharing it; replay only yields to a verified write.

Type Parameters

Section titled “Type Parameters”
Type Parameter
Host

Parameters

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

Returns

Section titled “Returns”

InvocationGate<Host>

invocationCallerContext()function

Section titled “invocationCallerContext()”
Signature
function invocationCallerContext(principal, computerId): object;

Project an admitted principal into App attribution; only the host chooses the fixed Computer context. The App caller grammar has no visitor actor, so the anonymous public reader is attributed as the reserved visitor key without a Computer. Host admission reads the principal, never this projection.

Parameters

Section titled “Parameters”
Parameter Type
principal OysterPrincipal
computerId string | null

Returns

Section titled “Returns”

object

Name Type
computerId string | null
actor | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
backgroundLane? string
backgroundOrigin? object
backgroundOrigin.method string
backgroundOrigin.seal string
role? "member" | "owner"
soleMember? true
workflow? object
workflow.workflowId string
workflow.runId string
workflow.nodeId string
workflow.armedBy | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }
idempotencyKey? string

invocationAuthorityOf()function

Section titled “invocationAuthorityOf()”
Signature
function invocationAuthorityOf(
  installation,
  release,
  ancestry?,
): InvocationAuthority;

Authority comes from the admitted installation and its verified backend bytes.

Parameters

Section titled “Parameters”
Parameter Type Default value
installation Installation undefined
release VerifiedRelease undefined
ancestry readonly InstanceId[] []

Returns

Section titled “Returns”

InvocationAuthority

admittedCallerFacts()function

Section titled “admittedCallerFacts()”
Signature
function admittedCallerFacts(
  installation,
  release,
  context,
  grants,
  ancestry?,
  sessionId?,
  agentPolicy?,
  method?,
  origin?,
): object;

Mint standalone facts only after host caller and Release admission.

Parameters

Section titled “Parameters”
Parameter Type Default value
installation Installation undefined
release VerifiedRelease undefined
context { 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; } undefined
context.computerId string | null undefined
context.actor | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } undefined
context.backgroundLane? string undefined
context.backgroundOrigin? { method: string; seal: string; } undefined
context.backgroundOrigin.method? string undefined
context.backgroundOrigin.seal? string undefined
context.role? "member" | "owner" undefined
context.soleMember? true undefined
context.workflow? { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; } undefined
context.workflow.workflowId? string undefined
context.workflow.runId? string undefined
context.workflow.nodeId? string undefined
context.workflow.armedBy? | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } undefined
context.idempotencyKey? string undefined
grants? readonly object[] undefined
ancestry? readonly InstanceId[] []
sessionId? string undefined
agentPolicy? { policyRevision: string; grantorMemberId: string; } undefined
agentPolicy.policyRevision? string appToolPolicySchema.fields.revision
agentPolicy.grantorMemberId? string appToolPolicySchema.fields.grantedBy
method? { name: string; effect: "read" | "write" | "external"; } undefined
method.name? string appApiMethodNameSchema
method.effect? "read" | "write" | "external" ...
origin? { method: string; seal: string; } undefined
origin.method? string undefined
origin.seal? string undefined

Returns

Section titled “Returns”

object

Name Type Default value
instanceId InstanceId instanceIdSchema
selection object selectionSchema
selection.instanceId InstanceId instanceIdSchema
selection.owner object ownerSchema
selection.owner.kind "installation" | "deployment" -
selection.owner.id string Schema.NonEmptyString
selection.appId AppId appIdSchema
selection.releaseId ReleaseId releaseIdSchema
selection.authorityVersion number -
artifactDigest Sha256Digest sha256DigestSchema
subject | { kind: "call"; context: { 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; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; } -
grants readonly object[] grantsSchema
deadlineAt number -
ancestry readonly InstanceId[] -

admittedMethodCallerFacts()function

Section titled “admittedMethodCallerFacts()”
Signature
function admittedMethodCallerFacts(
  host,
  installation,
  release,
  context,
  grants,
  method,
  ancestry?,
  sessionId?,
  agentPolicy?,
): Promise<{
  instanceId: InstanceId;
  selection: {
    instanceId: InstanceId;
    owner: {
      kind: "installation" | "deployment";
      id: string;
    };
    appId: AppId;
    releaseId: ReleaseId;
    authorityVersion: number;
  };
  artifactDigest: Sha256Digest;
  subject:
    | {
        kind: "call";
        context: {
          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;
        };
        sessionId?: string;
        agentPolicy?: {
          policyRevision: string;
          grantorMemberId: string;
        };
        method?: {
          name: string;
          effect: "read" | "write" | "external";
        };
        replay?: {
          lane: string;
          epoch: number;
          admitted: readonly string[];
        };
      }
    | {
        kind: "lifecycle";
        name: "onGitPush";
        eventId: string;
      }
    | {
        kind: "lifecycle";
        name: "syncRefused";
        lane: string;
        code: "access_changed" | "installation_unavailable";
      };
  grants: readonly object[];
  deadlineAt: number;
  ancestry: readonly InstanceId[];
}>;

Seal the host-verified named method after its current admission checks.

Parameters

Section titled “Parameters”
Parameter Type Default value
host Pick<OysterHost, "backgroundOriginKey"> undefined
installation Installation undefined
release VerifiedRelease undefined
context { 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; } undefined
context.computerId string | null undefined
context.actor | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } undefined
context.backgroundLane? string undefined
context.backgroundOrigin? { method: string; seal: string; } undefined
context.backgroundOrigin.method? string undefined
context.backgroundOrigin.seal? string undefined
context.role? "member" | "owner" undefined
context.soleMember? true undefined
context.workflow? { workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; } undefined
context.workflow.workflowId? string undefined
context.workflow.runId? string undefined
context.workflow.nodeId? string undefined
context.workflow.armedBy? | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; } undefined
context.idempotencyKey? string undefined
grants? readonly object[] undefined
method? { name: string; effect: "read" | "write" | "external"; } undefined
method.name? string appApiMethodNameSchema
method.effect? "read" | "write" | "external" ...
ancestry? readonly InstanceId[] []
sessionId? string undefined
agentPolicy? { policyRevision: string; grantorMemberId: string; } undefined
agentPolicy.policyRevision? string appToolPolicySchema.fields.revision
agentPolicy.grantorMemberId? string appToolPolicySchema.fields.grantedBy

Returns

Section titled “Returns”

Promise<{ instanceId: InstanceId; selection: { instanceId: InstanceId; owner: { kind: "installation" | "deployment"; id: string; }; appId: AppId; releaseId: ReleaseId; authorityVersion: number; }; artifactDigest: Sha256Digest; subject: | { kind: "call"; context: { 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; }; sessionId?: string; agentPolicy?: { policyRevision: string; grantorMemberId: string; }; method?: { name: string; effect: "read" | "write" | "external"; }; replay?: { lane: string; epoch: number; admitted: readonly string[]; }; } | { kind: "lifecycle"; name: "onGitPush"; eventId: string; } | { kind: "lifecycle"; name: "syncRefused"; lane: string; code: "access_changed" | "installation_unavailable"; }; grants: readonly object[]; deadlineAt: number; ancestry: readonly InstanceId[]; }>