commit 93f71808f7400fc4bf34e9973586feb1dee59b43
parent e864478824624dab9df3203164a3591371a66401
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 22:49:37 +0000
storage: enforce local quota and safe cleanup admission (HCP-049)
- Serialize public and preference operation count and wire-byte admission.
- Bind reviewed cleanup to the complete current public inventory.
- Preserve pending, uncertain and corrupt records without automatic eviction.
- Verify quota races, selected cleanup and native transaction rollback.
Diffstat:
5 files changed, 1357 insertions(+), 0 deletions(-)
diff --git a/web/src/lib/persistence/local-inventory.ts b/web/src/lib/persistence/local-inventory.ts
@@ -0,0 +1,44 @@
+import type { PublicRecord } from '../contracts/local-records.ts';
+export type PublicInventoryRow = Readonly<{
+ key: string;
+ family: PublicRecord['family'];
+ id: string;
+ revision: number;
+ logicalBytes: number;
+ state: 'settled' | 'protected';
+}>;
+// Conservative local journal classification, not independently proven relay
+// evidence. Any unresolved historical receipt keeps the operation protected.
+export function publicRecordSettlement(
+ record: PublicRecord
+): 'settled' | 'protected' {
+ if (record.family === 'public_draft') return 'settled';
+ if (
+ !record.artifact ||
+ record.receipts.length === 0 ||
+ record.receipts.some(
+ (receipt) => receipt.status !== 'accepted' && receipt.status !== 'refused'
+ )
+ )
+ return 'protected';
+ return record.capture.targets.every((origin) =>
+ record.receipts.some((receipt) => receipt.origin === origin)
+ )
+ ? 'settled'
+ : 'protected';
+}
+export function publicInventoryRow(
+ record: PublicRecord,
+ logicalBytes: number
+): PublicInventoryRow {
+ return {
+ key: record.family + ':' + record.id,
+ family: record.family,
+ id: record.id,
+ revision: record.revision,
+ logicalBytes,
+ state: publicRecordSettlement(record)
+ };
+}
+export const PUBLIC_CLEANUP_CONSEQUENCES =
+ 'Removing selected records loses their local drafts or recovery receipts. It does not delete remote copies or reverse accepted effects. Pending or uncertain work is protected. Browser-local storage is not a backup.';
diff --git a/web/src/lib/persistence/quota.ts b/web/src/lib/persistence/quota.ts
@@ -0,0 +1,395 @@
+import { canonicalPublicKey } from '../contracts/public-key.ts';
+import {
+ exactLocalFields,
+ type PublicRecord
+} from '../contracts/local-records.ts';
+import { canonicalLocalId } from '../private-handles.ts';
+import { LOCAL_PERSISTENCE_BUDGETS } from '../config/budgets.ts';
+import {
+ browserDatabaseState,
+ browserDatabaseTransaction,
+ type BrowserDatabase
+} from './database.ts';
+import {
+ decodePublicRecord,
+ publicRecordSnapshot,
+ publicRecordWire,
+ type PublicRecordHandle
+} from './records.ts';
+import {
+ publicInventoryRow,
+ PUBLIC_CLEANUP_CONSEQUENCES,
+ type PublicInventoryRow
+} from './local-inventory.ts';
+
+declare const repositoryBrand: unique symbol;
+declare const inventoryBrand: unique symbol;
+declare const cleanupBrand: unique symbol;
+export type PublicQuotaRepository = Readonly<{ [repositoryBrand]: true }>;
+export type PublicInventory = Readonly<{ [inventoryBrand]: true }>;
+export type PublicCleanup = Readonly<{ [cleanupBrand]: true }>;
+export type PublicQuotaFailure =
+ | 'invalid_scope'
+ | 'invalid_record'
+ | 'invalid_selection'
+ | 'protected'
+ | 'conflict'
+ | 'capacity'
+ | 'corrupt_record'
+ | 'unavailable'
+ | 'aborted'
+ | 'unknown_completion';
+export type PublicQuotaResult<T> =
+ | Readonly<{ ok: true; value: T }>
+ | Readonly<{ ok: false; reason: PublicQuotaFailure }>;
+type Scope = Readonly<{ database: BrowserDatabase; owner: string }>;
+type Store = 'public_drafts' | 'public_operations' | 'preference_operations';
+type Row = Readonly<{
+ store: Store;
+ wire: string;
+ record: PublicRecord;
+ bytes: number;
+}>;
+type Inspection = Readonly<{
+ repository: PublicQuotaRepository;
+ rows: readonly Row[];
+}>;
+type Cleanup = Readonly<{ inventory: Inspection; selected: readonly string[] }>;
+const repositories = new WeakMap<PublicQuotaRepository, Scope>();
+const inventories = new WeakMap<PublicInventory, Inspection>();
+const cleanups = new WeakMap<PublicCleanup, Cleanup>();
+const stores: readonly Store[] = [
+ 'public_drafts',
+ 'public_operations',
+ 'preference_operations'
+];
+function failed(reason: PublicQuotaFailure): PublicQuotaResult<never> {
+ return { ok: false, reason };
+}
+function scopeOf(repository: PublicQuotaRepository): Scope | undefined {
+ const scope = repositories.get(repository);
+ try {
+ return scope && browserDatabaseState(scope.database).state === 'ready'
+ ? scope
+ : undefined;
+ } catch {
+ return undefined;
+ }
+}
+// A namespace capability only; installed-account authorization belongs to the
+// account workflow. This repository never acquires any private store.
+export function createPublicQuotaRepository(
+ database: BrowserDatabase,
+ expectedOwner: unknown
+): PublicQuotaRepository | undefined {
+ const owner = canonicalPublicKey(expectedOwner);
+ try {
+ if (!owner || browserDatabaseState(database).state !== 'ready')
+ return undefined;
+ const handle = Object.freeze({}) as PublicQuotaRepository;
+ repositories.set(handle, { database, owner });
+ return handle;
+ } catch {
+ return undefined;
+ }
+}
+function stored(
+ value: unknown,
+ store: Store,
+ owner: string,
+ id: string
+): Row | undefined {
+ if (
+ !exactLocalFields(value, ['owner', 'id', 'wire']) ||
+ value.owner !== owner ||
+ value.id !== id ||
+ typeof value.wire !== 'string'
+ )
+ return undefined;
+ const admitted = decodePublicRecord(value.wire, owner, id);
+ if (!admitted.ok) return undefined;
+ const record = publicRecordSnapshot(admitted.value, owner, id);
+ const family =
+ store === 'public_drafts'
+ ? 'public_draft'
+ : store === 'public_operations'
+ ? 'public_operation'
+ : 'preference_operation';
+ return record?.family === family
+ ? {
+ store,
+ record,
+ wire: value.wire,
+ bytes: new TextEncoder().encode(value.wire).length
+ }
+ : undefined;
+}
+function transaction<T>(
+ scope: Scope,
+ mode: 'readonly' | 'readwrite',
+ finish: (
+ rows: readonly Row[],
+ transaction: IDBTransaction,
+ refuse: (reason: PublicQuotaFailure) => void
+ ) => PublicQuotaResult<T> | undefined
+): Promise<PublicQuotaResult<T>> {
+ let active: IDBTransaction;
+ try {
+ active = browserDatabaseTransaction(scope.database, stores, mode);
+ } catch {
+ return Promise.resolve(failed('unavailable'));
+ }
+ return new Promise((resolve) => {
+ let result: PublicQuotaResult<T> | undefined;
+ let rows = Array.from<Row>([]),
+ draftCount = 0,
+ operationCount = 0,
+ operationBytes = 0;
+ function refuse(reason: PublicQuotaFailure) {
+ result = failed(reason);
+ try {
+ active.abort();
+ } catch {
+ result = failed('unknown_completion');
+ }
+ }
+ active.addEventListener('complete', () =>
+ resolve(result ?? failed('unknown_completion'))
+ );
+ active.addEventListener('abort', () =>
+ resolve(result && !result.ok ? result : failed('aborted'))
+ );
+ function scan(index: number): void {
+ try {
+ const store = stores[index];
+ if (store === undefined) {
+ const finished = finish(rows, active, refuse);
+ if (finished !== undefined) result = finished;
+ return;
+ }
+ const request = active
+ .objectStore(store)
+ .index('by_owner')
+ .openCursor(IDBKeyRange.only(scope.owner));
+ request.addEventListener('success', () => {
+ try {
+ const cursor = request.result;
+ if (!cursor) {
+ scan(index + 1);
+ return;
+ }
+ const key = cursor.primaryKey;
+ const id =
+ Array.isArray(key) && key.length === 2 && key[0] === scope.owner
+ ? canonicalLocalId(key[1])
+ : undefined;
+ const row = id && stored(cursor.value, store, scope.owner, id);
+ if (!row) {
+ refuse('corrupt_record');
+ return;
+ }
+ if (row.record.family === 'public_draft') draftCount++;
+ else {
+ operationCount++;
+ operationBytes += row.bytes;
+ }
+ if (
+ draftCount > LOCAL_PERSISTENCE_BUDGETS.publicDrafts ||
+ operationCount > LOCAL_PERSISTENCE_BUDGETS.publicOperations ||
+ operationBytes > LOCAL_PERSISTENCE_BUDGETS.publicOperationBytes
+ ) {
+ refuse('capacity');
+ return;
+ }
+ rows = rows.concat(row);
+ cursor.continue();
+ } catch {
+ refuse('aborted');
+ }
+ });
+ } catch {
+ refuse('aborted');
+ }
+ }
+ scan(0);
+ });
+}
+// Explicit new-row admission only. Artifact/CAS transitions retain HCP050.
+// Logical bytes include the exact stored record wire, not browser disk/heap use.
+export function admitPublicOperation(
+ repository: PublicQuotaRepository,
+ expectedId: unknown,
+ handle: PublicRecordHandle
+): Promise<PublicQuotaResult<Readonly<{ id: string; revision: number }>>> {
+ const scope = scopeOf(repository),
+ id = canonicalLocalId(expectedId);
+ if (!scope) return Promise.resolve(failed('invalid_scope'));
+ if (!id) return Promise.resolve(failed('invalid_record'));
+ const record = publicRecordSnapshot(handle, scope.owner, id),
+ wire = publicRecordWire(handle, scope.owner, id);
+ if (
+ !record ||
+ !wire ||
+ record.family === 'public_draft' ||
+ record.revision !== 0
+ )
+ return Promise.resolve(failed('invalid_record'));
+ const store: Store =
+ record.family === 'public_operation'
+ ? 'public_operations'
+ : 'preference_operations';
+ const bytes = new TextEncoder().encode(wire).length;
+ return transaction(scope, 'readwrite', (rows, active, refuse) => {
+ const previous = rows.find(
+ (row) => row.store === store && row.record.id === id
+ );
+ if (previous)
+ return previous.wire === wire
+ ? { ok: true, value: { id, revision: 0 } }
+ : (refuse('conflict'), undefined);
+ const operations = rows.filter(
+ (row) => row.record.family !== 'public_draft'
+ );
+ if (
+ operations.length >= LOCAL_PERSISTENCE_BUDGETS.publicOperations ||
+ operations.reduce((sum, row) => sum + row.bytes, bytes) >
+ LOCAL_PERSISTENCE_BUDGETS.publicOperationBytes
+ ) {
+ refuse('capacity');
+ return;
+ }
+ active.objectStore(store).put({ owner: scope.owner, id, wire });
+ return { ok: true, value: { id, revision: 0 } };
+ });
+}
+export function inspectPublicStorage(
+ repository: PublicQuotaRepository
+): Promise<PublicQuotaResult<PublicInventory>> {
+ const scope = scopeOf(repository);
+ if (!scope) return Promise.resolve(failed('invalid_scope'));
+ return transaction(scope, 'readonly', (rows) => {
+ const handle = Object.freeze({}) as PublicInventory;
+ inventories.set(handle, { repository, rows });
+ return { ok: true, value: handle };
+ });
+}
+export function publicInventorySnapshot(
+ repository: PublicQuotaRepository,
+ handle: PublicInventory
+):
+ | Readonly<{ rows: readonly PublicInventoryRow[]; consequences: string }>
+ | undefined {
+ const inventory = inventories.get(handle);
+ return scopeOf(repository) && inventory?.repository === repository
+ ? {
+ rows: inventory.rows.map((row) =>
+ publicInventoryRow(row.record, row.bytes)
+ ),
+ consequences: PUBLIC_CLEANUP_CONSEQUENCES
+ }
+ : undefined;
+}
+export function reviewPublicCleanup(
+ repository: PublicQuotaRepository,
+ handle: PublicInventory,
+ selection: unknown
+): PublicQuotaResult<PublicCleanup> {
+ const inventory = inventories.get(handle);
+ if (!scopeOf(repository) || inventory?.repository !== repository)
+ return failed('invalid_scope');
+ try {
+ if (!Array.isArray(selection)) return failed('invalid_selection');
+ const length = selection.length;
+ if (
+ !Number.isSafeInteger(length) ||
+ length <= 0 ||
+ length >
+ LOCAL_PERSISTENCE_BUDGETS.publicDrafts +
+ LOCAL_PERSISTENCE_BUDGETS.publicOperations
+ )
+ return failed('invalid_selection');
+ let selected = Array.from<string>([]);
+ for (let index = 0; index < length; index++) {
+ const key: unknown = selection[index];
+ if (typeof key !== 'string' || selected.includes(key))
+ return failed('invalid_selection');
+ const row = inventory.rows.find(
+ (row) => publicInventoryRow(row.record, row.bytes).key === key
+ );
+ if (!row) return failed('invalid_selection');
+ if (publicInventoryRow(row.record, row.bytes).state !== 'settled')
+ return failed('protected');
+ selected = selected.concat(key);
+ }
+ if (!scopeOf(repository)) return failed('invalid_scope');
+ const token = Object.freeze({}) as PublicCleanup;
+ cleanups.set(token, { inventory, selected });
+ return { ok: true, value: token };
+ } catch {
+ return failed('invalid_selection');
+ }
+}
+export function publicCleanupSnapshot(
+ repository: PublicQuotaRepository,
+ handle: PublicCleanup
+):
+ | Readonly<{
+ selected: readonly PublicInventoryRow[];
+ logicalBytesRemoved: number;
+ consequences: string;
+ }>
+ | undefined {
+ const cleanup = cleanups.get(handle);
+ if (!scopeOf(repository) || cleanup?.inventory.repository !== repository)
+ return undefined;
+ const selected = cleanup.inventory.rows
+ .map((row) => publicInventoryRow(row.record, row.bytes))
+ .filter((row) => cleanup.selected.includes(row.key));
+ return {
+ selected,
+ logicalBytesRemoved: selected.reduce(
+ (sum, row) => sum + row.logicalBytes,
+ 0
+ ),
+ consequences: PUBLIC_CLEANUP_CONSEQUENCES
+ };
+}
+export function commitPublicCleanup(
+ repository: PublicQuotaRepository,
+ handle: PublicCleanup
+): Promise<PublicQuotaResult<readonly string[]>> {
+ const cleanup = cleanups.get(handle),
+ scope = scopeOf(repository);
+ if (!scope || cleanup?.inventory.repository !== repository)
+ return Promise.resolve(failed('invalid_scope'));
+ return transaction(scope, 'readwrite', (rows, active, refuse) => {
+ const before = cleanup.inventory.rows;
+ if (
+ rows.length !== before.length ||
+ rows.some(
+ (row, i) =>
+ row.store !== before[i].store ||
+ row.record.id !== before[i].record.id ||
+ row.wire !== before[i].wire
+ )
+ ) {
+ refuse('conflict');
+ return;
+ }
+ const selected = rows.filter((row) =>
+ cleanup.selected.includes(publicInventoryRow(row.record, row.bytes).key)
+ );
+ if (
+ selected.length !== cleanup.selected.length ||
+ selected.some(
+ (row) => publicInventoryRow(row.record, row.bytes).state !== 'settled'
+ )
+ ) {
+ refuse('protected');
+ return;
+ }
+ for (const row of selected)
+ active.objectStore(row.store).delete([scope.owner, row.record.id]);
+ return { ok: true, value: Array.from(cleanup.selected) };
+ });
+}
diff --git a/web/tests/e2e/local-inventory.spec.ts b/web/tests/e2e/local-inventory.spec.ts
@@ -0,0 +1,777 @@
+import { expect, test, type Page } from '@playwright/test';
+import { build } from 'vite';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createStaticHarness } from '../integration/harness/static.ts';
+import type * as Database from '../../src/lib/persistence/database.ts';
+import type * as Records from '../../src/lib/persistence/records.ts';
+import type * as Quota from '../../src/lib/persistence/quota.ts';
+import type {
+ PublicOperationRecord,
+ PreferenceOperationRecord
+} from '../../src/lib/contracts/local-records.ts';
+import { getEventHash, finalizeEvent } from 'applesauce-core/helpers';
+import { randomUUID } from 'node:crypto';
+import type * as Drafts from '../../src/lib/persistence/drafts.ts';
+declare global {
+ interface Window {
+ hcp049: typeof Database & typeof Drafts & typeof Quota & typeof Records;
+ hcp049Database: Database.BrowserDatabase;
+ hcp049Repository: Drafts.PublicDraftRepository;
+ hcp049Quota: Quota.PublicQuotaRepository;
+ }
+}
+const owner =
+ '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798';
+const form = {
+ title: '',
+ description: 'unfinished',
+ location: '',
+ amount: '.',
+ currency: '',
+ unit: '',
+ quantity: '',
+ contactType: '' as const,
+ contactValue: ''
+};
+let server: Awaited<ReturnType<typeof createStaticHarness>>;
+let bundle: string;
+test.beforeAll(async () => {
+ server = await createStaticHarness();
+ const source = (name: string) =>
+ fileURLToPath(
+ new URL('../../src/lib/persistence/' + name, import.meta.url)
+ );
+ // Compile the exact current production modules together so both use the same
+ // genuine WeakMap database ownership. This virtual entry is test-only.
+ const result = await build({
+ configFile: false,
+ logLevel: 'silent',
+ plugins: [
+ {
+ name: 'hcp049-test-entry',
+ resolveId(id) {
+ if (id === 'virtual:hcp049') return '\0hcp049';
+ },
+ load(id) {
+ if (id === '\0hcp049')
+ return `export * from ${JSON.stringify(source('database.ts'))};export * from ${JSON.stringify(source('drafts.ts'))};export * from ${JSON.stringify(source('quota.ts'))};export * from ${JSON.stringify(source('records.ts'))};`;
+ }
+ }
+ ],
+ build: {
+ write: false,
+ minify: false,
+ rolldownOptions: { input: 'virtual:hcp049' },
+ lib: { entry: 'virtual:hcp049', name: 'hcp049', formats: ['iife'] }
+ }
+ });
+ const output = Array.isArray(result) ? result[0] : result;
+ if (!('output' in output)) throw new Error('missing test bundle');
+ const chunks = output.output.filter((item) => item.type === 'chunk');
+ expect(chunks).toHaveLength(1);
+ bundle = chunks[0].code;
+ console.log(
+ JSON.stringify({
+ fixture: 'HCP049_ACTUAL_MODULES_REAL_IDB',
+ bundleSha256: createHash('sha256').update(bundle).digest('hex'),
+ exposure: 'test-only virtual entry, no production route or dependency'
+ })
+ );
+});
+test.afterAll(async () => server.close());
+async function load(page: Page, selectedOwner = owner) {
+ await page.goto(server.url + '/search');
+ await page.addScriptTag({ content: bundle });
+ await page.evaluate(async (expectedOwner) => {
+ const api = window.hcp049;
+ const opened = await api.openBrowserDatabase();
+ if (opened.state !== 'ready') throw new Error(opened.reason);
+ const repository = api.createPublicDraftRepository(
+ opened.owner,
+ expectedOwner
+ );
+ if (!repository) throw new Error('missing repository');
+ window.hcp049Database = opened.owner;
+ window.hcp049Repository = repository;
+ const quota = api.createPublicQuotaRepository(opened.owner, expectedOwner);
+ if (!quota) throw new Error('missing quota repository');
+ window.hcp049Quota = quota;
+ }, selectedOwner);
+}
+function operation(content = 'public quota fixture'): PublicOperationRecord {
+ const id = randomUUID();
+ const template = {
+ pubkey: owner,
+ kind: 30402,
+ created_at: 100,
+ tags: [
+ ['d', 'quota'],
+ ['published_at', '100']
+ ],
+ content
+ };
+ return {
+ schema: 1,
+ family: 'public_operation',
+ owner,
+ id,
+ revision: 0,
+ source: { type: 'draft', id, revision: 0 },
+ capture: {
+ kind: 30402,
+ wire: JSON.stringify(template),
+ hash: getEventHash(template),
+ targets: ['wss://one.example.org'],
+ policyFingerprint: 'a'.repeat(64)
+ },
+ artifact: null,
+ receipts: []
+ };
+}
+async function admit(
+ page: Page,
+ row: PublicOperationRecord | PreferenceOperationRecord
+) {
+ return page.evaluate(async (row) => {
+ const api = window.hcp049;
+ const decoded = api.decodePublicRecord(
+ JSON.stringify(row),
+ row.owner,
+ row.id
+ );
+ if (!decoded.ok) throw new Error(decoded.reason);
+ return api.admitPublicOperation(window.hcp049Quota, row.id, decoded.value);
+ }, row);
+}
+async function seed(
+ page: Page,
+ rows: readonly (PublicOperationRecord | PreferenceOperationRecord)[]
+) {
+ await page.evaluate(async (rows) => {
+ const api = window.hcp049;
+ for (const row of rows) {
+ const decoded = api.decodePublicRecord(
+ JSON.stringify(row),
+ row.owner,
+ row.id
+ );
+ if (!decoded.ok) throw new Error(decoded.reason);
+ }
+ const transaction = api.browserDatabaseTransaction(
+ window.hcp049Database,
+ ['public_operations', 'preference_operations'],
+ 'readwrite'
+ );
+ for (const row of rows)
+ transaction
+ .objectStore(
+ row.family === 'public_operation'
+ ? 'public_operations'
+ : 'preference_operations'
+ )
+ .put({ owner: row.owner, id: row.id, wire: JSON.stringify(row) });
+ await new Promise<void>((resolve, reject) => {
+ transaction.addEventListener('complete', () => resolve());
+ transaction.addEventListener('abort', () =>
+ reject(new Error('fixture seed aborted'))
+ );
+ });
+ }, rows);
+}
+test('two genuine tabs race the final operation slot; refusal preserves all original records', async ({
+ page,
+ context
+}) => {
+ await load(page);
+ const initial = Array.from({ length: 99 }, () => operation());
+ await seed(page, initial);
+ const second = await context.newPage();
+ await load(second);
+ const candidates = [operation(), operation()];
+ const results = await Promise.all([
+ admit(page, candidates[0]),
+ admit(second, candidates[1])
+ ]);
+ expect(results.filter((row) => row.ok)).toHaveLength(1);
+ expect(results.filter((row) => !row.ok)).toEqual([
+ { ok: false, reason: 'capacity' }
+ ]);
+ const snapshot = await page.evaluate(async () => {
+ const result = await window.hcp049.inspectPublicStorage(window.hcp049Quota);
+ if (!result.ok) throw new Error(result.reason);
+ return window.hcp049.publicInventorySnapshot(
+ window.hcp049Quota,
+ result.value
+ );
+ });
+ expect(snapshot?.rows).toHaveLength(100);
+ for (const row of initial)
+ expect(snapshot?.rows.some((stored) => stored.id === row.id)).toBe(true);
+ await second.close();
+});
+test('aggregate 8MiB logical wire admission rejects before count100 and keeps the existing bytes', async ({
+ page
+}) => {
+ await load(page);
+ const sample = operation('p'.repeat(220000));
+ const size = Buffer.byteLength(JSON.stringify(sample));
+ const count = Math.floor(8388608 / size);
+ expect(count).toBeLessThan(100);
+ const rows = Array.from({ length: count }, () => ({
+ ...sample,
+ id: randomUUID()
+ }));
+ await seed(page, rows);
+ expect(await admit(page, { ...sample, id: randomUUID() })).toEqual({
+ ok: false,
+ reason: 'capacity'
+ });
+ const result = await page.evaluate(async () => {
+ const api = window.hcp049,
+ inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ return api.publicInventorySnapshot(window.hcp049Quota, inv.value);
+ });
+ expect(result?.rows).toHaveLength(count);
+ expect(result?.rows.reduce((sum, row) => sum + row.logicalBytes, 0)).toBe(
+ count * size
+ );
+});
+test('reviewed draft cleanup reports local-loss consequences and atomically deletes only the selected record', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp049;
+ const first = await api.createPublicDraft(window.hcp049Repository, form);
+ const second = await api.createPublicDraft(window.hcp049Repository, {
+ ...form,
+ title: 'keep'
+ });
+ if (!first.ok || !second.ok) throw new Error('missing drafts');
+ const inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ const key = 'public_draft:' + first.value.id;
+ const reviewed = api.reviewPublicCleanup(window.hcp049Quota, inv.value, [
+ key
+ ]);
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ const impact = api.publicCleanupSnapshot(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ const committed = await api.commitPublicCleanup(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ const rows = await api.listPublicDrafts(window.hcp049Repository);
+ return { impact, committed, rows, second: second.value, key };
+ }, form);
+ expect(result.impact?.selected).toHaveLength(1);
+ expect(result.impact?.consequences).toContain(
+ 'does not delete remote copies'
+ );
+ expect(result.committed).toEqual({ ok: true, value: [result.key] });
+ expect(result.rows).toEqual({ ok: true, value: [result.second] });
+});
+test('pending capture is protected and changed inventory conflicts without partial deletion', async ({
+ page
+}) => {
+ await load(page);
+ const row = operation();
+ expect((await admit(page, row)).ok).toBe(true);
+ const result = await page.evaluate(
+ async ({ form, row }) => {
+ const api = window.hcp049;
+ const draft = await api.createPublicDraft(window.hcp049Repository, form);
+ if (!draft.ok) throw new Error(draft.reason);
+ const inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ const protectedResult = api.reviewPublicCleanup(
+ window.hcp049Quota,
+ inv.value,
+ ['public_operation:' + row.id]
+ );
+ const reviewed = api.reviewPublicCleanup(window.hcp049Quota, inv.value, [
+ 'public_draft:' + draft.value.id
+ ]);
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ const updated = await api.savePublicDraft(
+ window.hcp049Repository,
+ draft.value.id,
+ 0,
+ { ...form, title: 'new revision' }
+ );
+ const committed = await api.commitPublicCleanup(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ const retained = await api.readPublicDraft(
+ window.hcp049Repository,
+ draft.value.id
+ );
+ return { protectedResult, updated, committed, retained };
+ },
+ { form, row }
+ );
+ expect(result.protectedResult).toEqual({ ok: false, reason: 'protected' });
+ expect(result.committed).toEqual({ ok: false, reason: 'conflict' });
+ expect(result.retained).toEqual(result.updated);
+});
+test('an unknown record added after review aborts cleanup; fixed public stores never enumerate private metadata', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp049;
+ const draft = await api.createPublicDraft(window.hcp049Repository, form);
+ if (!draft.ok) throw new Error(draft.reason);
+ const inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ const reviewed = api.reviewPublicCleanup(window.hcp049Quota, inv.value, [
+ 'public_draft:' + draft.value.id
+ ]);
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ const transaction = api.browserDatabaseTransaction(
+ window.hcp049Database,
+ ['public_operations', 'private_sends'],
+ 'readwrite'
+ );
+ transaction.objectStore('public_operations').put({
+ owner: draft.value.owner,
+ id: '3d030bf5-901d-45e1-8251-41cbdf805e96',
+ wire: '{"schema":99}'
+ });
+ transaction.objectStore('private_sends').put({
+ owner: draft.value.owner,
+ id: 'b1d6d23d-79f3-4779-9b03-e289712cc73f',
+ wire: 'private metadata sentinel'
+ });
+ await new Promise<void>((resolve, reject) => {
+ transaction.addEventListener('complete', () => resolve());
+ transaction.addEventListener('abort', () =>
+ reject(new Error('fixture abort'))
+ );
+ });
+ const acquired: string[][] = [];
+ const descriptor = Object.getOwnPropertyDescriptor(
+ IDBDatabase.prototype,
+ 'transaction'
+ );
+ if (!descriptor) throw new Error('missing transaction descriptor');
+ const original = descriptor.value as IDBDatabase['transaction'];
+ IDBDatabase.prototype.transaction = function (storeNames, mode, options) {
+ acquired.push(
+ typeof storeNames === 'string' ? [storeNames] : Array.from(storeNames)
+ );
+ return original.call(this, storeNames, mode, options);
+ };
+ try {
+ const committed = await api.commitPublicCleanup(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ const retained = await api.readPublicDraft(
+ window.hcp049Repository,
+ draft.value.id
+ );
+ return { committed, retained, acquired };
+ } finally {
+ IDBDatabase.prototype.transaction = original;
+ }
+ }, form);
+ expect(result.committed).toEqual({ ok: false, reason: 'corrupt_record' });
+ expect(result.retained.ok).toBe(true);
+ expect(
+ result.acquired
+ .flat()
+ .every((store) =>
+ [
+ 'public_drafts',
+ 'public_operations',
+ 'preference_operations'
+ ].includes(store)
+ )
+ ).toBe(true);
+});
+
+test('cleanup selection reads the reviewed indexed array rather than a replaced iterator', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp049;
+ const first = await api.createPublicDraft(window.hcp049Repository, form);
+ const second = await api.createPublicDraft(window.hcp049Repository, form);
+ if (!first.ok || !second.ok) throw new Error('missing drafts');
+ const inventory = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inventory.ok) throw new Error(inventory.reason);
+ const firstKey = 'public_draft:' + first.value.id;
+ const secondKey = 'public_draft:' + second.value.id;
+ const selection = [firstKey];
+ let iteratorReads = 0;
+ selection[Symbol.iterator] = () => {
+ iteratorReads++;
+ return [secondKey].values();
+ };
+ const reviewed = api.reviewPublicCleanup(
+ window.hcp049Quota,
+ inventory.value,
+ selection
+ );
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ return {
+ impact: api.publicCleanupSnapshot(window.hcp049Quota, reviewed.value),
+ firstKey,
+ iteratorReads
+ };
+ }, form);
+ expect(result.iteratorReads).toBe(0);
+ expect(result.impact?.selected.map((row) => row.key)).toEqual([
+ result.firstKey
+ ]);
+});
+
+function preference(
+ content = 'public inbox preference fixture'
+): PreferenceOperationRecord {
+ const id = randomUUID();
+ const template = {
+ pubkey: owner,
+ kind: 10050,
+ created_at: 100,
+ tags: [],
+ content
+ };
+ return {
+ schema: 1,
+ family: 'preference_operation',
+ owner,
+ id,
+ revision: 0,
+ consent: 'explicit_review',
+ source: { type: 'inbox_head', wire: null },
+ capture: {
+ kind: 10050,
+ wire: JSON.stringify(template),
+ hash: getEventHash(template),
+ targets: ['wss://one.example.org'],
+ policyFingerprint: 'a'.repeat(64)
+ },
+ artifact: null,
+ receipts: []
+ };
+}
+test('public and preference journals share the count ceiling and exact-wire idempotent replay', async ({
+ page
+}) => {
+ await load(page);
+ const first = operation();
+ expect((await admit(page, first)).ok).toBe(true);
+ expect(await admit(page, first)).toEqual({
+ ok: true,
+ value: { id: first.id, revision: 0 }
+ });
+ await seed(
+ page,
+ Array.from({ length: 98 }, (_, index) =>
+ index % 2 ? operation() : preference()
+ )
+ );
+ const last = preference();
+ expect((await admit(page, last)).ok).toBe(true);
+ expect(await admit(page, operation())).toEqual({
+ ok: false,
+ reason: 'capacity'
+ });
+ const snapshot = await page.evaluate(async () => {
+ const api = window.hcp049,
+ inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ return api.publicInventorySnapshot(window.hcp049Quota, inv.value);
+ });
+ expect(snapshot?.rows).toHaveLength(100);
+ expect(
+ snapshot?.rows.filter((row) => row.family === 'preference_operation')
+ ).toHaveLength(50);
+});
+test('mixed preference/public exact stored wires share the 8MiB aggregate ceiling', async ({
+ page
+}) => {
+ await load(page);
+ const publicSample = operation('p'.repeat(220000)),
+ preferenceSample = preference('q'.repeat(220000));
+ let bytes = 0;
+ const rows: (PublicOperationRecord | PreferenceOperationRecord)[] = [];
+ for (let index = 0; index < 100; index++) {
+ const row = {
+ ...(index % 2 ? preferenceSample : publicSample),
+ id: randomUUID()
+ };
+ const size = Buffer.byteLength(JSON.stringify(row));
+ if (bytes + size > 8388608) break;
+ rows.push(row);
+ bytes += size;
+ }
+ await seed(page, rows);
+ expect(await admit(page, { ...preferenceSample, id: randomUUID() })).toEqual({
+ ok: false,
+ reason: 'capacity'
+ });
+ const snapshot = await page.evaluate(async () => {
+ const api = window.hcp049,
+ inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ return api.publicInventorySnapshot(window.hcp049Quota, inv.value);
+ });
+ expect(snapshot?.rows.reduce((sum, row) => sum + row.logicalBytes, 0)).toBe(
+ bytes
+ );
+ expect(
+ snapshot?.rows.some((row) => row.family === 'preference_operation')
+ ).toBe(true);
+});
+function signedSettledOperation(): PublicOperationRecord {
+ const key = crypto.getRandomValues(new Uint8Array(32));
+ try {
+ const base = finalizeEvent(
+ {
+ kind: 30402,
+ created_at: 100,
+ tags: [['d', 'quota']],
+ content: 'public signature fixture'
+ },
+ key
+ );
+ const template = {
+ pubkey: base.pubkey,
+ kind: 30402,
+ created_at: 101,
+ tags: [['d', 'quota']],
+ content: 'public settled artifact fixture'
+ };
+ const hash = getEventHash(template);
+ const wire = JSON.stringify(template);
+ const artifact = finalizeEvent(
+ { ...template, tags: template.tags.map((tag) => [...tag]) },
+ key
+ );
+ const id = randomUUID();
+ return {
+ schema: 1,
+ family: 'public_operation',
+ owner: base.pubkey,
+ id,
+ revision: 0,
+ source: { type: 'draft', id, revision: 0 },
+ capture: {
+ kind: 30402,
+ wire,
+ hash,
+ targets: ['wss://one.example.org'],
+ policyFingerprint: 'a'.repeat(64)
+ },
+ artifact: { eventId: artifact.id, wire: JSON.stringify(artifact) },
+ receipts: [
+ {
+ actionId: randomUUID(),
+ origin: 'wss://one.example.org',
+ role: 'publication',
+ attempt: 1,
+ eventId: artifact.id,
+ status: 'accepted',
+ observedAtMilliseconds: 1000,
+ readbackWire: null
+ }
+ ]
+ };
+ } finally {
+ key.fill(0);
+ }
+}
+test('actual verified signed settled operation permits reviewed local cleanup; unresolved history remains protected', async ({
+ page
+}) => {
+ const settled = signedSettledOperation();
+ await load(page, settled.owner);
+ const uncertain: PublicOperationRecord = {
+ ...settled,
+ id: randomUUID(),
+ receipts: [
+ ...settled.receipts,
+ {
+ ...settled.receipts[0],
+ status: 'unknown',
+ observedAtMilliseconds: 1001
+ }
+ ]
+ };
+ expect((await admit(page, settled)).ok).toBe(true);
+ expect((await admit(page, uncertain)).ok).toBe(true);
+ const result = await page.evaluate(
+ async ({ settled, uncertain }) => {
+ const api = window.hcp049,
+ inv = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inv.ok) throw new Error(inv.reason);
+ const denied = api.reviewPublicCleanup(window.hcp049Quota, inv.value, [
+ 'public_operation:' + uncertain.id
+ ]);
+ const reviewed = api.reviewPublicCleanup(window.hcp049Quota, inv.value, [
+ 'public_operation:' + settled.id
+ ]);
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ const removed = await api.commitPublicCleanup(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ const next = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!next.ok) throw new Error(next.reason);
+ return {
+ denied,
+ removed,
+ remaining: api.publicInventorySnapshot(window.hcp049Quota, next.value)
+ };
+ },
+ { settled, uncertain }
+ );
+ expect(result.denied).toEqual({ ok: false, reason: 'protected' });
+ expect(result.removed).toEqual({
+ ok: true,
+ value: ['public_operation:' + settled.id]
+ });
+ expect(result.remaining?.rows.map((row) => row.id)).toEqual([uncertain.id]);
+});
+test('successful native put and delete requests followed by transaction abort never acknowledge or lose records', async ({
+ page
+}) => {
+ await load(page);
+ const row = operation();
+ const result = await page.evaluate(
+ async ({ row, form }) => {
+ const api = window.hcp049;
+ const decoded = api.decodePublicRecord(
+ JSON.stringify(row),
+ row.owner,
+ row.id
+ );
+ if (!decoded.ok) throw new Error(decoded.reason);
+ const putDescriptor = Object.getOwnPropertyDescriptor(
+ IDBObjectStore.prototype,
+ 'put'
+ );
+ const deleteDescriptor = Object.getOwnPropertyDescriptor(
+ IDBObjectStore.prototype,
+ 'delete'
+ );
+ if (!putDescriptor || !deleteDescriptor)
+ throw new Error('missing native methods');
+ const nativePut = putDescriptor.value as IDBObjectStore['put'];
+ const nativeDelete = deleteDescriptor.value as IDBObjectStore['delete'];
+ let putSuccesses = 0,
+ deleteSuccesses = 0;
+ IDBObjectStore.prototype.put = function (...args) {
+ const request = nativePut.apply(this, args);
+ request.addEventListener('success', () => {
+ putSuccesses++;
+ this.transaction.abort();
+ });
+ return request;
+ };
+ let inserted: Quota.PublicQuotaResult<
+ Readonly<{ id: string; revision: number }>
+ >;
+ try {
+ inserted = await api.admitPublicOperation(
+ window.hcp049Quota,
+ row.id,
+ decoded.value
+ );
+ } finally {
+ Object.defineProperty(IDBObjectStore.prototype, 'put', putDescriptor);
+ }
+ const draft = await api.createPublicDraft(window.hcp049Repository, form);
+ if (!draft.ok) throw new Error(draft.reason);
+ const inventory = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inventory.ok) throw new Error(inventory.reason);
+ const reviewed = api.reviewPublicCleanup(
+ window.hcp049Quota,
+ inventory.value,
+ ['public_draft:' + draft.value.id]
+ );
+ if (!reviewed.ok) throw new Error(reviewed.reason);
+ IDBObjectStore.prototype.delete = function (...args) {
+ const request = nativeDelete.apply(this, args);
+ request.addEventListener('success', () => {
+ deleteSuccesses++;
+ this.transaction.abort();
+ });
+ return request;
+ };
+ let deleted: Quota.PublicQuotaResult<readonly string[]>;
+ try {
+ deleted = await api.commitPublicCleanup(
+ window.hcp049Quota,
+ reviewed.value
+ );
+ } finally {
+ Object.defineProperty(
+ IDBObjectStore.prototype,
+ 'delete',
+ deleteDescriptor
+ );
+ }
+ const retained = await api.readPublicDraft(
+ window.hcp049Repository,
+ draft.value.id
+ );
+ const next = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!next.ok) throw new Error(next.reason);
+ return {
+ inserted,
+ deleted,
+ putSuccesses,
+ deleteSuccesses,
+ retained,
+ inventory: api.publicInventorySnapshot(window.hcp049Quota, next.value)
+ };
+ },
+ { row, form }
+ );
+ expect(result.putSuccesses).toBe(1);
+ expect(result.deleteSuccesses).toBe(1);
+ expect(result.inserted).toEqual({ ok: false, reason: 'aborted' });
+ expect(result.deleted).toEqual({ ok: false, reason: 'aborted' });
+ expect(result.retained.ok).toBe(true);
+ expect(result.inventory?.rows).toHaveLength(1);
+ expect(result.inventory?.rows[0].family).toBe('public_draft');
+});
+
+test('negative proxy-array length cannot mint an empty cleanup authorization', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp049;
+ const draft = await api.createPublicDraft(window.hcp049Repository, form);
+ if (!draft.ok) throw new Error(draft.reason);
+ const inventory = await api.inspectPublicStorage(window.hcp049Quota);
+ if (!inventory.ok) throw new Error(inventory.reason);
+ let indexedReads = 0;
+ const selection = new Proxy(['public_draft:' + draft.value.id], {
+ get(target, key, receiver) {
+ if (key === 'length') return -1;
+ if (key === '0') indexedReads++;
+ return Reflect.get(target, key, receiver) as unknown;
+ }
+ });
+ const reviewed = api.reviewPublicCleanup(
+ window.hcp049Quota,
+ inventory.value,
+ selection
+ );
+ return { reviewed, indexedReads };
+ }, form);
+ expect(result.reviewed).toEqual({ ok: false, reason: 'invalid_selection' });
+ expect(result.indexedReads).toBe(0);
+});
diff --git a/web/tests/integration/local-inventory.test.ts b/web/tests/integration/local-inventory.test.ts
@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ createPublicQuotaRepository,
+ inspectPublicStorage,
+ reviewPublicCleanup,
+ commitPublicCleanup,
+ type PublicQuotaRepository,
+ type PublicInventory,
+ type PublicCleanup
+} from '../../src/lib/persistence/quota.ts';
+import type { BrowserDatabase } from '../../src/lib/persistence/database.ts';
+await test('actual public quota API denies fabricated guest capabilities without private storage acquisition', async () => {
+ const database = Object.freeze({
+ kind: 'browser_database'
+ }) as BrowserDatabase;
+ assert.equal(
+ createPublicQuotaRepository(
+ database,
+ '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
+ ),
+ undefined
+ );
+ const repository = Object.freeze({}) as PublicQuotaRepository;
+ assert.deepEqual(await inspectPublicStorage(repository), {
+ ok: false,
+ reason: 'invalid_scope'
+ });
+ assert.deepEqual(
+ reviewPublicCleanup(repository, Object.freeze({}) as PublicInventory, []),
+ { ok: false, reason: 'invalid_scope' }
+ );
+ assert.deepEqual(
+ await commitPublicCleanup(repository, Object.freeze({}) as PublicCleanup),
+ { ok: false, reason: 'invalid_scope' }
+ );
+});
diff --git a/web/tests/unit/local-inventory.test.ts b/web/tests/unit/local-inventory.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import type { PublicOperationRecord } from '../../src/lib/contracts/local-records.ts';
+import {
+ publicRecordSettlement,
+ publicInventoryRow,
+ PUBLIC_CLEANUP_CONSEQUENCES
+} from '../../src/lib/persistence/local-inventory.ts';
+const id = '3d030bf5-901d-45e1-8251-41cbdf805e96';
+const row: PublicOperationRecord = {
+ schema: 1,
+ family: 'public_operation',
+ owner: '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
+ id,
+ revision: 0,
+ source: { type: 'draft', id, revision: 0 },
+ capture: {
+ kind: 30402,
+ wire: 'controlled policy input only',
+ hash: 'a'.repeat(64),
+ targets: ['wss://one.example.org', 'wss://two.example.org'],
+ policyFingerprint: 'b'.repeat(64)
+ },
+ artifact: null,
+ receipts: []
+};
+// Pure classification only; these deliberately controlled policy inputs grant
+// no storage capability. Actual codecs/native IDB qualify browser admission.
+function receipt(
+ origin: string,
+ status: 'accepted' | 'refused' | 'unknown' | 'timed_out' | 'stopped'
+) {
+ return {
+ actionId: id,
+ origin,
+ role: 'publication' as const,
+ attempt: 1,
+ eventId: 'a'.repeat(64),
+ status,
+ observedAtMilliseconds: 1000,
+ readbackWire: null
+ };
+}
+describe('conservative public cleanup policy', () => {
+ it('unsigned capture and signed intent with no receipts stay protected', () => {
+ expect(publicRecordSettlement(row)).toBe('protected');
+ expect(
+ publicRecordSettlement({
+ ...row,
+ artifact: { eventId: 'a'.repeat(64), wire: 'controlled' }
+ })
+ ).toBe('protected');
+ });
+ it('missing target evidence stays protected', () => {
+ expect(
+ publicRecordSettlement({
+ ...row,
+ artifact: { eventId: 'a'.repeat(64), wire: 'controlled' },
+ receipts: [receipt(row.capture.targets[0], 'accepted')]
+ })
+ ).toBe('protected');
+ });
+ for (const status of ['unknown', 'timed_out', 'stopped'] as const)
+ it(
+ 'retains unresolved ' +
+ status +
+ ' even alongside later positive observations',
+ () => {
+ expect(
+ publicRecordSettlement({
+ ...row,
+ artifact: { eventId: 'a'.repeat(64), wire: 'controlled' },
+ receipts: [
+ receipt(row.capture.targets[0], status),
+ receipt(row.capture.targets[0], 'accepted'),
+ receipt(row.capture.targets[1], 'accepted')
+ ]
+ })
+ ).toBe('protected');
+ }
+ );
+ it('all named terminal observations allow local settlement without claiming remote deletion', () => {
+ const record = {
+ ...row,
+ artifact: { eventId: 'a'.repeat(64), wire: 'controlled' },
+ receipts: [
+ receipt(row.capture.targets[0], 'accepted'),
+ receipt(row.capture.targets[1], 'refused')
+ ]
+ };
+ expect(publicRecordSettlement(record)).toBe('settled');
+ expect(publicInventoryRow(record, 123)).toEqual({
+ key: 'public_operation:' + id,
+ family: 'public_operation',
+ id,
+ revision: 0,
+ logicalBytes: 123,
+ state: 'settled'
+ });
+ expect(PUBLIC_CLEANUP_CONSEQUENCES).toContain(
+ 'does not delete remote copies'
+ );
+ expect(PUBLIC_CLEANUP_CONSEQUENCES).toContain('not a backup');
+ });
+});