@runeditrun/rer 0.0.0-stage → 0.1.0

package/modules/portability/legacy-files.mjs

@@ -0,0 +1,43 @@
+import { lstat } from 'node:fs/promises';
+import { policy } from './catalogue.mjs';
+import { createPortability } from './index.mjs';
+import { createImport, uploadPart, finalizeImport, abortImport } from './import.mjs';
+import { readLegacyArchive, ArchiveVerifier } from './format.mjs';
+import { fileRecords, exportArchive } from './files.mjs';
+import { ensureLegacyAudit, legacyEmptyTables, requireLegacyEmpty } from './legacy-safety.mjs';
+import { insist, PortabilityError } from './storage.mjs';
+
+export async function recoverLegacyArchive({db,buckets,policy:input,migrations},path,output,transient,acknowledged) {
+ insist(acknowledged===true,'legacy_acknowledgement_required',409);
+ insist(typeof output==='string' && output!==path,'legacy_output_required',409);
+ insist(!(await lstat(output).catch(error=>{if(error.code==='ENOENT')return null;throw error;})),'legacy_output_exists',409);
+ // Whole-file verification precedes even staging/audit schema writes.
+ for await(const record of fileRecords(path,readLegacyArchive)){}
+ const context={db,buckets,config:policy(input),migrations},emptyTables=await legacyEmptyTables(db);
+ await requireLegacyEmpty(context,emptyTables);
+ let id,manifest,closing,integrity,status,complete=false;
+ try {
+  for await(const record of fileRecords(path,readLegacyArchive)) {
+   if(record.kind==='manifest') {
+    // This is a local staging envelope, never an assertion of v1 provenance.
+    // Normal import/finalize retain their v2 checks and erasure fence.
+    manifest={...record,version:2};integrity=new ArchiveVerifier(manifest);
+    id=await createImport(context,manifest,'legacy-v1',{
+     event:'legacy_v1_unverified_restore',acknowledgedUnverifiedMetadata:true,
+     sourceIdentity:record.sourceIdentity,exportedAt:record.exportedAt,
+     recoveryOutput:output,emptyTables,
+    });
+    // A refused schema writes nothing, not even the audit table.
+    await ensureLegacyAudit(db);
+   }else if(record.kind==='part') {integrity.add(record);await uploadPart(context,id,record.index,record);}
+   else closing=record;
+  }
+  status=await finalizeImport(context,id,{contentHash:closing.contentHash,archiveHash:integrity.digest()});complete=true;
+ }finally{if(id&&!complete)await abortImport(context,id);}
+ // A fresh export binds the recovered installation from this point forward.
+ // A failure here must be reported; the durable restore audit remains intact.
+ try {
+  const recovered=await exportArchive(await createPortability({db,buckets,policy:input}),output,transient);
+  return {...recovered,legacyRecovery:true,unverifiedMetadata:true,restoredContentHash:closing.contentHash,...(status.bridged?{bridged:status.bridged}:{})};
+ }catch{throw new PortabilityError('legacy_restored_export_failed',500);}
+}

package/modules/portability/legacy-safety.mjs

@@ -0,0 +1,27 @@
+import { all, statement, guard, quote, insist } from './storage.mjs';
+import { canonicalJson } from './hash.mjs';
+
+// Recovery requires a new installation, including excluded identity tables and
+// normally replaceable product rows. Only SQLite/migration/transfer bookkeeping
+// may already exist. Do not use the product's export exclusions for this check.
+export async function legacyEmptyTables(db) {
+ const tables=await all(db,"SELECT name FROM sqlite_master WHERE type='table' AND sql IS NOT NULL ORDER BY name");
+ return tables.map(t=>t.name).filter(name=>!(/^(sqlite_|_cf_|rer_portability_)/i.test(name) || ['d1_migrations','_rer_deploy_migrations','_rer_portability_migrations'].includes(name.toLowerCase())));
+}
+export async function requireLegacyEmpty({db,buckets},tables) {
+ for(const table of tables)insist(!(await statement(db,`SELECT 1 FROM ${quote(table)} LIMIT 1`).first()),'legacy_target_not_empty:'+table,409);
+ for(const [name,bucket] of Object.entries(buckets))insist(!(await bucket.list({limit:1})).objects.length,'legacy_bucket_not_empty:'+name,409);
+}
+export function legacyEmptyGuards(db,row) {
+ return (row.metadata.legacyRecovery?.emptyTables??[]).map(table=>guard(db,`NOT EXISTS(SELECT 1 FROM ${quote(table)})`));
+}
+export async function ensureLegacyAudit(db) {
+ // Additive sidecar, installed only by recovery; existing product migrations
+ // and transfer cleanup cannot remove the completed recovery audit.
+ await db.prepare('CREATE TABLE IF NOT EXISTS rer_portability_recovery_audit (id TEXT PRIMARY KEY, recorded_at TEXT NOT NULL, details TEXT NOT NULL)').run();
+}
+export function legacyAuditStatements(db,row) {
+ if(!row.metadata.legacyRecovery)return [];
+ const {emptyTables,...details}=row.metadata.legacyRecovery;
+ return [statement(db,'INSERT INTO rer_portability_recovery_audit VALUES(?,?,?)',row.id,new Date().toISOString(),canonicalJson({...details,contentHash:row.metadata.contentHash,...(row.metadata.bridge?{bridged:row.metadata.bridge}:{})}))];
+}

