@fungi.computer/oyster 0.32.0 → 0.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +59 -0
  2. package/dist/app-sandbox.d.ts +2 -2
  3. package/dist/app-sandbox.js +2 -2
  4. package/dist/app-test-copies.d.ts +87 -0
  5. package/dist/app-test-copies.js +170 -0
  6. package/dist/app-test-copy-page.d.ts +4 -0
  7. package/dist/app-test-copy-page.js +89 -0
  8. package/dist/approval-deadline.d.ts +2 -0
  9. package/dist/approval-deadline.js +7 -0
  10. package/dist/approval-home.d.ts +26 -3
  11. package/dist/approval-home.js +148 -18
  12. package/dist/apps/index.d.ts +1 -1
  13. package/dist/apps/index.js +1 -1
  14. package/dist/browser/operations.d.ts +1 -1
  15. package/dist/cloudflare.d.ts +68 -3
  16. package/dist/cloudflare.js +214 -3
  17. package/dist/embed-metafiles.js +2 -2
  18. package/dist/embed-scripts.js +1 -1
  19. package/dist/host.d.ts +20 -4
  20. package/dist/host.js +314 -3
  21. package/dist/installation-operations.d.ts +247 -8
  22. package/dist/installation-operations.js +145 -7
  23. package/dist/installation-recovery-page.d.ts +24 -0
  24. package/dist/installation-recovery-page.js +168 -0
  25. package/dist/mcp.js +42 -13
  26. package/dist/older-oyster-store.d.ts +1 -1
  27. package/dist/older-oyster-store.js +2 -4
  28. package/dist/page/app-permissions.js +8 -7
  29. package/dist/page/computer-handles.d.ts +0 -1
  30. package/dist/page/mount.d.ts +2 -101
  31. package/dist/page/mount.js +1 -22
  32. package/dist/page-config.d.ts +102 -0
  33. package/dist/page-config.js +24 -0
  34. package/dist/page-script.js +2 -2
  35. package/dist/platform-skills.generated.d.ts +5 -2
  36. package/dist/platform-skills.generated.js +6 -2
  37. package/dist/recovery-style.d.ts +5 -0
  38. package/dist/recovery-style.js +32 -0
  39. package/dist/standalone/agents.d.ts +1 -1
  40. package/dist/standalone/agents.js +43 -7
  41. package/dist/standalone/computer-fleet.js +3 -0
  42. package/dist/standalone/computer.d.ts +6 -2
  43. package/dist/standalone/computer.js +27 -14
  44. package/dist/standalone/media.js +7 -2
  45. package/dist/standalone/preview.d.ts +21 -20
  46. package/dist/standalone/preview.js +147 -151
  47. package/dist/standalone/registry.d.ts +14 -21
  48. package/dist/standalone/registry.js +74 -28
  49. package/dist/standalone/worker.js +6 -3
  50. package/dist/starter-agent.d.ts +6 -2
  51. package/dist/starter-agent.js +25 -4
  52. package/dist/upgrade/old-worker-http.d.ts +2 -0
  53. package/dist/upgrade/old-worker-http.js +22 -0
  54. package/dist/upgrade/old-worker-readonly.d.ts +14 -0
  55. package/dist/upgrade/old-worker-readonly.js +22 -0
  56. package/dist/upgrade/old-worker-sql.d.ts +10 -0
  57. package/dist/upgrade/old-worker-sql.js +68 -0
  58. package/dist/upgrade/old-worker-stream.d.ts +12 -0
  59. package/dist/upgrade/old-worker-stream.js +54 -0
  60. package/dist/upgrade/private-stage.d.ts +23 -0
  61. package/dist/upgrade/private-stage.js +109 -0
  62. package/dist/upgrade/standalone-001.d.ts +16 -0
  63. package/dist/upgrade/standalone-001.js +31 -0
  64. package/dist/upgrade/standalone-01.d.ts +37 -0
  65. package/dist/upgrade/standalone-01.js +55 -0
  66. package/dist/upgrade/standalone-02.d.ts +37 -0
  67. package/dist/upgrade/standalone-02.js +55 -0
  68. package/dist/workers.d.ts +45 -14
  69. package/dist/workers.js +198 -21
  70. package/docs/api/README.md +8 -3
  71. package/docs/api/apps.md +21 -0
  72. package/docs/api/cloudflare.md +57 -0
  73. package/docs/api/host.md +263 -25
  74. package/docs/api/page/mount.md +13 -81
  75. package/docs/api/workers-git.md +246 -1
  76. package/docs/api/workers.md +518 -95
  77. package/package.json +38 -24
package/dist/workers.d.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import type { ApprovalListInput, ApprovalAnswerInput, AutoApproveInput } from "@fungi.computer/approvals";
2
- import type { HostActor } from "@fungi.computer/puffball/app";
2
+ import type { HostActor, AppMethodCallContext } from "@fungi.computer/puffball/app";
3
3
  import { type OysterApprovalCall } from "./approval-home.js";
