@fungi.computer/oyster 0.32.0 → 0.33.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 (50) hide show
  1. package/README.md +59 -0
  2. package/dist/app-test-copies.d.ts +87 -0
  3. package/dist/app-test-copies.js +170 -0
  4. package/dist/app-test-copy-page.d.ts +4 -0
  5. package/dist/app-test-copy-page.js +89 -0
  6. package/dist/browser/operations.d.ts +1 -1
  7. package/dist/cloudflare.d.ts +68 -3
  8. package/dist/cloudflare.js +214 -3
  9. package/dist/embed-metafiles.js +2 -2
  10. package/dist/host.d.ts +16 -0
  11. package/dist/host.js +309 -1
  12. package/dist/installation-operations.d.ts +247 -8
  13. package/dist/installation-operations.js +145 -7
  14. package/dist/installation-recovery-page.d.ts +24 -0
  15. package/dist/installation-recovery-page.js +168 -0
  16. package/dist/older-oyster-store.d.ts +1 -1
  17. package/dist/older-oyster-store.js +2 -4
  18. package/dist/page/mount.d.ts +2 -101
  19. package/dist/page/mount.js +1 -22
  20. package/dist/page-config.d.ts +102 -0
  21. package/dist/page-config.js +24 -0
  22. package/dist/page-script.js +1 -1
  23. package/dist/recovery-style.d.ts +5 -0
  24. package/dist/recovery-style.js +32 -0
  25. package/dist/standalone/agents.d.ts +1 -1
  26. package/dist/upgrade/old-worker-http.d.ts +2 -0
  27. package/dist/upgrade/old-worker-http.js +22 -0
  28. package/dist/upgrade/old-worker-readonly.d.ts +14 -0
  29. package/dist/upgrade/old-worker-readonly.js +22 -0
  30. package/dist/upgrade/old-worker-sql.d.ts +10 -0
  31. package/dist/upgrade/old-worker-sql.js +68 -0
  32. package/dist/upgrade/old-worker-stream.d.ts +12 -0
  33. package/dist/upgrade/old-worker-stream.js +54 -0
  34. package/dist/upgrade/private-stage.d.ts +23 -0
  35. package/dist/upgrade/private-stage.js +109 -0
  36. package/dist/upgrade/standalone-001.d.ts +16 -0
  37. package/dist/upgrade/standalone-001.js +31 -0
  38. package/dist/upgrade/standalone-01.d.ts +37 -0
  39. package/dist/upgrade/standalone-01.js +55 -0
  40. package/dist/upgrade/standalone-02.d.ts +37 -0
  41. package/dist/upgrade/standalone-02.js +55 -0
  42. package/dist/workers.d.ts +15 -1
  43. package/dist/workers.js +117 -7
  44. package/docs/api/README.md +8 -3
  45. package/docs/api/cloudflare.md +57 -0
  46. package/docs/api/host.md +223 -14
  47. package/docs/api/page/mount.md +10 -78
  48. package/docs/api/workers-git.md +246 -1
  49. package/docs/api/workers.md +352 -14
  50. package/package.json +23 -10
package/dist/workers.d.ts CHANGED
@@ -1,5 +1,5 @@
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";
@@ -22,6 +22,7 @@ import * as Schema from "effect/Schema";
22
22
  import type { Release } from "@fungi.computer/puffball";
23
23
  import { type Backend, type Instance, type OwnerState } from "./index.js";
24
24
  import { r2ArtifactStore, type FrameBindingReply, type FrameBindingMethod, type FrameBindingProps } from "./cloudflare.js";
25
+ import type { AppTestCopy, AppTestCopyAuthority } from "./app-test-copies.js";
25
26
  import { type BackgroundFrameState, type InvocationFacts, type InvocationFrame } from "./invocation.js";
26
27
  import { type InstallationCommit, type InstanceResult, type OysterAuth, type OysterHost, type OysterJson } from "./host.js";
27
28
  import { type AppStorageResult, type AppStorageWrite, type AppStorageReset, type ResolvedAppStorage } from "@fungi.computer/agar/storage";
@@ -377,10 +378,23 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
377
378
  private runtime;
378
379
  private limits;
379
380
  private readonly frames;
381
+ private readonly testCopies;
380
382
  /** Content-addressed backends are verified once per Instance, not per call. */
381
383
  private readonly backends;
382
384
  private readonly gitJournal;
383
385
  constructor(ctx: DurableObjectState, env: Env);