package/modules/portability/lines.mjs

@@ -0,0 +1,36 @@
+/** Read one bounded UTF-8 line at a time; never materialize the complete archive. */
+export async function* archiveLines(source, maxLineBytes) {
+  if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1) throw new Error('Invalid archive line limit.');
+  const reader = source.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  let buffer = new Uint8Array(Math.min(maxLineBytes, 65_536)), bytes = 0;
+  function append(fragment) {
+    const required = bytes + fragment.byteLength;
+    if (required > maxLineBytes) throw new Error('An archive line exceeds the supported size.');
+    if (required > buffer.length) {
+      const grown = new Uint8Array(Math.min(maxLineBytes, Math.max(required, buffer.length * 2)));
+      grown.set(buffer.subarray(0, bytes)); buffer = grown;
+    }
+    buffer.set(fragment, bytes); bytes = required;
+  }
+  function line() {
+    const value = decoder.decode(buffer.subarray(0, bytes)); bytes = 0;
+    return value.endsWith('\r') ? value.slice(0, -1) : value;
+  }
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      let offset = 0;
+      for (let index = 0; index < next.value.length; index++) {
+        if (next.value[index] !== 10) continue;
+        append(next.value.subarray(offset, index));
+        yield line(); offset = index + 1;
+      }
+      append(next.value.subarray(offset));
+    }
+    if (bytes) yield line();
+  } finally {
+    await reader.cancel(); reader.releaseLock();
+  }
+}

package/modules/portability/migration-history.mjs

@@ -0,0 +1,18 @@
+import { DatabaseSync } from 'node:sqlite';
+import { policy, schemaIdentity } from './catalogue.mjs';
+
+// Replays a chosen set of the destination's migrations, in its applied order,
+// into a scratch database and returns the resulting archive schema identity.
+// Node runners only: restore uses it to place an older archive within the
+// destination's history (see bridge.mjs). plan: [{name,statements}].
+export function migrationReplay(plan,input) {
+  const config=policy(input);
+  return {names:plan.map(migration=>migration.name),statements:name=>plan.find(m=>m.name===name).statements,async schemaAfter(names) {
+    const scratch=new DatabaseSync(':memory:');
+    const db={prepare:sql=>{const query=scratch.prepare(sql);let values=[];return {bind(...args){values=args;return this;},async all(){return {results:query.all(...values)};}};}};
+    try {
+      for(const migration of plan.filter(m=>names.includes(m.name)))for(const sql of migration.statements)scratch.exec(sql);
+      return await schemaIdentity(db,config);
+    }finally{scratch.close();}
+  }};
+}

package/modules/portability/migration-statements.mjs

@@ -0,0 +1,23 @@
+import { tokens, identifier, folded } from './generated.mjs';
+
+// Whether one migration statement can change rows a restore carries. Only
+// CREATE TABLE (not AS SELECT), CREATE INDEX and ALTER TABLE ... ADD COLUMN
+// are additive: SQLite refuses ADD COLUMN with a non-constant default, so a
+// restored row takes the same value the migration gave existing rows. Any
+// other statement (INSERT, UPDATE, DELETE, triggers, table rebuilds) changes
+// data unless it names none of the restorable tables, as when it only touches
+// operator-auth or other excluded tables.
+export function changesData(sql,restorable) {
+  const list=tokens(sql),words=list.map(t=>t.quoted?undefined:folded(t.text));
+  const kind=words.slice(0,4).filter(w=>!['temp','temporary','unique'].includes(w)).slice(0,2).join(' ');
+  if(kind==='create table')return topLevelWords(list,words).includes('as');
+  if(kind==='create index')return false;
+  if(kind==='alter table' && words.find((w,i)=>i>2 && ['add','rename','drop'].includes(w))==='add')return false;
+  const names=new Set(restorable.map(folded));
+  return list.some(t=>t.quoted ? !t.text.startsWith("'") && names.has(folded(identifier(t))) : t.text.split('.').some(part=>names.has(folded(part))));
+}
+function topLevelWords(list,words) {
+  let depth=0;const result=[];
+  list.forEach((t,i)=>{if(t.text==='(')depth++;else if(t.text===')')depth--;else if(!depth)result.push(words[i]);});
+  return result;
+}

package/modules/portability/payloads.mjs

