@redue/cli 0.1.0-alpha.2 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.0-alpha.3 — 2026-10-06
+
+Install: `npm install --global @redue/cli@alpha`.
+
+- Fix selected execution outcomes remaining hidden behind an older observer/cache
+  after a missed reload notification. A newer failure must not leave an older
+  passing receipt eligible for reuse.
+- Withhold applicability during incomplete receipt persistence, unreadable or
+  changing selection, and client connections to an older observer.
+- Preserve immutable run history. Upgrade requires an observer stop/start;
+  receipts need not be deleted. See the [maintainer notice](docs/user/receipt-selection-notice.md).
+
 ## 0.1.0-alpha.2 — 2026-10-06
 
 Install: `npm install --global @redue/cli@alpha`.

package/README.md

@@ -1,5 +1,8 @@
 # REDUE
 
+Maintainer notice: alpha.2 users should review the
+[receipt-selection correction and interim guidance](docs/user/receipt-selection-notice.md).
+
 **Know what still holds. Redo what's due.**
 
 You ran the checks. Then the code changed—or a new coding agent started with no

package/docs/user/receipt-selection-notice.md

@@ -0,0 +1,60 @@
+# Receipt selection correction in alpha.3
+
+**Known affected release: `@redue/cli@0.1.0-alpha.2`. Fixed in
+`@redue/cli@0.1.0-alpha.3`.** No exploit or affected-user count is established.
+REDUE remains an alpha.
+
+If a wrapper persisted a newer outcome but its observer reload notification
+failed, the observer could continue selecting an older passing receipt. Cached
+and synchronized status could then present that older result as CURRENT and
+eligible for reuse. A separate reproduced write-failure window left a new
+immutable outcome recorded while replacing the selected receipt failed.
+
+Until upgraded, do not rely solely on affected CURRENT output to skip checks.
+Run verification when needed and inspect its actual outcome; a successful status
+command is not proof that the latest execution passed.
+
+## What changes
+
+The observer refreshes REDUE-owned receipt selection before publishing status.
+Clients check that a response represents the current readable selection. Missing,
+unreadable, malformed, incompatible, or replaced selection cannot authorize
+reuse. A new client connecting to an alpha.2 observer returns UNVERIFIED and
+asks for a restart, even when the old response says CURRENT.
+
+A small owned pending-update record also withholds applicability after an
+incomplete receipt write. Successful recording clears only that check's pending
+entry. It does not discard another check's incomplete outcome or automatically
+promote an orphaned journal entry. Inspect the failed run and storage error, fix
+the storage problem, then record that check again. An unreadable/malformed pending
+record requires operator inspection; do not delete receipts to obtain green status.
+
+Historical PASS/FAIL and immutable `runs-v1` files remain intact. Stable applicable
+FAIL remains a failure and is never reuse-eligible. This guard tracks owned
+receipt replacement; it does not replace input-content validation or promise an
+atomic decision against concurrent edits/writes.
+
+## Upgrade and restart
+
+From each initialized project, stop its observer before replacing the installation.
+After all observers for that installation have stopped, upgrade it once, then
+restart each observer with its existing configuration and state selection:
+
+```sh
+redue stop
+npm install --global @redue/cli@0.1.0-alpha.3
+redue --version
+redue start
+redue status --sync --json
+```
+
+Use the same npm `--prefix`, project `--config`, and `--state-dir` you already use,
+if customized. On Windows use `npm.cmd`/`redue.cmd` where required by the existing
+shell policy. Stop all observers belonging to the installation before replacing
+it, then start each with the upgraded binary. For an independently installed
+candidate, its `stop` command can stop the older observer in the same explicitly
+selected owned state. Do not run `remove-state`; receipts need not be deleted.
+
+Restart preserves historical receipts and reconciles inputs. It does not promise
+CURRENT: a newer failure, unstable execution, incomplete contract, changed input,
+or observation uncertainty remains visible under the normal rules.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/cached-state.mjs

