background-replay

Import

Import

import * as api from "@fungi.computer/puffball/background-replay";

Exports

Kind	Export	Description
Ttype alias	BackgroundOrigin	Origin evidence, never a retained grant or credential.
Ttype alias	ClaimedJobAdmission	A claim either passes origin admission or refuses before binding effects.
Ttype alias	BackgroundBinding	Host-minted replay port; an App cannot declare this binding.
Ttype alias	BackgroundWake	A host wake cannot confer authority without fresh directory and method admission.
Ttype alias	BackgroundMember	A retained identity eligible for member-only replay.
Ttype alias	BackgroundSyncRefusal	One available App’s member-lane cleanup, delivered with zero binding grants.
Ttype alias	BackgroundRefusalCode	Closed, durable refusal reasons for the affected member lane.
Ttype alias	BackgroundAdmission	Existing method admission outcomes interpreted by the replay owner.
Ttype alias	BackgroundReplayPorts	Directory resolution and fresh continuation admission remain host-owned.
Ttype alias	BackgroundReplayDecision	A refused wake settles its lane; retry uses the existing Carrier backoff.
constconstant	backgroundOriginSchema	The caller’s single lightweight grammar for a host-sealed enqueue origin.
constconstant	claimedJobAdmissionSchema	The closed result of checking a claimed job’s origin in a fresh replay frame.
constconstant	backgroundWakeSchema	Identity and observed revisions only. Unknown fields, including bearer material, refuse.
constconstant	backgroundRefusalCodeSchema	The App can settle a refused lane without receiving any binding authority.
constconstant	backgroundSyncRefusalSchema	Cleanup payload for one refused member lane; contains no actor or authority.
fnfunction	backgroundOriginKey()	Derive a non-extractable host signing key; no secret is sent to an App.
fnfunction	sealBackgroundOrigin()	Seal only host-verified Instance, member lane and foreground method attribution.
fnfunction	admitClaimedOrigin()	Verify origin evidence against this frame’s fresh admission; guest input never throws.
fnfunction	actorLane()	A queue lane is an actor identity, never a credential or grant.
fnfunction	mayDefer()	Only ordinary member calls may enqueue background work; ancestry is host-held.
fnfunction	backgroundContext()	Host-only projection: replace incoming eligibility with the verified write’s sealed origin.
fnfunction	mayEnqueueBackground()	App-side eligibility reads only the host-attested context; it never invents ancestry.
fnfunction	readmitBackground()	Resolve then re-admit. Observed revisions are evidence, never equality pins.

BackgroundOriginTtype alias

Signature

type BackgroundOrigin = z.output<typeof backgroundOriginSchema>;

Origin evidence, never a retained grant or credential.

---

ClaimedJobAdmissionTtype alias

Signature

type ClaimedJobAdmission = z.output<typeof claimedJobAdmissionSchema>;

A claim either passes origin admission or refuses before binding effects.

---

BackgroundBindingTtype alias

Signature

type BackgroundBinding = Readonly<{
  admit: (origin) => Promise<ClaimedJobAdmission>;
}>;

Host-minted replay port; an App cannot declare this binding.

---

BackgroundWakeTtype alias

Signature

type BackgroundWake = z.output<typeof backgroundWakeSchema>;

A host wake cannot confer authority without fresh directory and method admission.

---

BackgroundMemberTtype alias

Signature

type BackgroundMember = BackgroundWake["actor"];

A retained identity eligible for member-only replay.

---

BackgroundSyncRefusalTtype alias

Signature

type BackgroundSyncRefusal = z.output<typeof backgroundSyncRefusalSchema>;

One available App’s member-lane cleanup, delivered with zero binding grants.

---

BackgroundRefusalCodeTtype alias

Signature

type BackgroundRefusalCode = z.output<typeof backgroundRefusalCodeSchema>;

Closed, durable refusal reasons for the affected member lane.

---

BackgroundAdmissionTtype alias

Signature

type BackgroundAdmission =
  | Readonly<{
      kind: "admitted";
      context: AppMethodCallContext;
    }>
  | Readonly<{
      kind: "refused";
      code:
        | "level_too_low"
        | "requires_not_granted"
        | "not_approved"
        | "denied"
        | "unavailable"
        | "stale_authority";
    }>;

Existing method admission outcomes interpreted by the replay owner.

---

BackgroundReplayPortsTtype alias