4
4
  import { type BootCapabilityGrant, type BootCapabilityLease } from "./boot-capability.js";
5
5
  import { type Installation } from "./apps/installation.js";
6
+ import { type UiBootCheckOutcome } from "./boot-gate.js";
6
7
  import { type BrowserBinding } from "./browser/sessions.js";
7
8
  import { type InstallationOperationRequest, type InstallationOperationReply } from "./installation-operations.js";
8
9
  import { installationWorkerEntrypoint } from "./installation-execution.js";
@@ -19,9 +20,10 @@ import { r2FileSource } from "./r2-files.js";
19
20
  import { type FileSource } from "./files.js";
20
21
  import { DurableObject, type WorkerEntrypoint } from "cloudflare:workers";
21
22
  import * as Schema from "effect/Schema";
22
- import type { Release } from "@fungi.computer/puffball";
23
+ import { type Release } from "@fungi.computer/puffball";
23
24
  import { type Backend, type Instance, type OwnerState } from "./index.js";
24
25
  import { r2ArtifactStore, type FrameBindingReply, type FrameBindingMethod, type FrameBindingProps } from "./cloudflare.js";
26
+ import type { AppTestCopy, AppTestCopyAuthority } from "./app-test-copies.js";
25
27
  import { type BackgroundFrameState, type InvocationFacts, type InvocationFrame } from "./invocation.js";
26
28
  import { type InstallationCommit, type InstanceResult, type OysterAuth, type OysterHost, type OysterJson } from "./host.js";
27
29
  import { type AppStorageResult, type AppStorageWrite, type AppStorageReset, type ResolvedAppStorage } from "@fungi.computer/agar/storage";
@@ -77,7 +79,7 @@ export type OysterWorkerEnv = Readonly<{
77
79
  /** Worker Loader that runs App backends. */
78
80
  LOADER: WorkerLoader;
79
81
  }>;
80
- /** The installation registry: one SQLite-backed Durable Object per Oyster. */
82
+ /** Installation metadata and UI verdicts in one SQLite-backed Durable Object per tenant. */
81
83
  export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEnv> extends DurableObject<Env> {
82
84
  #private;
83
85
  /** The plain root has the same single owner-key host as OysterInstance. */
@@ -86,17 +88,14 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
86
88
  approvalSubmit(pin: Readonly<{
87
89
  tenantId: string;
88
90
  origin: string;
89
- }>, call: OysterApprovalCall): Promise<{
90
- readonly kind: "pending_approval";
91
- readonly recordId: string;
92
- readonly description: {
93
- readonly title: string;
94
- readonly inputBytes: number;
95
- readonly inputSha256: string;
96
- };
97
- } | import("@fungi.computer/approvals").ApprovalApplyResult>;
91
+ }>, call: OysterApprovalCall): Promise<import("./approval-home.js").OysterApprovalResult>;
92
+ /** Cancellation has the same trusted host identity as submission, never App input. */
93
+ approvalCancel(pin: Readonly<{
94
+ tenantId: string;
95
+ origin: string;
96
+ }>, call: OysterApprovalCall): Promise<void>;
98
97
  private approvalHome;
99
- /** Recover approved work from the durable home, not a last-request memory pin. */
98
+ /** Expire approvals; no alarm may dispatch a waiting call's App write. */
100
99
  private approvalAlarm;
101
100
  /** Read a bounded page for the current member of the pinned native home. */