@@ -2,22 +2,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {processAlive} from './process-liveness.mjs';
+import {readReceipts,readReceiptSnapshot,receiptRevision} from './state-store.mjs';
 const unknown=(reason,checks)=>({schema:1,state:'unverified',current:0,stale:0,failed:0,observed_failed:0,
   unverified:checks.length,
   checks:checks.map(c=>({name:c.name,result:null,freshness:'UNVERIFIED',reason,
     invocation:null,changed_inputs:[],reuse_eligible:false})),
   observation:{healthy:false,reason}});
 export function unavailableCached(state,reason,checks=[]) {
-  try {const value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));
-    const checks=(value.checks||[]).map(row=>({...row,freshness:'UNVERIFIED',
-      reason,reuse_eligible:false,declared_inputs_match:null}));
-    return {...value,state:'unverified',current:0,stale:0,failed:0,
-      unverified:Math.max(1,checks.length),checks,
-      observation:{...value.observation,healthy:false,reason}};
-  }catch{return unknown(reason,checks);}
+  let value;try{value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));}
+  catch{value=unknown(reason,checks);}
+  if(!value||!Array.isArray(value.checks))value=unknown(reason,checks);
+  let receipts=null,revision=null;
+  try{const snapshot=readReceiptSnapshot(state);receipts=snapshot.value.checks;revision=snapshot.revision;}
+  catch(error){reason+=`; latest receipt unavailable; prior outcome only: ${error.message}`;
+    try{receipts=readReceipts(state).checks;}catch{/* retain cached historical rows */}}
+  const rows=(value.checks||[]).map(row=>{
+    const latest=receipts?.[row.name];
+    return {...row,...(receipts?{result:latest?.result||null,invocation:latest?.invocation||null,
+      target_provenance:latest?.target||null,coverage_at_run:latest?.coverage||null}:{}),
+      freshness:'UNVERIFIED',reason,reuse_eligible:false,declared_inputs_match:null};
+  });
+  return {...value,receipt_revision:revision,state:'unverified',current:0,stale:0,failed:0,
+    observed_failed:rows.filter(row=>row.result==='FAIL').length,
+    unverified:Math.max(1,rows.length),checks:rows,
+    observation:{...value.observation,healthy:false,reason}};
 }
 export function readCachedStatus(state,checks=[]) {
   try{const value=JSON.parse(fs.readFileSync(path.join(state,'status.json')));
+    if(typeof value.receipt_revision!=='string')
+      return unavailableCached(state,'receipt selection is unconfirmed; synchronize status or restart an older observer',checks);
+    if(value.receipt_revision!==receiptRevision(state))
+      return unavailableCached(state,'receipt selection changed; synchronize status to evaluate the latest outcome',checks);
     if(Date.now()>=value.updated_at&&Date.now()<=value.expires_at&&
       value.expires_at-value.updated_at<=3000){
       if(processAlive(value.pid))return value;

package/src/cli.mjs

@@ -15,7 +15,7 @@ import {createHash,randomUUID} from 'node:crypto';
 import {assertOwnedStatePlacement} from './owned-state.mjs';
 import {permittedRoots} from './installed-inputs.mjs';
 import {acquireRunLock,inspectRunLock,recoverRunLock} from './run-lock.mjs';
-import {atomicJson,commitReceipt} from './state-store.mjs';
+import {atomicJson,commitReceipt,receiptRevision} from './state-store.mjs';
 import {timing} from './decision-profile.mjs';
 import {readCachedStatus,unavailableCached} from './cached-state.mjs';
 import {renderRun} from './presentation.mjs';
@@ -284,7 +284,7 @@ async function execute() {
     const persistenceStarted=performance.now();
     commitReceipt(state,name,receipt);
     timing('cli.receipt_persistence',persistenceStarted);
-    try{await call({action:'reload'});}catch{/* next read remains conservative */}
+    try{await call({action:'reload'});}catch{/* receipt revisions invalidate older status even when reload IPC is unavailable */}
     const summary={check:name,result,target:target.status,
       invocation:invocation.status,...(invocation.errorCode?{error_code:invocation.errorCode}:{}),
       stable,coverage_qualified:receipt.coverage.qualified};
@@ -376,7 +376,18 @@ async function main(){
   if(action==='sync'||action==='detail'){
     const started=performance.now();
     let value;try{value=await decisionCall({action:'sync',contextHashes:contextHashes()},
-      Number(process.env.VSTATE_SYNC_TIMEOUT_MS||decisionDeadlineMs));}
+      Number(process.env.VSTATE_SYNC_TIMEOUT_MS||decisionDeadlineMs));
+      // A client upgrade can encounter an older running observer. Its successful
+      // control response does not establish that it evaluated the latest receipt.
+      if(value.receipt_revision===null){
+        value=unavailableCached(state,'latest receipt selection unavailable; inspect receipt state before reuse',config.checks);
+      }else if(typeof value.receipt_revision!=='string'){
+        value=unavailableCached(state,'observer cannot confirm latest receipt selection; stop and start the observer after upgrading',config.checks);
+        process.exitCode=2;
+      }else if(value.receipt_revision!==receiptRevision(state)){
+        value=unavailableCached(state,'receipt selection changed during synchronization; retry synchronized status',config.checks);
+        process.exitCode=2;
+      }}
     catch(e){value=unavailableCached(state,e.message,config.checks);process.exitCode=2;}
     timing('cli.synchronized_status',started,{available:value.observation?.healthy?1:0});
     if(action==='sync')console.log(JSON.stringify(value));

package/src/daemon.mjs

@@ -14,7 +14,7 @@ import {sha} from './plan.mjs';
 import {InputIndex} from './index.mjs';
 import {permittedRoots} from './installed-inputs.mjs';
 import {assertOwnedStatePlacement} from './owned-state.mjs';
-import {atomicJson,readReceipts} from './state-store.mjs';
+import {atomicJson,readReceipts,readReceiptSnapshot,receiptRevision} from './state-store.mjs';
 import {history} from './observation.mjs';
 import {inputKey} from './decision-validation.mjs';
 import {timing} from './decision-profile.mjs';
@@ -33,6 +33,7 @@ fs.writeFileSync(path.join(lock,'pid'),String(process.pid),{mode:0o600});
 const generation=randomUUID(), startedAt=Date.now();
 let index, receipts={}, watcher, healthy=false, reason='initial reconciliation', stopping=false;
 let receiptStateError=null;
+let receiptStateRevision=null;
 const external=new Map();
 for(const check of config.checks)for(const boundary of permittedRoots(root,check.allowedExternalRoots||[]))
   if(!external.has(boundary))external.set(boundary,{root:boundary,watcher:null,index:null,
@@ -77,9 +78,20 @@ function event(kind,fields={}) {
     repository:root,...fields})+'\n');
 }
 function loadReceipts() {
-  try {receipts=readReceipts(state).checks;receiptStateError=null;}
-  catch(e){receipts={};receiptStateError=e.message;event('receipt_state_unavailable',
-    {classification:e.name||'Error'});}
+  try {const snapshot=readReceiptSnapshot(state);receipts=snapshot.value.checks;
+    receiptStateRevision=snapshot.revision;receiptStateError=null;}
+  catch(e){receiptStateRevision=null;
+    // A readable selector can still supply explicitly historical outcomes after
+    // restart. The failed snapshot guard remains authoritative for applicability.
+    try{receipts=readReceipts(state).checks;}catch{/* retain previous historical rows */}
+    const next=`latest receipt unavailable; prior outcome only: ${e.message}`;
+    if(receiptStateError!==next)event('receipt_state_unavailable',
+      {classification:e.name||'Error'});
+    receiptStateError=next;}
+}
+function refreshReceipts() {
+  try {if(receiptStateRevision===null||receiptRevision(state)!==receiptStateRevision)loadReceipts();}
+  catch {loadReceipts();}
 }
 function persistedPlan(bundle) {
   return {schema:1,provider:bundle.provider,root:bundle.root,discoveredAt:bundle.discoveredAt,
@@ -298,13 +310,16 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
   });
 }
 function status(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=false) {
+  // Reload notifications accelerate visibility but are not required for it: a
+  // wrapper may persist its outcome even when its control connection is denied.
+  refreshReceipts();
   const checks=rows(contextHashes,synchronizedInstalled,synchronizedFilesystem), current=checks.filter(r=>r.freshness==='CURRENT'&&r.result==='PASS').length,
     failed=checks.filter(r=>r.freshness==='CURRENT'&&r.result==='FAIL').length,
     observedFailed=checks.filter(r=>r.result==='FAIL').length,
     stale=checks.filter(r=>r.freshness==='STALE').length,
     unverified=checks.filter(r=>r.freshness==='UNVERIFIED').length||(!checks.length?1:0);
   const stateName=failed?'failed':unverified?'unverified':stale?'stale':'current';
-  const now=Date.now();return {schema:1,state:stateName,current,failed,observed_failed:observedFailed,
+  const now=Date.now();return {schema:1,receipt_revision:receiptStateRevision,state:stateName,current,failed,observed_failed:observedFailed,
     stale,unverified,checks,
     observation:{healthy:healthy&&!planning&&!recovering&&!index?.unavailable,
       generation,observed_at:lastObservation,

package/src/state-store.mjs

@@ -19,19 +19,55 @@ export function readReceipts(state){
   let value;
   try{value=JSON.parse(fs.readFileSync(path.join(state,'receipts-v1.json'),'utf8'));}
   catch(e){if(e.code==='ENOENT')return {schema:STATE_SCHEMA,checks:{}};throw e;}
-  if(value.schema!==STATE_SCHEMA||!value.checks||typeof value.checks!=='object')
+  if(!value||typeof value!=='object'||Array.isArray(value)||value.schema!==STATE_SCHEMA||
+    !value.checks||typeof value.checks!=='object'||Array.isArray(value.checks))
     throw Error(`incompatible receipt state in ${state}; inspect or remove only this vstate state directory`);
   return value;
 }
 
+// This identity detects replacement of REDUE's owned, atomically written receipt
+// selector. It is not an input-content fingerprint or permission to reuse inputs.
+export function receiptRevision(state){
+  // A failed/crashed owned writer may have persisted a new immutable outcome
+  // without replacing the selector. Never certify its older selection.
+  try {fs.lstatSync(path.join(state,'receipt-selection-pending-v1.json'));
+    throw Error('receipt selection update incomplete; inspect the failed run, then record a new execution to recover');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  try {const stat=fs.statSync(path.join(state,'receipts-v1.json'),{bigint:true});
+    if(!stat.isFile())throw Error('receipt selector is not a file');
+    return JSON.stringify(['dev','ino','size','mtimeNs','ctimeNs'].map(key=>String(stat[key])));
+  }catch(error){if(error.code==='ENOENT')return 'absent';throw error;}
+}
+
+export function readReceiptSnapshot(state){
+  const revision=receiptRevision(state),value=readReceipts(state);
+  if(receiptRevision(state)!==revision)
+    throw Error('receipt selection changed during read; retry status');
+  return {revision,value};
+}
+
 export function commitReceipt(state,name,receipt){
   const prior=readReceipts(state),runId=receipt.invocation?.runId;
   if(!/^[0-9a-f-]{36}$/.test(runId||''))throw Error('receipt lacks a valid run ID');
   const runs=path.join(state,'runs-v1');
   fs.mkdirSync(runs,{recursive:true,mode:0o700});
+  // The caller holds the state run lock. Leave this marker on any write failure;
+  // only a later successful owned commit may clear it. No journal scan guesses
+  // which incomplete execution should become the selected evidence.
+  const pending=path.join(state,'receipt-selection-pending-v1.json');
+  let updates={schema:STATE_SCHEMA,checks:{}};
+  try {updates=JSON.parse(fs.readFileSync(pending,'utf8'));
+    if(updates?.schema!==STATE_SCHEMA||!updates.checks||typeof updates.checks!=='object'||Array.isArray(updates.checks))
+      throw Error('incompatible incomplete receipt update; inspect owned state before recording');
+  }catch(error){if(error.code!=='ENOENT')throw error;}
+  updates.checks[name]={runId};
+  atomicJson(pending,updates);
   // One immutable outcome per invocation. Never overwrite an existing run.
   fs.writeFileSync(path.join(runs,runId+'.json'),
     JSON.stringify({schema:STATE_SCHEMA,check:name,receipt}),{flag:'wx',mode:0o600});
   prior.checks[name]=receipt;
   atomicJson(path.join(state,'receipts-v1.json'),prior);
+  delete updates.checks[name];
+  if(Object.keys(updates.checks).length)atomicJson(pending,updates);
+  else fs.unlinkSync(pending);
 }