Signature

type BackgroundReplayPorts<Principal> = Readonly<{
  resolve: (actor) => Promise<Principal | null>;
  admit: (principal, wake) => Promise<BackgroundAdmission>;
}>;

Directory resolution and fresh continuation admission remain host-owned.

Type Parameters

Type Parameter
Principal

---

BackgroundReplayDecisionTtype alias

Signature

type BackgroundReplayDecision =
  | Readonly<{
      kind: "admitted";
      context: AppMethodCallContext;
    }>
  | Readonly<{
      kind: "refused";
      code: BackgroundRefusalCode;
    }>
  | Readonly<{
      kind: "retry";
    }>;

A refused wake settles its lane; retry uses the existing Carrier backoff.

backgroundOriginSchemaconstconstant

Signature

const backgroundOriginSchema: ZodMiniLazy<
  ZodMiniObject<
    {
      method: ZodMiniString<string>;
      seal: ZodMiniString<string>;
    },
    $strict
  >
> = appMethodCallerSchema.shape.backgroundOrigin.def.innerType;

The caller’s single lightweight grammar for a host-sealed enqueue origin.

---

claimedJobAdmissionSchemaconstconstant

Signature

const claimedJobAdmissionSchema: ZodLazy<
  ZodUnion<
    readonly [
      ZodObject<
        {
          kind: ZodLiteral<"admitted">;
        },
        $strict
      >,
      ZodObject<
        {
          kind: ZodLiteral<"refused">;
          code: ZodLiteral<"access_changed">;
        },
        $strict
      >,
    ]
  >
>;

The closed result of checking a claimed job’s origin in a fresh replay frame.

---

backgroundWakeSchemaconstconstant

Signature

const backgroundWakeSchema: ZodLazy<
  ZodObject<
    {
      installationId: ZodString;
      actor: ZodObject<
        {
          kind: ZodMiniLiteral<"member">;
          memberId: ZodMiniString<string>;
        },
        $strict
      >;
      lane: ZodString;
      originMethod: ZodString;
      observed: ZodObject<
        {
          authorityVersion: ZodLazy<ZodNumber>;
          artifactDigest: ZodCustom<Sha256Digest, Sha256Digest>;
          membershipVersion: ZodOptional<ZodLazy<ZodNumber>>;
        },
        $strict
      >;
      epoch: ZodLazy<ZodNumber>;
    },
    $strict
  >
>;

Identity and observed revisions only. Unknown fields, including bearer material, refuse.

---

backgroundRefusalCodeSchemaconstconstant

Signature

const backgroundRefusalCodeSchema: ZodEnum<{
  access_changed: "access_changed";
  installation_unavailable: "installation_unavailable";
}>;

The App can settle a refused lane without receiving any binding authority.

---

backgroundSyncRefusalSchemaconstconstant

Signature

const backgroundSyncRefusalSchema: ZodObject<
  {
    lane: ZodString;
    code: ZodEnum<{
      access_changed: "access_changed";
      installation_unavailable: "installation_unavailable";
    }>;
  },
  $strict
>;

Cleanup payload for one refused member lane; contains no actor or authority.

backgroundOriginKey()fnfunction

Signature

function backgroundOriginKey(secret): Promise<CryptoKey>;

Derive a non-extractable host signing key; no secret is sent to an App.

Parameters

Parameter	Type
secret	string

Returns

Promise<CryptoKey>

---

sealBackgroundOrigin()fnfunction

Signature

function sealBackgroundOrigin(
  key,
  claims,
): Promise<{
  method: string;
  seal: string;
}>;

Seal only host-verified Instance, member lane and foreground method attribution.

Parameters

Parameter	Type
key	CryptoKey
claims	Readonly<{ instanceId: string; lane: string; method: string; }>

Returns

Promise<{ method: string; seal: string; }>

---

admitClaimedOrigin()fnfunction

Signature

function admitClaimedOrigin(
  key,
  frame,
  raw,
): Promise<
  | {
      kind: "admitted";
    }
  | {
      kind: "refused";
      code: "access_changed";
    }
>;

Verify origin evidence against this frame’s fresh admission; guest input never throws.

Parameters

Parameter	Type
key	CryptoKey
frame	Readonly<{ instanceId: string; lane: string; admitted: readonly string[]; }>
raw	unknown

Returns

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

---

actorLane()fnfunction

Signature

