@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/README.md CHANGED
@@ -283,6 +283,65 @@ the low-level Instance, invocation and git ports. Most of the package's other
283
283
  entry points are parts that the standalone host and the Fungi Hub assemble; you
284
284
  do not need them to run Oyster.
285
285
 
286
+ ## Recover an App
287
+
288
+ Open `/recovery` on your Oyster and sign in as its owner. This host-owned page
289
+ and its forms load no App, Shell or page assets, so they remain usable when the
290
+ selected App or home Shell cannot load. The page shows the current Release and
291
+ the prior confirmed activation, including its recorded UI-check outcome.
292
+ `not_checked` is not a passing UI check.
293
+
294
+ Rollback becomes available once an App has had a new version confirmed after an
295
+ Oyster upgrade: the first such version records the starting point, and the next
296
+ one gives you a version to return to. Until then the page says there is no
297
+ earlier version.
298
+
299
+ The installation owner retains its latest two distinct confirmed activations,
300
+ independently of expiring request receipts. Rollback chooses the prior
301
+ activation; if a newer selection never completed, it chooses the latest
302
+ confirmed one. The target must still belong to this App, Instance, host scope
303
+ and store incarnation. The owner selects the Release, not the browser.
304
+
305
+ **Roll back** submits a fresh, idempotent installation command fenced by the
306
+ displayed authority version and store generation. Admission is not completion:
307
+ the redirected observation reports the retained request state; refresh it to see
308
+ settlement. Normal artifact verification, permissions and Instance schema checks
309
+ still apply. Nothing rolls back automatically.
310
+
311
+ Rollback preserves the Instance and uses **current App data**. It does not
312
+ restore old data, undo completed external effects or provide a state-schema
313
+ migration. The owner API is `GET /api/installations/:installationId/recovery`
314
+ and `POST /api/installations/:installationId/rollback`; the POST takes only
315
+ `authorityVersion` and `storeGeneration`, with an `Idempotency-Key` header.
316
+ These routes reject App-mediated and cross-origin browser requests.
317
+
318
+ ### Try disposable App data
319
+
320
+ On a native host with App-facet cloning, **Open test copy** snapshots the
321
+ enabled App's current data into one disposable sibling. It is not another
322
+ Installation or product Instance. Its page uses the selected Release's ordinary
323
+ sandboxed App UI and backend/method transports, without loading the editable
324
+ Shell. Creating and discarding the copy still work when App and Shell assets
325
+ cannot load; interacting with its App UI naturally needs that UI's assets.
326
+
327
+ The copy has no live bindings, Computer, capabilities or outbound network. Its
328
+ SQLite changes never promote into the live App. It expires after five minutes,
329
+ without renewal on retry, and **Discard test copy** retires it sooner. Selection
330
+ or store changes, installation revocation and deletion also retire it. This is
331
+ not a backup, data restoration, schema migration or reversal of external
332
+ effects. Hosts without the native copy service report it unavailable; rollback
333
+ does not depend on that service.
334
+
335
+ Owner-direct, same-origin forms use `POST /recovery/:installationId/test-copy`
336
+ and `POST /recovery/:installationId/test-copy/:copyId/discard`, fenced by
337
+ `authorityVersion` and `storeGeneration`. Creation takes a `requestId`; discard
338
+ names the host-minted `copyId`. Those identities are separate: replaying an old
339
+ creation request cannot revive a retired resource or let its delayed discard
340
+ retire a later copy. The latest request receipt is retained, not an unbounded
341
+ request history. The copy page is `GET` at that copy's path; its sibling
342
+ `PUT .../backend` and `POST .../methods/:name` doors retain current owner and
343
+ selection admission. No Release or lifetime is caller-selectable.
344
+
286
345
  ## Limits and errors
287
346
 
288
347
  An App's backend gets 1,000 ms of CPU and 50 subrequests per call unless the
