@fuzdev/fuz_app 0.143.0 → 0.145.0

package/dist/testing/CLAUDE.md

@@ -968,7 +968,9 @@ source of truth for wire-shape conformance.
   gates `describe_fact_serving_cross_tests` (the cell-scoped per-reference +
   admin-only bare-hash fact-serving parity suite); like cells it stays off the
   declared surface and is `true` on every spine that mounts the serve routes +
-  the `_testing_put_fact` seeder. `ready` gates `describe_ready_cross_tests`
+  the `_testing_put_fact` seeder (whose optional `holder` records a
+  `fact_holder` row, so a non-admin can reference what it seeds) — it also
+  gates `describe_cell_ref_admission_cross_tests`. `ready` gates `describe_ready_cross_tests`
   (anonymous `GET /ready` → `200 {ready: true}` on a clean spine bootstrap);
   like cells/sse the `/ready` deploy gate stays off the declared surface, `true`
   on every spine that live-mounts it over the shared `expected_schema.json`.
@@ -1640,6 +1642,28 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   complete action list plus its own spec. Daemon-token-gated like its siblings;
   the Rust mirror is `fuz_testing::create_testing_action_manifest_action_spec`.
 
+### Cell ref admission parity — `cross_backend/cell_ref_admission.ts`
+
+`describe_cell_ref_admission_cross_tests({setup_test, capabilities, rpc_path?})`
+— possession-gated ref admission over real HTTP: a non-admin `cell_create`
+naming a stored fact it never put and one naming an unstored hash get one
+identical `403 cell_ref_not_held` (status + error body); a system-put fact is
+refused too; the uploader's public cell serves the bytes to anyone; a second
+actor putting identical bytes becomes a holder; an editor keeps refs another
+writer introduced and is refused adding (or restoring a dropped) unheld one; a
+shallow and a deep clone carry each row's source refs, while a patch adding an
+unheld ref or moving a child's ref onto the root is refused; the keeper (a
+global admin) is ungated; a grantee who read a fact through a granted cell
+can't name its hash in a cell of its own, before or after the revoke; the ref
+grammar is exact (prose, markup, `blake3:zz`, uppercase, object keys are not
+refs); and a hidden cell's update, a create under a hidden parent, and a clone
+of a hidden source answer `404` whatever `data` names. Facts are put through
+`cross_put_fact` (exported by `fact_serving.ts`), whose `holder` maps onto
+`_testing_put_fact`'s optional `holder` key. Gated on
+`capabilities.fact_serving`; cross-process only. fuz_app's own wiring is
+`src/test/cross_backend/cell_ref_admission.cross.test.ts`; the in-process
+cases are `src/test/auth/cell_ref_admission{,.fact_less}.db.test.ts`.
+
 ### Token-scope surface parity — `cross_backend/token_scope_surface.ts`
 
 `describe_token_scope_surface_cross_tests({setup_test, capabilities, rpc_path?,

package/dist/testing/cross_backend/cell_crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_crud.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_crud.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6D9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E,eAAO,MAAM,8BAA8B,GAC1C,SAAS,uCAAuC,KAC9C,IA6fF,CAAC"}
+{"version":3,"file":"cell_crud.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_crud.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6D9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAG1E,eAAO,MAAM,8BAA8B,GAC1C,SAAS,uCAAuC,KAC9C,IAggBF,CAAC"}

package/dist/testing/cross_backend/cell_crud.js

@@ -100,14 +100,17 @@ export const describe_cell_crud_cross_tests = (options) => {
         });
         test_if(capabilities.cell_crud, 'refs are deduped and lexicographically sorted (deterministic, cross-impl-identical)', async () => {
             const fixture = await setup_test();
-            const owner = await fixture.create_account({ username: 'cell_refs_owner' });
             const t = fixture.fresh_transport();
-            const owner_headers = owner.create_session_headers();
+            // The keeper — a global admin, whom ref admission doesn't gate — so
+            // fabricated hashes nobody holds are writable refs (a non-admin
+            // writing them is `cell_ref_not_held`, the admission suite's
+            // subject), and the case runs on backends without the fact chain.
+            const owner_headers = fixture.create_session_headers();
             // Three valid distinct fact hashes that sort a < b < c, embedded in
             // `data` in a deliberately unsorted, nested, duplicated order. Both
             // spines must derive `refs` as the sorted [a, b, c] regardless of
             // traversal order or `HashSet` iteration — the byte-identical
-            // cross-backend contract (Rust `extract_refs` ↔ TS `derive_refs`).
+            // cross-backend contract (Rust `extract_refs` ↔ TS `derive_cell_refs`).
             const ref_a = `blake3:${'a'.repeat(64)}`;
             const ref_b = `blake3:${'b'.repeat(64)}`;
             const ref_c = `blake3:${'c'.repeat(64)}`;

package/dist/testing/cross_backend/cell_gated_create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAoE9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAqB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAuTF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IA25BF,CAAC"}
+{"version":3,"file":"cell_gated_create.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_gated_create.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAoE9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AAqB1E,eAAO,MAAM,sCAAsC,GAClD,SAAS,uCAAuC,KAC9C,IAuTF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,kCAAkC,GAC9C,SAAS,uCAAuC,KAC9C,IAs6BF,CAAC"}

package/dist/testing/cross_backend/cell_gated_create.js

@@ -241,37 +241,48 @@ export const describe_cell_gated_create_cross_tests = (options) => {
 export const describe_cell_moderate_cross_tests = (options) => {
     const { setup_test, capabilities } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    // Seed `content` as an embedded fact the author holds (as their upload
+    // would) — a non-admin cell may reference only a fact its writer holds —
+    // and return the post `data` referencing it, `{}` for no fact.
+    const author_post_data = async (fixture, author, post_fact_content) => {
+        if (post_fact_content === undefined)
+            return { post_data: {}, hash: null };
+        const { hash } = expect_output(await cross_rpc_call(
+        // origin-free — the daemon-token middleware discards the credential beside an `Origin`
+        fixture.fresh_transport({ origin: null }), rpc_path, '_testing_put_fact', { content: post_fact_content, holder: author.actor.id }, fixture.create_daemon_token_headers()), TestingPutFactOutput);
+        return { post_data: { cover: hash }, hash };
+    };
     // Build an admin-owned public space (moderated `post` policy) + a
-    // participant's pending post under it.
-    const setup_pending_post_on = async (fixture, post_data = {}) => {
+    // participant's pending post under it, optionally carrying a fact the
+    // author put.
+    const setup_pending_post_on = async (fixture, post_fact_content) => {
         const space = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_create', { kind: SPACE_CELL_KIND, data: SPACE_POLICY, visibility: 'public' }, fixture.create_session_headers()), CellCreateOutput);
         const author = await fixture.create_account({
             username: 'moderate_author',
             roles: [PARTICIPATION_ROLE]
         });
+        const { post_data, hash } = await author_post_data(fixture, author, post_fact_content);
         const post = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_create', { kind: 'post', data: post_data, parent_id: space.cell.id }, author.create_session_headers()), CellCreateOutput);
-        return { fixture, space, author, post };
+        return { fixture, space, author, post, hash };
     };
     const setup_pending_post = async () => setup_pending_post_on(await setup_test());
     // A non-admin's policy root (a parentless non-`space` kind stays open under
     // the test authorizer, and contributions read the policy off any root) + a
-    // participant's pending post under it.
-    const setup_stewarded_post_on = async (fixture, post_data = {}) => {
+    // participant's pending post under it, optionally carrying a fact the author
+    // put.
+    const setup_stewarded_post_on = async (fixture, post_fact_content) => {
         const root_owner = await fixture.create_account({ username: 'steward_root_owner' });
         const root = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_create', { kind: 'forum', data: SPACE_POLICY, visibility: 'public' }, root_owner.create_session_headers()), CellCreateOutput);
         const author = await fixture.create_account({
             username: 'steward_author',
             roles: [PARTICIPATION_ROLE]
         });
+        const { post_data, hash } = await author_post_data(fixture, author, post_fact_content);
         const post = expect_output(await cross_rpc_call(fixture.transport, rpc_path, 'cell_create', { kind: 'post', data: post_data, parent_id: root.cell.id }, author.create_session_headers()), CellCreateOutput);
         assert.strictEqual(post.cell.moderation, 'pending', "the root's policy gates the post");
-        return { fixture, root, root_owner, author, post };
+        return { fixture, root, root_owner, author, post, hash };
     };
     const setup_stewarded_post = async () => setup_stewarded_post_on(await setup_test());
-    /** Seed an embedded fact over the daemon channel; returns its `blake3:` hash. */
-    const put_fact = async (fixture, content) => expect_output(await cross_rpc_call(
-    // origin-free — the daemon-token middleware discards the credential beside an `Origin`
-    fixture.fresh_transport({ origin: null }), rpc_path, '_testing_put_fact', { content }, fixture.create_daemon_token_headers()), TestingPutFactOutput).hash;
     /** The status of a fact GET — `null` headers = anon. */
     const fact_status = async (fixture, path, headers) => {
         const transport = headers === null ? fixture.fresh_transport({ origin: null }) : fixture.transport;
@@ -507,9 +518,8 @@ export const describe_cell_moderate_cross_tests = (options) => {
             assert.deepStrictEqual(await reach(author_h), everywhere, 'author, rejected');
         });
         test_if(capabilities.cell_gated_create && capabilities.fact_serving, "a pending post's fact is 404 to anon, even flipped public; live once approved", async () => {
-            const fixture = await setup_test();
-            const hash = await put_fact(fixture, 'pending-post-fact');
-            const { author, post } = await setup_pending_post_on(fixture, { cover: hash });
+            const { fixture, author, post, hash } = await setup_pending_post_on(await setup_test(), 'pending-post-fact');
+            assert.ok(hash !== null);
             await set_visibility(fixture, author.create_session_headers(), post.cell.id, 'public');
             const path = `/api/cells/${post.cell.id}/facts/${hash}`;
             assert.strictEqual(await fact_status(fixture, path, null), 404, 'anon');
@@ -569,9 +579,8 @@ export const describe_cell_moderate_cross_tests = (options) => {
             assert.strictEqual(await outcome(fixture, 'cell_get', get, null), 'cell_not_found', 'anon');
         });
         test_if(capabilities.cell_gated_create && capabilities.fact_serving, "the root owner fetches a pending post's fact; anon 404", async () => {
-            const fixture = await setup_test();
-            const hash = await put_fact(fixture, 'stewarded-post-fact');
-            const { root_owner, post } = await setup_stewarded_post_on(fixture, { cover: hash });
+            const { fixture, root_owner, post, hash } = await setup_stewarded_post_on(await setup_test(), 'stewarded-post-fact');
+            assert.ok(hash !== null);
             const path = `/api/cells/${post.cell.id}/facts/${hash}`;
             assert.strictEqual(await fact_status(fixture, path, null), 404, 'anon');
             assert.strictEqual(await fact_status(fixture, path, root_owner.create_session_headers()), 200, 'steward');

package/dist/testing/cross_backend/cell_ref_admission.d.ts

@@ -0,0 +1,4 @@
+import '../assert_dev_env.js';
+import type { RpcPathCapabilityGatedCrossSuiteOptions } from './setup.js';
+export declare const describe_cell_ref_admission_cross_tests: (options: RpcPathCapabilityGatedCrossSuiteOptions) => void;
+//# sourceMappingURL=cell_ref_admission.d.ts.map

package/dist/testing/cross_backend/cell_ref_admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_ref_admission.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cell_ref_admission.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA2D9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,YAAY,CAAC;AA6B1E,eAAO,MAAM,uCAAuC,GACnD,SAAS,uCAAuC,KAC9C,IA8eF,CAAC"}

package/dist/testing/cross_backend/cell_ref_admission.js

@@ -0,0 +1,268 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for **possession-gated cell ref admission** — a
+ * non-admin `cell_create` / `cell_update` / `cell_clone` may introduce a fact
+ * ref only to a fact its acting actor holds (a `fact_holder` row, recorded on
+ * every put that names the actor), else `403` with reason
+ * `cell_ref_not_held`. Twins the Rust `fuz_cell_actions` `cell_authz` cases of
+ * the same names, over real HTTP:
+ *
+ * - **create admits a new ref only for a holder** — a stored fact the caller
+ *   never put and a hash nothing is stored under are refused with one
+ *   identical answer (status + error body — no existence oracle), as is a
+ *   system-put fact; the uploader's public cell serves the bytes to anyone; a
+ *   second actor putting identical bytes becomes a holder;
+ * - **update keeps existing refs** — an editor keeps refs another writer
+ *   introduced, and adding an unheld one (or dropping a ref and adding it
+ *   back) is refused;
+ * - **clone carries source refs per row** — a shallow and a deep clone carry
+ *   each row's source refs without holding them; a patch adding an unheld
+ *   ref, or carrying a child's ref onto the root, is refused;
+ * - **a global admin is not gated**;
+ * - **a revoked grantee can't re-reference** — a reader who saw a hash through
+ *   a granted cell can't name it in a cell of its own, before or after the
+ *   revoke (a known hash is not a read capability);
+ * - **extraction parity** — a ref is a whole string value exactly matching
+ *   `blake3:` + 64 lowercase hex: a hash in prose or markup, `blake3:zz`, an
+ *   uppercase digest, and an object key are not refs on either spine;
+ * - **admission answers after the masks** — an update of a hidden cell, a
+ *   create under a hidden parent, and a clone of a hidden source answer `404`
+ *   whatever their `data` names.
+ *
+ * Facts are put through `_testing_put_fact`, with `holder` naming the actor a
+ * real upload would record. Gated on `capabilities.fact_serving` (the
+ * seeder + the serve routes); runs under every `cross_backend_*` project.
+ *
+ * @module
+ */
+import { describe, assert } from 'vitest';
+import { CellCloneOutput, CellCreateOutput, CellGetOutput, CellUpdateOutput } from '../../auth/cell_action_specs.js';
+import { CellGrantCreateOutput } from '../../auth/cell_grant_action_specs.js';
+import { create_rpc_post_init } from '../rpc_helpers.js';
+import { test_if } from './capabilities.js';
+import { cross_rpc_call, error_reason, expect_output } from './cell_cross_helpers.js';
+import { cross_put_fact } from './fact_serving.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+/** The admission refusal's reason, on both spines. */
+const CELL_REF_NOT_HELD = 'cell_ref_not_held';
+/** A well-formed hash no fact is stored under. */
+const UNSTORED_HASH = `blake3:${'e'.repeat(64)}`;
+/** The status + error of a refused RPC call, for comparing two refusals byte for byte. */
+const refusal = async (transport, rpc_path, method, params, headers) => {
+    const init = create_rpc_post_init(method, params);
+    Object.assign(init.headers, headers);
+    const res = await transport(rpc_path, init);
+    const body = (await res.json());
+    assert.ok(body.error !== undefined, `expected a refusal, got ${JSON.stringify(body)}`);
+    return { status: res.status, error: body.error };
+};
+const assert_not_held = (r, label) => {
+    assert.ok(!r.ok, `${label}: expected a refusal, got ${JSON.stringify(r.result)}`);
+    assert.strictEqual(error_reason(r), CELL_REF_NOT_HELD, `${label}: ${JSON.stringify(r.error)}`);
+};
+export const describe_cell_ref_admission_cross_tests = (options) => {
+    const { setup_test, capabilities } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    describe('cell ref admission parity (possession-gated refs)', () => {
+        test_if(capabilities.fact_serving, 'create admits a new ref only for a holder; refusals are identical for stored and unstored hashes', async () => {
+            const fixture = await setup_test();
+            const alice = await fixture.create_account({ username: 'ref_alice' });
+            const bob = await fixture.create_account({ username: 'ref_bob' });
+            const t = fixture.fresh_transport();
+            const bob_headers = bob.create_session_headers();
+            const uploaded = await cross_put_fact(fixture, rpc_path, {
+                content: 'alice photo bytes',
+                holder: alice.actor.id
+            });
+            const seeded = await cross_put_fact(fixture, rpc_path, { content: 'seeded bytes' });
+            // Bob names a stored fact he never put, and a hash nothing is stored
+            // under: both refused, with one identical answer.
+            const stored = await refusal(t, rpc_path, 'cell_create', { kind: 'doc', data: { cover: uploaded }, visibility: 'public' }, bob_headers);
+            const unstored = await refusal(t, rpc_path, 'cell_create', { kind: 'doc', data: { cover: UNSTORED_HASH }, visibility: 'public' }, bob_headers);
+            assert.strictEqual(stored.status, 403);
+            assert.deepStrictEqual(stored, unstored, 'stored vs unstored refusal differs');
+            assert.strictEqual(stored.error.data?.reason, CELL_REF_NOT_HELD);
+            assert.strictEqual(stored.error.message, 'cell data references a fact the caller does not hold');
+            // A system-put fact has no holder at all.
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { files: [seeded] } }, bob_headers), 'system-put ref');
+            // The uploader holds it — her public cell serves the bytes to anyone.
+            const created = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { kind: 'doc', data: { cover: uploaded }, visibility: 'public' }, alice.create_session_headers()), CellCreateOutput);
+            assert.deepStrictEqual(created.cell.refs, [uploaded]);
+            const anon = fixture.fresh_transport({ origin: null });
+            const served = await anon(`/api/cells/${created.cell.id}/facts/${uploaded}`, {
+                method: 'GET'
+            });
+            assert.strictEqual(served.status, 200, 'the uploader’s public cell did not serve');
+            assert.strictEqual(await served.text(), 'alice photo bytes');
+            // Bob puts identical bytes himself: possession, so he holds it too.
+            assert.strictEqual(await cross_put_fact(fixture, rpc_path, {
+                content: 'alice photo bytes',
+                holder: bob.actor.id
+            }), uploaded);
+            expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { cover: uploaded } }, bob_headers), CellCreateOutput);
+        });
+        test_if(capabilities.fact_serving, 'update keeps existing refs and refuses new unheld ones', async () => {
+            const fixture = await setup_test();
+            const alice = await fixture.create_account({ username: 'ref_upd_alice' });
+            const bob = await fixture.create_account({ username: 'ref_upd_bob' });
+            const t = fixture.fresh_transport();
+            const alice_headers = alice.create_session_headers();
+            const bob_headers = bob.create_session_headers();
+            const alices = await cross_put_fact(fixture, rpc_path, {
+                content: 'alice cover bytes',
+                holder: alice.actor.id
+            });
+            const alices_other = await cross_put_fact(fixture, rpc_path, {
+                content: 'alice other bytes',
+                holder: alice.actor.id
+            });
+            const bobs = await cross_put_fact(fixture, rpc_path, {
+                content: 'bob file bytes',
+                holder: bob.actor.id
+            });
+            // Alice's cell carries her ref; Bob edits it through an editor grant.
+            const cell_id = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { cover: alices } }, alice_headers), CellCreateOutput).cell.id;
+            expect_output(await cross_rpc_call(t, rpc_path, 'cell_grant_create', { cell_id, level: 'editor', principal: { kind: 'actor', actor_id: bob.actor.id } }, alice_headers), CellGrantCreateOutput);
+            // Keeping Alice's ref — beside an edit and a ref Bob holds — is admitted.
+            const kept = expect_output(await cross_rpc_call(t, rpc_path, 'cell_update', { cell_id, data: { cover: alices, label: 'edited', file: bobs } }, bob_headers), CellUpdateOutput);
+            assert.deepStrictEqual(kept.cell.refs, [alices, bobs].sort());
+            // Adding one he doesn't hold is refused.
+            for (const added of [alices_other, UNSTORED_HASH]) {
+                assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_update', { cell_id, data: { cover: alices, file: added } }, bob_headers), `update adding ${added}`);
+            }
+            // Dropping a ref and adding it back is a new ref — the base is what
+            // the cell carries now.
+            expect_output(await cross_rpc_call(t, rpc_path, 'cell_update', { cell_id, data: { label: 'dropped' } }, bob_headers), CellUpdateOutput);
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_update', { cell_id, data: { cover: alices } }, bob_headers), 'update restoring a dropped ref');
+        });
+        test_if(capabilities.fact_serving, 'clone carries source refs per row without holding them', async () => {
+            const fixture = await setup_test();
+            const alice = await fixture.create_account({ username: 'ref_clone_alice' });
+            const bob = await fixture.create_account({ username: 'ref_clone_bob' });
+            const t = fixture.fresh_transport();
+            const alice_headers = alice.create_session_headers();
+            const bob_headers = bob.create_session_headers();
+            const cover = await cross_put_fact(fixture, rpc_path, {
+                content: 'cover bytes',
+                holder: alice.actor.id
+            });
+            const attachment = await cross_put_fact(fixture, rpc_path, {
+                content: 'attachment bytes',
+                holder: alice.actor.id
+            });
+            const create = async (data) => expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data, visibility: 'public' }, alice_headers), CellCreateOutput).cell.id;
+            const source = await create({ cover });
+            const child = await create({ file: attachment });
+            const inserted = await cross_rpc_call(t, rpc_path, 'cell_item_insert', { parent_id: source, child_id: child, position: 'a0' }, alice_headers);
+            assert.ok(inserted.ok, JSON.stringify(inserted.error));
+            // Shallow: the root row carries the source's ref.
+            const shallow = expect_output(await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: source }, bob_headers), CellCloneOutput);
+            assert.deepStrictEqual(shallow.cell.refs, [cover]);
+            assert.strictEqual(shallow.cell.created_by, bob.actor.id);
+            // Deep: each child row is checked against its own source row, so the
+            // child's ref — not on the root — is carried too.
+            const deep = expect_output(await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: source, deep: true }, bob_headers), CellCloneOutput);
+            assert.deepStrictEqual(deep.cell.refs, [cover]);
+            const bundle = expect_output(await cross_rpc_call(t, rpc_path, 'cell_get', { id: deep.cell.id }, bob_headers), CellGetOutput);
+            assert.strictEqual(bundle.items.length, 1, 'the deep clone dropped its child');
+            const cloned_child = expect_output(await cross_rpc_call(t, rpc_path, 'cell_get', { id: bundle.items[0].child_id }, bob_headers), CellGetOutput);
+            assert.notStrictEqual(cloned_child.cell.id, child);
+            assert.deepStrictEqual(cloned_child.cell.refs, [attachment]);
+            // A patch introducing an unheld ref is refused, deep or shallow.
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: source, deep: true, with_data_patch: { extra: UNSTORED_HASH } }, bob_headers), 'deep clone with an unheld patch ref');
+            // The child's ref is not on the root: carrying it onto the root through
+            // a patch is a new ref there.
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: source, with_data_patch: { extra: attachment } }, bob_headers), 'clone moving a child ref onto the root');
+        });
+        test_if(capabilities.fact_serving, 'a global admin is not gated on refs', async () => {
+            const fixture = await setup_test();
+            const t = fixture.fresh_transport();
+            const seeded = await cross_put_fact(fixture, rpc_path, { content: 'admin seeded bytes' });
+            // The keeper holds the global admin grant.
+            for (const named of [seeded, UNSTORED_HASH]) {
+                const created = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { cover: named } }, fixture.create_session_headers()), CellCreateOutput);
+                assert.deepStrictEqual(created.cell.refs, [named]);
+            }
+        });
+        test_if(capabilities.fact_serving, 'a revoked grantee cannot re-reference a fact it read', async () => {
+            const fixture = await setup_test();
+            const alice = await fixture.create_account({ username: 'ref_rev_alice' });
+            const bob = await fixture.create_account({ username: 'ref_rev_bob' });
+            const t = fixture.fresh_transport();
+            const alice_headers = alice.create_session_headers();
+            const bob_headers = bob.create_session_headers();
+            const hash = await cross_put_fact(fixture, rpc_path, {
+                content: 'alice private bytes',
+                holder: alice.actor.id
+            });
+            const cell_id = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { file: hash }, visibility: 'private' }, alice_headers), CellCreateOutput).cell.id;
+            const grant = expect_output(await cross_rpc_call(t, rpc_path, 'cell_grant_create', { cell_id, level: 'viewer', principal: { kind: 'actor', actor_id: bob.actor.id } }, alice_headers), CellGrantCreateOutput).grant;
+            // Bob reads the bytes through the granted cell, so he has seen the hash…
+            const read = await t(`/api/cells/${cell_id}/facts/${hash}`, {
+                method: 'GET',
+                headers: bob_headers
+            });
+            assert.strictEqual(read.status, 200, 'the grantee could not read the fact');
+            // …but naming it in a public cell of his own is refused, now and after
+            // the revoke: seeing a hash is not holding the bytes.
+            const republish = { data: { file: hash }, visibility: 'public' };
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_create', republish, bob_headers), 'grantee republish');
+            const revoked = await cross_rpc_call(t, rpc_path, 'cell_grant_revoke', { grant_id: grant.id }, alice_headers);
+            assert.ok(revoked.ok, JSON.stringify(revoked.error));
+            assert_not_held(await cross_rpc_call(t, rpc_path, 'cell_create', republish, bob_headers), 'revoked grantee republish');
+            // The revoked grant also closes the clone path.
+            const clone = await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: cell_id }, bob_headers);
+            assert.strictEqual(error_reason(clone), 'cell_not_found');
+        });
+        test_if(capabilities.fact_serving, 'a ref is a whole exact hash string — prose, markup, malformed, and uppercase are not refs', async () => {
+            const fixture = await setup_test();
+            const bob = await fixture.create_account({ username: 'ref_grammar_bob' });
+            const t = fixture.fresh_transport();
+            const exact = `blake3:${'0123456789abcdef'.repeat(4)}`;
+            const not_refs = {
+                prose: `see ${exact} for details`,
+                markup: `![cover](${exact})`,
+                padded: ` ${exact}`,
+                newline: `${exact}\n`,
+                short: 'blake3:zz',
+                empty_digest: 'blake3:',
+                long: `blake3:${'a'.repeat(65)}`,
+                upper: `blake3:${'0123456789ABCDEF'.repeat(4)}`,
+                other_algo: `sha256:${'a'.repeat(64)}`,
+                keyed: { [exact]: 1 }
+            };
+            // The keeper's write is ungated, so the derived refs show the grammar
+            // alone: none of the near-misses is a ref, the exact hash is.
+            const keeper = fixture.create_session_headers();
+            const none = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: not_refs }, keeper), CellCreateOutput);
+            assert.strictEqual(none.cell.refs, null, JSON.stringify(none.cell.refs));
+            const one = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { ...not_refs, file: exact } }, keeper), CellCreateOutput);
+            assert.deepStrictEqual(one.cell.refs, [exact]);
+            // Not a ref, so a non-admin needs no holding to write it.
+            const prose = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: not_refs }, bob.create_session_headers()), CellCreateOutput);
+            assert.strictEqual(prose.cell.refs, null);
+        });
+        test_if(capabilities.fact_serving, 'ref admission answers after the 404 masks', async () => {
+            const fixture = await setup_test();
+            const alice = await fixture.create_account({ username: 'ref_mask_alice' });
+            const bob = await fixture.create_account({ username: 'ref_mask_bob' });
+            const t = fixture.fresh_transport();
+            const bob_headers = bob.create_session_headers();
+            const alices = await cross_put_fact(fixture, rpc_path, {
+                content: 'alice hidden bytes',
+                holder: alice.actor.id
+            });
+            const hidden = expect_output(await cross_rpc_call(t, rpc_path, 'cell_create', { data: { file: alices }, visibility: 'private' }, alice.create_session_headers()), CellCreateOutput).cell.id;
+            // An update of a hidden cell answers its mask whatever `data` names —
+            // an unheld new ref or the hidden cell's own ref alike.
+            for (const named of [UNSTORED_HASH, alices]) {
+                const r = await cross_rpc_call(t, rpc_path, 'cell_update', { cell_id: hidden, data: { file: named } }, bob_headers);
+                assert.strictEqual(error_reason(r), 'cell_not_found', `update naming ${named}`);
+            }
+            const under = await cross_rpc_call(t, rpc_path, 'cell_create', { data: { file: UNSTORED_HASH }, parent_id: hidden }, bob_headers);
+            assert.strictEqual(error_reason(under), 'cell_not_found', 'create under a hidden parent');
+            const clone = await cross_rpc_call(t, rpc_path, 'cell_clone', { source_id: hidden, with_data_patch: { extra: UNSTORED_HASH } }, bob_headers);
+            assert.strictEqual(error_reason(clone), 'cell_not_found', 'clone of a hidden source');
+        });
+    });
+};

package/dist/testing/cross_backend/expected_schema.json

@@ -33,7 +33,12 @@
 		"scope",
 		"token_hash"
 	],
-	"app_settings": ["id", "open_signup", "updated_at", "updated_by"],
+	"app_settings": [
+		"id",
+		"open_signup",
+		"updated_at",
+		"updated_by"
+	],
 	"audit_log": [
 		"account_id",
 		"actor_id",
@@ -47,8 +52,16 @@
 		"target_account_id",
 		"target_actor_id"
 	],
-	"auth_session": ["account_id", "created_at", "expires_at", "id"],
-	"bootstrap_lock": ["bootstrapped", "id"],
+	"auth_session": [
+		"account_id",
+		"created_at",
+		"expires_at",
+		"id"
+	],
+	"bootstrap_lock": [
+		"bootstrapped",
+		"id"
+	],
 	"cell": [
 		"created_at",
 		"created_by",
@@ -65,7 +78,12 @@
 		"updated_by",
 		"visibility"
 	],
-	"cell_field": ["created_at", "name", "source_id", "target_id"],
+	"cell_field": [
+		"created_at",
+		"name",
+		"source_id",
+		"target_id"
+	],
 	"cell_grant": [
 		"actor_id",
 		"cell_id",
@@ -76,11 +94,44 @@
 		"role",
 		"scope_id"
 	],
-	"cell_item": ["child_id", "created_at", "parent_id", "position"],
-	"fact": ["bytes", "content_type", "created_at", "external_url", "hash", "size"],
-	"fact_ref": ["source_hash", "target_hash"],
-	"invite": ["claimed_at", "claimed_by", "created_at", "created_by", "email", "id", "username"],
-	"memo": ["created_at", "fn_id", "input_hash", "output_hash"],
+	"cell_item": [
+		"child_id",
+		"created_at",
+		"parent_id",
+		"position"
+	],
+	"fact": [
+		"bytes",
+		"content_type",
+		"created_at",
+		"external_url",
+		"hash",
+		"size"
+	],
+	"fact_holder": [
+		"actor_id",
+		"created_at",
+		"hash"
+	],
+	"fact_ref": [
+		"source_hash",
+		"target_hash"
+	],
+	"invite": [
+		"claimed_at",
+		"claimed_by",
+		"created_at",
+		"created_by",
+		"email",
+		"id",
+		"username"
+	],
+	"memo": [
+		"created_at",
+		"fn_id",
+		"input_hash",
+		"output_hash"
+	],
 	"role_grant": [
 		"actor_id",
 		"created_at",
@@ -114,5 +165,10 @@
 		"to_account_id",
 		"to_actor_id"
 	],
-	"schema_version": ["applied_at", "name", "namespace", "sequence"]
+	"schema_version": [
+		"applied_at",
+		"name",
+		"namespace",
+		"sequence"
+	]
 }

package/dist/testing/cross_backend/fact_serving.d.ts

@@ -1,5 +1,5 @@
 import '../assert_dev_env.js';
-import type { RpcPathCapabilityGatedCrossSuiteOptions, SetupTest } from './setup.js';
+import type { RpcPathCapabilityGatedCrossSuiteOptions, SetupTest, TestFixture } from './setup.js';
 /**
  * The fact suite adds one optional knob to the shared cell options: a setup
  * variant whose keeper carries a **second actor**. Only the multi-actor case
@@ -9,5 +9,23 @@ import type { RpcPathCapabilityGatedCrossSuiteOptions, SetupTest } from './setup
 export interface FactServingCrossTestOptions extends RpcPathCapabilityGatedCrossSuiteOptions {
     readonly setup_test_multi_actor?: SetupTest;
 }
+/** Input for `cross_put_fact` — `_testing_put_fact`'s params. */
+export interface CrossPutFactInput {
+    readonly content: string;
+    readonly content_type?: string;
+    /** The actor the put is on behalf of — recorded as a holder. Omit for a system put. */
+    readonly holder?: string;
+}
+/**
+ * Seed an embedded fact over the daemon channel via `_testing_put_fact`;
+ * returns its `blake3:` hash. A `holder` is recorded in `fact_holder` (a
+ * deduplicated put included), as a real upload records its uploader.
+ *
+ * @param fixture - the test fixture (its daemon token drives the backdoor)
+ * @param rpc_path - the backend's RPC path
+ * @param input - the content, optional content type, and optional holder
+ * @returns the fact hash
+ */
+export declare const cross_put_fact: (fixture: Pick<TestFixture, "fresh_transport" | "create_daemon_token_headers">, rpc_path: string, input: CrossPutFactInput) => Promise<string>;
 export declare const describe_fact_serving_cross_tests: (options: FactServingCrossTestOptions) => void;
 //# sourceMappingURL=fact_serving.d.ts.map

package/dist/testing/cross_backend/fact_serving.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fact_serving.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/fact_serving.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA8C9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uCAAuC;IAC3F,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,CAAC;CAC5C;AA8BD,eAAO,MAAM,iCAAiC,GAAI,SAAS,2BAA2B,KAAG,IAiOxF,CAAC"}
+{"version":3,"file":"fact_serving.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/fact_serving.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAiD9B,OAAO,KAAK,EAAE,uCAAuC,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElG;;;;;GAKG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uCAAuC;IAC3F,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,CAAC;CAC5C;AAgBD,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAC1B,SAAS,IAAI,CAAC,WAAW,EAAE,iBAAiB,GAAG,6BAA6B,CAAC,EAC7E,UAAU,MAAM,EAChB,OAAO,iBAAiB,KACtB,OAAO,CAAC,MAAM,CAaV,CAAC;AAgBR,eAAO,MAAM,iCAAiC,GAAI,SAAS,2BAA2B,KAAG,IAgOxF,CAAC"}