function actorLane(actor): string;

A queue lane is an actor identity, never a credential or grant.

Parameters

Parameter	Type
actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }

Returns

string

---

mayDefer()fnfunction

Signature

function mayDefer(context, ancestry): boolean;

Only ordinary member calls may enqueue background work; ancestry is host-held.

Parameters

Parameter	Type	Description
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; }	-
context.computerId	string | null	-
context.actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	-
context.backgroundLane?	string	Host-attested enqueue eligibility for this ordinary write; absent otherwise.
context.backgroundOrigin?	{ method: string; seal: string; }	Host-sealed foreground method for durable jobs; paired with backgroundLane.
context.backgroundOrigin.method	string	-
context.backgroundOrigin.seal	string	-
context.role?	"member" | "owner"	Team role attested by the host, never selected by App method input.
context.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.
context.workflow?	{ workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }	Present only on a Workflow node invocation admitted by its host.
context.workflow.workflowId	string	Published Workflow selected by the run owner.
context.workflow.runId	string	Run identity held by the run owner.
context.workflow.nodeId	string	Node selected by the stored published Workflow.
context.workflow.armedBy	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	Actor that armed the run, re-admitted by the host at dispatch.
context.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.
ancestry	readonly string[]	-

Returns

boolean

---

backgroundContext()fnfunction

Signature

function backgroundContext(context, ancestry, method, origin): object;

Host-only projection: replace incoming eligibility with the verified write’s sealed origin.

Parameters

Parameter	Type	Description
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; }	-
context.computerId	string | null	-
context.actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	-
context.backgroundLane?	string	Host-attested enqueue eligibility for this ordinary write; absent otherwise.
context.backgroundOrigin?	{ method: string; seal: string; }	Host-sealed foreground method for durable jobs; paired with backgroundLane.
context.backgroundOrigin.method	string	-
context.backgroundOrigin.seal	string	-
context.role?	"member" | "owner"	Team role attested by the host, never selected by App method input.
context.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.
context.workflow?	{ workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }	Present only on a Workflow node invocation admitted by its host.
context.workflow.workflowId	string	Published Workflow selected by the run owner.
context.workflow.runId	string	Run identity held by the run owner.
context.workflow.nodeId	string	Node selected by the stored published Workflow.
context.workflow.armedBy	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	Actor that armed the run, re-admitted by the host at dispatch.
context.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.
ancestry	readonly string[]	-
method	Readonly<{ name: string; effect: AppApi["methods"][string]["effect"]; }>	-
origin	| { method: string; seal: string; } | undefined	-

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.

---

mayEnqueueBackground()fnfunction

Signature

function mayEnqueueBackground(context): boolean;

App-side eligibility reads only the host-attested context; it never invents ancestry.

Parameters

Parameter	Type	Description
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; }	-
context.computerId	string | null	-
context.actor	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	-
context.backgroundLane?	string	Host-attested enqueue eligibility for this ordinary write; absent otherwise.
context.backgroundOrigin?	{ method: string; seal: string; }	Host-sealed foreground method for durable jobs; paired with backgroundLane.
context.backgroundOrigin.method	string	-
context.backgroundOrigin.seal	string	-
context.role?	"member" | "owner"	Team role attested by the host, never selected by App method input.
context.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.
context.workflow?	{ workflowId: string; runId: string; nodeId: string; armedBy: | { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }; }	Present only on a Workflow node invocation admitted by its host.
context.workflow.workflowId	string	Published Workflow selected by the run owner.
context.workflow.runId	string	Run identity held by the run owner.
context.workflow.nodeId	string	Node selected by the stored published Workflow.
context.workflow.armedBy	| { kind: "member"; memberId: string; } | { kind: "agent"; agentId: string; } | { kind: "team-key"; keyId: string; }	Actor that armed the run, re-admitted by the host at dispatch.
context.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.

Returns

boolean

---

readmitBackground()fnfunction

Signature

function readmitBackground<Principal>(
  input,
  ports,
): Promise<BackgroundReplayDecision>;

Resolve then re-admit. Observed revisions are evidence, never equality pins.

Type Parameters

Type Parameter
Principal

Parameters

Parameter	Type
input	unknown
ports	BackgroundReplayPorts<Principal>

Returns

Promise<BackgroundReplayDecision>

References

backgroundSyncAllowed

Re-exports backgroundSyncAllowed