@@ -0,0 +1,87 @@
1
+ import { z } from "zod";
2
+ import * as Effect from "effect/Effect";
3
+ import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
4
+ import { AppInstanceError, type Instance } from "./index.js";
5
+ /** A test copy is fenced to the same store and owner selection as its source. */
6
+ export declare const appTestCopyAuthoritySchema: z.ZodObject<{
7
+ selection: z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
8
+ readonly instanceId: import("./instance-id.js").InstanceId;
9
+ readonly owner: {
10
+ readonly kind: "installation" | "deployment";
11
+ readonly id: string;
12
+ };
13
+ readonly appId: import("@fungi.computer/puffball").AppId;
14
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
15
+ readonly authorityVersion: number;
16
+ }, unknown>>;
17
+ storeGeneration: z.ZodString;
18
+ }, z.core.$strict>;
19
+ /** Exact source selection and store incarnation observed by the owner. */
20
+ export type AppTestCopyAuthority = z.output<typeof appTestCopyAuthoritySchema>;
21
+ /** Host-owned identity and fixed deadline of one disposable App-data sibling. */
22
+ export declare const appTestCopySchema: z.ZodObject<{
23
+ selection: z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
24
+ readonly instanceId: import("./instance-id.js").InstanceId;
25
+ readonly owner: {
26
+ readonly kind: "installation" | "deployment";
27
+ readonly id: string;
28
+ };
29
+ readonly appId: import("@fungi.computer/puffball").AppId;
30
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
31
+ readonly authorityVersion: number;
32
+ }, unknown>>;
33
+ storeGeneration: z.ZodString;
34
+ copyId: z.ZodString;
35
+ expiresAt: z.ZodNumber;
36
+ }, z.core.$strict>;
37
+ /** Observed sibling identity and nonrenewing deadline, never live host grants. */
38
+ export type AppTestCopy = z.output<typeof appTestCopySchema>;
39
+ /** Native operations stay with the Instance; only the App facet is cloned. */
40
+ export type AppTestCopyPorts = Readonly<{
41
+ owner: WatchdogSqliteOwner;
42
+ now: () => number;
43
+ source: () => Effect.Effect<Readonly<{
44
+ instance: Instance;
45
+ storeGeneration: string;
46
+ }> | null, Error>;
47
+ clone: () => Effect.Effect<void, Error>;
48
+ purge: () => Effect.Effect<void, Error>;
49
+ wake: (at: number) => Effect.Effect<void, Error>;
50
+ }>;
51
+ /** One bounded durable lifecycle, independent of App and editable Shell code. */
52
+ export declare function createAppTestCopies(ports: AppTestCopyPorts): {
53
+ open: (authority: AppTestCopyAuthority, requestId: string) => Effect.Effect<{
54
+ selection: {
55
+ readonly instanceId: import("./instance-id.js").InstanceId;
56
+ readonly owner: {
57
+ readonly kind: "installation" | "deployment";
58
+ readonly id: string;
59
+ };
60
+ readonly appId: import("@fungi.computer/puffball").AppId;
61
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
62
+ readonly authorityVersion: number;
63
+ };
64
+ storeGeneration: string;
65
+ copyId: string;
66
+ expiresAt: number;
67
+ }, Error | AppInstanceError, never>;
68
+ inspect: (authority: AppTestCopyAuthority) => Effect.Effect<{
69
+ selection: {
70
+ readonly instanceId: import("./instance-id.js").InstanceId;
71
+ readonly owner: {
72
+ readonly kind: "installation" | "deployment";
73
+ readonly id: string;
74
+ };
75
+ readonly appId: import("@fungi.computer/puffball").AppId;
76
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
77
+ readonly authorityVersion: number;
78
+ };
79
+ storeGeneration: string;
80
+ copyId: string;
81
+ expiresAt: number;
82
+ } | null, Error, never>;
83
+ withCopy: <A>(authority: AppTestCopyAuthority, copyId: string, work: (copy: AppTestCopy) => Effect.Effect<A, Error>) => Effect.Effect<A, Error | AppInstanceError, never>;
84
+ discard: (authority: AppTestCopyAuthority, copyId: string) => Effect.Effect<boolean, Error, never>;
85
+ expire: () => Effect.Effect<void, Error, never>;
86
+ revoke: () => Effect.Effect<void, Error, never>;
87
+ };
@@ -0,0 +1,170 @@
1
+ import { z } from "zod";
2
+ import * as Effect from "effect/Effect";
3
+ import * as Exit from "effect/Exit";
4
+ import * as Semaphore from "effect/Semaphore";
5
+ import { defineIdFamily } from "@fungi.computer/cairn/id";
6
+ import { ownerCodec } from "./apps/installation.js";
7
+ import { installationRequestIdSchema } from "./installation-operations.js";
8
+ import { AppInstanceError, selectionSchema } from "./index.js";
9
+ /** A test copy is fenced to the same store and owner selection as its source. */
10
+ export const appTestCopyAuthoritySchema = z.strictObject({
11
+ selection: ownerCodec(selectionSchema),
12
+ storeGeneration: z.string().min(1).max(256),
13
+ });
14
+ /** Resource identity is host-minted, never an idempotency key or an Instance. */
15
+ const appTestCopyIds = defineIdFamily({
16
+ family: "app-test-copy",
17
+ version: 1,
18
+ kinds: { copy: { prefix: "appcopy" } },
19
+ });
20
+ /** Host-owned identity and fixed deadline of one disposable App-data sibling. */
21
+ export const appTestCopySchema = appTestCopyAuthoritySchema.extend({
22
+ copyId: z.string().refine((value) => appTestCopyIds.copy.is(value)),
23
+ expiresAt: z.number().int().nonnegative(),
24
+ });
25
+ const recordSchema = appTestCopySchema.extend({
26
+ requestId: installationRequestIdSchema,
27
+ phase: z.enum(["creating", "active", "closing", "closed"]),
28
+ });
29
+ // Private resource ceiling, not caller-selectable policy or a renewable lease.
30
+ const lifetimeMs = 5 * 60 * 1000;
31
+ function matches(a, b) {
32
+ const left = a.selection;
33
+ const right = b.selection;
34
+ return (a.storeGeneration === b.storeGeneration &&
35
+ left.instanceId === right.instanceId &&
36
+ left.owner.kind === right.owner.kind &&
37
+ left.owner.id === right.owner.id &&
38
+ left.appId === right.appId &&
39
+ left.releaseId === right.releaseId &&
40
+ left.authorityVersion === right.authorityVersion);
41
+ }
42
+ function metadata(record) {
43
+ return {
44
+ selection: record.selection,
45
+ storeGeneration: record.storeGeneration,
46
+ copyId: record.copyId,
47
+ expiresAt: record.expiresAt,
48
+ };
49
+ }
50
+ /** One bounded durable lifecycle, independent of App and editable Shell code. */
51
+ export function createAppTestCopies(ports) {
52
+ const sql = ports.owner.sql;
53
+ sql.exec("CREATE TABLE IF NOT EXISTS app_test_copy (id INTEGER PRIMARY KEY CHECK(id=1), record TEXT NOT NULL) STRICT");
54
+ const lock = Semaphore.makeUnsafe(1);
55
+ const attempt = (work) => Effect.try({
56
+ try: work,
57
+ catch: (cause) => cause instanceof Error ? cause : new Error("Test copy storage failed"),
58
+ });
59
+ const read = attempt(() => {
60
+ const row = sql
61
+ .exec("SELECT record FROM app_test_copy WHERE id=1")
62
+ .toArray()[0];
63
+ if (row === undefined)
64
+ return null;
65
+ const stored = z.strictObject({ record: z.string() }).parse(row);
66
+ return recordSchema.parse(JSON.parse(stored.record));
67
+ });
68
+ const write = (record) => attempt(() => {
69
+ sql.exec("INSERT INTO app_test_copy(id,record) VALUES(1,?) ON CONFLICT(id) DO UPDATE SET record=excluded.record", JSON.stringify(record));
70
+ });
71
+ const close = (record) => Effect.gen(function* () {
72
+ yield* write({ ...record, phase: "closing" });
73
+ // The expiry wake preceded clone. Purging must not depend on another
74
+ // scheduler write; a failed purge remains closing for that wake/replay.
75
+ yield* ports.purge();
76
+ yield* write({ ...record, phase: "closed" });
77
+ });
78
+ const currentSource = (authority) => ports.source().pipe(Effect.map((source) => source !== null &&
79
+ source.instance.status === "active" &&
80
+ source.instance.stateSchema !== null &&
81
+ matches(authority, {
82
+ selection: source.instance,
83
+ storeGeneration: source.storeGeneration,
84
+ })));
85
+ const live = Effect.gen(function* () {
86
+ const record = yield* read;
87
+ if (record === null || record.phase === "closed")
88
+ return null;
89
+ if (record.phase !== "active" ||
90
+ record.expiresAt <= ports.now() ||
91
+ !(yield* currentSource(record))) {
92
+ yield* close(record);
93
+ return null;
94
+ }
95
+ return record;
96
+ });
97
+ const inspect = (authority) => lock.withPermits(1)(live.pipe(Effect.map((record) => record !== null && matches(record, authority)
98
+ ? metadata(record)
99
+ : null)));
100
+ // The native adapter bounds work. Keep its allocation and invocation under
101
+ // the same permit as retirement, not merely its initial metadata read.
102
+ const withCopy = (authority, copyId, work) => lock.withPermits(1)(Effect.gen(function* () {
103
+ const record = yield* live;
104
+ if (record?.copyId !== copyId || !matches(record, authority))
105
+ return yield* Effect.fail(new AppInstanceError("expired"));
106
+ const result = yield* work(metadata(record));
107
+ const current = yield* live;
108
+ if (current?.copyId !== copyId || !matches(current, authority))
109
+ return yield* Effect.fail(new AppInstanceError("revoked"));
110
+ return result;
111
+ }));
112
+ const open = (authority, requestId) => lock.withPermits(1)(Effect.gen(function* () {
113
+ const input = yield* attempt(() => appTestCopyAuthoritySchema.parse(authority));
114
+ const id = yield* attempt(() => installationRequestIdSchema.parse(requestId));
115
+ if (!(yield* currentSource(input)))
116
+ return yield* Effect.fail(new AppInstanceError("instance_inactive"));
117
+ yield* live;
118
+ const current = yield* read;
119
+ if (current?.phase === "closed" && current.requestId === id)
120
+ return yield* Effect.fail(new AppInstanceError("expired"));
121
+ if (current !== null && current.phase !== "closed") {
122
+ if (current.phase === "active" &&
123
+ current.requestId === id &&
124
+ matches(current, input))
125
+ return metadata(current);
126
+ return yield* Effect.fail(new AppInstanceError("conflicting_owner_state"));
127
+ }
128
+ const record = {
129
+ ...input,
130
+ copyId: appTestCopyIds.copy.generate(),
131
+ requestId: id,
132
+ expiresAt: ports.now() + lifetimeMs,
133
+ phase: "creating",
134
+ };
135
+ yield* write(record);
136
+ return yield* Effect.gen(function* () {
137
+ // Retain cleanup before clone, including a crash before publication.
138
+ yield* ports.wake(record.expiresAt);
139
+ yield* ports.clone();
140
+ const active = { ...record, phase: "active" };
141
+ yield* write(active);
142
+ return metadata(active);
143
+ }).pipe(Effect.onExit((exit) => Exit.isFailure(exit) ? close(record) : Effect.void));
144
+ }));
145
+ const discard = (authority, copyId) => lock.withPermits(1)(Effect.gen(function* () {
146
+ const record = yield* read;
147
+ if (record === null ||
148
+ record.phase === "closed" ||
149
+ record.copyId !== copyId ||
150
+ !matches(record, authority))
151
+ return false;
152
+ yield* close(record);
153
+ return true;
154
+ }));
155
+ const expire = () => lock.withPermits(1)(Effect.gen(function* () {
156
+ const record = yield* read;
157
+ if (record === null || record.phase === "closed")
158
+ return;
159
+ if (record.phase !== "active" || record.expiresAt <= ports.now())
160
+ yield* close(record);
161
+ else
162
+ yield* ports.wake(record.expiresAt);
163
+ }));
164
+ const revoke = () => lock.withPermits(1)(Effect.gen(function* () {
165
+ const record = yield* read;
166
+ if (record !== null && record.phase !== "closed")
167
+ yield* close(record);
168
+ }));
169
+ return { open, inspect, withCopy, discard, expire, revoke };
170
+ }
@@ -0,0 +1,4 @@
1
+ import type { AppTestCopy } from "./app-test-copies.js";
2
+ import type { AppDeclaration } from "@fungi.computer/puffball/app";
3
+ /** Ordinary App mounting, but only the sibling backend/method doors are supplied. */
4
+ export declare function appTestCopyPage(installationId: string, copy: AppTestCopy, declaration: AppDeclaration | null, pageModule: string): Promise<Response>;
@@ -0,0 +1,89 @@
1
+ import { recoveryStyle } from "./recovery-style.js";
2
+ import { html, raw } from "hono/html";
3
+ import { appSandbox } from "./app-sandbox.js";
4
+ /** Ordinary App mounting, but only the sibling backend/method doors are supplied. */
5
+ export async function appTestCopyPage(installationId, copy, declaration, pageModule) {
6
+ const base = `/recovery/${encodeURIComponent(installationId)}/test-copy/${encodeURIComponent(copy.copyId)}`;
7
+ const config = {
8
+ workbench: false,
9
+ shellModuleUrl: null,
10
+ storage: false,
11
+ appsOpen: false,
12
+ computerId: null,
13
+ authorityVersion: copy.selection.authorityVersion,
14
+ commands: declaration?.commands ?? [],
15
+ icon: declaration?.icon ?? null,
16
+ roles: declaration?.roles ?? [],
17
+ capabilities: [],
18
+ installationId,
19
+ appId: copy.selection.appId,
20
+ releaseId: copy.selection.releaseId,
21
+ uiUrl: `/ui/${installationId}/${copy.selection.releaseId}/`,
22
+ backendUrl: `${base}/backend`,
23
+ methodsUrl: `${base}/methods/`,
24
+ };
25
+ return new Response(await html `<!doctype html>
26
+ <html lang="en">
27
+ <meta charset="utf-8" />
28
+ <meta name="viewport" content="width=device-width" />
29
+ <title>Test copy · ${installationId}</title>
30
+ ${recoveryStyle}
31
+ <style>
32
+ html,
33
+ body {
34
+ margin: 0;
35
+ height: 100%;
36
+ }
37
+ body {
38
+ display: flex;
39
+ flex-direction: column;
40
+ }
41
+ iframe {
42
+ border: 0;
43
+ width: 100%;
44
+ flex: 1;
45
+ min-height: 0;
46
+ }
47
+ </style>
48
+ <header class="bar">
49
+ <strong>Disposable test copy: ${installationId}</strong>
50
+ <p class="muted">
51
+ Changes stay in this copy, not the live App. Live capabilities and
52
+ network access are unavailable. Expires at
53
+ ${new Date(copy.expiresAt).toISOString()}.
54
+ </p>
55
+ <form method="post" action="${base}/discard">
56
+ <input
57
+ type="hidden"
58
+ name="authorityVersion"
59
+ value="${copy.selection.authorityVersion}"
60
+ />
61
+ <input
62
+ type="hidden"
63
+ name="storeGeneration"
64
+ value="${copy.storeGeneration}"
65
+ />
66
+ <input type="hidden" name="copyId" value="${copy.copyId}" />
67
+ <button type="submit">Discard test copy</button>
68
+ </form>
69
+ <a href="/recovery">App recovery</a>
70
+ </header>
71
+ <iframe
72
+ id="oyster-app"
73
+ sandbox="${appSandbox}"
74
+ src="${config.uiUrl}"
75
+ title="${installationId} test copy"
76
+ ></iframe>
77
+ <script type="application/json" id="oyster-config">
78
+ ${raw(JSON.stringify(config).replaceAll("<", "\\u003c"))}
79
+ </script>
80
+ <script type="module" src="${pageModule}"></script>
81
+ </html>`, {
82
+ headers: {
83
+ "Content-Type": "text/html; charset=utf-8",
84
+ "Cache-Control": "no-store",
85
+ "X-Content-Type-Options": "nosniff",
86
+ "Content-Security-Policy": "default-src 'none'; script-src 'self'; worker-src 'none'; style-src 'unsafe-inline'; frame-src 'self'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'self'; frame-ancestors 'none'",
87
+ },
88
+ });
89
+ }
@@ -124,8 +124,8 @@ export declare const closeResultSchema: z.ZodObject<{
124
124
  leaseId: z.ZodString;
125
125
  closed: z.ZodLiteral<true>;
126
126
  provider: z.ZodEnum<{
127
- closed: "closed";
128
127
  closing: "closing";
128
+ closed: "closed";
129
129
  }>;
130
130
  }, z.core.$strict>;
