app

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

commit 8dab3390cbd7e3d43ec3f04c08d0befbf5074523
parent 7fe4608cace18acf6eba216dca49cc43fa27c48e
Author: triesap <tyson@radroots.org>
Date:   Tue,  6 Oct 2026 11:53:16 +0000

availability: Retain unsupported and future head uncertainty (HCP-034)

- Preserve verified coordinate winners before focused display
- Apply explicit five minute injected wall clock quarantine
- Prevent reentrant assessment from resurrecting older heads
- Verify seventeen cases and preserve Native source boundaries

Diffstat:
Aweb/src/lib/catalog/clock-policy.ts | 24++++++++++++++++++++++++
Aweb/src/lib/catalog/head-state.ts | 173+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Aweb/tests/unit/head-state.test.ts | 331+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 528 insertions(+), 0 deletions(-)

diff --git a/web/src/lib/catalog/clock-policy.ts b/web/src/lib/catalog/clock-policy.ts @@ -0,0 +1,24 @@ +// Explicit prototype display policy; protocol order and signed timestamps stay +// unchanged. A caller supplies wall-clock seconds, independently of the +// monotonic clock used for bounded request deadlines. +export const FUTURE_QUARANTINE_SECONDS = 300; +export type WallClock = Readonly<{ nowSeconds: () => number }>; +export type FutureAssessment = + 'within_policy' | 'future_quarantined' | 'clock_unavailable'; +export function wallClockAvailable(value: number): boolean { + return ( + Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER + ); +} +export function assessFutureTimestamp( + createdAt: number, + nowSeconds: number +): FutureAssessment { + if (!wallClockAvailable(nowSeconds)) return 'clock_unavailable'; + if (!Number.isSafeInteger(createdAt) || createdAt < 0) + throw new Error('food_head_timestamp_invalid'); + // Subtract rather than adding skew to a potentially maximum-safe timestamp. + return createdAt - nowSeconds > FUTURE_QUARANTINE_SECONDS + ? 'future_quarantined' + : 'within_policy'; +} diff --git a/web/src/lib/catalog/head-state.ts b/web/src/lib/catalog/head-state.ts @@ -0,0 +1,173 @@ +import { + projectFoodParts, + type FoodProjection +} from '../contracts/food-availability-v1/read.ts'; +import { + verifiedEnvelopeSnapshot, + type VerifiedEnvelope +} from '../nostr/verified-envelope.ts'; +import { + createPublicHeadCandidate, + publicHeadEnvelope, + publicHeadSnapshot, + selectPublicHead, + type PublicHead, + type PublicHeadDecision, + type PublicHeadSnapshot +} from './heads.ts'; +import { + assessFutureTimestamp, + wallClockAvailable, + type WallClock +} from './clock-policy.ts'; + +declare const stateBrand: unique symbol; +export type FoodHeadState = Readonly<{ readonly [stateBrand]: true }>; +export type ClockDirection = + 'initial' | 'forward' | 'backward' | 'unchanged' | 'unavailable'; +export type FoodHeadDisplay = + 'focused_known' | 'unsupported' | 'future_quarantined' | 'clock_unavailable'; +export type FoodHeadStateSnapshot = Readonly<{ + head: PublicHeadSnapshot; + classification: 'focused' | 'unsupported'; + display: FoodHeadDisplay; + assessedAtSeconds: number | null; + clockDirection: ClockDirection; + unsupportedReason: string | undefined; + food: FoodProjection | undefined; +}>; +interface Owner { + readonly head: PublicHead; + readonly nowSeconds: () => number; + readonly lastValidClock: number | undefined; + readonly view: FoodHeadStateSnapshot; +} +const owners = new WeakMap<FoodHeadState, Owner>(); +function ownerOf(state: FoodHeadState): Owner { + const owner = owners.get(state); + if (!owner) throw new Error('food_head_state_invalid'); + return owner; +} +function assess( + selectedHead: PublicHead, + nowSeconds: () => number, + lastValidClock: number | undefined +): Owner { + const head = publicHeadSnapshot(selectedHead); + const event = verifiedEnvelopeSnapshot(publicHeadEnvelope(selectedHead)); + if (!event) throw new Error('food_head_proof_invalid'); + const projected = projectFoodParts(event); + const focused = projected.outcome === 'focused'; + let now: number | undefined; + try { + const sample = nowSeconds(); + if (wallClockAvailable(sample)) now = sample; + } catch { + /* Unavailable clock denies display, never discards new evidence. */ + } + const clockDirection: ClockDirection = + now === undefined + ? 'unavailable' + : lastValidClock === undefined + ? 'initial' + : now > lastValidClock + ? 'forward' + : now < lastValidClock + ? 'backward' + : 'unchanged'; + const timing = + now === undefined + ? 'clock_unavailable' + : assessFutureTimestamp(head.created_at, now); + const display: FoodHeadDisplay = + timing !== 'within_policy' + ? timing + : focused + ? 'focused_known' + : 'unsupported'; + const view: FoodHeadStateSnapshot = { + head, + classification: focused ? 'focused' : 'unsupported', + display, + assessedAtSeconds: now ?? null, + clockDirection, + unsupportedReason: + projected.outcome === 'rejected' + ? projected.error.code + : projected.outcome === 'excluded' + ? projected.partition + : undefined, + food: + display === 'focused_known' && projected.outcome === 'focused' + ? projected.projection + : undefined + }; + return { + head: selectedHead, + nowSeconds, + lastValidClock: now ?? lastValidClock, + view + }; +} +export function createFoodHeadState( + head: PublicHead, + clock: WallClock +): FoodHeadState { + if (publicHeadSnapshot(head).kind !== 30402) + throw new Error('food_head_kind_invalid'); + const readClock = clock.nowSeconds; + if (typeof readClock !== 'function') + throw new Error('food_head_clock_invalid'); + const token = Object.freeze({}) as FoodHeadState; + owners.set( + token, + assess(head, () => readClock(), undefined) + ); + return token; +} +// No profile admission can run before HCP033 selects the generic winner. +export function advanceFoodHeadState( + state: FoodHeadState, + proof: VerifiedEnvelope +): PublicHeadDecision | 'ignored' { + const owner = ownerOf(state), + candidate = createPublicHeadCandidate(proof); + if (!candidate) return 'ignored'; + const selected = selectPublicHead(owner.head, candidate); + if (selected.decision === 'applied') { + // Reserve the protocol winner before invoking caller-controlled clock code. + // Until assessment settles, expose its evidence with no display authority. + const pending: Owner = { + ...assess(selected.head, () => NaN, owner.lastValidClock), + nowSeconds: owner.nowSeconds + }; + owners.set(state, pending); + publishAssessment(state, pending); + } + return selected.decision; +} +// Called by a bounded explicit refresh, never an automatic wall-clock timer. +export function refreshFoodHeadState(state: FoodHeadState): void { + publishAssessment(state, ownerOf(state)); +} +function publishAssessment(state: FoodHeadState, owner: Owner): void { + const measured = assess(owner.head, owner.nowSeconds, owner.lastValidClock); + // A nested advance or refresh owns its replacement; never publish stale data. + if (owners.get(state) === owner) owners.set(state, measured); +} +export function foodHeadStateHead(state: FoodHeadState): PublicHead { + return ownerOf(state).head; +} +export function foodHeadStateSnapshot( + state: FoodHeadState +): FoodHeadStateSnapshot { + const view = ownerOf(state).view; + return { + ...view, + head: { ...view.head }, + food: + view.food === undefined + ? undefined + : (JSON.parse(JSON.stringify(view.food)) as FoodProjection) + }; +} diff --git a/web/tests/unit/head-state.test.ts b/web/tests/unit/head-state.test.ts @@ -0,0 +1,331 @@ +import { afterAll, describe, expect, it } from 'vitest'; +import { readFileSync } from 'node:fs'; +import { finalizeEvent } from 'applesauce-core/helpers'; +import { + verifyEnvelope, + type VerifiedEnvelope +} from '../../src/lib/nostr/verified-envelope.ts'; +import { + createPublicHeadCandidate, + publicHeadSnapshot +} from '../../src/lib/catalog/heads.ts'; +import { assessFutureTimestamp } from '../../src/lib/catalog/clock-policy.ts'; +import { + createFoodHeadState, + advanceFoodHeadState, + refreshFoodHeadState, + foodHeadStateSnapshot, + foodHeadStateHead, + type FoodHeadState +} from '../../src/lib/catalog/head-state.ts'; + +const corpus = JSON.parse( + readFileSync( + new URL( + '../../../contracts/interop/food_availability/corpus.v1.json', + import.meta.url + ), + 'utf8' + ) +) as { vectors: { id: string; signed_wires: Record<string, string> }[] }; +const base = JSON.parse( + corpus.vectors.find((v) => v.id.endsWith('_032'))!.signed_wires.previous +) as { tags: string[][]; content: string; created_at: number }; +const keys: Uint8Array[] = []; +afterAll(() => { + for (const key of keys) key.fill(0); +}); +function fixture() { + const key = crypto.getRandomValues(new Uint8Array(32)); + keys.push(key); + const signed = ( + time = base.created_at, + tags = base.tags, + content = base.content, + kind = 30402 + ) => + JSON.stringify( + finalizeEvent({ kind, created_at: time, tags, content }, key) + ); + const proof = (raw: string) => { + const result = verifyEnvelope(raw); + if (!result.ok) throw new Error('Invalid signed test event'); + return result.value; + }; + const candidate = (raw: string) => { + const value = createPublicHeadCandidate(proof(raw)); + if (!value) throw new Error('Expected public head'); + return value; + }; + let now = base.created_at; + let calls = 0; + const clock = { + nowSeconds: () => { + calls++; + return now; + } + }; + const state = createFoodHeadState(candidate(signed()), clock); + return { + signed, + proof, + candidate, + state, + clock, + setNow: (v: number) => { + now = v; + }, + calls: () => calls + }; +} +function status(value: string) { + return base.tags.map((t) => (t[0] === 'status' ? ['status', value] : [...t])); +} +describe('verified food head display uncertainty', () => { + it('reserves a new winner before its clock callback and never overwrites a still newer accepted head', () => { + const f = fixture(); + const newer = f.proof(f.signed(base.created_at + 2, status('unknown'))); + let armed = false; + let entered = false; + const clock = { + nowSeconds: () => { + if (armed && !entered) { + entered = true; + advanceFoodHeadState(state, newer); + } + return base.created_at; + } + }; + const state: FoodHeadState = createFoodHeadState( + foodHeadStateHead(f.state), + clock + ); + armed = true; + advanceFoodHeadState(state, f.proof(f.signed(base.created_at + 1))); + expect(foodHeadStateSnapshot(state)).toMatchObject({ + display: 'unsupported', + head: { created_at: base.created_at + 2 } + }); + expect(foodHeadStateSnapshot(state).food).toBeUndefined(); + expect(publicHeadSnapshot(foodHeadStateHead(state)).created_at).toBe( + base.created_at + 2 + ); + }); + it('cannot publish an older focused assessment after clock callback accepts a newer unsupported winner', () => { + const f = fixture(); + const newer = f.proof(f.signed(base.created_at + 2, status('unknown'))); + let armed = false; + let entered = false; + const clock = { + nowSeconds: () => { + if (armed && !entered) { + entered = true; + expect(advanceFoodHeadState(state, newer)).toBe('applied'); + } + return base.created_at; + } + }; + const state: FoodHeadState = createFoodHeadState( + foodHeadStateHead(f.state), + clock + ); + armed = true; + refreshFoodHeadState(state); + expect(foodHeadStateSnapshot(state)).toMatchObject({ + display: 'unsupported', + head: { created_at: base.created_at + 2 } + }); + expect(foodHeadStateSnapshot(state).food).toBeUndefined(); + expect(publicHeadSnapshot(foodHeadStateHead(state)).created_at).toBe( + base.created_at + 2 + ); + }); + it('projects the focused known head without claiming assured stock', () => { + const f = fixture(); + const view = foodHeadStateSnapshot(f.state); + expect(view.display).toBe('focused_known'); + expect(view.food?.status).toBe('active'); + expect(view.clockDirection).toBe('initial'); + expect(view.head).toEqual(publicHeadSnapshot(foodHeadStateHead(f.state))); + }); + it('keeps a newer unsupported status and never returns the older active projection', () => { + const f = fixture(); + const raw = f.signed(base.created_at + 1, status('unknown')); + expect(advanceFoodHeadState(f.state, f.proof(raw))).toBe('applied'); + const view = foodHeadStateSnapshot(f.state); + expect(view.display).toBe('unsupported'); + expect(view.food).toBeUndefined(); + expect(view.head.id).toBe((JSON.parse(raw) as { id: string }).id); + expect(view.unsupportedReason).toBe('food_status_invalid'); + }); + it('blocks generic operational and ambiguous newer heads before focused filtering', () => { + for (const tags of [ + base.tags.filter((t) => !t[0].startsWith('radroots:')), + [ + ['d', base.tags.find((t) => t[0] === 'd')![1]], + ['radroots:primary_bin', 'stock'] + ], + [...base.tags, ['radroots:primary_bin', 'stock']] + ]) { + const f = fixture(); + advanceFoodHeadState( + f.state, + f.proof(f.signed(base.created_at + 1, tags)) + ); + expect(foodHeadStateSnapshot(f.state).classification).toBe('unsupported'); + expect(foodHeadStateSnapshot(f.state).food).toBeUndefined(); + } + }); + it('cannot let a bad signature or forged proof suppress good evidence', () => { + const f = fixture(); + const before = foodHeadStateSnapshot(f.state); + const raw = JSON.parse( + f.signed(base.created_at + 1, status('unknown')) + ) as { sig: string }; + raw.sig = '0'.repeat(128); + expect(verifyEnvelope(JSON.stringify(raw)).ok).toBe(false); + expect( + advanceFoodHeadState(f.state, raw as unknown as VerifiedEnvelope) + ).toBe('ignored'); + expect(foodHeadStateSnapshot(f.state)).toEqual(before); + }); + it('does not resurrect an older focused head arriving after unsupported evidence', () => { + const f = fixture(); + advanceFoodHeadState( + f.state, + f.proof(f.signed(base.created_at + 1, status('unknown'))) + ); + const before = foodHeadStateSnapshot(f.state); + expect(advanceFoodHeadState(f.state, f.proof(f.signed()))).toBe('older'); + expect(foodHeadStateSnapshot(f.state)).toEqual(before); + }); + it('uses strict greater-than-five-minute quarantine with fractional wall clock support', () => { + expect(assessFutureTimestamp(1300, 1000)).toBe('within_policy'); + expect(assessFutureTimestamp(1301, 1000)).toBe('future_quarantined'); + expect(assessFutureTimestamp(1301, 1000.5)).toBe('future_quarantined'); + expect(assessFutureTimestamp(Number.MAX_SAFE_INTEGER, 0)).toBe( + 'future_quarantined' + ); + }); + it('quarantines the protocol winner without changing its signed timestamp', () => { + const f = fixture(); + const raw = f.signed(base.created_at + 301); + advanceFoodHeadState(f.state, f.proof(raw)); + const view = foodHeadStateSnapshot(f.state); + expect(view.display).toBe('future_quarantined'); + expect(view.classification).toBe('focused'); + expect(view.food).toBeUndefined(); + expect(view.head.created_at).toBe(base.created_at + 301); + }); + it('explicit refresh exposes forward and backward clock transitions without changing winner', () => { + const f = fixture(); + advanceFoodHeadState(f.state, f.proof(f.signed(base.created_at + 301))); + const id = foodHeadStateSnapshot(f.state).head.id; + f.setNow(base.created_at + 1); + refreshFoodHeadState(f.state); + expect(foodHeadStateSnapshot(f.state)).toMatchObject({ + display: 'focused_known', + clockDirection: 'forward' + }); + f.setNow(base.created_at); + refreshFoodHeadState(f.state); + expect(foodHeadStateSnapshot(f.state)).toMatchObject({ + display: 'future_quarantined', + clockDirection: 'backward' + }); + expect(foodHeadStateSnapshot(f.state).head.id).toBe(id); + }); + it('cannot restore an older current view while the winner is quarantined', () => { + const f = fixture(); + advanceFoodHeadState(f.state, f.proof(f.signed(base.created_at + 301))); + expect(advanceFoodHeadState(f.state, f.proof(f.signed()))).toBe('older'); + expect(foodHeadStateSnapshot(f.state).display).toBe('future_quarantined'); + expect(foodHeadStateSnapshot(f.state).food).toBeUndefined(); + }); + it('retains incompatible evidence while future and still denies food after clock catches up', () => { + const f = fixture(); + advanceFoodHeadState( + f.state, + f.proof(f.signed(base.created_at + 301, status('unknown'))) + ); + expect(foodHeadStateSnapshot(f.state)).toMatchObject({ + display: 'future_quarantined', + classification: 'unsupported' + }); + f.setNow(base.created_at + 1); + refreshFoodHeadState(f.state); + expect(foodHeadStateSnapshot(f.state).display).toBe('unsupported'); + expect(foodHeadStateSnapshot(f.state).food).toBeUndefined(); + }); + it('unavailable clock preserves the new winner and fails closed for display', () => { + const f = fixture(); + f.setNow(NaN); + advanceFoodHeadState(f.state, f.proof(f.signed(base.created_at + 1))); + expect(foodHeadStateSnapshot(f.state)).toMatchObject({ + display: 'clock_unavailable', + clockDirection: 'unavailable', + assessedAtSeconds: null + }); + expect(foodHeadStateSnapshot(f.state).head.created_at).toBe( + base.created_at + 1 + ); + expect(foodHeadStateSnapshot(f.state).food).toBeUndefined(); + f.setNow(base.created_at + 1); + refreshFoodHeadState(f.state); + expect(foodHeadStateSnapshot(f.state).display).toBe('focused_known'); + }); + it('clock throwing or invalid numeric samples never manufacture a display time', () => { + const f = fixture(); + const state = createFoodHeadState(foodHeadStateHead(f.state), { + nowSeconds: () => { + throw new Error('clock failure'); + } + }); + expect(foodHeadStateSnapshot(state).display).toBe('clock_unavailable'); + for (const now of [NaN, Infinity, -1, Number.MAX_SAFE_INTEGER + 1]) + expect(assessFutureTimestamp(base.created_at, now)).toBe( + 'clock_unavailable' + ); + }); + it('duplicates and other coordinates do not sample clock or replace state', () => { + const f = fixture(); + const before = foodHeadStateSnapshot(f.state), + calls = f.calls(); + expect(advanceFoodHeadState(f.state, f.proof(f.signed()))).toBe( + 'duplicate' + ); + const tags = base.tags.map((t) => (t[0] === 'd' ? ['d', 'other'] : t)); + expect( + advanceFoodHeadState( + f.state, + f.proof(f.signed(base.created_at + 1, tags)) + ) + ).toBe('coordinate_mismatch'); + expect(f.calls()).toBe(calls); + expect(foodHeadStateSnapshot(f.state)).toEqual(before); + }); + it('protects detached projection and head metadata from mutation and rejects forged owners', () => { + const f = fixture(); + const view = foodHeadStateSnapshot(f.state); + if (!view.food) throw new Error('Expected focused food'); + (view.food as { title: string }).title = 'mutated'; + (view.head as { created_at: number }).created_at = 0; + expect(foodHeadStateSnapshot(f.state).food?.title).not.toBe('mutated'); + expect(foodHeadStateSnapshot(f.state).head.created_at).toBe( + base.created_at + ); + expect(() => foodHeadStateSnapshot({} as FoodHeadState)).toThrow( + 'food_head_state_invalid' + ); + }); + it('does not treat public metadata coordinates as food state', () => { + const f = fixture(); + for (const kind of [0, 10050]) + expect(() => + createFoodHeadState( + f.candidate(f.signed(base.created_at, [], '{}', kind)), + f.clock + ) + ).toThrow('food_head_kind_invalid'); + }); +});