@@ -0,0 +1,52 @@
+import { stream, run, all, insist } from './storage.mjs';
+import { base64, unbase64, StreamHash } from './hash.mjs';
+export async function* byteChunks(source,limit) {
+  const reader=(source instanceof ReadableStream?source:new Response(source).body).getReader();
+  let pending=new Uint8Array(limit),used=0;
+  try {
+    for(;;) {
+      const {value,done}=await reader.read();if(done)break;
+      let offset=0;
+      while(offset<value.length) {
+        const n=Math.min(limit-used,value.length-offset);pending.set(value.subarray(offset,offset+n),used);offset+=n;used+=n;
+        if(used===limit){yield pending;pending=new Uint8Array(limit);used=0;}
+      }
+    }
+    if(used)yield pending.subarray(0,used);
+  } finally {await reader.cancel();reader.releaseLock();}
+}
+export async function capturePayload(db,id,number,source) {
+  const hash=new StreamHash();let size=0,segment=0;
+  for await(const bytes of byteChunks(source,16000)) {
+    hash.update(bytes);size+=bytes.length;
+    await run(db,'INSERT INTO rer_portability_segments VALUES(?,?,?,?)',id,-1-number,segment++,base64(bytes));
+  }
+  return {size,sha256:hash.digest()};
+}
+export async function payloadRange(db,id,number,offset,length) {
+  const rows=await all(db,'SELECT segment,data FROM rer_portability_segments WHERE job=? AND part=? AND segment>=? AND segment<=? ORDER BY segment',id,-1-number,Math.floor(offset/16000),Math.floor((offset+length-1)/16000));
+  const result=new Uint8Array(length);let used=0;
+  for(const row of rows) {
+    const bytes=unbase64(row.data),start=Math.max(0,offset-row.segment*16000),n=Math.min(bytes.length-start,length-used);
+    result.set(bytes.subarray(start,start+n),used);used+=n;
+  }
+  insist(used===length,'payload_changed');return result;
+}
+export async function writeObject(bucket,descriptor,source) {
+  const metadata={httpMetadata:descriptor.httpMetadata?{...descriptor.httpMetadata}:undefined,customMetadata:descriptor.customMetadata};
+  if(metadata.httpMetadata?.cacheExpiry)metadata.httpMetadata.cacheExpiry=new Date(metadata.httpMetadata.cacheExpiry);
+  const hash=new StreamHash();let size=0;
+  if(descriptor.size<=5*1024*1024) {
+    const bytes=new Uint8Array(descriptor.size);
+    for await(const chunk of byteChunks(source,65536)) {insist(size+chunk.length<=bytes.length,'binary_size');bytes.set(chunk,size);hash.update(chunk);size+=chunk.length;}
+    insist(size===descriptor.size && hash.digest()===descriptor.sha256,'binary_checksum');
+    await bucket.put(descriptor.key,bytes,metadata);return;
+  }
+  const upload=await bucket.createMultipartUpload(descriptor.key,metadata),parts=[];
+  try {
+    for await(const chunk of byteChunks(source,5*1024*1024)) {
+      hash.update(chunk);size+=chunk.length;parts.push(await upload.uploadPart(parts.length+1,chunk));
+    }
+    insist(size===descriptor.size && hash.digest()===descriptor.sha256,'binary_checksum');await upload.complete(parts);
+  } catch(e) {await upload.abort();throw e;}
+}

package/modules/portability/provider-data.mjs

@@ -0,0 +1,25 @@
+import { all, quote, insist } from './storage.mjs';
+import { sidecar, copyRowid } from './copies.mjs';
+const TRANSIENT=['oa_setup_links','rer_dependency_keys','rer_dependency_pending','rer_dependency_codes','oa_provider_sessions','oa_provider_session_pins','oa_oidc_transactions','oa_step_up_challenges','oa_identity_provider_health'];
+// Mandatory secret/session filtering even when a product explicitly includes a table.
+export async function dropProviderData(db,tables,copies) {
+ const commands=[];
+ for(const table of tables) {
+  const copy=copies[table.name];if(!copy)continue;
+  const condition=TRANSIENT.includes(table.name)?'1':table.name==='oa_sessions' && table.columns.some(c=>c.name==='kind')?"kind='oidc'":null;
+  if(condition) {
+   commands.push(db.prepare(`DELETE FROM ${quote(sidecar(copy))} WHERE rer_portability_copy_rowid IN (SELECT ${copyRowid(table)} FROM ${quote(copy)} WHERE ${condition})`));
+   commands.push(db.prepare(`DELETE FROM ${quote(copy)} WHERE ${condition}`));
+  }
+  if(table.name==='rer_dependency_link')commands.push(db.prepare(`UPDATE ${quote(copy)} SET needs_relink=1`));
+  if(table.name==='oa_identity_providers')commands.push(db.prepare(`UPDATE ${quote(copy)} SET status='unlinked',jwks=NULL,pending_issuer=NULL,pending_client_id=NULL,pending_preset=NULL,pending_at=NULL`));
+  if(table.name==='oa_auth_settings')commands.push(db.prepare(`UPDATE ${quote(copy)} SET idp_sign_in=0,first_setup=0,generation=generation+1`));
+ }
+ if(commands.length)await db.batch(commands);
+}
+export async function refuseProviderData(db,copies,tables) {
+ for(const name of TRANSIENT) if(copies[name])insist(!(await all(db,`SELECT 1 FROM ${quote(copies[name])} LIMIT 1`)).length,'provider_transient_data',409);
+ if(copies.oa_sessions && tables.find(t=>t.name==='oa_sessions')?.columns.some(c=>c.name==='kind'))insist(!(await all(db,`SELECT 1 FROM ${quote(copies.oa_sessions)} WHERE kind='oidc' LIMIT 1`)).length,'provider_session_data',409);
+ if(copies.rer_dependency_link)insist(!(await all(db,`SELECT 1 FROM ${quote(copies.rer_dependency_link)} WHERE needs_relink!=1 LIMIT 1`)).length,'provider_relink_required',409);
+ if(copies.oa_auth_settings)insist(!(await all(db,`SELECT 1 FROM ${quote(copies.oa_auth_settings)} WHERE idp_sign_in!=0 OR first_setup!=0 LIMIT 1`)).length,'provider_sign_in_must_be_off',409);
+}