131
131
  /** Parsed `markdown` input. */
@@ -5,16 +5,18 @@ import { WorkerEntrypoint } from "cloudflare:workers";
5
5
  import { type GuestLimits } from "./guest-policy.js";
6
6
  export type { GuestLimits } from "./guest-policy.js";
7
7
  import type { ArtifactHeads, ArtifactDeletes, ArtifactStore, ArtifactStreams, VerifiedObjectCache } from "./release.js";
8
- import { type AppBackendBindingName } from "@fungi.computer/puffball/app";
8
+ import { type AppBackendBindingName, type AppMethodCallContext } from "@fungi.computer/puffball/app";
9
9
  import { type InvocationFrame, type InvocationGate } from "./invocation.js";
10
+ import * as Effect from "effect/Effect";
10
11
  import * as Schema from "effect/Schema";
11
12
  import { z } from "zod";
12
13
  import type { ResourceRef } from "./apps/installation.js";
13
- import type { Release } from "@fungi.computer/puffball";
14
+ import type { Release, AppApi } from "@fungi.computer/puffball";
14
15
  import { type UiBootCheckOutcome } from "./boot-gate.js";
16
+ import { type AppTestCopy, type AppTestCopyAuthority, type AppTestCopyPorts } from "./app-test-copies.js";
15
17
  export { checkBackendConstruction } from "./boot-construction.js";