386
+ /** Every wake owner shares the native alarm; none may postpone another. */
387
+ private scheduleWake;
388
+ /** Open only under the existing Instance serialization and pinned tenant. */
389
+ openTestCopy(authority: AppTestCopyAuthority, requestId: string, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy>>;
390
+ /** Observation rechecks both applied selection and current registry incarnation. */
391
+ inspectTestCopy(authority: AppTestCopyAuthority, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy | null>>;
392
+ /** A delayed discard cannot target a later sibling. */
393
+ discardTestCopy(authority: AppTestCopyAuthority, copyId: string, tenantId?: TenantId): Promise<InstanceResult<boolean>>;
394
+ /** Uses the ordinary invocation facade, without live bindings or host context. */
395
+ testCopyBackend(authority: AppTestCopyAuthority, copyId: string, request: Request, limits?: GuestLimits, tenantId?: TenantId): Promise<Response>;
396
+ /** Declared methods share copy isolation, never a live invocation frame or binding env. */
397
+ callTestCopy(authority: AppTestCopyAuthority, copyId: string, name: string, input: Schema.Json, caller: AppMethodCallContext, limits?: GuestLimits, tenantId?: TenantId): Promise<InstanceResult<unknown>>;
384
398
  /** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
385
399
  protected hostFor(scope: TenantScope): Promise<OysterHost>;
386
400
  /** Reconstruct current host admission for each wake; non-default tenants get no wakes. */
package/dist/workers.js CHANGED
@@ -36,7 +36,7 @@ import * as Schema from "effect/Schema";
36
36
  import * as Stream from "effect/Stream";
37
37
  import { releaseSchema } from "@fungi.computer/puffball/effect";
38
38
  import { AppInstanceError, } from "./index.js";
39
- import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
39
+ import { createCloudflareAppInstance, createCloudflareAppTestCopies, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
40
40
  import { invocationFactsSchema, assertBackgroundBinding, admitBackgroundFrame, } from "./invocation.js";
41
41
  import { deliverBackground, deliverGitPush } from "./internal/delivery.js";
42
42
  import { reportSlowInvocation } from "./internal/invocation-timing.js";
@@ -568,6 +568,18 @@ export class OysterBinding extends oysterBindingEntrypoint(oysterBindings) {
568
568
  function instanceHandle(target, scope, budget) {
569
569
  const { tenantId, origin } = scope;
570
570
  return {
571
+ testCopies: {
572
+ open: (authority, requestId) => target.openTestCopy(authority, requestId, tenantId),
573
+ inspect: (authority) => target.inspectTestCopy(authority, tenantId),
574
+ discard: (authority, copyId) => target.discardTestCopy(authority, copyId, tenantId),
575
+ fetch: (authority, copyId, request) => target.testCopyBackend(authority, copyId, request, budget, tenantId),
576
+ call: async (authority, copyId, name, input, caller) => {
577
+ const reply = await target.callTestCopy(authority, copyId, name, input, caller, budget, tenantId);
578
+ return reply.ok
579
+ ? { ok: true, value: appMethodReplySchema.parse(reply.value) }
580
+ : reply;
581
+ },
582
+ },
571
583
  prepare: (state, release) => target.prepare(state, release, budget, { tenantId, origin }),
572
584
  apply: (state, release) => target.apply(state, release, budget, { tenantId, origin }),
573
585
  fetch: (facts, request) => target.backend(facts, request, budget, tenantId),
@@ -600,6 +612,7 @@ export class OysterInstance extends DurableObject {
600
612
  runtime;
601
613
  limits = guestLimits();
602
614
  frames;
615
+ testCopies;
603
616
  /** Content-addressed backends are verified once per Instance, not per call. */
604
617
  backends;
605
618
  gitJournal;
@@ -616,6 +629,44 @@ export class OysterInstance extends DurableObject {
616
629
  this.backends = backendCache(r2ArtifactStore(env.RELEASES));
617
630
  this.runtime = this.createRuntime(this.limits);
618
631
  this.frames = createCloudflareInvocationGate(ctx, (frame) => this.closeBackground(frame));
632
+ this.testCopies = createCloudflareAppTestCopies(ctx, env.LOADER, {
633
+ limits: () => this.limits,
634
+ source: () => Effect.tryPromise({
635
+ try: async () => {
636
+ const instance = await Effect.runPromise(this.runtime.inspect());
637
+ if (instance?.owner.id !== this.installationId())
638
+ return null;
639
+ const store = registryInstallations(env, this.scope());
640
+ const installation = await store.get(instance.owner.id);
641
+ if (!isCommittedInstallation(installation, { ...instance, status: "enabled" }, this.release(instance.releaseId)))
642
+ return null;
643
+ return { instance, storeGeneration: await store.generation() };
644
+ },
645
+ catch: (cause) => cause instanceof Error
646
+ ? cause
647
+ : new Error("Copy source unavailable"),
648
+ }),
649
+ resolve: (releaseId) => Effect.tryPromise({
650
+ try: async () => {
651
+ const release = this.release(releaseId);
652
+ const backend = await this.backends(release);
653
+ if (backend === null)
654
+ throw new Error("Release has no backend");
655
+ return {
656
+ release,
657
+ ...backend,
658
+ api: backend.declaration?.api ?? null,
659
+ };
660
+ },
661
+ catch: (cause) => cause instanceof Error
662
+ ? cause
663
+ : new Error("Copy Release unavailable"),
664
+ }),
665
+ wake: (at) => Effect.tryPromise({
666
+ try: () => this.scheduleWake(at),
667
+ catch: (cause) => cause instanceof Error ? cause : new Error("Copy wake unavailable"),
668
+ }),
669
+ });
619
670
  // Local delivery avoids calling this Instance's own RPC stub from its alarm.
620
671
  const instances = {
621
672
  get: (instanceId) => this.localInstance(instanceId),
@@ -648,13 +699,53 @@ export class OysterInstance extends DurableObject {
648
699
  receipt: { lane: wake.lane, epoch: wake.epoch },
649
700
  };
650
701
  },
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
- }),
702
+ scheduleWake: (at) => this.scheduleWake(at),
656
703
  }));
657
704
  }
705
+ /** Every wake owner shares the native alarm; none may postpone another. */
706
+ scheduleWake(at) {
707
+ return this.ctx.storage.transaction(async (transaction) => {
708
+ const current = await transaction.getAlarm();
709
+ if (current === null || at < current)
710
+ await transaction.setAlarm(at);
711
+ });
712
+ }
713
+ /** Open only under the existing Instance serialization and pinned tenant. */
714
+ openTestCopy(authority, requestId, tenantId = defaultTenant) {
715
+ this.requireTenant(tenantId);
716
+ return this.frames.exclusive(() => result(this.testCopies.open(authority, requestId)));
717
+ }
718
+ /** Observation rechecks both applied selection and current registry incarnation. */
719
+ inspectTestCopy(authority, tenantId = defaultTenant) {
720
+ this.requireTenant(tenantId);
721
+ return this.frames.exclusive(() => result(this.testCopies.inspect(authority)));
722
+ }
723
+ /** A delayed discard cannot target a later sibling. */
724
+ discardTestCopy(authority, copyId, tenantId = defaultTenant) {
725
+ this.requireTenant(tenantId);
726
+ return this.frames.exclusive(() => result(this.testCopies.discard(authority, copyId)));
727
+ }
728
+ /** Uses the ordinary invocation facade, without live bindings or host context. */
729
+ async testCopyBackend(authority, copyId, request, limits, tenantId = defaultTenant) {
730
+ this.requireTenant(tenantId);
731
+ try {
732
+ return await this.frames.exclusive(() => {
733
+ this.runtimeFor(limits);
734
+ return Effect.runPromise(this.testCopies.fetch(authority, copyId, request));
735
+ });
736
+ }
737
+ catch (cause) {
738
+ return Response.json({ error: cause instanceof AppInstanceError ? cause.code : "failed" }, { status: cause instanceof AppInstanceError ? 403 : 502 });
739
+ }
740
+ }
741
+ /** Declared methods share copy isolation, never a live invocation frame or binding env. */
742
+ callTestCopy(authority, copyId, name, input, caller, limits, tenantId = defaultTenant) {
743
+ this.requireTenant(tenantId);
744
+ return this.frames.exclusive(() => {
745
+ this.runtimeFor(limits);
746
+ return result(this.testCopies.call(authority, copyId, name, input, caller));
747
+ });
748
+ }
658
749
  /** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
659
750
  hostFor(scope) {
660
751
  return Promise.resolve(ownerKeyRootHost(this.env, { scope }));
@@ -831,7 +922,14 @@ export class OysterInstance extends DurableObject {
831
922
  }
832
923
  /** Carrier owns retries, dead letters and retained delivery receipts. */
833
924
  async alarm() {
834
- await (await this.gitJournal).alarm();
925
+ // Neither duty may mask the other; the first failure still surfaces.
926
+ const settled = await Promise.allSettled([
927
+ this.gitJournal.then((journal) => journal.alarm()),
928
+ Effect.runPromise(this.testCopies.expire()),
929
+ ]);
930
+ const failed = settled.find((outcome) => outcome.status === "rejected");
931
+ if (failed !== undefined)
932
+ throw failed.reason;
835
933
  }
836
934
  /** Installation changes end guest work; a Workflow cancel targets only its run. */
837
935
  async revoke(installationId, runId, tenantId = defaultTenant) {
@@ -847,6 +945,8 @@ export class OysterInstance extends DurableObject {
847
945
  if (installationId !== this.installationId())
848
946
  throw new AppInstanceError("instance_owner_mismatch");
849
947
  await this.frames.revoke(new AppInstanceError("revoked"), runId === undefined ? undefined : { runId });
948
+ if (runId === undefined)
949
+ await Effect.runPromise(this.testCopies.revoke());
850
950
  }
851
951
  /** One registry read re-admits a guest binding packet against its frame. */
852
952
  async assertCurrent(frame) {
@@ -1006,6 +1106,16 @@ export class OysterInstance extends DurableObject {
1006
1106
  checkTenant();
1007
1107
  if (!(await committed()))
1008
1108
  return { ok: false, code: "stale_authority" };
1109
+ try {
1110
+ await Effect.runPromise(this.testCopies.revoke());
1111
+ }
1112
+ catch (cause) {
1113
+ // A stuck test copy must not block the selection that retires it:
1114
+ // it stays closing and the alarm's expiry retries the purge.
1115
+ console.error("Oyster: test copy revoke failed during activation", {
1116
+ causeClass: causeClass(cause),
1117
+ });
1118
+ }
1009
1119
  // These pins attest the committed owner, not successful activation.
1010
1120
  // Persist before boot so a failed first activation can be retried or
1011
1121
  // revoked/deleted without ever claiming an active lifecycle receipt.
@@ -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
 
@@ -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
package/docs/api/host.md CHANGED
@@ -74,6 +74,26 @@ readonly code:
74
74
 
75
75
  ## Type Aliases
76
76
 
77
+ ### AppTestCopyAuthority
78
+
79
+ ```ts
80
+ type AppTestCopyAuthority = z.output<typeof appTestCopyAuthoritySchema>;
81
+ ```
82
+
83
+ Exact source selection and store incarnation observed by the owner.
84
+
85
+ ---
86
+
87
+ ### AppTestCopy
88
+
89
+ ```ts
90
+ type AppTestCopy = z.output<typeof appTestCopySchema>;
91
+ ```
92
+
93
+ Observed sibling identity and nonrenewing deadline, never live host grants.
94
+
95
+ ---
96
+
77
97
  ### CapabilityMethodKind
78
98
 
79
99
  ```ts
@@ -214,6 +234,19 @@ The result of one Instance operation; refusals carry Oyster's error code.
214
234
 
215
235
  ```ts
216
236
  type InstanceHandle = Readonly<{
237
+ testCopies?: Readonly<{
238
+ open: (authority, requestId) => Promise<InstanceResult<AppTestCopy>>;
239
+ inspect: (authority) => Promise<InstanceResult<AppTestCopy | null>>;
240
+ discard: (authority, copyId) => Promise<InstanceResult<boolean>>;
241
+ fetch: (authority, copyId, request) => Promise<Response>;
242
+ call: (
243
+ authority,
244
+ copyId,
245
+ name,
246
+ input,
247
+ caller,
248
+ ) => Promise<InstanceResult<AppMethodReply>>;
249
+ }>;
217
250
  prepare: (
218
251
  state,
219
252
  release,
@@ -500,6 +533,60 @@ One host's declared routes and the one way to serve them.
500
533
 
501
534
  ```ts
502
535
  type InstallationOperations = Readonly<{
536
+ recovery: Promise<
537
+ | {
538
+ authorityVersion: number;
539
+ storeGeneration: string;
540
+ release: {
541
+ releaseId: Schema.refine<ReleaseId, Schema.String>;
542
+ appId: Schema.refine<AppId, Schema.String>;
543
+ artifact: Schema.Struct<{
544
+ artifactRef: Schema.refine<ArtifactRef, Schema.String>;
545
+ artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
546
+ provenance: Schema.Struct<{
547
+ sourceRevision: Schema.refine<..., ...>;
548
+ sourceTreeDigest: Schema.refine<..., ...>;
549
+ buildRecipeDigest: Schema.refine<..., ...>;
550
+ }>;
551
+ }>;
552
+ };
553
+ uiCheck: | {
554
+ kind: "passed";
555
+ }
556
+ | {
557
+ kind: "failed";
558
+ code: "ui_mount_failed";
559
+ diagnostics?: {
560
+ failedPredicate: | "unexpected_candidate_request"
561
+ | "response_status"
562
+ | "request_failed"
563
+ | "page_error"
564
+ | "candidate_not_mounted";
565
+ errorName?: | "Error"
566
+ | "TypeError"
567
+ | "RangeError"
568
+ | "SyntaxError"
569
+ | "AbortError"
570
+ | "TimeoutError"
571
+ | "Other";
572
+ finalUrlPath: string;
573
+ consoleErrors: string[];
574
+ pageErrors: string[];
575
+ failedRequests: object[];
576
+ droppedCount: number;
577
+ };
578
+ }
579
+ | {
580
+ kind: "not_checked";
581
+ code: | "boot_runner_unavailable"
582
+ | "boot_browser_binding_missing"
583
+ | "boot_clone_unavailable"
584
+ | "boot_timeout"
585
+ | "boot_cleanup_failed"
586
+ | "ui_check_not_run_on_host";
587
+ };
588
+ }
589
+ | null>;
503
590
  admit: Promise<
504
591
  | {
505
592
  requestId: string;
@@ -975,20 +1062,16 @@ type InstallationOperations = Readonly<{
975
1062
  | null>;
976
1063
  load: Promise<
977
1064
  | {
978
- admission: {
1065
+ admission: | {
979
1066
  requestId: string;
980
1067
  installationId: string;
981
1068
  release: {
982
1069
  releaseId: Schema.refine<ReleaseId, Schema.String>;
983
1070
  appId: Schema.refine<AppId, Schema.String>;
984
1071
  artifact: Schema.Struct<{
985
- artifactRef: Schema.refine<ArtifactRef, Schema.String>;
986
- artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
987
- provenance: Schema.Struct<{
988
- sourceRevision: ...;
989
- sourceTreeDigest: ...;
990
- buildRecipeDigest: ...;
991
- }>;
1072
+ artifactRef: Schema.refine<..., ...>;
1073
+ artifactDigest: Schema.refine<..., ...>;
1074
+ provenance: Schema.Struct<...>;
992
1075
  }>;
993
1076
  };
994
1077
  actor: | {
@@ -1005,7 +1088,36 @@ type InstallationOperations = Readonly<{
1005
1088
  };
1006
1089
  intent: "install-or-select" | "install-or-remint" | "create-only";
1007
1090
  origin: "workflow" | "owner-direct";
1008
- };
1091
+ }
1092
+ | {
1093
+ authorityVersion: number;
1094
+ storeGeneration: string;
1095
+ requestId: string;
1096
+ installationId: string;
1097
+ actor: | {
1098
+ kind: z.ZodMiniLiteral<"member">;
1099
+ memberId: z.ZodMiniString<string>;
1100
+ }
1101
+ | {
1102
+ kind: z.ZodMiniLiteral<"agent">;
1103
+ agentId: z.ZodMiniString<string>;
1104
+ }
1105
+ | {
1106
+ kind: z.ZodMiniLiteral<"team-key">;
1107
+ keyId: z.ZodMiniString<string>;
1108
+ };
1109
+ intent: "rollback";
1110
+ origin: "owner-direct";
1111
+ release: {
1112
+ releaseId: Schema.refine<ReleaseId, Schema.String>;
1113
+ appId: Schema.refine<AppId, Schema.String>;
1114
+ artifact: Schema.Struct<{
1115
+ artifactRef: Schema.refine<..., ...>;
1116
+ artifactDigest: Schema.refine<..., ...>;
1117
+ provenance: Schema.Struct<...>;
1118
+ }>;
1119
+ };
1120
+ };
1009
1121
  scope: {
1010
1122
  tenantId: string & Brand<"OysterTenantId">;
1011
1123
  origin: string;
@@ -1124,7 +1236,7 @@ type InstallationOperations = Readonly<{
1124
1236
  }
1125
1237
  | null>;
1126
1238
  plan: Promise<{
1127
- admission: {
1239
+ admission: | {
1128
1240
  requestId: string;
1129
1241
  installationId: string;
1130
1242
  release: {
@@ -1134,9 +1246,9 @@ type InstallationOperations = Readonly<{
1134
1246
  artifactRef: Schema.refine<ArtifactRef, Schema.String>;
1135
1247
  artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
1136
1248
  provenance: Schema.Struct<{
1137
- sourceRevision: Schema.refine<..., ...>;
1138
- sourceTreeDigest: Schema.refine<..., ...>;
1139
- buildRecipeDigest: Schema.refine<..., ...>;
1249
+ sourceRevision: ...;
1250
+ sourceTreeDigest: ...;
1251
+ buildRecipeDigest: ...;
1140
1252
  }>;
1141
1253
  }>;
1142
1254
  };
@@ -1154,7 +1266,40 @@ type InstallationOperations = Readonly<{
1154
1266
  };
1155
1267
  intent: "install-or-select" | "install-or-remint" | "create-only";
1156
1268
  origin: "workflow" | "owner-direct";
1157
- };
1269
+ }
1270
+ | {
1271
+ authorityVersion: number;
1272
+ storeGeneration: string;
1273
+ requestId: string;
1274
+ installationId: string;
1275
+ actor: | {
1276
+ kind: z.ZodMiniLiteral<"member">;
1277
+ memberId: z.ZodMiniString<string>;
1278
+ }
1279
+ | {
1280
+ kind: z.ZodMiniLiteral<"agent">;
1281
+ agentId: z.ZodMiniString<string>;
1282
+ }
1283
+ | {
1284
+ kind: z.ZodMiniLiteral<"team-key">;
1285
+ keyId: z.ZodMiniString<string>;
1286
+ };
1287
+ intent: "rollback";
1288
+ origin: "owner-direct";
1289
+ release: {
1290
+ releaseId: Schema.refine<ReleaseId, Schema.String>;
1291
+ appId: Schema.refine<AppId, Schema.String>;
1292
+ artifact: Schema.Struct<{
1293
+ artifactRef: Schema.refine<ArtifactRef, Schema.String>;
1294
+ artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
1295
+ provenance: Schema.Struct<{
1296
+ sourceRevision: ...;
1297
+ sourceTreeDigest: ...;
1298
+ buildRecipeDigest: ...;
1299
+ }>;
1300
+ }>;
1301
+ };
1302
+ };
1158
1303
  scope: {
1159
1304
  tenantId: string & Brand<"OysterTenantId">;
1160
1305
  origin: string;
@@ -1382,6 +1527,70 @@ another store read or hash.
1382
1527
 
1383
1528
  ## Variables
1384
1529
 
1530
+ ### appTestCopyAuthoritySchema
1531
+
1532
+ ```ts
1533
+ const appTestCopyAuthoritySchema: ZodObject<
1534
+ {
1535
+ selection: ZodPipe<
1536
+ ZodUnknown,
1537
+ ZodTransform<
1538
+ {
1539
+ instanceId: InstanceId;
1540
+ owner: {
1541
+ kind: "installation" | "deployment";
1542
+ id: string;
1543
+ };
1544
+ appId: AppId;
1545
+ releaseId: ReleaseId;
1546
+ authorityVersion: number;
1547
+ },
1548
+ unknown
1549
+ >
1550
+ >;
1551
+ storeGeneration: ZodString;
1552
+ },
1553
+ $strict
1554
+ >;
1555
+ ```
1556
+
1557
+ A test copy is fenced to the same store and owner selection as its source.
1558
+
1559
+ ---
1560
+
1561
+ ### appTestCopySchema
1562
+
1563
+ ```ts
1564
+ const appTestCopySchema: ZodObject<
1565
+ {
1566
+ selection: ZodPipe<
1567
+ ZodUnknown,
1568
+ ZodTransform<
1569
+ {
1570
+ instanceId: InstanceId;
1571
+ owner: {
1572
+ kind: "installation" | "deployment";
1573
+ id: string;
1574
+ };
1575
+ appId: AppId;
1576
+ releaseId: ReleaseId;
1577
+ authorityVersion: number;
1578
+ },
1579
+ unknown
1580
+ >
1581
+ >;
1582
+ storeGeneration: ZodString;
1583
+ copyId: ZodString;
1584
+ expiresAt: ZodNumber;
1585
+ },
1586
+ $strict
1587
+ >;
1588
+ ```
1589
+
1590
+ Host-owned identity and fixed deadline of one disposable App-data sibling.
1591
+
1592
+ ---
1593
+
1385
1594
  ### capabilityMethodKindSchema
1386
1595
 
1387
1596
  ```ts