102
101
  approvalList(pin: Readonly<{
@@ -122,6 +121,10 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
122
121
  readonly title: string;
123
122
  readonly inputBytes: number;
124
123
  readonly inputSha256: string;
124
+ readonly app?: {
125
+ readonly displayName: string;
126
+ readonly operationLabel: string;
127
+ } | undefined;
125
128
  };
126
129
  readonly by: {
127
130
  readonly kind: "human";
@@ -133,8 +136,8 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
133
136
  readonly state: "pending" | "expired" | "denied" | "applied" | "requested" | "approved" | "claimed" | "outcome_unknown";
134
137
  readonly updatedAt: number;
135
138
  readonly module: string;
136
- readonly recordId: string;
137
139
  readonly authorityFence: string;
140
+ readonly recordId: string;
138
141
  readonly requester: {
139
142
  readonly principalId: string;
140
143
  readonly agentId: string | null;
@@ -233,6 +236,21 @@ export declare class OysterRegistry<Env extends OysterWorkerEnv = OysterWorkerEn
233
236
  compareAndPut(installation: Installation, expectedAuthorityVersion: number, expectedGeneration: string, tenantId?: TenantId): Promise<InstallationCommit>;
234
237
  private writeInstallation;
235
238
  private decode;
239
+ /** Trusted host verdicts, local to this tenant, origin, Release and check version. */
240
+ bootUiResult(input: Readonly<{
241
+ tenantId: string;
242
+ origin: string;
243
+ releaseId: string;
244
+ artifactDigest: string;
245
+ checkVersion: string;
246
+ }> & (Readonly<{
247
+ kind: "read";
248
+ }> | Readonly<{
249
+ kind: "record";
250
+ outcome: Exclude<UiBootCheckOutcome, {
251
+ kind: "not_checked";
252
+ }>;
253
+ }>)): UiBootCheckOutcome | null;
236
254
  /** Issue, resolve, or revoke one bounded capability without storing its token. */
237
255
  bootCapability(input: Readonly<{
238
256
  kind: "issue";
@@ -377,10 +395,23 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
377
395
  private runtime;
378
396
  private limits;
379
397
  private readonly frames;
398
+ private readonly testCopies;
380
399
  /** Content-addressed backends are verified once per Instance, not per call. */
381
400
  private readonly backends;
382
401
  private readonly gitJournal;
383
402
  constructor(ctx: DurableObjectState, env: Env);
403
+ /** Every wake owner shares the native alarm; none may postpone another. */
404
+ private scheduleWake;
405
+ /** Open only under the existing Instance serialization and pinned tenant. */
406
+ openTestCopy(authority: AppTestCopyAuthority, requestId: string, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy>>;
407
+ /** Observation rechecks both applied selection and current registry incarnation. */
408
+ inspectTestCopy(authority: AppTestCopyAuthority, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy | null>>;
409
+ /** A delayed discard cannot target a later sibling. */
410
+ discardTestCopy(authority: AppTestCopyAuthority, copyId: string, tenantId?: TenantId): Promise<InstanceResult<boolean>>;
411
+ /** Uses the ordinary invocation facade, without live bindings or host context. */
412
+ testCopyBackend(authority: AppTestCopyAuthority, copyId: string, request: Request, limits?: GuestLimits, tenantId?: TenantId): Promise<Response>;
413
+ /** Declared methods share copy isolation, never a live invocation frame or binding env. */
414
+ callTestCopy(authority: AppTestCopyAuthority, copyId: string, name: string, input: Schema.Json, caller: AppMethodCallContext, limits?: GuestLimits, tenantId?: TenantId): Promise<InstanceResult<unknown>>;
384
415
  /** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
385
416
  protected hostFor(scope: TenantScope): Promise<OysterHost>;
386
417
  /** Reconstruct current host admission for each wake; non-default tenants get no wakes. */
package/dist/workers.js CHANGED
@@ -6,8 +6,8 @@ import { z } from "zod";
6
6
  import { bootCapabilityGrantSchema, bootCapabilityLeaseSchema, reportBootPage, validateCapabilityAssetSet, } from "./boot-capability.js";
7
7
  import { serveBootCapability } from "./boot-capability-route.js";
8
8
  import { installationSchema, isCommittedInstallation, } from "./apps/installation.js";
9
- import { BOOT_DEADLINE_MS, BOOT_TRANSPORT_GRACE_MS, readBootUi, } from "./boot-gate.js";
10
- import { checkBootPage } from "./browser/boot.js";
9
+ import { BOOT_DEADLINE_MS, BOOT_TRANSPORT_GRACE_MS, readBootUi, uiBootCheckOutcomeSchema, } from "./boot-gate.js";
10
+ import { BOOT_CHECK_VERSION, checkBootPage } from "./browser/boot.js";
11
11
  import { bindingSessions } from "./browser/sessions.js";
12
12
  import { registryInstallations } from "./internal/registry-installations.js";
13
13
  import { migrateInstallationRows } from "./installation-migration.js";
@@ -34,9 +34,10 @@ import { DurableObject } from "cloudflare:workers";
34
34
  import * as Effect from "effect/Effect";
35
35
  import * as Schema from "effect/Schema";
36
36
  import * as Stream from "effect/Stream";
37
+ import { parseReleaseId, parseSha256Digest, } from "@fungi.computer/puffball";
37
38
  import { releaseSchema } from "@fungi.computer/puffball/effect";
38
39
  import { AppInstanceError, } from "./index.js";
39
- import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
40
+ import { createCloudflareAppInstance, createCloudflareAppTestCopies, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
40
41
  import { invocationFactsSchema, assertBackgroundBinding, admitBackgroundFrame, } from "./invocation.js";
41
42
  import { deliverBackground, deliverGitPush } from "./internal/delivery.js";
42
43
  import { reportSlowInvocation } from "./internal/invocation-timing.js";
@@ -62,11 +63,13 @@ const bootCapabilityRows = z.array(z.strictObject({
62
63
  expires_at: z.number().int(),
63
64
  record: z.string().max(2_000_000),
64
65
  }));
66
+ const recordedBootOutcome = uiBootCheckOutcomeSchema.refine((outcome) => outcome.kind !== "not_checked", "An inconclusive UI check is not a Release verdict");
67
+ const bootResultRow = z.strictObject({ record: z.string() });
65
68
  const approvalHomePinRow = Schema.Struct({
66
69
  tenant_id: tenantIdSchema,
67
70
  origin: Schema.String,
68
71
  });
69
- /** The installation registry: one SQLite-backed Durable Object per Oyster. */
72
+ /** Installation metadata and UI verdicts in one SQLite-backed Durable Object per tenant. */
70
73
  export class OysterRegistry extends DurableObject {
71
74
  #installationStore;
72
75
  /** Decided once, before this version writes anything, and never revised. */
@@ -81,6 +84,10 @@ export class OysterRegistry extends DurableObject {
81
84
  approvalSubmit(pin, call) {
82
85
  return this.approvalHome(pin).submit(call);
83
86
  }
87
+ /** Cancellation has the same trusted host identity as submission, never App input. */
88
+ approvalCancel(pin, call) {
89
+ return this.approvalHome(pin).cancel(call);
90
+ }
84
91
  approvalHome(pin) {
85
92
  const scope = tenantScope(Schema.decodeUnknownSync(tenantIdSchema)(pin.tenantId), pin.origin);
86
93
  if (this.ctx.id.name !== scope.durableName("registry"))
@@ -116,7 +123,7 @@ export class OysterRegistry extends DurableObject {
116
123
  });
117
124
  return this.#approval;
118
125
  }
119
- /** Recover approved work from the durable home, not a last-request memory pin. */
126
+ /** Expire approvals; no alarm may dispatch a waiting call's App write. */
120
127
  async approvalAlarm() {
121
128
  const raw = this.ctx.storage.sql
122
129
  .exec("SELECT tenant_id, origin FROM oyster_approval_home WHERE id = 1")
@@ -166,6 +173,7 @@ export class OysterRegistry extends DurableObject {
166
173
  migrateInstallationRows(ctx.storage);
167
174
  this.#installationStore = createInstallationStoreGeneration(ctx.storage);
168
175
  ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS boot_capabilities (id TEXT PRIMARY KEY, token_digest TEXT NOT NULL, expires_at INTEGER NOT NULL, record TEXT NOT NULL) STRICT");
176
+ ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS oyster_boot_results (origin TEXT NOT NULL, release_id TEXT NOT NULL, artifact_digest TEXT NOT NULL, check_version TEXT NOT NULL, record TEXT NOT NULL, PRIMARY KEY (origin, release_id, artifact_digest, check_version)) STRICT");
169
177
  ensureAppSourceTables(ctx.storage.sql);
170
178
  this.#installationOperations = createInstallationOperations({
171
179
  owner: ctx.storage,
@@ -438,6 +446,25 @@ export class OysterRegistry extends DurableObject {
438
446
  const { record } = Schema.decodeUnknownSync(recordRow)(row);
439
447
  return installationSchema.parse(JSON.parse(record));
440
448
  }
449
+ /** Trusted host verdicts, local to this tenant, origin, Release and check version. */
450
+ bootUiResult(input) {
451
+ const scope = tenantScope(Schema.decodeUnknownSync(tenantIdSchema)(input.tenantId), input.origin);
452
+ if (this.ctx.id.name !== scope.durableName("registry"))
453
+ throw new Error("Boot result namespace does not match tenant");
454
+ const releaseId = parseReleaseId(input.releaseId);
455
+ const artifactDigest = parseSha256Digest(input.artifactDigest);
456
+ const checkVersion = z.string().min(1).parse(input.checkVersion);
457
+ if (input.kind === "record") {
458
+ const outcome = recordedBootOutcome.parse(input.outcome);
459
+ this.ctx.storage.sql.exec("INSERT INTO oyster_boot_results (origin, release_id, artifact_digest, check_version, record) VALUES (?, ?, ?, ?, ?) ON CONFLICT (origin, release_id, artifact_digest, check_version) DO NOTHING", scope.origin, releaseId, artifactDigest, checkVersion, JSON.stringify(outcome));
460
+ }
461
+ const row = this.ctx.storage.sql
462
+ .exec("SELECT record FROM oyster_boot_results WHERE origin = ? AND release_id = ? AND artifact_digest = ? AND check_version = ?", scope.origin, releaseId, artifactDigest, checkVersion)
463
+ .toArray()[0];
464
+ return row === undefined
465
+ ? null
466
+ : recordedBootOutcome.parse(JSON.parse(bootResultRow.parse(row).record));
467
+ }
441
468
  /** Issue, resolve, or revoke one bounded capability without storing its token. */
442
469
  bootCapability(input) {
443
470
  if (input.kind === "issue") {
@@ -568,6 +595,18 @@ export class OysterBinding extends oysterBindingEntrypoint(oysterBindings) {
568
595
  function instanceHandle(target, scope, budget) {
569
596
  const { tenantId, origin } = scope;
570
597
  return {
598
+ testCopies: {
599
+ open: (authority, requestId) => target.openTestCopy(authority, requestId, tenantId),
600
+ inspect: (authority) => target.inspectTestCopy(authority, tenantId),
601
+ discard: (authority, copyId) => target.discardTestCopy(authority, copyId, tenantId),
602
+ fetch: (authority, copyId, request) => target.testCopyBackend(authority, copyId, request, budget, tenantId),
603
+ call: async (authority, copyId, name, input, caller) => {
604
+ const reply = await target.callTestCopy(authority, copyId, name, input, caller, budget, tenantId);
605
+ return reply.ok
606
+ ? { ok: true, value: appMethodReplySchema.parse(reply.value) }
607
+ : reply;
608
+ },
609
+ },
571
610
  prepare: (state, release) => target.prepare(state, release, budget, { tenantId, origin }),
572
611
  apply: (state, release) => target.apply(state, release, budget, { tenantId, origin }),
573
612
  fetch: (facts, request) => target.backend(facts, request, budget, tenantId),
@@ -600,6 +639,7 @@ export class OysterInstance extends DurableObject {
600
639
  runtime;
601
640
  limits = guestLimits();
602
641
  frames;
642
+ testCopies;
603
643
  /** Content-addressed backends are verified once per Instance, not per call. */
604
644
  backends;
605
645
  gitJournal;
@@ -616,6 +656,44 @@ export class OysterInstance extends DurableObject {
616
656
  this.backends = backendCache(r2ArtifactStore(env.RELEASES));
617
657
  this.runtime = this.createRuntime(this.limits);
618
658
  this.frames = createCloudflareInvocationGate(ctx, (frame) => this.closeBackground(frame));
659
+ this.testCopies = createCloudflareAppTestCopies(ctx, env.LOADER, {
660
+ limits: () => this.limits,
661
+ source: () => Effect.tryPromise({
662
+ try: async () => {
663
+ const instance = await Effect.runPromise(this.runtime.inspect());
664
+ if (instance?.owner.id !== this.installationId())
665
+ return null;
666
+ const store = registryInstallations(env, this.scope());
667
+ const installation = await store.get(instance.owner.id);
668
+ if (!isCommittedInstallation(installation, { ...instance, status: "enabled" }, this.release(instance.releaseId)))
669
+ return null;
670
+ return { instance, storeGeneration: await store.generation() };
671
+ },
672
+ catch: (cause) => cause instanceof Error
673
+ ? cause
674
+ : new Error("Copy source unavailable"),
675
+ }),
676
+ resolve: (releaseId) => Effect.tryPromise({
677
+ try: async () => {
678
+ const release = this.release(releaseId);
679
+ const backend = await this.backends(release);
680
+ if (backend === null)
681
+ throw new Error("Release has no backend");
682
+ return {
683
+ release,
684
+ ...backend,
685
+ api: backend.declaration?.api ?? null,
686
+ };
687
+ },
688
+ catch: (cause) => cause instanceof Error
689
+ ? cause
690
+ : new Error("Copy Release unavailable"),
691
+ }),
692
+ wake: (at) => Effect.tryPromise({
693
+ try: () => this.scheduleWake(at),
694
+ catch: (cause) => cause instanceof Error ? cause : new Error("Copy wake unavailable"),
695
+ }),
696
+ });
619
697
  // Local delivery avoids calling this Instance's own RPC stub from its alarm.
620
698
  const instances = {
621
699
  get: (instanceId) => this.localInstance(instanceId),
@@ -648,13 +726,53 @@ export class OysterInstance extends DurableObject {
648
726
  receipt: { lane: wake.lane, epoch: wake.epoch },
649
727
  };
650
728
  },
651
- scheduleWake: (at) => ctx.storage.transaction(async (transaction) => {
652
- const current = await transaction.getAlarm();
653
- if (current === null || at < current)
654
- await transaction.setAlarm(at);
655
- }),
729
+ scheduleWake: (at) => this.scheduleWake(at),
656
730
  }));
657
731
  }
732
+ /** Every wake owner shares the native alarm; none may postpone another. */
733
+ scheduleWake(at) {
734
+ return this.ctx.storage.transaction(async (transaction) => {
735
+ const current = await transaction.getAlarm();
736
+ if (current === null || at < current)
737
+ await transaction.setAlarm(at);
738
+ });
739
+ }
740
+ /** Open only under the existing Instance serialization and pinned tenant. */
741
+ openTestCopy(authority, requestId, tenantId = defaultTenant) {
742
+ this.requireTenant(tenantId);
743
+ return this.frames.exclusive(() => result(this.testCopies.open(authority, requestId)));
744
+ }
745
+ /** Observation rechecks both applied selection and current registry incarnation. */
746
+ inspectTestCopy(authority, tenantId = defaultTenant) {
747
+ this.requireTenant(tenantId);
748
+ return this.frames.exclusive(() => result(this.testCopies.inspect(authority)));
749
+ }
750
+ /** A delayed discard cannot target a later sibling. */
751
+ discardTestCopy(authority, copyId, tenantId = defaultTenant) {
752
+ this.requireTenant(tenantId);
753
+ return this.frames.exclusive(() => result(this.testCopies.discard(authority, copyId)));
754
+ }
755
+ /** Uses the ordinary invocation facade, without live bindings or host context. */
756
+ async testCopyBackend(authority, copyId, request, limits, tenantId = defaultTenant) {
757
+ this.requireTenant(tenantId);
758
+ try {
759
+ return await this.frames.exclusive(() => {
760
+ this.runtimeFor(limits);
761
+ return Effect.runPromise(this.testCopies.fetch(authority, copyId, request));
762
+ });
763
+ }
764
+ catch (cause) {
765
+ return Response.json({ error: cause instanceof AppInstanceError ? cause.code : "failed" }, { status: cause instanceof AppInstanceError ? 403 : 502 });
766
+ }
767
+ }
768
+ /** Declared methods share copy isolation, never a live invocation frame or binding env. */
769
+ callTestCopy(authority, copyId, name, input, caller, limits, tenantId = defaultTenant) {
770
+ this.requireTenant(tenantId);
771
+ return this.frames.exclusive(() => {
772
+ this.runtimeFor(limits);
773
+ return result(this.testCopies.call(authority, copyId, name, input, caller));
774
+ });
775
+ }
658
776
  /** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
659
777
  hostFor(scope) {
660
778
  return Promise.resolve(ownerKeyRootHost(this.env, { scope }));
@@ -831,7 +949,14 @@ export class OysterInstance extends DurableObject {
831
949
  }
832
950
  /** Carrier owns retries, dead letters and retained delivery receipts. */
833
951
  async alarm() {
834
- await (await this.gitJournal).alarm();
952
+ // Neither duty may mask the other; the first failure still surfaces.
953
+ const settled = await Promise.allSettled([
954
+ this.gitJournal.then((journal) => journal.alarm()),
955
+ Effect.runPromise(this.testCopies.expire()),
956
+ ]);
957
+ const failed = settled.find((outcome) => outcome.status === "rejected");
958
+ if (failed !== undefined)
959
+ throw failed.reason;
835
960
  }
836
961
  /** Installation changes end guest work; a Workflow cancel targets only its run. */
837
962
  async revoke(installationId, runId, tenantId = defaultTenant) {
@@ -847,6 +972,8 @@ export class OysterInstance extends DurableObject {
847
972
  if (installationId !== this.installationId())
848
973
  throw new AppInstanceError("instance_owner_mismatch");
849
974
  await this.frames.revoke(new AppInstanceError("revoked"), runId === undefined ? undefined : { runId });
975
+ if (runId === undefined)
976
+ await Effect.runPromise(this.testCopies.revoke());
850
977
  }
851
978
  /** One registry read re-admits a guest binding packet against its frame. */
852
979
  async assertCurrent(frame) {
@@ -1006,6 +1133,16 @@ export class OysterInstance extends DurableObject {
1006
1133
  checkTenant();
1007
1134
  if (!(await committed()))
1008
1135
  return { ok: false, code: "stale_authority" };
1136
+ try {
1137
+ await Effect.runPromise(this.testCopies.revoke());
1138
+ }
1139
+ catch (cause) {
1140
+ // A stuck test copy must not block the selection that retires it:
1141
+ // it stays closing and the alarm's expiry retries the purge.
1142
+ console.error("Oyster: test copy revoke failed during activation", {
1143
+ causeClass: causeClass(cause),
1144
+ });
1145
+ }
1009
1146
  // These pins attest the committed owner, not successful activation.
1010
1147
  // Persist before boot so a failed first activation can be retried or
1011
1148
  // revoked/deleted without ever claiming an active lifecycle receipt.
@@ -1104,20 +1241,38 @@ export function serveOysterBootCapability(request, env, scope) {
1104
1241
  /**
1105
1242
  * The standalone UI boot check: the Worker's own BROWSER binding opens the
1106
1243
  * pinned `/_boot/` page on the host-selected origin, with a capability in
1107
- * that tenant's registry. Without a BROWSER binding the UI is not checked.
1244
+ * that tenant's registry. Definitive results survive separate installations
1245
+ * and registry restarts, but never cross an origin, tenant or check version.
1246
+ * Without a BROWSER binding an unchecked UI remains not checked.
1108
1247
  */
1109
1248
  function oysterBootUi(env, scope) {
1110
1249
  const artifacts = r2ArtifactStore(env.RELEASES);
1111
1250
  const capabilities = registryBootCapabilities(env, scope);
1112
1251
  const sessions = env.BROWSER === undefined ? null : bindingSessions(env.BROWSER);
1113
- return (release) => reportBootPage({
1114
- origin: scope.origin,
1115
- check: sessions === null ? null : (target) => checkBootPage(sessions, target),
1116
- readUi: () => readBootUi(artifacts, release),
1117
- bucket: env.RELEASES,
1118
- capabilities,
1119
- now: Date.now,
1120
- });
1252
+ const registry = () => env.REGISTRY.getByName(scope.durableName("registry"));
1253
+ return async (release) => {
1254
+ const key = {
1255
+ tenantId: scope.tenantId,
1256
+ origin: scope.origin,
1257
+ releaseId: release.releaseId,
1258
+ artifactDigest: release.artifact.artifactDigest,
1259
+ checkVersion: BOOT_CHECK_VERSION,
1260
+ };
1261
+ const recorded = await registry().bootUiResult({ ...key, kind: "read" });
1262
+ if (recorded !== null)
1263
+ return recordedBootOutcome.parse(recorded);
1264
+ const outcome = await reportBootPage({
1265
+ origin: scope.origin,
1266
+ check: sessions === null ? null : (target) => checkBootPage(sessions, target),
1267
+ readUi: () => readBootUi(artifacts, release),
1268
+ bucket: env.RELEASES,
1269
+ capabilities,
1270
+ now: Date.now,
1271
+ });
1272
+ if (outcome.kind === "not_checked")
1273
+ return outcome;
1274
+ return recordedBootOutcome.parse(await registry().bootUiResult({ ...key, kind: "record", outcome }));
1275
+ };
1121
1276
  }
1122
1277
  /**
1123
1278
  * Create an Oyster host backed by this Worker environment's registry,
@@ -1138,7 +1293,29 @@ export function oysterWorkerHost(env, auth, options = {}) {
1138
1293
  });
1139
1294
  let host = {
1140
1295
  approvals: {
1141
- submit: (call) => registry().approvalSubmit({ tenantId: scope.tenantId, origin: scope.origin }, call),
1296
+ submit: async (call, signal) => {
1297
+ const cancelled = () => signal.aborted;
1298
+ if (cancelled())
1299
+ return { kind: "refused", reason: "cancelled" };
1300
+ const home = registry();
1301
+ const result = home.approvalSubmit(pin, call);
1302
+ const aborted = Promise.withResolvers();
1303
+ const onAbort = () => {
1304
+ aborted.resolve(undefined);
1305
+ };
1306
+ signal.addEventListener("abort", onAbort, { once: true });
1307
+ try {
1308
+ if (cancelled())
1309
+ onAbort();
1310
+ await Promise.race([result, aborted.promise]);
1311
+ if (cancelled())
1312
+ await home.approvalCancel(pin, call);
1313
+ return await result;
1314
+ }
1315
+ finally {
1316
+ signal.removeEventListener("abort", onAbort);
1317
+ }
1318
+ },
1142
1319
  },
1143
1320
  auth,
1144
1321
  workbench: {
@@ -148,9 +148,14 @@ installed Apps are cleared once: Oyster Home asks you to reinstall them with
148
148
  `npx @fungi.computer/oyster install-apps`, which restores the Apps and their App
149
149
  settings, while each App's own backend database starts empty. Agents, Sessions,
150
150
  files and keys are kept. From 0.2 or earlier, Oyster answers every request with
151
- `409` and `store_from_older_oyster`; deploy under new resource names or tear the
152
- old one down first. The changelog entry for each release says when it resets
153
- data.
151
+ `409` and `store_from_older_oyster` and leaves the store untouched. Do not tear
152
+ the old Worker down or deploy over it: verify its release first (0.0.1 needs a
153
+ release-matched bridge; 0.1 and 0.2 are archived through their own Worker before
154
+ a fresh setup under new names). A bridge at the old Worker's name accepts only
155
+ the owner's export request and answers everything else `503 oyster_archiving`.
156
+ The archive workflow is still being built and its registry SQL export is not a
157
+ certified archive, so keep the old Worker and its stores until you have one. The
158
+ changelog entry for each release says when it resets data.
154
159
 
155
160
  ### Run on celld
156
161
 
package/docs/api/apps.md CHANGED
@@ -2400,3 +2400,24 @@ longer listed by the host.
2400
2400
  #### Returns
2401
2401
 
2402
2402
  [`PermissionScreen`](#permissionscreen)
2403
+
2404
+ ---
2405
+
2406
+ ### appCallTargetName()
2407
+
2408
+ ```ts
2409
+ function appCallTargetName(directory, appId): string;
2410
+ ```
2411
+
2412
+ The directory's display name for an App-call target, else the shared plain copy.
2413
+
2414
+ #### Parameters
2415
+
2416
+ | Parameter | Type |
2417
+ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2418
+ | `directory` | \| `Readonly`\<\{ `apps`: readonly `Readonly`\<\{ `appId`: `string`; `displayName?`: `string`; \}\>[]; `installing?`: readonly `Readonly`\<\{ `appId?`: `string`; `displayName`: `string`; \}\>[]; \}\> \| `null` |
2419
+ | `appId` | `string` |
2420
+
2421
+ #### Returns
2422
+
2423
+ `string`
@@ -149,6 +149,19 @@ Loader memoization and class lookup; entrypoint access is not required.
149
149
 
150
150
  ---
151
151
 
152
+ ### AppTestCopyBackend
153
+
154
+ ```ts
155
+ type AppTestCopyBackend = Backend &
156
+ Readonly<{
157
+ api: AppApi | null;
158
+ }>;
159
+ ```
160
+
161
+ Verified code and its declaration travel together at the copy boundary.
162
+
163
+ ---
164
+
152
165
  ### FrameBindingReply
153
166
 
154
167
  ```ts
@@ -454,6 +467,50 @@ _typeof_ `WorkerEntrypoint`
454
467
 
455
468
  ---
456
469
 
470
+ ### createCloudflareAppTestCopies()
471
+
472
+ ```ts
473
+ function createCloudflareAppTestCopies<FacetClass>(
474
+ ctx,
475
+ loader,
476
+ ports,
477
+ limits?,
478
+ ): object;
479
+ ```
480
+
481
+ Disposable App-data siblings use the same native facade and wire decoder as live
482
+ invocation, but no invocation frame, binding factory or live host env. The
483
+ surrounding Instance owns current authority and shared alarm scheduling.
484
+
485
+ #### Type Parameters
486
+
487
+ | Type Parameter |
488
+ | -------------- |
489
+ | `FacetClass` |
490
+
491
+ #### Parameters
492
+
493
+ | Parameter | Type |
494
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
495
+ | `ctx` | [`AppInstanceContext`](#appinstancecontext)\<`FacetClass`\> |
496
+ | `loader` | \| `Readonly`\<\{ `get`: (`id`, `configure`) => `Readonly`\<\{ `getDurableObjectClass`: (`exportName`) => `FacetClass`; \}\>; \}\> \| `undefined` |
497
+ | `ports` | `Pick`\<`Readonly`\<\{ `owner`: `WatchdogSqliteOwner`; `now`: () => `number`; `source`: () => `Effect`\< \| `Readonly`\<\{ `instance`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: ...; `id`: ...; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; `stateSchema`: ... \| ...; `desiredStatus`: ... \| ... \| ...; `status`: ... \| ... \| ... \| ...; \}; `storeGeneration`: `string`; \}\> \| `null`, `Error`\>; `clone`: () => `Effect`\<`void`, `Error`\>; `purge`: () => `Effect`\<`void`, `Error`\>; `wake`: (`at`) => `Effect`\<`void`, `Error`\>; \}\>, `"source"` \| `"wake"`\> & `Readonly`\<\{ `limits?`: () => [`GuestLimits`](#guestlimits); `resolve`: (`releaseId`) => `Effect`\<[`AppTestCopyBackend`](#apptestcopybackend), `Error`\>; \}\> |
498
+ | `limits?` | `Partial`\<`Readonly`\<\{ `cpuMs`: `number`; `subRequests`: `number`; \}\>\> |
499
+
500
+ #### Returns
501
+
502
+ | Name | Type | Default value | Description |
503
+ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
504
+ | `open()` | (`authority`, `requestId`) => `Effect`\<\{ `selection`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: `"installation"` \| `"deployment"`; `id`: `string`; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; \}; `storeGeneration`: `string`; `copyId`: `string`; `expiresAt`: `number`; \}, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Clone current App data once under the retained request and fixed deadline. |
505
+ | `inspect()` | (`authority`) => `Effect`\< \| \{ `selection`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: `"installation"` \| `"deployment"`; `id`: `string`; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; \}; `storeGeneration`: `string`; `copyId`: `string`; `expiresAt`: `number`; \} \| `null`, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Observe the sibling, retiring expired or unavailable source selections. |
506
+ | `discard()` | (`authority`, `copyId`) => `Effect`\<`boolean`, `Error`, `never`\> | `copies.discard` | Discard only this resource, retaining its latest request receipt. |
507
+ | `expire()` | () => `Effect`\<`void`, `Error`, `never`\> | `copies.expire` | Shared native alarm cleanup; incomplete phases need no source service. |
508
+ | `revoke()` | () => `Effect`\<`void`, `Error`, `never`\> | `copies.revoke` | Retire the sibling when its owning installation loses authority. |
509
+ | `fetch()` | (`authority`, `copyId`, `request`) => `Effect`\<`Response`, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Run ordinary backend HTTP with bounded bodies and no live bindings. |
510
+ | `call()` | (`authority`, `copyId`, `method`, `input`, `caller`) => `Effect`\< \| \{ `kind`: `"ok"`; `value`: `JSONType`; \} \| \{ `kind`: `"refused"`; `code`: `"invalid"` \| `"unavailable"` \| `"conflict"` \| `"forbidden"` \| `"not_found"`; `message`: `string`; \}, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Use the ordinary typed facade and verified method codecs, without live grants. |
511
+
512
+ ---
513
+
457
514
  ### createCloudflareInvocationGate()
458
515
 
459
516
  ```ts