16
18
  import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
17
- import { AppInstanceError, type AppInstance, type InstancePorts } from "./index.js";
19
+ import { AppInstanceError, type AppInstance, type Backend, type InstancePorts } from "./index.js";
18
20
  /**
19
21
  * The zone's edge cache as a {@link VerifiedObjectCache}: each verified object
20
22
  * under a digest-named key on `origin` that no route serves. A failed write is
@@ -122,6 +124,69 @@ export type AppInstanceLoader<FacetClass> = Readonly<{
122
124
  getDurableObjectClass: (exportName: string) => FacetClass;
123
125
  }>;
124
126
  }>;
127
+ /** Verified code and its declaration travel together at the copy boundary. */
128
+ export type AppTestCopyBackend = Backend & Readonly<{
129
+ api: AppApi | null;
130
+ }>;
131
+ /**
132
+ * Disposable App-data siblings use the same native facade and wire decoder as
133
+ * live invocation, but no invocation frame, binding factory or live host env.
134
+ * The surrounding Instance owns current authority and shared alarm scheduling.
135
+ */
136
+ export declare function createCloudflareAppTestCopies<FacetClass>(ctx: AppInstanceContext<FacetClass>, loader: AppInstanceLoader<FacetClass> | undefined, ports: Pick<AppTestCopyPorts, "source" | "wake"> & Readonly<{
137
+ limits?: () => GuestLimits;
138
+ resolve: (releaseId: AppTestCopy["selection"]["releaseId"]) => Effect.Effect<AppTestCopyBackend, Error>;
139
+ }>, limits?: Partial<GuestLimits>): {
140
+ /** Clone current App data once under the retained request and fixed deadline. */
141
+ open: (authority: AppTestCopyAuthority, requestId: string) => Effect.Effect<{
142
+ selection: {
143
+ readonly instanceId: import("./instance-id.js").InstanceId;
144
+ readonly owner: {
145
+ readonly kind: "installation" | "deployment";
146
+ readonly id: string;
147
+ };
148
+ readonly appId: import("@fungi.computer/puffball").AppId;
149
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
150
+ readonly authorityVersion: number;
151
+ };
152
+ storeGeneration: string;
153
+ copyId: string;
154
+ expiresAt: number;
155
+ }, Error | AppInstanceError, never>;
156
+ /** Observe the sibling, retiring expired or unavailable source selections. */
157
+ inspect: (authority: AppTestCopyAuthority) => Effect.Effect<{
158
+ selection: {
159
+ readonly instanceId: import("./instance-id.js").InstanceId;
160
+ readonly owner: {
161
+ readonly kind: "installation" | "deployment";
162
+ readonly id: string;
163
+ };
164
+ readonly appId: import("@fungi.computer/puffball").AppId;
165
+ readonly releaseId: import("@fungi.computer/puffball").ReleaseId;
166
+ readonly authorityVersion: number;
167
+ };
168
+ storeGeneration: string;
169
+ copyId: string;
170
+ expiresAt: number;
171
+ } | null, Error | AppInstanceError, never>;
172
+ /** Discard only this resource, retaining its latest request receipt. */
173
+ discard: (authority: AppTestCopyAuthority, copyId: string) => Effect.Effect<boolean, Error, never>;
174
+ /** Shared native alarm cleanup; incomplete phases need no source service. */
175
+ expire: () => Effect.Effect<void, Error, never>;
176
+ /** Retire the sibling when its owning installation loses authority. */
177
+ revoke: () => Effect.Effect<void, Error, never>;
178
+ /** Run ordinary backend HTTP with bounded bodies and no live bindings. */
179
+ fetch: (authority: AppTestCopyAuthority, copyId: string, request: Request) => Effect.Effect<Response, Error | AppInstanceError, never>;
180
+ /** Use the ordinary typed facade and verified method codecs, without live grants. */
181
+ call: (authority: AppTestCopyAuthority, copyId: string, method: string, input: Schema.Json, caller: AppMethodCallContext) => Effect.Effect<{
182
+ kind: "ok";
183
+ value: z.core.util.JSONType;
184
+ } | {
185
+ kind: "refused";
186
+ code: "invalid" | "unavailable" | "conflict" | "forbidden" | "not_found";
187
+ message: string;
188
+ }, Error | AppInstanceError, never>;
189
+ };
125
190
  /** Stop the shared native App facet at cohort drain or revocation. */
126
191
  export declare function createCloudflareInvocationGate<Host, FacetClass>(ctx: Pick<AppInstanceContext<FacetClass>, "facets">, close: (frame: InvocationFrame<Host>) => Promise<void>): InvocationGate<Host>;
127
192
  /**