package/modules/portability/restore-safety.mjs

@@ -0,0 +1,30 @@
+import { all,statement,guard,quote,insist } from './storage.mjs';
+const identifier=value=>value.replace(/[A-Z]/g,c=>c.toLowerCase());
+
+export async function excludedDependentGuards(db,targets,replaceable) {
+  if(!replaceable.length)return [];
+  const tables=await all(db,"SELECT name,sql FROM sqlite_master WHERE type='table' AND sql IS NOT NULL ORDER BY name"),references=[];
+  // REFERENCES is required in every FK declaration. Tables without that keyword have no
+  // FKs, including D1's protected metadata tables which refuse PRAGMA inspection.
+  for(const table of tables.filter(t=>/\bREFERENCES\b/i.test(t.sql)))for(const fk of await all(db,`PRAGMA foreign_key_list(${quote(table.name)})`)) {
+    const parent=tables.find(t=>identifier(t.name)===identifier(fk.table))?.name??fk.table;
+    if([fk.on_delete,fk.on_update].some(action=>['CASCADE','SET NULL','SET DEFAULT'].includes(action)))references.push({child:table.name,parent});
+  }
+  const affected=new Set(replaceable),protectedTables=new Map();
+  let changed=true;
+  while(changed) {
+    changed=false;
+    for(const {child,parent} of references)if(affected.has(parent)) {
+      if(!targets.some(t=>t.name===child))protectedTables.set(child,parent);
+      if(!affected.has(child)){affected.add(child);changed=true;}
+    }
+  }
+  const guards=[];
+  for(const [child,parent] of protectedTables) {
+    // Conservatively refuse populated excluded dependents, including transitive actions.
+    // Repeat this condition inside the atomic commit to catch rows added after validation.
+    insist(!(await statement(db,`SELECT 1 FROM ${quote(child)} LIMIT 1`).first()),'excluded_destination_dependents:'+child+':'+parent,409);
+    guards.push(guard(db,`NOT EXISTS(SELECT 1 FROM ${quote(child)})`));
+  }
+  return guards;
+}

package/modules/portability/schema/portability.sql

