commit e864478824624dab9df3203164a3591371a66401
parent 7c22a771f5c267fa5d92673cc2f072d1ba4367b8
Author: triesap <tyson@radroots.org>
Date: Tue, 6 Oct 2026 22:21:56 +0000
storage: add single-worker public draft autosave (HCP-048)
- Retain immutable draft IDs, revisions, times and forms through uncertain writes
- Coalesce pending edits without replacing current input with older acknowledgments
- Flush and recheck the latest edit before closing the public draft controller
- Verify lifecycle reentry, explicit recovery and genuine browser persistence
Diffstat:
5 files changed, 1151 insertions(+), 92 deletions(-)
diff --git a/web/src/lib/persistence/drafts.ts b/web/src/lib/persistence/drafts.ts
@@ -2,7 +2,8 @@ import { boundedUtf8 } from '../contracts/food-availability-v1/text.ts';
import { canonicalPublicKey } from '../contracts/public-key.ts';
import {
exactLocalFields,
- type PublicDraftRecord
+ type PublicDraftRecord,
+ type PublicDraftForm
} from '../contracts/local-records.ts';
import { canonicalLocalId, newLocalId } from '../private-handles.ts';
import { safeUnsignedInteger } from '../nostr/envelope-bounds.ts';
@@ -63,12 +64,16 @@ export function createPublicDraftRepository(
return undefined;
}
}
-function proposed(
- owner: string,
- id: string,
- revision: number,
+export function publicDraftRepositoryOwner(
+ repository: PublicDraftRepository
+): string | undefined {
+ return scopeOf(repository)?.owner;
+}
+
+// This copy is form admission only: no ID/time capture, storage or effect.
+export function publicDraftFormSnapshot(
form: unknown
-): PublicDraftRecord | undefined {
+): PublicDraftForm | undefined {
try {
if (
!exactLocalFields(form, [
@@ -84,9 +89,7 @@ function proposed(
])
)
return undefined;
- // Capture each caller field once before validating that captured value.
- // Even a changing Proxy cannot substitute a coercible object after a check.
- const captured = {
+ const copy = {
title: form.title,
description: form.description,
location: form.location,
@@ -98,33 +101,62 @@ function proposed(
contactValue: form.contactValue
};
if (
- captured.contactType !== '' &&
- captured.contactType !== 'email' &&
- captured.contactType !== 'phone' &&
- captured.contactType !== 'https'
+ typeof copy.title !== 'string' ||
+ typeof copy.description !== 'string' ||
+ typeof copy.location !== 'string' ||
+ typeof copy.amount !== 'string' ||
+ typeof copy.currency !== 'string' ||
+ typeof copy.unit !== 'string' ||
+ typeof copy.quantity !== 'string' ||
+ typeof copy.contactValue !== 'string' ||
+ (copy.contactType !== '' &&
+ copy.contactType !== 'email' &&
+ copy.contactType !== 'phone' &&
+ copy.contactType !== 'https')
)
return undefined;
- let composedBytes = 0;
+ let bytes = 0;
for (const text of [
- captured.title,
- captured.description,
- captured.location,
- captured.amount,
- captured.currency,
- captured.unit,
- captured.quantity,
- captured.contactType,
- captured.contactValue
+ copy.title,
+ copy.description,
+ copy.location,
+ copy.amount,
+ copy.currency,
+ copy.unit,
+ copy.quantity,
+ copy.contactType,
+ copy.contactValue
]) {
- if (
- typeof text !== 'string' ||
- !boundedUtf8(text, LOCAL_PERSISTENCE_BUDGETS.draftComposedBytes)
- )
+ if (!boundedUtf8(text, LOCAL_PERSISTENCE_BUDGETS.draftComposedBytes))
return undefined;
- composedBytes += new TextEncoder().encode(text).length;
- if (composedBytes > LOCAL_PERSISTENCE_BUDGETS.draftComposedBytes)
+ bytes += new TextEncoder().encode(text).length;
+ if (bytes > LOCAL_PERSISTENCE_BUDGETS.draftComposedBytes)
return undefined;
}
+ return {
+ title: copy.title,
+ description: copy.description,
+ location: copy.location,
+ amount: copy.amount,
+ currency: copy.currency,
+ unit: copy.unit,
+ quantity: copy.quantity,
+ contactType: copy.contactType,
+ contactValue: copy.contactValue
+ };
+ } catch {
+ return undefined;
+ }
+}
+function proposed(
+ owner: string,
+ id: string,
+ revision: number,
+ form: unknown
+): PublicDraftRecord | undefined {
+ try {
+ const captured = publicDraftFormSnapshot(form);
+ if (!captured) return undefined;
const row = {
schema: 1,
family: 'public_draft',
@@ -212,36 +244,10 @@ export function createPublicDraft(
repository: PublicDraftRepository,
form: unknown
): Promise<DraftResult<PublicDraftRecord>> {
- const scope = scopeOf(repository);
- if (!scope) return Promise.resolve(failed('invalid_scope'));
- const id = newLocalId();
- if (!id) return Promise.resolve(failed('invalid_id'));
- const row = proposed(scope.owner, id, 0, form);
- if (!row) return Promise.resolve(failed('invalid_form'));
- return transaction(scope, 'readwrite', (store, decide, refuse) => {
- const collision = store.get([scope.owner, id]);
- collision.addEventListener('success', () => {
- if (collision.result !== undefined) {
- refuse('conflict');
- return;
- }
- const count = store
- .index('by_owner')
- .count(IDBKeyRange.only(scope.owner));
- count.addEventListener('success', () => {
- if (count.result >= LOCAL_PERSISTENCE_BUDGETS.publicDrafts) {
- refuse('cap_reached');
- return;
- }
- const put = store.put({
- owner: scope.owner,
- id,
- wire: JSON.stringify(row)
- });
- put.addEventListener('success', () => decide({ ok: true, value: row }));
- });
- });
- });
+ const captured = capturePublicDraftCreate(repository, form);
+ return captured.ok
+ ? commitPublicDraftWrite(repository, captured.value)
+ : Promise.resolve(captured);
}
export function readPublicDraft(
repository: PublicDraftRepository,
@@ -273,39 +279,15 @@ export function savePublicDraft(
expectedRevision: unknown,
form: unknown
): Promise<DraftResult<PublicDraftRecord>> {
- const scope = scopeOf(repository),
- id = canonicalLocalId(expectedId);
- if (!scope) return Promise.resolve(failed('invalid_scope'));
- if (!id) return Promise.resolve(failed('invalid_id'));
- const revision = safeUnsignedInteger(expectedRevision);
- if (revision === undefined || revision === Number.MAX_SAFE_INTEGER)
- return Promise.resolve(failed('invalid_revision'));
- const row = proposed(scope.owner, id, revision + 1, form);
- if (!row) return Promise.resolve(failed('invalid_form'));
- return transaction(scope, 'readwrite', (store, decide, refuse) => {
- const request = store.get([scope.owner, id]);
- request.addEventListener('success', () => {
- if (request.result === undefined) {
- refuse('not_found');
- return;
- }
- const previous = stored(request.result, scope.owner, id);
- if (!previous) {
- refuse('corrupt_record');
- return;
- }
- if (previous.revision !== revision) {
- refuse('conflict');
- return;
- }
- const put = store.put({
- owner: scope.owner,
- id,
- wire: JSON.stringify(row)
- });
- put.addEventListener('success', () => decide({ ok: true, value: row }));
- });
- });
+ const captured = capturePublicDraftSave(
+ repository,
+ expectedId,
+ expectedRevision,
+ form
+ );
+ return captured.ok
+ ? commitPublicDraftWrite(repository, captured.value)
+ : Promise.resolve(captured);
}
export function listPublicDrafts(
repository: PublicDraftRepository
@@ -343,3 +325,156 @@ export function listPublicDrafts(
});
});
}
+
+// Immutable attempted local writes retain their original ID, revision, time and
+// full form. They authorize only this repository's bounded local transaction.
+declare const writeBrand: unique symbol;
+export type PublicDraftWrite = Readonly<{ [writeBrand]: true }>;
+type Write = Readonly<{
+ repository: PublicDraftRepository;
+ wire: string;
+ expectedRevision: number | null;
+}>;
+const writes = new WeakMap<PublicDraftWrite, Write>();
+function capture(
+ repository: PublicDraftRepository,
+ id: string,
+ expectedRevision: number | null,
+ form: unknown
+): DraftResult<PublicDraftWrite> {
+ const scope = scopeOf(repository);
+ if (!scope) return failed('invalid_scope');
+ const row = proposed(
+ scope.owner,
+ id,
+ expectedRevision === null ? 0 : expectedRevision + 1,
+ form
+ );
+ if (!row) return failed('invalid_form');
+ const handle = Object.freeze({}) as PublicDraftWrite;
+ writes.set(handle, {
+ repository,
+ wire: JSON.stringify(row),
+ expectedRevision
+ });
+ return { ok: true, value: handle };
+}
+export function capturePublicDraftCreate(
+ repository: PublicDraftRepository,
+ form: unknown
+): DraftResult<PublicDraftWrite> {
+ if (!scopeOf(repository)) return failed('invalid_scope');
+ const id = newLocalId();
+ return id ? capture(repository, id, null, form) : failed('invalid_id');
+}
+export function capturePublicDraftSave(
+ repository: PublicDraftRepository,
+ expectedId: unknown,
+ expectedRevision: unknown,
+ form: unknown
+): DraftResult<PublicDraftWrite> {
+ if (!scopeOf(repository)) return failed('invalid_scope');
+ const id = canonicalLocalId(expectedId),
+ revision = safeUnsignedInteger(expectedRevision);
+ if (!id) return failed('invalid_id');
+ if (revision === undefined || revision === Number.MAX_SAFE_INTEGER)
+ return failed('invalid_revision');
+ return capture(repository, id, revision, form);
+}
+function writeOf(
+ repository: PublicDraftRepository,
+ handle: PublicDraftWrite
+): Write | undefined {
+ const write = writes.get(handle);
+ return scopeOf(repository) && write?.repository === repository
+ ? write
+ : undefined;
+}
+export function publicDraftWriteSnapshot(
+ repository: PublicDraftRepository,
+ handle: PublicDraftWrite
+): PublicDraftRecord | undefined {
+ const write = writeOf(repository, handle);
+ return write ? (JSON.parse(write.wire) as PublicDraftRecord) : undefined;
+}
+export function commitPublicDraftWrite(
+ repository: PublicDraftRepository,
+ handle: PublicDraftWrite
+): Promise<DraftResult<PublicDraftRecord>> {
+ const write = writeOf(repository, handle),
+ scope = scopeOf(repository);
+ if (!write || !scope) return Promise.resolve(failed('invalid_scope'));
+ const row = JSON.parse(write.wire) as PublicDraftRecord;
+ return transaction(scope, 'readwrite', (store, decide, refuse) => {
+ const request = store.get([scope.owner, row.id]);
+ request.addEventListener('success', () => {
+ if (request.result !== undefined) {
+ const previous = stored(request.result, scope.owner, row.id);
+ if (!previous) {
+ refuse('corrupt_record');
+ return;
+ }
+ if (JSON.stringify(previous) === write.wire) {
+ decide({ ok: true, value: row });
+ return;
+ }
+ if (
+ write.expectedRevision === null ||
+ previous.revision !== write.expectedRevision
+ ) {
+ refuse('conflict');
+ return;
+ }
+ const put = store.put({
+ owner: scope.owner,
+ id: row.id,
+ wire: write.wire
+ });
+ put.addEventListener('success', () => decide({ ok: true, value: row }));
+ return;
+ }
+ if (write.expectedRevision !== null) {
+ refuse('not_found');
+ return;
+ }
+ const count = store
+ .index('by_owner')
+ .count(IDBKeyRange.only(scope.owner));
+ count.addEventListener('success', () => {
+ if (count.result >= LOCAL_PERSISTENCE_BUDGETS.publicDrafts) {
+ refuse('cap_reached');
+ return;
+ }
+ const put = store.put({
+ owner: scope.owner,
+ id: row.id,
+ wire: write.wire
+ });
+ put.addEventListener('success', () => decide({ ok: true, value: row }));
+ });
+ });
+ });
+}
+export type DraftWriteObservation =
+ | Readonly<{ state: 'committed'; value: PublicDraftRecord }>
+ | Readonly<{ state: 'base_observed' }>
+ | Readonly<{ state: 'conflict' }>
+ | Readonly<{ state: 'unavailable'; reason: DraftFailure }>;
+export async function observePublicDraftWrite(
+ repository: PublicDraftRepository,
+ handle: PublicDraftWrite
+): Promise<DraftWriteObservation> {
+ const write = writeOf(repository, handle);
+ if (!write) return { state: 'unavailable', reason: 'invalid_scope' };
+ const expected = JSON.parse(write.wire) as PublicDraftRecord;
+ const read = await readPublicDraft(repository, expected.id);
+ if (!read.ok)
+ return read.reason === 'not_found' && write.expectedRevision === null
+ ? { state: 'base_observed' }
+ : { state: 'unavailable', reason: read.reason };
+ if (JSON.stringify(read.value) === write.wire)
+ return { state: 'committed', value: read.value };
+ return read.value.revision === write.expectedRevision
+ ? { state: 'base_observed' }
+ : { state: 'conflict' };
+}
diff --git a/web/src/lib/publishing/draft-controller.ts b/web/src/lib/publishing/draft-controller.ts
@@ -0,0 +1,256 @@
+import type {
+ PublicDraftForm,
+ PublicDraftRecord
+} from '../contracts/local-records.ts';
+import {
+ capturePublicDraftCreate,
+ capturePublicDraftSave,
+ commitPublicDraftWrite,
+ observePublicDraftWrite,
+ publicDraftFormSnapshot,
+ publicDraftWriteSnapshot,
+ publicDraftRepositoryOwner,
+ readPublicDraft,
+ type PublicDraftRepository,
+ type PublicDraftWrite,
+ type DraftFailure
+} from '../persistence/drafts.ts';
+
+declare const controllerBrand: unique symbol;
+export type PublicDraftController = Readonly<{ [controllerBrand]: true }>;
+export type DraftControllerSnapshot = Readonly<{
+ form: PublicDraftForm;
+ editVersion: number;
+ savedEditVersion: number;
+ draft: PublicDraftRecord | null;
+ state: 'editing' | 'saving' | 'saved' | 'failed' | 'closed';
+ failure: DraftFailure | null;
+}>;
+type Controller = {
+ edit(form: unknown): boolean;
+ flush(): Promise<boolean>;
+ retry(): Promise<boolean>;
+ saveClose(): Promise<boolean>;
+ close(): void;
+ snapshot(): DraftControllerSnapshot;
+};
+const controllers = new WeakMap<PublicDraftController, Controller>();
+export async function createPublicDraftController(
+ repository: PublicDraftRepository,
+ initialForm: unknown,
+ existingId?: string
+): Promise<PublicDraftController | undefined> {
+ if (!publicDraftRepositoryOwner(repository)) return undefined;
+ const initial = publicDraftFormSnapshot(initialForm);
+ if (!initial || !publicDraftRepositoryOwner(repository)) return undefined;
+ let saved: PublicDraftRecord | null = null;
+ if (existingId !== undefined) {
+ const read = await readPublicDraft(repository, existingId);
+ if (!read.ok || !publicDraftRepositoryOwner(repository)) return undefined;
+ saved = read.value;
+ }
+ let form = saved ? saved.form : initial;
+ let editVersion = 0,
+ savedEditVersion = saved ? 0 : -1;
+ let state: DraftControllerSnapshot['state'] = saved ? 'saved' : 'editing';
+ let failure: DraftFailure | null = null;
+ let closed = false;
+ let active: Promise<void> | undefined;
+ let attempted:
+ Readonly<{ capturedWrite: PublicDraftWrite; version: number }> | undefined;
+ // Exactly one captured attempt survives unknown receipts. Pending form is
+ // separate; acknowledging a prior attempt never replaces that current form.
+ async function resolveAttempt(): Promise<boolean> {
+ const current = attempted;
+ if (!current || closed) return false;
+ state = 'saving';
+ const expected = publicDraftWriteSnapshot(
+ repository,
+ current.capturedWrite
+ );
+ if (!expected) {
+ failure = 'invalid_scope';
+ state = 'failed';
+ return false;
+ }
+ const result = await commitPublicDraftWrite(
+ repository,
+ current.capturedWrite
+ );
+ if (closed) return false;
+ let receipt: PublicDraftRecord | undefined;
+ if (result.ok && JSON.stringify(result.value) === JSON.stringify(expected))
+ receipt = result.value;
+ else if (!result.ok && result.reason === 'unknown_completion') {
+ const observed = await observePublicDraftWrite(
+ repository,
+ current.capturedWrite
+ );
+ if (closed) return false;
+ if (
+ observed.state === 'committed' &&
+ JSON.stringify(observed.value) === JSON.stringify(expected)
+ )
+ receipt = observed.value;
+ else
+ failure =
+ observed.state === 'conflict'
+ ? 'conflict'
+ : observed.state === 'unavailable'
+ ? observed.reason
+ : 'unknown_completion';
+ } else failure = result.ok ? 'unknown_completion' : result.reason;
+ if (!receipt) {
+ state = 'failed';
+ return false;
+ }
+ saved = receipt;
+ savedEditVersion = current.version;
+ attempted = undefined;
+ failure = null;
+ state = savedEditVersion === editVersion ? 'saved' : 'editing';
+ return true;
+ }
+ async function pump(): Promise<void> {
+ while (!closed && failure === null && savedEditVersion !== editVersion) {
+ if (!attempted) {
+ const capturedVersion = editVersion;
+ const capturedForm = form;
+ const captured = saved
+ ? capturePublicDraftSave(
+ repository,
+ saved.id,
+ saved.revision,
+ capturedForm
+ )
+ : capturePublicDraftCreate(repository, capturedForm);
+ if (closed) return;
+ if (!captured.ok) {
+ failure = captured.reason;
+ state = 'failed';
+ return;
+ }
+ attempted = { capturedWrite: captured.value, version: capturedVersion };
+ }
+ if (!(await resolveAttempt())) return;
+ }
+ }
+ function start(): Promise<void> {
+ if (active) return active;
+ // Queue one owned worker so synchronous edits coalesce before capture.
+ const work = Promise.resolve()
+ .then(pump)
+ .catch(() => {
+ if (!closed) {
+ failure = 'unknown_completion';
+ state = 'failed';
+ }
+ })
+ .finally(() => {
+ active = undefined;
+ if (!closed && failure === null && savedEditVersion !== editVersion)
+ void start();
+ });
+ active = work;
+ return work;
+ }
+ const value: Controller = {
+ edit(input) {
+ if (closed || editVersion === Number.MAX_SAFE_INTEGER) return false;
+ const next = publicDraftFormSnapshot(input);
+ if (!next || closed || editVersion === Number.MAX_SAFE_INTEGER)
+ return false;
+ form = next;
+ editVersion++;
+ if (failure === null) {
+ state = 'editing';
+ void start();
+ }
+ return true;
+ },
+ async flush() {
+ if (closed || failure !== null) return false;
+ while (!closed && failure === null && savedEditVersion !== editVersion)
+ await start();
+ return !closed && failure === null && savedEditVersion === editVersion;
+ },
+ async retry() {
+ if (closed) return false;
+ if (active) await active;
+ if (closed) return false;
+ failure = null;
+ // Retained attempt is committed/read back as originally captured, never
+ // replaced with a new ID, time or payload during uncertain recovery.
+ while (!closed && failure === null && savedEditVersion !== editVersion)
+ await start();
+ return !closed && failure === null && savedEditVersion === editVersion;
+ },
+ async saveClose() {
+ while (await value.flush()) {
+ // The await permits a pending edit or lifecycle close. Check the exact
+ // current version and close together without another asynchronous gap.
+ if (closed || failure !== null) return false;
+ if (savedEditVersion !== editVersion) continue;
+ value.close();
+ return true;
+ }
+ return false;
+ },
+ close() {
+ if (closed) return;
+ closed = true;
+ state = 'closed';
+ // A native transaction already submitted may complete; its late result
+ // cannot alter this closed controller or trigger another write.
+ attempted = undefined;
+ },
+ snapshot() {
+ return {
+ form: { ...form },
+ editVersion,
+ savedEditVersion,
+ draft: saved
+ ? (JSON.parse(JSON.stringify(saved)) as PublicDraftRecord)
+ : null,
+ state,
+ failure
+ };
+ }
+ };
+ const handle = Object.freeze({}) as PublicDraftController;
+ controllers.set(handle, value);
+ return handle;
+}
+export function editPublicDraft(
+ controller: PublicDraftController,
+ form: unknown
+): boolean {
+ return controllers.get(controller)?.edit(form) ?? false;
+}
+export function publicDraftControllerSnapshot(
+ controller: PublicDraftController
+): DraftControllerSnapshot | undefined {
+ return controllers.get(controller)?.snapshot();
+}
+export function flushPublicDraft(
+ controller: PublicDraftController
+): Promise<boolean> {
+ return controllers.get(controller)?.flush() ?? Promise.resolve(false);
+}
+export function retryPublicDraft(
+ controller: PublicDraftController
+): Promise<boolean> {
+ return controllers.get(controller)?.retry() ?? Promise.resolve(false);
+}
+// Ordinary save-close is gated by a successful flush. Lifecycle/identity
+// teardown uses explicit close instead and makes no successful-save claim.
+export function saveAndClosePublicDraft(
+ controller: PublicDraftController
+): Promise<boolean> {
+ return controllers.get(controller)?.saveClose() ?? Promise.resolve(false);
+}
+export function closePublicDraftController(
+ controller: PublicDraftController
+): void {
+ controllers.get(controller)?.close();
+}
diff --git a/web/tests/e2e/draft-controller.spec.ts b/web/tests/e2e/draft-controller.spec.ts
@@ -0,0 +1,341 @@
+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 Controller from '../../src/lib/publishing/draft-controller.ts';
+import type * as Drafts from '../../src/lib/persistence/drafts.ts';
+declare global {
+ interface Window {
+ hcp048: typeof Database & typeof Drafts & typeof Controller;
+ hcp048Database: Database.BrowserDatabase;
+ hcp048Repository: Drafts.PublicDraftRepository;
+ }
+}
+const owner =
+ '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798';
+const peer = 'c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5';
+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: 'hcp048-test-entry',
+ resolveId(id) {
+ if (id === 'virtual:hcp048') return '\0hcp048';
+ },
+ load(id) {
+ if (id === '\0hcp048')
+ return `export * from ${JSON.stringify(source('database.ts'))};export * from ${JSON.stringify(source('drafts.ts'))};export * from ${JSON.stringify(source('../publishing/draft-controller.ts'))};`;
+ }
+ }
+ ],
+ build: {
+ write: false,
+ minify: false,
+ rolldownOptions: { input: 'virtual:hcp048' },
+ lib: { entry: 'virtual:hcp048', name: 'hcp048', 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: 'HCP048_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.hcp048;
+ 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.hcp048Database = opened.owner;
+ window.hcp048Repository = repository;
+ }, selectedOwner);
+}
+test('immutable capture replays the exact committed ID/time/form once and denies foreign handles', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(
+ async ({ form, peer }) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ const captured = api.capturePublicDraftCreate(repository, form);
+ if (!captured.ok) throw new Error(captured.reason);
+ const before = api.publicDraftWriteSnapshot(repository, captured.value);
+ if (!before) throw new Error('missing snapshot');
+ const immutable = JSON.stringify(before);
+ const mutable = before.form as { title: string };
+ mutable.title = 'foreign';
+ const absent = await api.observePublicDraftWrite(
+ repository,
+ captured.value
+ );
+ const first = await api.commitPublicDraftWrite(
+ repository,
+ captured.value
+ );
+ const replay = await api.commitPublicDraftWrite(
+ repository,
+ captured.value
+ );
+ const observed = await api.observePublicDraftWrite(
+ repository,
+ captured.value
+ );
+ const other = api.createPublicDraftRepository(
+ window.hcp048Database,
+ peer
+ );
+ if (!other) throw new Error('missing foreign namespace');
+ const foreign = await api.commitPublicDraftWrite(other, captured.value);
+ const rows = await api.listPublicDrafts(repository);
+ return { immutable, absent, first, replay, observed, foreign, rows };
+ },
+ { form, peer }
+ );
+ expect(result.absent).toEqual({ state: 'base_observed' });
+ expect(result.first).toEqual({
+ ok: true,
+ value: JSON.parse(
+ result.immutable
+ ) as import('../../src/lib/contracts/local-records.ts').PublicDraftRecord
+ });
+ expect(result.replay).toEqual(result.first);
+ expect(result.observed).toEqual({
+ state: 'committed',
+ value: JSON.parse(
+ result.immutable
+ ) as import('../../src/lib/contracts/local-records.ts').PublicDraftRecord
+ });
+ expect(result.foreign).toEqual({ ok: false, reason: 'invalid_scope' });
+ expect(result.rows).toEqual({
+ ok: true,
+ value: [
+ JSON.parse(
+ result.immutable
+ ) as import('../../src/lib/contracts/local-records.ts').PublicDraftRecord
+ ]
+ });
+});
+test('genuine autosave coalesces pending edits, resumes durable input, and flushes before save-close', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ const controller = await api.createPublicDraftController(repository, form);
+ if (!controller) throw new Error('missing controller');
+ api.editPublicDraft(controller, { ...form, title: 'first' });
+ api.editPublicDraft(controller, { ...form, title: 'latest', amount: '1.' });
+ const flushed = await api.flushPublicDraft(controller);
+ const saved = api.publicDraftControllerSnapshot(controller);
+ if (!saved?.draft) throw new Error('missing saved draft');
+ const resumed = await api.createPublicDraftController(
+ repository,
+ form,
+ saved.draft.id
+ );
+ if (!resumed) throw new Error('missing resumed controller');
+ api.editPublicDraft(resumed, {
+ ...saved.form,
+ description: 'newer partial'
+ });
+ const closed = await api.saveAndClosePublicDraft(resumed);
+ const final = api.publicDraftControllerSnapshot(resumed);
+ const retained = await api.readPublicDraft(repository, saved.draft.id);
+ const late = api.editPublicDraft(resumed, form);
+ return { flushed, saved, closed, final, retained, late };
+ }, form);
+ expect(result.flushed).toBe(true);
+ expect(result.saved).toMatchObject({
+ state: 'saved',
+ editVersion: 2,
+ savedEditVersion: 2,
+ draft: { revision: 0 },
+ form: { title: 'latest', amount: '1.' }
+ });
+ expect(result.closed).toBe(true);
+ expect(result.final).toMatchObject({
+ state: 'closed',
+ draft: { revision: 1, form: { description: 'newer partial' } }
+ });
+ expect(result.retained).toEqual({ ok: true, value: result.final?.draft });
+ expect(result.late).toBe(false);
+});
+test('owner capacity refusal retains dirty input and prevents save-close without deleting drafts', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ for (let i = 0; i < 20; i++) {
+ const created = await api.createPublicDraft(repository, form);
+ if (!created.ok) throw new Error(created.reason);
+ }
+ const controller = await api.createPublicDraftController(repository, form);
+ if (!controller) throw new Error('missing controller');
+ api.editPublicDraft(controller, { ...form, title: 'retain dirty input' });
+ const closed = await api.saveAndClosePublicDraft(controller);
+ const snapshot = api.publicDraftControllerSnapshot(controller);
+ const rows = await api.listPublicDrafts(repository);
+ return { closed, snapshot, count: rows.ok ? rows.value.length : -1 };
+ }, form);
+ expect(result.closed).toBe(false);
+ expect(result.snapshot).toMatchObject({
+ state: 'failed',
+ failure: 'cap_reached',
+ form: { title: 'retain dirty input' },
+ savedEditVersion: -1,
+ draft: null
+ });
+ expect(result.count).toBe(20);
+});
+test('an advanced competing revision conflicts with the original capture and keeps the current input', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ const created = await api.createPublicDraft(repository, form);
+ if (!created.ok) throw new Error(created.reason);
+ const capture = api.capturePublicDraftSave(
+ repository,
+ created.value.id,
+ 0,
+ { ...form, title: 'attempted' }
+ );
+ if (!capture.ok) throw new Error(capture.reason);
+ const competitor = await api.savePublicDraft(
+ repository,
+ created.value.id,
+ 0,
+ { ...form, title: 'competitor' }
+ );
+ const observed = await api.observePublicDraftWrite(
+ repository,
+ capture.value
+ );
+ const commit = await api.commitPublicDraftWrite(repository, capture.value);
+ const retained = await api.readPublicDraft(repository, created.value.id);
+ return { competitor, observed, commit, retained };
+ }, form);
+ expect(result.competitor.ok).toBe(true);
+ expect(result.observed).toEqual({ state: 'conflict' });
+ expect(result.commit).toEqual({ ok: false, reason: 'conflict' });
+ expect(result.retained).toEqual(result.competitor);
+});
+test('private-shaped input is denied and closing the database invalidates genuine captures and workers', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ const denied = await api.createPublicDraftController(repository, {
+ body: 'private',
+ subject: 'private'
+ });
+ const controller = await api.createPublicDraftController(repository, form);
+ const captured = api.capturePublicDraftCreate(repository, form);
+ if (!controller || !captured.ok) throw new Error('missing genuine handles');
+ api.closeBrowserDatabase(window.hcp048Database);
+ const commit = await api.commitPublicDraftWrite(repository, captured.value);
+ const flush = await api.flushPublicDraft(controller);
+ const snapshot = api.publicDraftControllerSnapshot(controller);
+ return { denied: denied === undefined, commit, flush, snapshot };
+ }, form);
+ expect(result.denied).toBe(true);
+ expect(result.commit).toEqual({ ok: false, reason: 'invalid_scope' });
+ expect(result.flush).toBe(false);
+ expect(result.snapshot).toMatchObject({
+ state: 'failed',
+ failure: 'invalid_scope',
+ draft: null
+ });
+});
+
+test('real repository clock reentry cannot acknowledge an older payload as the latest input', async ({
+ page
+}) => {
+ await load(page);
+ const result = await page.evaluate(async (form) => {
+ const api = window.hcp048,
+ repository = window.hcp048Repository;
+ const controller = await api.createPublicDraftController(repository, form);
+ if (!controller) throw new Error('missing controller');
+ const original = Date.now;
+ let calls = 0;
+ Date.now = () => {
+ calls++;
+ if (calls === 1)
+ api.editPublicDraft(controller, {
+ ...form,
+ title: 'clock reentrant latest'
+ });
+ return original();
+ };
+ try {
+ api.editPublicDraft(controller, {
+ ...form,
+ title: 'older captured form'
+ });
+ const flushed = await api.flushPublicDraft(controller);
+ const snapshot = api.publicDraftControllerSnapshot(controller);
+ const rows = await api.listPublicDrafts(repository);
+ return { flushed, snapshot, rows, calls };
+ } finally {
+ Date.now = original;
+ }
+ }, form);
+ expect(result.flushed).toBe(true);
+ expect(result.calls).toBe(2);
+ expect(result.snapshot).toMatchObject({
+ state: 'saved',
+ editVersion: 2,
+ savedEditVersion: 2,
+ form: { title: 'clock reentrant latest' },
+ draft: { revision: 1, form: { title: 'clock reentrant latest' } }
+ });
+ expect(result.rows).toEqual({ ok: true, value: [result.snapshot?.draft] });
+});
diff --git a/web/tests/integration/draft-controller.test.ts b/web/tests/integration/draft-controller.test.ts
@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ createPublicDraftController,
+ flushPublicDraft,
+ editPublicDraft,
+ type PublicDraftController
+} from '../../src/lib/publishing/draft-controller.ts';
+import type { PublicDraftRepository } from '../../src/lib/persistence/drafts.ts';
+await test('actual autosave factory rejects a fabricated owner without opening storage or acquiring private input', async () => {
+ const repository = Object.freeze({}) as PublicDraftRepository;
+ const privateInput = {
+ get body() {
+ throw new Error('must not read private input');
+ }
+ };
+ assert.equal(
+ await createPublicDraftController(repository, privateInput),
+ undefined
+ );
+ const controller = Object.freeze({}) as PublicDraftController;
+ assert.equal(editPublicDraft(controller, privateInput), false);
+ assert.equal(await flushPublicDraft(controller), false);
+});
diff --git a/web/tests/unit/draft-controller.test.ts b/web/tests/unit/draft-controller.test.ts
@@ -0,0 +1,303 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { PublicDraftRecord } from '../../src/lib/contracts/local-records.ts';
+import type {
+ PublicDraftRepository,
+ PublicDraftWrite,
+ DraftResult
+} from '../../src/lib/persistence/drafts.ts';
+
+// Controlled receipt timing tests qualify the actual controller logic. Genuine
+// IndexedDB persistence is qualified separately by the browser integration.
+type Fixture = {
+ rows: Map<object, PublicDraftRecord>;
+ commits: object[];
+ clock: number;
+ outcome:
+ undefined | ((write: object) => Promise<DraftResult<PublicDraftRecord>>);
+ observed: 'committed' | 'base_observed';
+ captureHook: undefined | (() => void);
+};
+const fixture = vi.hoisted<Fixture>(() => ({
+ rows: new Map<object, PublicDraftRecord>(),
+ commits: [],
+ clock: 1000,
+ outcome: undefined,
+ observed: 'committed',
+ captureHook: undefined
+}));
+vi.mock('../../src/lib/persistence/drafts.ts', async (importOriginal) => {
+ const actual =
+ await importOriginal<
+ typeof import('../../src/lib/persistence/drafts.ts')
+ >();
+ const capture = (form: unknown, revision: number) => {
+ fixture.captureHook?.();
+ const admitted = actual.publicDraftFormSnapshot(form);
+ if (!admitted)
+ return { ok: false as const, reason: 'invalid_form' as const };
+ const handle = Object.freeze({}) as PublicDraftWrite;
+ fixture.rows.set(handle, {
+ schema: 1,
+ family: 'public_draft',
+ owner: '79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798',
+ id: '3d030bf5-901d-45e1-8251-41cbdf805e96',
+ revision,
+ savedAtMilliseconds: fixture.clock++,
+ form: admitted
+ });
+ return { ok: true as const, value: handle };
+ };
+ return {
+ ...actual,
+ publicDraftRepositoryOwner: () => 'controlled-unit-owner',
+ capturePublicDraftCreate: (
+ _repository: PublicDraftRepository,
+ form: unknown
+ ) => capture(form, 0),
+ capturePublicDraftSave: (
+ _repository: PublicDraftRepository,
+ _id: string,
+ revision: number,
+ form: unknown
+ ) => capture(form, revision + 1),
+ publicDraftWriteSnapshot: (
+ _repository: PublicDraftRepository,
+ write: PublicDraftWrite
+ ) => fixture.rows.get(write),
+ commitPublicDraftWrite: async (
+ _repository: PublicDraftRepository,
+ write: PublicDraftWrite
+ ) => {
+ fixture.commits.push(write);
+ if (fixture.outcome) return fixture.outcome(write);
+ const row = fixture.rows.get(write);
+ if (!row) throw new Error('missing controlled capture');
+ return { ok: true as const, value: structuredClone(row) };
+ },
+ observePublicDraftWrite: (
+ _repository: PublicDraftRepository,
+ write: PublicDraftWrite
+ ) => {
+ if (fixture.observed === 'base_observed')
+ return Promise.resolve({ state: 'base_observed' as const });
+ const row = fixture.rows.get(write);
+ if (!row) throw new Error('missing controlled capture');
+ return Promise.resolve({
+ state: 'committed' as const,
+ value: structuredClone(row)
+ });
+ }
+ };
+});
+import {
+ createPublicDraftController,
+ editPublicDraft,
+ flushPublicDraft,
+ publicDraftControllerSnapshot,
+ retryPublicDraft,
+ saveAndClosePublicDraft,
+ closePublicDraftController
+} from '../../src/lib/publishing/draft-controller.ts';
+const repository = Object.freeze({}) as PublicDraftRepository;
+const form = {
+ title: '',
+ description: '',
+ location: '',
+ amount: '.',
+ currency: '',
+ unit: '',
+ quantity: '',
+ contactType: '' as const,
+ contactValue: ''
+};
+beforeEach(() => {
+ fixture.rows.clear();
+ fixture.commits = [];
+ fixture.clock = 1000;
+ fixture.outcome = undefined;
+ fixture.observed = 'committed';
+ fixture.captureHook = undefined;
+});
+async function controller() {
+ const value = await createPublicDraftController(repository, form);
+ if (!value) throw new Error('missing controlled controller');
+ return value;
+}
+describe('single owned public autosave worker', () => {
+ it('synchronous pending edits coalesce into one actual controller capture', async () => {
+ const value = await controller();
+ expect(editPublicDraft(value, { ...form, title: 'one' })).toBe(true);
+ expect(editPublicDraft(value, { ...form, title: 'latest' })).toBe(true);
+ expect(await flushPublicDraft(value)).toBe(true);
+ expect(fixture.commits).toHaveLength(1);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'saved',
+ editVersion: 2,
+ savedEditVersion: 2,
+ form: { title: 'latest' },
+ draft: { form: { title: 'latest' } }
+ });
+ });
+ it('delayed acknowledgement never overwrites newer input and only one write runs at a time', async () => {
+ let acknowledge: (() => void) | undefined;
+ fixture.outcome = async (write) => {
+ const row = fixture.rows.get(write);
+ if (!row) throw new Error('missing capture');
+ if (fixture.commits.length === 1)
+ await new Promise<void>((resolve) => {
+ acknowledge = resolve;
+ });
+ return { ok: true, value: structuredClone(row) };
+ };
+ const value = await controller();
+ editPublicDraft(value, { ...form, title: 'first' });
+ const flushed = flushPublicDraft(value);
+ await Promise.resolve();
+ expect(fixture.commits).toHaveLength(1);
+ editPublicDraft(value, { ...form, title: 'newer' });
+ expect(publicDraftControllerSnapshot(value)?.form.title).toBe('newer');
+ if (!acknowledge) throw new Error('missing delayed acknowledgement');
+ acknowledge();
+ expect(await flushed).toBe(true);
+ expect(fixture.commits).toHaveLength(2);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'saved',
+ form: { title: 'newer' },
+ draft: { revision: 1 }
+ });
+ });
+ it('unknown receipt with exact readback acknowledges the original captured payload', async () => {
+ fixture.outcome = () =>
+ Promise.resolve({ ok: false, reason: 'unknown_completion' });
+ const value = await controller();
+ editPublicDraft(value, { ...form, title: 'retained' });
+ expect(await flushPublicDraft(value)).toBe(true);
+ expect(fixture.rows.size).toBe(1);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'saved',
+ draft: { form: { title: 'retained' }, savedAtMilliseconds: 1000 }
+ });
+ });
+ it('unobserved unknown result blocks navigation and explicit retry retains the same ID/time/capture before pending edits', async () => {
+ fixture.outcome = () =>
+ Promise.resolve({ ok: false, reason: 'unknown_completion' });
+ fixture.observed = 'base_observed';
+ const value = await controller();
+ editPublicDraft(value, { ...form, title: 'attempted' });
+ expect(await flushPublicDraft(value)).toBe(false);
+ const original = fixture.commits[0];
+ editPublicDraft(value, { ...form, title: 'pending' });
+ expect(await saveAndClosePublicDraft(value)).toBe(false);
+ expect(publicDraftControllerSnapshot(value)?.state).toBe('failed');
+ fixture.outcome = undefined;
+ expect(await retryPublicDraft(value)).toBe(true);
+ expect(fixture.commits[1]).toBe(original);
+ expect(fixture.rows.size).toBe(2);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'saved',
+ form: { title: 'pending' },
+ draft: { revision: 1 }
+ });
+ });
+ it('quota failure retains dirty input and prevents save-close', async () => {
+ fixture.outcome = () =>
+ Promise.resolve({ ok: false, reason: 'cap_reached' });
+ const value = await controller();
+ editPublicDraft(value, { ...form, description: 'retain me' });
+ expect(await saveAndClosePublicDraft(value)).toBe(false);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'failed',
+ failure: 'cap_reached',
+ form: { description: 'retain me' },
+ savedEditVersion: -1
+ });
+ });
+ it('closing while a request is pending fences late acknowledgements and subsequent captures', async () => {
+ let finish: (() => void) | undefined;
+ fixture.outcome = async (write) => {
+ await new Promise<void>((resolve) => {
+ finish = resolve;
+ });
+ const row = fixture.rows.get(write);
+ if (!row) throw new Error('missing capture');
+ return { ok: true, value: row };
+ };
+ const value = await controller();
+ editPublicDraft(value, form);
+ const flushed = flushPublicDraft(value);
+ await Promise.resolve();
+ closePublicDraftController(value);
+ if (!finish) throw new Error('missing pending receipt');
+ finish();
+ expect(await flushed).toBe(false);
+ expect(fixture.commits).toHaveLength(1);
+ expect(editPublicDraft(value, form)).toBe(false);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'closed',
+ savedEditVersion: -1,
+ draft: null
+ });
+ });
+ it('private composer shapes and caller snapshot mutations cannot enter public autosave', async () => {
+ const value = await controller();
+ expect(
+ editPublicDraft(value, { body: 'private', subject: 'private' })
+ ).toBe(false);
+ const copy = publicDraftControllerSnapshot(value);
+ if (!copy) throw new Error('missing snapshot');
+ const mutable = copy.form as { title: string };
+ mutable.title = 'foreign mutation';
+ expect(publicDraftControllerSnapshot(value)?.form.title).toBe('');
+ expect(fixture.commits).toHaveLength(0);
+ });
+ it('save-close rechecks an edit arriving after an already-saved flush resolves', async () => {
+ const value = await controller();
+ editPublicDraft(value, { ...form, title: 'first' });
+ expect(await flushPublicDraft(value)).toBe(true);
+ const closing = saveAndClosePublicDraft(value);
+ expect(
+ editPublicDraft(value, { ...form, title: 'latest before close' })
+ ).toBe(true);
+ expect(await closing).toBe(true);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'closed',
+ savedEditVersion: 2,
+ editVersion: 2,
+ draft: { form: { title: 'latest before close' } }
+ });
+ });
+
+ it('input admission cannot revive a controller closed by a reentrant proxy', async () => {
+ const value = await controller();
+ const input = new Proxy(form, {
+ get(target, property, receiver) {
+ if (property === 'title') closePublicDraftController(value);
+ return Reflect.get(target, property, receiver) as unknown;
+ }
+ });
+ expect(editPublicDraft(value, input)).toBe(false);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'closed',
+ editVersion: 0,
+ draft: null
+ });
+ expect(fixture.commits).toHaveLength(0);
+ });
+ it('capture reentry never labels older form bytes with the newer edit version', async () => {
+ const value = await controller();
+ fixture.captureHook = () => {
+ fixture.captureHook = undefined;
+ editPublicDraft(value, { ...form, title: 'newer during capture' });
+ };
+ editPublicDraft(value, { ...form, title: 'first captured' });
+ expect(await flushPublicDraft(value)).toBe(true);
+ expect(fixture.commits).toHaveLength(2);
+ expect(publicDraftControllerSnapshot(value)).toMatchObject({
+ state: 'saved',
+ editVersion: 2,
+ savedEditVersion: 2,
+ form: { title: 'newer during capture' },
+ draft: { revision: 1, form: { title: 'newer during capture' } }
+ });
+ });
+});