Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions docs/release-d1-journal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Inactive D1 journal storage adapter

This is a capability qualification slice, not a publisher or operational service.
No production schema migration, Worker route, workflow, secret, permission, or
activation is added. The module is outside the production Worker build. It statically imports the portable semantic replay validator, with differential
tests against the existing reviewed local replay. Callers cannot replace it. No flag in supplied JSON grants authentication or release authority.

## Actual D1 API path

The adapter uses `withSession('first-primary')` for sequential read/write readback.
It reads and hashes the bounded chain, validates transitions, then appends with a
single `INSERT ... SELECT ... WHERE` statement checking sequence and expected
tail in the database. A stale observation cannot become an unconditional write.
The schema scopes sequence and digest uniqueness by project. No lease expiry,
unlock, retry or remote publication is implemented. A thrown write call is unknown;
a zero-change conditional write is a conflict; a missing readback is unverified.

Cloudflare documents prepared statements, transactional batch rollback and
sequentially consistent sessions at:
https://developers.cloudflare.com/d1/worker-api/d1-database/

The adapter only needs one statement per append, avoiding JavaScript-interleaved
transactions unsupported by a D1 binding. Successful CAS only fences cooperating
journal writers, not Sites or existing publication mutations. This is not a lock
around the live site. The reference schema is deliberately outside active
`drizzle` migrations.

## Qualification and limitations

Normal Node tests cover contract failures with synthetic bindings. Separately,
`qualify-d1-journal.cjs` exercises the actual D1 binding in official Miniflare,
including a concurrent single-winner append, wrong-project/stale inputs, sticky
denial, runtime restart, a real committed write followed by an injected transport
failure, tampered-chain rejection, and execution of portable replay and a journal append inside actual local
workerd. Eleven additional differential cases cover valid and invalid transitions. Synthetic binding tests are not emulator
checks; emulator checks are not remote production verification.

Use an isolated scratch installation of pinned `miniflare@4.20260730.0`, then run:

NODE_PATH=/absolute/path/to/scratch/node_modules node tools/release-coordination/qualify-d1-journal.cjs

The harness creates temporary local storage and removes only its own fixture.
The production repository dependency set is unchanged. The experiment's explicit
output keeps productionD1Verified, authenticationVerified, remoteFencing and
productionActionAllowed false. It does not claim cross-region consistency testing,
power-loss guarantees or production privilege isolation.

