app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

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:
Mweb/src/lib/persistence/drafts.ts | 319++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----------------------
Aweb/src/lib/publishing/draft-controller.ts | 256+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/e2e/draft-controller.spec.ts | 341+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/integration/draft-controller.test.ts | 24++++++++++++++++++++++++
Aweb/tests/unit/draft-controller.test.ts | 303+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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' } } + }); + }); +});