@@ -0,0 +1,25 @@
+CREATE TABLE rer_portability_state (
+  id INTEGER PRIMARY KEY CHECK(id=1), source_identity TEXT NOT NULL, epoch INTEGER NOT NULL DEFAULT 0,
+  import_job TEXT, applying INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE rer_portability_jobs (
+  id TEXT PRIMARY KEY, kind TEXT NOT NULL, actor TEXT NOT NULL, phase TEXT NOT NULL,
+  completed INTEGER NOT NULL DEFAULT 0, metadata TEXT NOT NULL
+);
+CREATE TABLE rer_portability_parts (
+  job TEXT NOT NULL REFERENCES rer_portability_jobs(id) ON DELETE CASCADE,
+  idx INTEGER NOT NULL, sha256 TEXT NOT NULL, PRIMARY KEY(job,idx)
+);
+CREATE TABLE rer_portability_segments (
+  job TEXT NOT NULL REFERENCES rer_portability_jobs(id) ON DELETE CASCADE,
+  part INTEGER NOT NULL, segment INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY(job,part,segment)
+);
+CREATE TABLE rer_portability_owned (
+  job TEXT NOT NULL REFERENCES rer_portability_jobs(id) ON DELETE CASCADE,
+  bucket TEXT NOT NULL, key TEXT NOT NULL, PRIMARY KEY(job,bucket,key)
+);
+CREATE TABLE rer_portability_journal (
+  source TEXT NOT NULL, tombstone TEXT NOT NULL, PRIMARY KEY(source,tombstone)
+);
+CREATE TABLE rer_portability_epochs (source TEXT PRIMARY KEY, epoch INTEGER NOT NULL);
+CREATE TABLE rer_portability_guard (value INTEGER NOT NULL CHECK(value=1));

package/modules/portability/storage.mjs

@@ -0,0 +1,49 @@
+import { canonicalJson } from './hash.mjs';
+export class PortabilityError extends Error {
+  constructor(code, status=400) { super(code); this.code=code; this.status=status; }
+}
+export function insist(condition, code, status=400) { if (!condition) throw new PortabilityError(code,status); }
+export const quote = name => '"'+name.replaceAll('"','""')+'"';
+export const statement = (db,sql,...values) => values.length ? db.prepare(sql).bind(...values) : db.prepare(sql);
+export const all = async (db,sql,...values) => (await statement(db,sql,...values).all()).results;
+export const run = (db,sql,...values) => statement(db,sql,...values).run();
+export function guard(db,condition,...values) {
+  return statement(db,`INSERT INTO rer_portability_guard(value) SELECT CASE WHEN (${condition}) THEN 1 ELSE 0 END`,...values);
+}
+export async function state(db) {
+  await run(db,'INSERT OR IGNORE INTO rer_portability_state(id,source_identity) VALUES(1,?)',crypto.randomUUID());
+  return statement(db,'SELECT * FROM rer_portability_state WHERE id=1').first();
+}
+export async function job(db,id,kind) {
+  const row=await statement(db,'SELECT * FROM rer_portability_jobs WHERE id=?',id).first();
+  insist(row && (!kind || row.kind===kind),'job_not_found',404);
+  return {...row, metadata:JSON.parse(row.metadata)};
+}
+export function save(db,row) {
+  return statement(db,'UPDATE rer_portability_jobs SET phase=?,completed=?,metadata=? WHERE id=?',row.phase,row.completed,canonicalJson(row.metadata),row.id);
+}
+export function partStatements(db,id,part) {
+  const json=canonicalJson(part), result=[statement(db,'INSERT INTO rer_portability_parts VALUES(?,?,?)',id,part.index,part.sha256)];
+  for(let i=0,segment=0;i<json.length;segment++) {
+    let end=Math.min(i+32000,json.length);
+    const last=json.charCodeAt(end-1),next=json.charCodeAt(end);
+    if(last>=0xd800 && last<=0xdbff && next>=0xdc00 && next<=0xdfff) end--;
+    result.push(statement(db,'INSERT INTO rer_portability_segments VALUES(?,?,?,?)',id,part.index,segment,json.slice(i,end)));i=end;
+  }
+  return result;
+}
+export async function readPart(db,id,index) {
+  const rows=await all(db,'SELECT data FROM rer_portability_segments WHERE job=? AND part=? ORDER BY segment',id,index);
+  insist(rows.length,'part_missing');
+  return JSON.parse(rows.map(x=>x.data).join(''));
+}
+export async function* parts(db,id,count) { for(let i=0;i<count;i++) yield await readPart(db,id,i); }
+export function stream(generator) {
+  const iterator=generator[Symbol.asyncIterator]();
+  return new ReadableStream({async pull(controller){try{const next=await iterator.next();if(next.done)controller.close();else controller.enqueue(next.value);}catch(e){controller.error(e);}},async cancel(){await iterator.return?.();}});
+}
+export function transferTables(row) { return Object.values(row.metadata.copies??{}).flatMap(name=>[name,name+'_meta']); }
+export async function cleanCopies(db,row) {
+  await db.batch([...transferTables(row).map(name=>db.prepare(`DROP TABLE IF EXISTS ${quote(name)}`)),
+    statement(db,'DELETE FROM rer_portability_parts WHERE job=?',row.id),statement(db,'DELETE FROM rer_portability_segments WHERE job=?',row.id)]);
+}

package/modules/release/README.md

@@ -0,0 +1,212 @@
+# `rer release`
+
+Before a Base release, run `pnpm verify:scale` for the full import-kit datasets. It
+is not part of `pnpm verify`: run it on a machine with at least 16 GB of memory and
+nothing else heavy running, because its D1 datasets are large.
+
+Set `PUBLIC_PROJECT` to the edition's project identity and `PUBLIC_REPOSITORY`
+to its public GitHub destination URL. From Base, run:
+
+```sh
+pnpm rer release --repo /path/to/seed --ref main \
+  --project "$PUBLIC_PROJECT" --repository "$PUBLIC_REPOSITORY" \
+  --output /path/to/new-release-directory
+```
+
+The `rer` bin and `node bin/rer.mjs` expose the same command. Node 22+, Python 3,
+Git, pnpm and tar are required. Use a full, clean seed clone with its declared
+package-manager version and browser prerequisites available. The producer reads
+committed `seed.json`, `package.json`, `RELEASE.json`, `LICENSE`, `CONTRACT.md` and
+`AGENTS.md`. Version declarations must agree. `--project` declares the publishing
+identity; `--repository` is the credential-free public destination URL. Neither is inferred
+from repository naming or old site listings.
+
+When either `edition.json` or `rer-project.json` exists, both must be ordinary
+committed JSON objects. Before installing dependencies, running verification,
+creating output or tagging, the producer requires `edition.json.id` and
+`rer-project.json.projectId` to agree with `--project`. Separately,
+`rer-project.json.sourceRepository` must agree with `--repository`. If
+`edition.json.custody.repository` is present it must agree with `--repository`
+too; the custody declaration is optional. The project identity may differ from
+the repository identity. Repository fields are credential-free HTTPS GitHub
+URLs; identity comparison ignores case and a terminal `.git` in URLs. Missing,
+malformed, partial or inconsistent identities fail closed. The selected
+committed tree supplies the declarations.
+
+The platform reads these same HTTPS GitHub URLs, plus bare an owner and repository name separated by a slash for releases that carry it; ordinary release editions still require the URL here.
+
+Every publication scan receives the explicit project and destination: source
+history, staged final annotations, parentless exports and dry runs. If GitHub's
+API returns a complete Not Found response with HTTP status 404 for that exact
+agreed repository destination, references to it are `pending-public-destination`
+with severity `INFO` in the report's `info` array. Other missing repositories and
+existing private repositories, including the agreed target, still fail. A distinct project identity receives ordinary
+reference checks. Empty, malformed or unresolved API responses remain
+INCOMPLETE. This rule does not exempt other defects in the same file or message
+and does not authorize publication. Legacy sources with neither declaration
+accept independent project and repository inputs, retain strict reference checks
+and cannot receive this INFO classification.
+
+It installs frozen dependencies and runs `pnpm run verify` in a disposable clone
+of the exact selected commit, then scans the original repository's complete
+local-ref history with publish-check. A verify that mutates tracked source fails.
+When declared in the committed package, it runs `pnpm run verify:release` after
+default verification succeeds. Keep capacity, maximum-size memory and load cases
+in that release-only script. Both dry runs and releases require it to pass;
+`gates.verify.release` records its result. Routine CI and default verification
+do not invoke it.
+Child logs are suppressed to avoid credential disclosure; the receipt retains
+exit status and numeric final summaries from Node's spec/TAP reporters and
+Playwright's text reporters. Counts add across suites: `tests`, `passed`,
+`failed`, `skipped` and `flaky`; nonzero `cancelled`, `todo`, `interrupted` and
+`notRun` counts are retained when reported. Playwright's total includes each
+outcome once, with flaky tests counted separately from passed tests. Node's
+reported total is used directly. Unrecognized output is suppressed and contributes
+no counts; the child exit status still determines the verification gate. Source
+metadata and Git blobs are never loaded as producer code.
+
+With `--tag`, passing gates produce `public-source.tar`, containing the checked tree's
+exact ordinary files without Git history, and a hash-pinned site bundle:
+`site/<id>/<version>/release.json`, published documents and `site/registry.json`.
+Export attributes cannot silently omit or substitute bytes. The site metadata
+comes from committed seed and contract data; no screenshots, install guarantees
+or verified maturity claims are invented. Copy the reviewed bundle into the site
+release registry through its normal review process; the one-entry generated
+registry is input for that integration, not a replacement for the site's registry.
+
+By default, success writes only the receipt, publication report and site preview;
+its provenance says `publication: dry-run`. It creates no tag or source archive.
+Pass **`--tag`** to create an annotated local `v<version>` tag at the verified
+commit and the exact source export. Existing tags are never changed. The command
+**never pushes,
+changes repository visibility, dispatches Actions, deploys or edits a site**.
+Publication and deployment retain their separate owner authorization.
+
+`--dry-run` performs the real install, verify and history scan and suppresses
+tag creation even with `--tag`. `--tag --dry-run` also prepares the source archive
+for inspection. Existing tags do not prevent previews.
+If gates fail, it exits 1, omits the source export, records BLOCKED in
+`release-receipt.json` and still prepares a site preview whose provenance says
+`publication: blocked`, with the actual gate results. That preview is for local
+review and must not enter the public registry. Blocked `--tag` releases without
+`--dry-run` produce only the receipt and redacted publication report. A bare
+blocked release still writes the blocked preview. Invalid inputs exit 2. Outputs
+must be new directories outside the source and may not traverse symlinks.
+
+The first producer supports MIT seed listings and ordinary-file source trees.
+Service integration bundles remain outside this command. Run producer tests
+with `pnpm verify:release`; fixtures never replace seed verification in a pilot.
+
+For a first public release whose private development history must stay private,
+add `--clean-history --env-file /path/to/credentials.env`. The default history
+gate is unchanged. This explicit mode constructs an ordinary-file parentless Git
+repository, verifies its tree equals the selected source tree, and runs the full
+history scanner against that actual public export, including environment hashes.
+Passing tagged releases include `public-git/` with `main` and an annotated release
+tag. The private source tag points to the verified private commit; the export tag
+and site provenance point to the parentless public commit. The receipt records
+both identities and `publicationHistory: parentless-export`. Never push private
+source history to the public repository. Neither mode publishes anything.
+
+Public export commit and annotated-tag messages contain the version and optional
+`RELEASE.json.publicReleaseNotes` only. Private source commit identities stay in
+the private release receipt. The clean export's final annotated tag exists
+before publication inspection, and the checked repository is copied unchanged
+into `public-git/`. Ordinary releases inspect their source history and stage the
+exact final annotation in a disposable checkout for inspection before creating
+the source tag. Release notes pass the same content rules as the public tree.
+
+## Releasing a seed that is already public
+
+Use `--onto` to create one public child of the destination's current branch from
+an independently developed private source tree:
+
+```sh
+pnpm rer release --repo /path/to/private-seed --ref main \
+  --project "$PUBLIC_PROJECT" --repository "$PUBLIC_REPOSITORY" \
+  --onto "$PUBLIC_REPOSITORY#main" --tag v1.2.3 --dry-run \
+  --env-file ~/.env --output /path/to/new-release-directory
+```
+
+The committed version must match the tag. The credential-free `--onto` URL must
+match `--repository` and the committed destination declarations; its explicit
+branch must exist in a confirmed PUBLIC repository. Pending, private, unresolved
+or ambiguous destinations and an existing public version tag are refused.
+`--onto` and `--clean-history` are mutually exclusive.
+
+The producer pins the advertised public tip, installs frozen dependencies and
+runs the exact selected private commit's real verification. It builds an
+isolated public repository containing only public ancestry and the selected
+source blobs. The new commit has exactly the pinned public tip as its sole
+parent, and its tree must equal the private source tree, including executable
+modes and raw blob bytes. Attributes cannot change or omit source content.
+Private source commits and refs are never imported. Public commit and annotated
+tag messages contain only `vVERSION` and optional trimmed
+`RELEASE.json.publicReleaseNotes`.
+
+The actual final annotation is staged before the real publication inspection,
+which receives `--public-base` for the declared destination. Only PASS with
+complete history inspection and that exact pinned base can produce artifacts.
+The destination's visibility, branch tip and absent version tag are checked
+again after scanning and immediately before final handoff. A changed, removed,
+unresolved or ambiguous head blocks the artifact; start again against the new
+public tip. The producer never pushes anything.
+
+A passing tagged run writes `public-git/`, `public-source.tar`, the site bundle,
+`publish-check.json`, `release-receipt.json` and `PUBLISH.md`. The receipt uses
+`publicationHistory: public-child`, names `publicParent`, and records the public
+commit, exact tree and annotated tag object. Site provenance names the public
+child. `--tag vVERSION --dry-run` prepares and scans the same public tag and
+handoff without changing any private source tag. Without `--dry-run`, success
+also annotates the selected private source commit as in existing modes. An
+untagged run remains a preview without public Git/archive/handoff artifacts.
+
+Review the report and receipt before publishing. The generated `PUBLISH.md`
+contains this complete shell sequence with concrete artifact-specific values;
+the angle-bracket values below mark those substitutions. Run the generated
+commands as written, from any directory, without changing their values:
+
+```sh
+set -eu
+artifact='<ARTIFACT_DIRECTORY>'
+cd -- "$artifact/public-git"
+release_output=$(node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/release-receipt.json") || exit 1
+test "$release_output" = '<RELEASE_RECEIPT_SHA256>'
+release_output=$(node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/publish-check.json") || exit 1
+test "$release_output" = '<PUBLISH_CHECK_SHA256>'
+release_output=$(node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/public-git/.git/config") || exit 1
+test "$release_output" = '<PUBLIC_GIT_CONFIG_SHA256>'
+# Discard inherited Git overrides while keeping authentication in the environment.
+release_git() {
+  node -e 'const cp=require("node:child_process"); const env=Object.fromEntries(Object.entries(process.env).filter(([k])=>!k.startsWith("GIT_") && k!=="GH_DEBUG" && k!=="DEBUG")); Object.assign(env,{GIT_CONFIG_NOSYSTEM:"1",GIT_CONFIG_GLOBAL:"/dev/null",GIT_NO_REPLACE_OBJECTS:"1",GIT_GRAFT_FILE:"/dev/null",GIT_TERMINAL_PROMPT:"0"}); const result=cp.spawnSync("git",["--no-replace-objects","-c","core.hooksPath=/dev/null","-c","core.useReplaceRefs=false","-c","push.followTags=false","-c","credential.helper=","-c","credential.helper=!gh auth git-credential",...process.argv.slice(1)],{env,stdio:"inherit"}); process.exit(result.status??1);' -- "$@"
+}
+release_output=$(release_git rev-parse --show-toplevel) || exit 1
+test "$release_output" = "$artifact/public-git"
+release_output=$(release_git rev-parse HEAD) || exit 1
+test "$release_output" = '<PUBLIC_COMMIT>'
+release_output=$(release_git rev-parse 'HEAD^{tree}') || exit 1
+test "$release_output" = '<PUBLIC_TREE>'
+release_output=$(release_git rev-list --parents -n 1 HEAD) || exit 1
+test "$release_output" = '<PUBLIC_COMMIT> <PINNED_PARENT>'
+release_output=$(release_git cat-file -t 'refs/tags/<VERSION_TAG>') || exit 1
+test "$release_output" = tag
+release_output=$(release_git rev-parse 'refs/tags/<VERSION_TAG>') || exit 1
+test "$release_output" = '<ANNOTATED_TAG_OBJECT>'
+release_output=$(release_git rev-parse 'refs/tags/<VERSION_TAG>^{commit}') || exit 1
+test "$release_output" = '<PUBLIC_COMMIT>'
+release_output=$(release_git ls-remote --refs -- '<DESTINATION_URL>' 'refs/heads/<DESTINATION_BRANCH>' 'refs/tags/<VERSION_TAG>') || exit 1
+test "$release_output" = '<PINNED_PARENT>	refs/heads/<DESTINATION_BRANCH>'
+release_git push --atomic --no-follow-tags -- '<DESTINATION_URL>' '<PUBLIC_COMMIT>:refs/heads/<DESTINATION_BRANCH>' '<ANNOTATED_TAG_OBJECT>:refs/tags/<VERSION_TAG>'
+```
+
+The receipt, report and Git config hashes bind the handoff to the reviewed
+artifact. The local checks require the exact commit, tree, sole parent,
+annotated tag object and peeled commit. The remote check requires exactly the
+pinned branch parent and no version tag. The final command makes one ordinary
+atomic push of that commit and tag; it never forces, rewrites history or pushes
+private refs. A failed guard requires a fresh artifact. Keep the private source
+tag in the private repository.
+
+Generated source commits and annotated tags identify Run Edit Run with the
+non-contact address `releases@runeditrun.invalid`. Provenance remains bound to
+the source commit and tree; the Git author address is not a delivery destination.

package/modules/release/catalogue.mjs

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+export const json = value => JSON.stringify(value, null, 2) + '\n';
+
+function clauses(text) {
+  const result = [];
+  let current = null;
+  const finish = () => {
+    if (!current) return;
+    const body = current.body.join(' ').replace(/\s+/gu, ' ').trim();
+    if (body) result.push({ id: current.id, title: current.title, text: body });
+    current = null;
+  };
+  const clauseLine = /^- \*\*([A-Z][A-Z0-9-]*-\d{3})\s+[—–-]\s+(.+?)\.?\*\*[ \t]*(.*)$/;
+  for (const line of text.split(/\r\n|\n|\r/)) {
+    const match = clauseLine.exec(line);
+    if (match) {
+      finish();
+      current = { id: match[1], title: match[2], body: [match[3]] };
+      continue;
+    }
+    if (!current) continue;
+    if (!line.trim() || /^[\t ]/.test(line)) {
+      current.body.push(line);
+      continue;
+    }
+    finish();
+  }
+  finish();
+  if (!result.length) throw Error('CONTRACT.md must contain published clauses');
+  return result;
+}
+
+export function catalogue(source, project, repository, gates, dryRun) {
+  const s = source.seed;
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s.id)) throw Error('Invalid seed listing ID');
+  for (const key of ['name', 'category', 'description', 'maturity'])
+    if (typeof s[key] !== 'string' || !s[key]) throw Error('Incomplete seed listing metadata');
+  const contract = clauses(source.bytes('CONTRACT.md').toString());
+  const licence = source.bytes('LICENSE').toString();
+  if (!licence.includes('Permission is hereby granted, free of charge')) throw Error('Declare a supported listing licence');
+  const docs = ['seed.json', 'CONTRACT.md', 'AGENTS.md', 'LICENSE', 'RELEASE.json',
+    ...['README.md', 'BASELINE.md', 'OPERATIONS.md', 'ACCEPTANCE.md'].filter(path => source.entries.has(path))];
+  const artifacts = docs.map(path => ({ path: `documents/${path}`, target: `agents/seeds/${s.id}/${path}`, sha256: sha256(source.bytes(path)) }));
+  const listing = { id: s.id, name: s.name, licence: 'MIT', repository, category: s.category,
+    categoryLabel: s.categoryLabel ?? s.category, version: s.version, oneLiner: s.description,
+    summary: s.description, maturity: s.maturity, replaces: s.replaces ?? [], clauses: contract,
+    clauseCount: contract.length, nonGoals: s.nonGoals ?? [], externals: (s.externals ?? []).map(e => ({
+      name: e.name ?? e.id, reason: e.reason ?? e.why, required: e.required, data: e.data ?? [], adapters: e.adapters ?? [],
+    })), extensionPoints: Array.isArray(s.extensionPoints) ? s.extensionPoints : Object.values(s.extensionPoints ?? {}).flat(),
+    shots: [], landing: null, hasReadme: docs.includes('README.md'), hasBaseline: docs.includes('BASELINE.md'), manifestFile: 'seed.json' };
+  for (const key of ['scope', 'spine', 'composition', 'operatingCost', 'limits', 'accessibility']) if (s[key] !== undefined) listing[key] = s[key];
+  return { schemaVersion: 1, project, release: s.version, provenance: {
+    kind: dryRun ? 'release-preview' : 'publisher-release', repository, revision: source.commit, tree: source.tree,
+    publication: dryRun ? (gates.verify.status === 'PASS' && gates.publishCheck.status === 'PASS' ? 'dry-run' : 'blocked') : 'local-release',
+    tag: source.tag, gates, note: dryRun
+      ? (source.publicTagStaged ? 'Local review preview; public export tag staged. No private source tag created or push performed.'
+        : 'Local review preview; no tag created or pushed and no visibility change.')
+      : 'Local tag and export; no push, deployment or visibility change.',
+  }, listing, artifacts };
+}
+
+export function writeCatalogue(source, output, manifest) {
+  const directory = resolve(output, 'site', source.seed.id, source.seed.version);
+  for (const artifact of manifest.artifacts) {
+    const path = resolve(directory, artifact.path);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, source.bytes(artifact.path.slice('documents/'.length)), { flag: 'wx' });
+  }
+  const bytes = json(manifest);
+  const releasePath = `${source.seed.id}/${source.seed.version}/release.json`;
+  writeFileSync(resolve(directory, 'release.json'), bytes, { flag: 'wx' });
+  writeFileSync(resolve(output, 'site/registry.json'), json({ schemaVersion: 1, snapshot: source.timestamp,
+    releases: [{ path: releasePath, sha256: sha256(bytes) }] }), { flag: 'wx' });
+  return { path: `site/${releasePath}`, sha256: sha256(bytes) };
+}