A deployable adapter still requires a supported isolated hosted test, authenticated
request admission, bounded schema
migration approval, and independent full live readback. Existing denied operations
must not be retried or bypassed to supply these capabilities. Current bundled
service and publication holds remain unchanged.
11 changes: 11 additions & 0 deletions tests/release-d1-journal.test.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
const test=require('node:test'),assert=require('node:assert/strict');
const {replay}=require('../scripts/lib/release-journal.cjs');
const modulePromise=import('../tools/release-coordination/d1-journal.mjs');
const intent={kind:'intent',operationId:'op',releaseId:'release',target:{projectId:'project',versionId:'version',sourceCommit:'a'.repeat(40),archiveSha256:'b'.repeat(64),environmentRevision:12,controls:{VC_ACTIVE_DELIVERY:'0',VC_PUBLISHER_ACTIVATION:'0',VC_PUBLISHER_OIDC:'1'}},beforeDeploymentId:'old'};
function empty(onRun){return {withSession(mode){assert.equal(mode,'first-primary');return {prepare(){return {bind(){return {all:async()=>({success:true,results:[]}),run:onRun}}}}}}}}
test('D1 reference requires explicit session and statically binds validator',async()=>{const {readD1Journal}=await modulePromise;await assert.rejects(()=>readD1Journal({db:{},project:'project',validate:replay}),/invalid-context/);const r=await readD1Journal({db:empty(),project:'project',validate:()=>{throw Error('must not run')}});assert.equal(r.state.sequence,0)});
test('D1 empty read preserves authority limits',async()=>{const {readD1Journal}=await modulePromise;const r=await readD1Journal({db:empty(),project:'project',validate:replay});assert.equal(r.state.sequence,0);assert.equal(r.authenticationVerified,false);assert.equal(r.productionActionAllowed,false)});
test('D1 wrong-project intent is rejected before any write',async()=>{let wrote=false;const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>{wrote=true}),project:'other',validate:replay,event:intent,expectedTail:null}),/project-target-mismatch/);assert.equal(wrote,false)});
test('D1 network failure holds unknown, without retry',async()=>{let calls=0;const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>{calls++;throw Error('network')}),project:'project',validate:replay,event:intent,expectedTail:null}),/outcome-unknown/);assert.equal(calls,1)});
test('D1 zero-change CAS cannot claim success',async()=>{const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>({success:true,meta:{changes:0}})),project:'project',validate:replay,event:intent,expectedTail:null}),/tail-moved/)});
test('D1 reported write without matching readback stays unverified',async()=>{const {appendD1Journal}=await modulePromise;await assert.rejects(()=>appendD1Journal({db:empty(async()=>({success:true,meta:{changes:1}})),project:'project',validate:replay,event:intent,expectedTail:null}),/readback-unverified/)});
13 changes: 13 additions & 0 deletions tests/release-portable-replay.test.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
const test=require('node:test'),assert=require('node:assert/strict');
const {replay}=require('../scripts/lib/release-journal.cjs');
const {hash,canonical}=require('../scripts/lib/release-receipts.cjs');
const portable=import('../tools/release-coordination/portable-replay.mjs');
const target={projectId:'project',versionId:'version',sourceCommit:'a'.repeat(40),archiveSha256:'b'.repeat(64),environmentRevision:12,controls:{VC_ACTIVE_DELIVERY:'0',VC_PUBLISHER_ACTIVATION:'0',VC_PUBLISHER_OIDC:'1'}};
const intent={kind:'intent',operationId:'op-1',releaseId:'release-1',target,beforeDeploymentId:'old'};
function records(events){let prior=null;return events.map((event,i)=>{const body={sequence:i+1,previousSha256:prior,event},record={...body,sha256:hash(canonical(body))};prior=record.sha256;return record})}
function inspection(){const body={kind:'deployment-byte-inspection',...target,deploymentId:'new'};return {...body,receiptSha256:hash(canonical(body)),transportOrigin:'caller-retained-service-response',authenticatedByThisModule:false,claimedDelivered:false}}
const result=status=>({kind:'result',operationId:'op-1',status,deploymentId:status==='reported-success'?'new':null});
for(const [name,events] of Object.entries({empty:[],intent:[intent],denied:[intent,result('denied')],uncertain:[intent,result('uncertain')],unattributed:[intent,result('uncertain'),{kind:'readback',operationId:'op-1',inspection:inspection()}],matched:[intent,result('reported-success'),{kind:'readback',operationId:'op-1',inspection:inspection()}]}))test('portable replay parity: '+name,async()=>{const r=records(events);assert.deepEqual(await (await portable).replayPortable(r),replay(r))});
for(const [name,events] of Object.entries({secondIntent:[intent,{...intent,operationId:'op-2'}],deniedReadback:[intent,result('denied'),{kind:'readback',operationId:'op-1',inspection:inspection()}],wrongOperation:[intent,{...result('uncertain'),operationId:'other'}],wrongControl:[intent,result('reported-success'),{kind:'readback',operationId:'op-1',inspection:{...inspection(),controls:{...target.controls,VC_ACTIVE_DELIVERY:'1'}}}]}))test('portable replay rejects same invalid transition: '+name,async()=>{const r=records(events);let message;try{replay(r)}catch(e){message=e.message}assert(message);await assert.rejects(()=>(awaitable(r)),e=>e.message===message)});
async function awaitable(r){return (await portable).replayPortable(r)}
test('portable rejects tampered chain',async()=>{const r=records([intent]);r[0].event={...intent,releaseId:'different'};await assert.rejects(()=>awaitable(r),/chain-mismatch/)});
10 changes: 10 additions & 0 deletions tools/release-coordination/d1-journal-reference.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
-- Isolated test schema only. Not an active migration or production table.
CREATE TABLE release_journal_reference (
project_id TEXT NOT NULL,
sequence INTEGER NOT NULL CHECK(sequence > 0 AND sequence <= 500),
previous_hash TEXT,
event_hash TEXT NOT NULL,
record_json TEXT NOT NULL,
PRIMARY KEY(project_id, sequence),
UNIQUE(project_id, event_hash)
);
48 changes: 48 additions & 0 deletions tools/release-coordination/d1-journal.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/* Inactive D1-binding storage adapter. No route, migration, identity or authority. */
import {replayPortable as validate} from './portable-replay.mjs';
const MAX_EVENTS=500,MAX_BYTES=1048576,MAX_EVENT=16384;
const fail=reason=>{throw Object.assign(new Error(reason),{reason})};
const plain=x=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.getPrototypeOf(x)===Object.prototype;
function canonical(x){if(Array.isArray(x))return '['+x.map(canonical).join(',')+']';if(plain(x))return '{'+Object.keys(x).sort().map(k=>JSON.stringify(k)+':'+canonical(x[k])).join(',')+'}';return JSON.stringify(x)}
async function digest(x){return [...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(canonical(x))))].map(v=>v.toString(16).padStart(2,'0')).join('')}
const bytes=x=>new TextEncoder().encode(x).byteLength;
const tag=x=>typeof x==='string'&&/^[A-Za-z0-9_-]{1,128}$/.test(x);
function context(db,project){if(!tag(project)||!db||typeof db.withSession!=='function')fail('invalid-context');return db.withSession('first-primary')}
async function read(session,project){
const r=await session.prepare('SELECT sequence,previous_hash,event_hash,record_json FROM release_journal_reference WHERE project_id=? ORDER BY sequence LIMIT 501').bind(project).all();
if(r.success!==true||!Array.isArray(r.results)||r.results.length>MAX_EVENTS)fail('journal-read-unverified');
let count=0,tail=null,size=0;const records=[];
for(const row of r.results){
if(typeof row.record_json!=='string'||(size+=bytes(row.record_json)+1)>MAX_BYTES||bytes(row.record_json)>MAX_EVENT)fail('journal-limit');
const record=JSON.parse(row.record_json),{sha256,...body}=record;
if(Object.keys(record).sort().join(',')!=='event,previousSha256,sequence,sha256'||record.sequence!==++count||record.previousSha256!==tail||row.sequence!==count||row.previous_hash!==tail||row.event_hash!==sha256||sha256!==await digest(body))fail('journal-chain-mismatch');
if(record.event?.kind==='intent'&&record.event.target?.projectId!==project)fail('project-target-mismatch');
records.push(record);tail=sha256;
}
// Statically bound portable validator; callers cannot substitute transition
// code. This still does not authenticate a service actor or grant admission.
const state=await validate(structuredClone(records));
if(!plain(state)||state.sequence!==count||state.tail!==tail||state.productionActionAllowed!==false)fail('transition-validation-required');
return {records,state,size};
}
export async function readD1Journal({db,project}){const s=context(db,project);const r=await read(s,project);return {...r,storage:'d1-binding-reference',productionActionAllowed:false,authenticationVerified:false,remoteFencing:false}}
export async function appendD1Journal({db,project,event,expectedTail}){
const session=context(db,project),prior=await read(session,project);
if(prior.state.tail!==expectedTail)fail('journal-tail-moved');
if(event?.kind==='intent'&&event.target?.projectId!==project)fail('project-target-mismatch');
const body={sequence:prior.records.length+1,previousSha256:expectedTail,event:structuredClone(event)};
const record={...body,sha256:await digest(body)},encoded=JSON.stringify(record);
if(prior.records.length>=MAX_EVENTS||bytes(encoded)>MAX_EVENT||prior.size+bytes(encoded)+1>MAX_BYTES)fail('journal-limit');
const next=await validate([...structuredClone(prior.records),structuredClone(record)]);
if(!plain(next)||next.sequence!==record.sequence||next.tail!==record.sha256||next.productionActionAllowed!==false)fail('transition-validation-required');
// All conditional predicates and append are one SQL statement. A stale read
// cannot become an unconditional write, even with two independent sessions.
let result;
try{result=await session.prepare('INSERT INTO release_journal_reference(project_id,sequence,previous_hash,event_hash,record_json) SELECT ?,?,?,?,? WHERE ?=(SELECT COUNT(*)+1 FROM release_journal_reference WHERE project_id=?) AND ? IS (SELECT event_hash FROM release_journal_reference WHERE project_id=? ORDER BY sequence DESC LIMIT 1)').bind(project,record.sequence,expectedTail,record.sha256,encoded,record.sequence,project,expectedTail,project).run();}
catch{fail('append-outcome-unknown-readback-required')}
if(result?.success!==true||![0,1].includes(result.meta?.changes))fail('append-outcome-unknown-readback-required');
if(result.meta.changes===0)fail('journal-tail-moved');
let observed;try{observed=await read(session,project)}catch{fail('append-readback-unverified')}
if(observed.records[record.sequence-1]?.sha256!==record.sha256)fail('append-readback-unverified');
return {recordSha256:record.sha256,state:next,observedState:observed.state,storage:'d1-binding-reference',authenticationVerified:false,remoteFencing:false,productionActionAllowed:false};
}
43 changes: 43 additions & 0 deletions tools/release-coordination/portable-replay.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
/* Portable counterpart of the local journal replay. No I/O or authority. */
const hash=async value=>[...new Uint8Array(await crypto.subtle.digest('SHA-256',new TextEncoder().encode(value)))].map(v=>v.toString(16).padStart(2,'0')).join('');
function canonical(v){if(Array.isArray(v))return '['+v.map(canonical).join(',')+']';if(v&&typeof v==='object')return '{'+Object.keys(v).sort().map(k=>JSON.stringify(k)+':'+canonical(v[k])).join(',')+'}';return JSON.stringify(v);}
const fail=m=>{throw Error(m);};
const plain=x=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.getPrototypeOf(x)===Object.prototype;
const keys=(x,want)=>{if(!plain(x)||Reflect.ownKeys(x).some(k=>typeof k!=='string'||!Object.hasOwn(Object.getOwnPropertyDescriptor(x,k),'value'))||Object.keys(x).sort().join(',')!==want.sort().join(','))fail('invalid-fields');};
const token=x=>typeof x==='string'&&/^[A-Za-z0-9_-]{1,128}$/.test(x);
function controls(x){keys(x,['VC_ACTIVE_DELIVERY','VC_PUBLISHER_ACTIVATION','VC_PUBLISHER_OIDC']);if(Object.values(x).some(v=>!['0','1'].includes(v)))fail('invalid-controls');}
function target(x){keys(x,['projectId','versionId','sourceCommit','archiveSha256','environmentRevision','controls']);controls(x.controls);if(!token(x.projectId)||typeof x.versionId!=='string'||x.versionId.length>256||!/^[a-f0-9]{40}$/.test(x.sourceCommit)||!/^[a-f0-9]{64}$/.test(x.archiveSha256)||!Number.isSafeInteger(x.environmentRevision)||x.environmentRevision<1)fail('invalid-target');}
async function inspectEvidence(x){
if(!plain(x)||x.kind!=='deployment-byte-inspection'||x.authenticatedByThisModule!==false||x.claimedDelivered!==false)fail('invalid-inspection');
const {receiptSha256,transportOrigin,authenticatedByThisModule,claimedDelivered,...body}=x;
if(transportOrigin!=='caller-retained-service-response'||receiptSha256!==await hash(canonical(body)))fail('inspection-digest-mismatch');
return x;
}
export async function replayPortable(records){
let tail=null,pending=null,status='empty',sequence=0;const operations=new Set();
for(const record of records){
keys(record,['sequence','previousSha256','event','sha256']);const {sha256,...body}=record;
if(record.sequence!==++sequence||record.previousSha256!==tail||sha256!==await hash(canonical(body)))fail('journal-chain-mismatch');
const e=record.event;if(!plain(e)||!token(e.operationId))fail('invalid-event');
if(e.kind==='intent'){
keys(e,['kind','operationId','releaseId','target','beforeDeploymentId']);target(e.target);
if(!token(e.releaseId)||typeof e.beforeDeploymentId!=='string'||!e.beforeDeploymentId||operations.has(e.operationId)||pending)fail('intent-blocked');
operations.add(e.operationId);pending=structuredClone(e);pending.result=null;status='intent-recorded';
}else if(e.kind==='result'){
keys(e,['kind','operationId','status','deploymentId']);
if(!pending||pending.operationId!==e.operationId||pending.result||!['reported-success','uncertain','denied'].includes(e.status))fail('result-blocked');
if(e.deploymentId!==null&&(typeof e.deploymentId!=='string'||!e.deploymentId||e.deploymentId===pending.beforeDeploymentId))fail('invalid-deployment-id');
if(e.status==='reported-success'&&e.deploymentId===null)fail('missing-deployment-id');
pending.result=structuredClone(e);status=e.status==='denied'?'denied-terminal':'awaiting-readback';
}else if(e.kind==='readback'){
keys(e,['kind','operationId','inspection']);if(!pending||pending.operationId!==e.operationId||pending.result?.status==='denied')fail('readback-blocked');
const v=await inspectEvidence(e.inspection),t=pending.target;
if(v.projectId!==t.projectId||v.versionId!==t.versionId||v.sourceCommit!==t.sourceCommit||v.archiveSha256!==t.archiveSha256||v.environmentRevision!==t.environmentRevision||canonical(v.controls)!==canonical(t.controls))fail('readback-target-mismatch');
if(!pending.result?.deploymentId){status='uncertain-unattributed';}
else if(v.deploymentId!==pending.result.deploymentId)fail('readback-operation-mismatch');
else{status='matched-readback-review-required';pending=null;}
}else fail('unsupported-event');
tail=record.sha256;
}
return {sequence,tail,status,pending,authority:'unverified',transportOrigin:'externally-retained-receipts-required',claimedDelivered:false,productionActionAllowed:false};
}
Loading
Loading