@aetheros/kernel-runtime 0.0.0-stage → 0.1.1

package/src/connectors.js

@@ -0,0 +1,71 @@
+const EFFECTS=new Set(['read','write']);
+const clone=value=>structuredClone(value);
+const text=(value,label)=>{if(typeof value!=='string'||!value.trim())throw new Error(label+' required');return value;};
+
+function stableJson(value,label){
+  const active=new Set();
+  const visit=item=>{
+    if(item===null||typeof item==='string'||typeof item==='boolean')return;
+    if(typeof item==='number'&&Number.isFinite(item))return;
+    if(typeof item!=='object'||ArrayBuffer.isView(item)||item instanceof Date||active.has(item))throw new Error(label+' must be stable JSON');
+    active.add(item);
+    if(Array.isArray(item)){for(let index=0;index<item.length;index+=1){if(!Object.hasOwn(item,index))throw new Error(label+' must be stable JSON');visit(item[index]);}}
+    else{const prototype=Object.getPrototypeOf(item);if(prototype!==Object.prototype&&prototype!==null)throw new Error(label+' must be stable JSON');for(const child of Object.values(item))visit(child);}
+    active.delete(item);
+  };
+  visit(value);
+  const encoded=JSON.stringify(value);
+  if(encoded===undefined)throw new Error(label+' must be stable JSON');
+  const decoded=JSON.parse(encoded);
+  if(JSON.stringify(decoded)!==encoded)throw new Error(label+' must be stable JSON');
+  return decoded;
+}
+
+/**
+ * Host-controlled connector boundary. Actor and tenant strings are assertions
+ * supplied by the host; authorize must verify them against its own identity system.
+ */
+export class ConnectorRegistry {
+  #connectors=new Map();
+  constructor({authorize}={}){
+    if(authorize!==undefined&&typeof authorize!=='function')throw new TypeError('Connector authorization must be a function');
+    this.authorize=authorize;
+  }
+  register({id,operations}){
+    text(id,'connector id');
+    if(this.#connectors.has(id))throw new Error('Connector already registered');
+    if(!Array.isArray(operations)||!operations.length)throw new Error('Connector operations required');
+    const selected=new Map();
+    for(const operation of operations){
+      if(!operation||typeof operation!=='object')throw new Error('Invalid connector operation');
+      text(operation.id,'operation id');
+      if(selected.has(operation.id)||!EFFECTS.has(operation.effect)||typeof operation.execute!=='function')throw new Error('Invalid connector operation');
+      if(operation.description!==undefined)text(operation.description,'operation description');
+      selected.set(operation.id,{effect:operation.effect,execute:operation.execute,description:operation.description});
+    }
+    this.#connectors.set(id,selected);return this;
+  }
+  list(){
+    return [...this.#connectors].map(([id,operations])=>({
+      id,
+      operations:[...operations].map(([operationId,{effect,description}])=>({id:operationId,effect,...(description&&{description})}))
+    }));
+  }
+  async invoke({connectorId,operationId,input,actor,tenantId,idempotencyKey,signal}){
+    text(connectorId,'connector id');text(operationId,'operation id');text(actor,'actor');text(tenantId,'tenantId');
+    signal?.throwIfAborted();
+    const operations=this.#connectors.get(connectorId);
+    if(!operations)throw new Error('Unknown connector');
+    const operation=operations.get(operationId);
+    if(!operation)throw new Error('Unknown connector operation');
+    if(operation.effect==='write')text(idempotencyKey,'idempotency key');
+    else if(idempotencyKey!==undefined)text(idempotencyKey,'idempotency key');
+    const safeInput=stableJson(input,'Connector input');
+    if(typeof this.authorize!=='function')throw new Error('Connector authorization required');
+    const request={connectorId,operationId,effect:operation.effect,actor,tenantId,input:clone(safeInput),...(idempotencyKey&&{idempotencyKey})};
+    if(await this.authorize(clone(request))!==true)throw new Error('Connector invocation denied');
+    signal?.throwIfAborted();
+    const result=await operation.execute({input:clone(safeInput),actor,tenantId,...(idempotencyKey&&{idempotencyKey}),...(signal&&{signal})});
+    return stableJson(result,'Connector result');
+  }
+}

package/src/effect-binding.js

@@ -0,0 +1,18 @@
+import {canonicalJson} from './canonical-json.js';
+
+// Internal shared validator: snapshot before any await or host callback.
+export function snapshotEffectBinding(binding) {
+  if (binding === undefined) return undefined;
+  let value;
+  try { value = JSON.parse(canonicalJson(binding)); } catch { throw new TypeError('Invalid effect binding'); }
+  if (!value || Array.isArray(value) || Object.keys(value).sort().join(',') !== 'claimId,decisionId,generation,reviewId' ||
+      ['reviewId', 'decisionId', 'claimId'].some(key => typeof value[key] !== 'string' || !value[key].trim()) ||
+      !Number.isSafeInteger(value.generation) || value.generation < 1) throw new TypeError('Invalid effect binding');
+  return value;
+}
+
+export function assertEffectBinding(stored, supplied) {
+  const expected = snapshotEffectBinding(stored);
+  if ((expected === undefined) !== (supplied === undefined) ||
+      (expected !== undefined && canonicalJson(expected) !== canonicalJson(supplied))) throw new Error('EFFECT_BINDING_CONFLICT');
+}

package/src/effect-journal.js

@@ -0,0 +1,142 @@
+import {createHash} from 'node:crypto';
+import {TransactionalStateStore} from './transactions.js';
+import {canonicalJson} from './canonical-json.js';
+import {snapshotEffectBinding, assertEffectBinding} from './effect-binding.js';
+
+const required = (value, label) => {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(label + ' required');
+  return value;
+};
+const clone = value => structuredClone(value);
+const canonical = value => {
+  try { return canonicalJson(value); } catch { throw new TypeError('JSON input required'); }
+};
+const digest = value => createHash('sha256').update(canonical(value)).digest('hex');
+const slot = (tenantId, effectKey) => createHash('sha256').update(JSON.stringify([tenantId, effectKey])).digest('hex');
+
+/**
+ * Durable, fail-closed local effect journal. This is an intent/state primitive,
+ * Cooperating processes use the same canonical path and transactional lock.
+ * Busy or abandoned locks fail closed; there is no stale-lock takeover.
+ * NOT a remote exactly-once guarantee. Authenticate/review every dispatch;
+ * never replay a dispatched non-idempotent effect automatically.
+ */
+export class FileEffectJournal {
+  #store;
+  constructor(path, options) { this.#store = new TransactionalStateStore(path, options); }
+  async #mutate(update) {
+    let result;
+    await this.#store.exclusive(() => this.#store.transaction(async state => {
+      result = await update(state);
+      return state;
+    }));
+    return result;
+  }
+  async prepare({tenantId, subject, connectorId, operationId, effectKey, input, kind = 'non-idempotent-write', binding} = {}) {
+    for (const [name, value] of Object.entries({tenantId, subject, connectorId, operationId, effectKey})) required(value, name);
+    if (!['non-idempotent-write', 'idempotent-write'].includes(kind)) throw new TypeError('Invalid write classification');
+    const requestDigest = digest(input);
+    const safeBinding = snapshotEffectBinding(binding);
+    return this.#mutate(async state => {
+      const key = slot(tenantId, effectKey);
+      const prior = state.tenants[key];
+      if (prior) {
+        assertEffectBinding(prior.binding, safeBinding);
+        if (prior.tenantId !== tenantId || prior.subject !== subject || prior.connectorId !== connectorId || prior.operationId !== operationId || prior.requestDigest !== requestDigest || prior.kind !== kind) throw new Error('EFFECT_KEY_CONFLICT');
+        return clone(prior);
+      }
+      const entry = {tenantId, subject, connectorId, operationId, effectKey, requestDigest, kind, ...(safeBinding && {binding: safeBinding}), status:'prepared'};
+      state.tenants[key] = entry;
+      return clone(entry);
+    });
+  }
+  async get({tenantId, effectKey} = {}) {
+    required(tenantId, 'tenantId'); required(effectKey, 'effectKey');
+    const state = await this.#store.load();
+    return clone(state.tenants[slot(tenantId, effectKey)] ?? null);
+  }
+  async markDispatched({tenantId, effectKey, binding} = {}) {
+    return this.#transition(tenantId, effectKey, 'dispatched', undefined, binding);
+  }
+  async confirm({tenantId, effectKey, receipt, binding} = {}) {
+    // The host must verify receipt against the remote operation before confirming.
+    if (receipt === undefined) throw new TypeError('Verified receipt required');
+    const safeReceipt = JSON.parse(canonical(receipt));
+    return this.#transition(tenantId, effectKey, 'confirmed', safeReceipt, binding);
+  }
+  async requireReconciliation({tenantId, effectKey, binding} = {}) {
+    return this.#transition(tenantId, effectKey, 'reconciliation_required', undefined, binding);
+  }
+  // Trusted-host primitive: authenticate, review and verify evidence outside this store.
+  // Compare the complete reviewed snapshot under the same lock as writer completion.
+  async confirmReconciled({expectedEntry, receipt, decisionId, subject, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || !['dispatched', 'reconciliation_required'].includes(expected.status) ||
+        !snapshotEffectBinding(expected.binding)) throw new TypeError('Bound uncertain effect required');
+    required(expected.tenantId, 'tenantId'); required(expected.effectKey, 'effectKey');
+    required(decisionId, 'decisionId'); required(subject, 'subject');
+    if (receipt === undefined || typeof beforeCommit !== 'function') throw new TypeError('Verified receipt and commit guard required');
+    const safeReceipt = JSON.parse(canonical(receipt));
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_RECONCILIATION_DENIED');
+      const next = {...prior, status:'confirmed', receipt:safeReceipt,
+        reconciliation:{decisionId, subject}};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  // Authenticated host recovery uses a complete reviewed snapshot, not binding alone.
+  async advancePreparedClaim({expectedEntry, nextGeneration, decisionId, subject, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || expected.status !== 'prepared' || !snapshotEffectBinding(expected.binding)) throw new TypeError('Bound prepared effect required');
+    required(expected.tenantId, 'tenantId'); required(expected.effectKey, 'effectKey');
+    required(decisionId, 'decisionId'); required(subject, 'subject');
+    if (!Number.isSafeInteger(nextGeneration) || nextGeneration <= expected.binding.generation || typeof beforeCommit !== 'function') throw new TypeError('Newer generation and commit guard required');
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_CLAIM_RECOVERY_DENIED');
+      const next = {...prior, binding:{...prior.binding, generation:nextGeneration},
+        claimRecovery:{decisionId, subject, previousGeneration:prior.binding.generation}};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  // Trusted-host CAS only; never use this to take over a dispatched action.
+  async advanceClaim({tenantId, effectKey, binding, nextGeneration} = {}) {
+    required(tenantId, 'tenantId'); required(effectKey, 'effectKey');
+    const expected = snapshotEffectBinding(binding);
+    if (!expected || !Number.isSafeInteger(nextGeneration) || nextGeneration <= expected.generation) throw new TypeError('Newer claim generation required');
+    return this.#mutate(async state => {
+      const key = slot(tenantId, effectKey), prior = state.tenants[key];
+      if (!prior) throw new Error('UNKNOWN_EFFECT');
+      assertEffectBinding(prior.binding, expected);
+      if (prior.status !== 'prepared') throw new Error('EFFECT_REPLAY_BLOCKED');
+      const next = {...prior, binding: {...expected, generation: nextGeneration}};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  async #transition(tenantId, effectKey, target, receipt, binding) {
+    required(tenantId, 'tenantId'); required(effectKey, 'effectKey');
+    const expected = snapshotEffectBinding(binding);
+    return this.#mutate(async state => {
+      const key = slot(tenantId, effectKey), prior = state.tenants[key];
+      if (!prior) throw new Error('UNKNOWN_EFFECT');
+      assertEffectBinding(prior.binding, expected);
+      if (prior.status === 'confirmed') {
+        if (target === 'confirmed' && digest(prior.receipt) === digest(receipt)) return clone(prior);
+        throw new Error('EFFECT_ALREADY_CONFIRMED');
+      }
+      if (target === 'dispatched' && prior.status !== 'prepared') throw new Error('EFFECT_REPLAY_BLOCKED');
+      if (target === 'confirmed' && prior.status !== 'dispatched' && prior.status !== 'reconciliation_required') throw new Error('EFFECT_NOT_DISPATCHED');
+      if (target === 'reconciliation_required' && prior.status !== 'dispatched' && prior.status !== 'reconciliation_required') throw new Error('EFFECT_NOT_DISPATCHED');
+      const next = {...prior, status:target, ...(target === 'confirmed' ? {receipt} : {})};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+}
+

package/src/encrypted-backups.js

@@ -0,0 +1,61 @@
+import {createCipheriv, createDecipheriv, randomBytes} from 'node:crypto';
+import {verifyStateBackup} from './backups.js';
+
+const FORMAT = 'aetheros-encrypted-state-backup';
+const ALGORITHM = 'aes-256-gcm';
+const MAX_BYTES = 16 * 1024 * 1024 + 512;
+const FIELDS = ['algorithm', 'ciphertext', 'format', 'iv', 'keyId', 'tag', 'tenantId', 'version'];
+function context(keyId, tenantId) {
+  for (const [value, max] of [[keyId, 128], [tenantId, 256]]) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error('Invalid encryption context');
+  }
+  return {format: FORMAT, version: 1, algorithm: ALGORITHM, keyId, tenantId};
+}
+function keyCopy(key) {
+  if (!Buffer.isBuffer(key) || key.length !== 32) throw new Error('A 32-byte encryption key is required');
+  return Buffer.from(key);
+}
+function decode(value, max, exact) {
+  if (typeof value !== 'string' || !value.length || value.length > 4 * Math.ceil(max / 3) || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) throw new Error('Invalid encrypted backup encoding');
+  const bytes = Buffer.from(value, 'base64');
+  if (bytes.length > max || (exact !== undefined && bytes.length !== exact) || bytes.toString('base64') !== value) throw new Error('Invalid encrypted backup encoding');
+  return bytes;
+}
+function plainBackup(checked) {
+  return {format: 'aetheros-state-backup', version: 1, state: checked.state, digest: checked.digest};
+}
+
+/** Keys are supplied by the host; no key material is retained in the envelope. */
+export function encryptStateBackup(backup, {key, keyId, tenantId} = {}) {
+  const header = context(keyId, tenantId), secret = keyCopy(key);
+  try {
+    const plaintext = Buffer.from(JSON.stringify(plainBackup(verifyStateBackup(backup))));
+    if (plaintext.length > MAX_BYTES) throw new Error('Encrypted backup exceeds size limit');
+    const iv = randomBytes(12), cipher = createCipheriv(ALGORITHM, secret, iv);
+    cipher.setAAD(Buffer.from(JSON.stringify(header)));
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return {...header, iv: iv.toString('base64'), ciphertext: ciphertext.toString('base64'), tag: cipher.getAuthTag().toString('base64')};
+  } finally { secret.fill(0); }
+}
+
+/** Verify host-selected tenant/key context and GCM authentication before returning any state. */
+export function decryptStateBackup(envelope, {key, keyId, tenantId} = {}) {
+  const header = context(keyId, tenantId), secret = keyCopy(key);
+  try {
+    if (!envelope || Object.getPrototypeOf(envelope) !== Object.prototype || Reflect.ownKeys(envelope).length !== FIELDS.length) throw new Error('Invalid encrypted backup envelope');
+    const descriptors = Object.getOwnPropertyDescriptors(envelope);
+    if (Reflect.ownKeys(envelope).some(field => !FIELDS.includes(field) || !descriptors[field].enumerable || !Object.hasOwn(descriptors[field], 'value'))) throw new Error('Invalid encrypted backup envelope');
+    for (const [field, value] of Object.entries(header)) if (envelope[field] !== value) throw new Error('Encrypted backup context mismatch');
+    const iv = decode(envelope.iv, 12, 12), tag = decode(envelope.tag, 16, 16), ciphertext = decode(envelope.ciphertext, MAX_BYTES);
+    let plaintext;
+    try {
+      const decipher = createDecipheriv(ALGORITHM, secret, iv);
+      decipher.setAAD(Buffer.from(JSON.stringify(header))); decipher.setAuthTag(tag);
+      plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    } catch { throw new Error('Encrypted backup authentication failed'); }
+    let parsed;
+    try { parsed = JSON.parse(plaintext.toString('utf8')); }
+    catch { throw new Error('Invalid encrypted backup payload'); }
+    return plainBackup(verifyStateBackup(parsed));
+  } finally { secret.fill(0); }
+}

package/src/encrypted-state.js

@@ -0,0 +1,35 @@
+import {TransactionalStateStore} from './transactions.js';
+import {createStateBackup} from './backups.js';
+import {encryptStateBackup, decryptStateBackup} from './encrypted-backups.js';
+
+const id = (value, label, max) => {
+  if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error('Invalid ' + label);
+  return value;
+};
+const keyCopy = key => {
+  if (!Buffer.isBuffer(key) || key.length !== 32) throw new Error('A 32-byte state encryption key is required');
+  return Buffer.from(key);
+};
+
+/** Encrypt live snapshots and temporary files while retaining local transaction semantics. */
+export function createEncryptedStateStore(path, {key, keyId, tenantId, readKeys = []} = {}) {
+  id(keyId, 'state key id', 128); id(tenantId, 'state storage context', 256);
+  if (!Array.isArray(readKeys) || readKeys.length > 32) throw new Error('Invalid state read-key ring');
+  const keys = new Map([[keyId, keyCopy(key)]]);
+  for (const entry of readKeys) {
+    if (!entry || keys.has(id(entry.keyId, 'state read-key id', 128))) throw new Error('Duplicate state key id');
+    keys.set(entry.keyId, keyCopy(entry.key));
+  }
+  const codec = Object.freeze({
+    async encode(state) {
+      const backup = await createStateBackup({load: async () => state});
+      return encryptStateBackup(backup, {key: keys.get(keyId), keyId, tenantId});
+    },
+    async decode(envelope) {
+      const selected = envelope?.keyId, secret = keys.get(selected);
+      if (!secret) throw new Error('Encrypted state key unavailable');
+      return decryptStateBackup(envelope, {key: secret, keyId: selected, tenantId}).state;
+    }
+  });
+  return new TransactionalStateStore(path, {codec});
+}

package/src/envelope-migrations.js

@@ -0,0 +1,62 @@
+import {canonicalJson} from './canonical-json.js';
+import {createStateBackup} from './backups.js';
+
+function version(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error('Invalid state envelope version');
+  return value;
+}
+function copy(value) {
+  const encoded = canonicalJson(value);
+  if (Buffer.byteLength(encoded) > 16 * 1024 * 1024) throw new Error('State import exceeds size limit');
+  return JSON.parse(JSON.stringify(value));
+}
+function definitions(migrations) {
+  if (!Array.isArray(migrations) || migrations.length > 256) throw new Error('Bounded envelope migrations required');
+  const byVersion = new Map();
+  for (const item of migrations) {
+    if (!item || typeof item !== 'object') throw new Error('Invalid envelope migration');
+    const from = version(item.from), to = version(item.to);
+    if (to !== from + 1 || byVersion.has(from) || typeof item.migrate !== 'function') throw new Error('Invalid envelope migration');
+    if (item.name !== undefined && (typeof item.name !== 'string' || !item.name.trim())) throw new Error('Invalid envelope migration name');
+    byVersion.set(from, {from, to, migrate: item.migrate, ...(item.name && {name: item.name})});
+  }
+  return byVersion;
+}
+function plan(current, target, byVersion) {
+  version(current); version(target);
+  if (target < 1 || target < current) throw new Error('Envelope downgrades are not supported');
+  if (target - current > 256) throw new Error('Envelope migration limit exceeded');
+  const result = [];
+  for (let from = current; from < target; from += 1) {
+    const step = byVersion.get(from);
+    if (!step) throw new Error('Missing envelope migration from version ' + from);
+    result.push({from, to: step.to, ...(step.name && {name: step.name})});
+  }
+  return result;
+}
+
+export function planStateEnvelopeMigration(currentVersion, targetVersion, migrations) {
+  return plan(currentVersion, targetVersion, definitions(migrations));
+}
+
+/** Pure snapshot transformation. Callbacks must not perform external effects. No files are written. */
+export async function migrateStateEnvelope(source, {targetVersion = 1, migrations = []} = {}) {
+  let next = copy(source);
+  if (!next || typeof next !== 'object' || Array.isArray(next)) throw new Error('State envelope object required');
+  const byVersion = definitions(migrations), applied = plan(next.version, targetVersion, byVersion);
+  for (const step of applied) {
+    const candidate = copy(await byVersion.get(step.from).migrate(structuredClone(next)));
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate) || candidate.version !== step.to) throw new Error('Migration must return envelope version ' + step.to);
+    next = candidate;
+  }
+  if (!next.tenants || typeof next.tenants !== 'object' || Array.isArray(next.tenants)) throw new Error('Migrated envelope requires tenants');
+  if (targetVersion === 1 && Object.keys(next).sort().join(',') !== 'tenants,version') throw new Error('Invalid version-1 envelope fields');
+  return {state: structuredClone(next), applied: structuredClone(applied)};
+}
+
+/** Produce a current-runtime backup for reviewed import through the guarded restore boundary. */
+export async function prepareStateImport(source, {targetVersion = 1, migrations = []} = {}) {
+  if (targetVersion !== 1) throw new Error('Runtime imports require envelope version 1');
+  const result = await migrateStateEnvelope(source, {targetVersion, migrations});
+  return {backup: await createStateBackup({load: async () => result.state}), applied: result.applied};
+}

package/src/guarded-restore.js

@@ -0,0 +1,68 @@
+import {randomUUID} from 'node:crypto';
+import {TokenAuthority} from './index.js';
+import {TransactionalStateStore} from './transactions.js';
+import {FileAuditLog} from './audit.js';
+import {createStateBackup, verifyStateBackup, restoreStateBackup} from './backups.js';
+
+const text = (value, label) => {
+  if (typeof value !== 'string' || !value.trim() || value.length > 256) throw new Error('Invalid ' + label);
+  return value;
+};
+const isDigest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+
+export class StateRestoreError extends Error {
+  constructor(code, stateMayHaveChanged) {
+    super(code === 'STATE_RESTORE_AUDIT_FAILED' ? 'State restore outcome could not be audited' : 'State restore failed');
+    this.name = 'StateRestoreError'; this.code = code; this.stateMayHaveChanged = stateMayHaveChanged;
+  }
+}
+
+/** Whole-store administration: tenantId is a host-fixed administrative storage context. */
+export class GuardedStateRestore {
+  constructor(store, authority, audit, {tenantId, loadBackup, authorizeRestore} = {}) {
+    if (!(store instanceof TransactionalStateStore) || !(authority instanceof TokenAuthority) || !(audit instanceof FileAuditLog)) throw new TypeError('Transactional store, authority and audit log required');
+    if (store.path === audit.state.path) throw new Error('Restore audit must use a separate state path');
+    if (typeof loadBackup !== 'function' || typeof authorizeRestore !== 'function') throw new TypeError('Host backup loader and restore policy required');
+    this.store = store; this.authority = authority; this.audit = audit;
+    this.tenantId = text(tenantId, 'restore administrative context');
+    this.loadBackup = loadBackup; this.authorizeRestore = authorizeRestore;
+  }
+  identity(token) { return this.authority.authenticate(token, {tenantId: this.tenantId, permission: 'admin'}); }
+  async review(backupId, {token} = {}) {
+    this.identity(token); text(backupId, 'backup id');
+    try {
+      const backup = verifyStateBackup(await this.loadBackup(backupId, {tenantId: this.tenantId}));
+      const current = await createStateBackup(this.store);
+      this.identity(token);
+      return {backupId, expectedBackupDigest: backup.digest, expectedCurrentDigest: current.digest, backupTenantCount: Object.keys(backup.state.tenants).length, currentTenantCount: Object.keys(current.state.tenants).length};
+    } catch { throw new Error('State restore review failed'); }
+  }
+  async restore({token, backupId, expectedBackupDigest, expectedCurrentDigest, acknowledgeQuiesced = false, signal} = {}) {
+    const identity = this.identity(token); text(backupId, 'backup id');
+    if (!isDigest(expectedBackupDigest) || !isDigest(expectedCurrentDigest)) throw new Error('Reviewed backup and current digests required');
+    if (acknowledgeQuiesced !== true) throw new Error('Confirm all writers and effect workers have stopped');
+    signal?.throwIfAborted();
+    const requestId = randomUUID(); let commitApproved = false, auditingResult = false, denied = false;
+    const record = (outcome, phase) => this.audit.state.exclusive(() => this.audit.append({tenantId: this.tenantId, actor: identity.subject, action: 'state.restore', outcome, metadata: {requestId, backupId, expectedBackupDigest, expectedCurrentDigest, phase}}));
+    try {
+      const checked = verifyStateBackup(await this.loadBackup(backupId, {tenantId: this.tenantId}));
+      this.identity(token); signal?.throwIfAborted();
+      if (checked.digest !== expectedBackupDigest) throw new Error('Backup changed since restore review');
+      const backup = {format: 'aetheros-state-backup', version: 1, state: checked.state, digest: checked.digest};
+      await record('success', 'intent');
+      const result = await restoreStateBackup(this.store, backup, {expectedCurrentDigest, beforeCommit: async context => {
+        const authenticated = this.identity(token); signal?.throwIfAborted();
+        const approved = await this.authorizeRestore({...context, backupId, identity: structuredClone(authenticated)});
+        this.identity(token); signal?.throwIfAborted();
+        if (approved !== true) { denied = true; return false; }
+        commitApproved = true; return true;
+      }});
+      auditingResult = true; await record('success', 'result'); auditingResult = false;
+      this.identity(token);
+      return result;
+    } catch {
+      try { await record(denied ? 'denied' : 'failed', commitApproved ? 'commit-or-result' : 'pre-commit'); } catch { /* An audit failure must never trigger an implicit restore retry. */ }
+      throw new StateRestoreError(auditingResult ? 'STATE_RESTORE_AUDIT_FAILED' : 'STATE_RESTORE_FAILED', commitApproved);
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,77 @@
+import {randomBytes,scryptSync,timingSafeEqual} from 'node:crypto';
+import {readFile,writeFile,rename,mkdir,open} from 'node:fs/promises';
+import {dirname,resolve} from 'node:path';
+
+const scopes=new Set(['read','write','workflow','approve','audit','admin']);
+const validate=(value,name)=>{if(typeof value!=='string'||!value.trim())throw new Error(name+' required');return value;};
+const clone=value=>structuredClone(value);
+const keyHash=(secret,salt)=>scryptSync(secret,salt,32);
+const verifyHash=(actual,expected)=>actual.length===expected.length&&timingSafeEqual(actual,expected);
+
+/** Credentials are generated once; only salted derived keys are retained. */
+export class TokenAuthority {
+ #tokens=new Map();
+ issue({tenantId,subject,permissions=['read'],expiresAt}){
+  validate(tenantId,'tenantId');validate(subject,'subject');
+  if(!Array.isArray(permissions)||!permissions.length||permissions.some(p=>!scopes.has(p)))throw new Error('Invalid permissions');
+  if(!Number.isSafeInteger(expiresAt)||expiresAt<=Date.now())throw new Error('Future expiry required');
+  const id=randomBytes(16).toString('hex'),secret=randomBytes(32).toString('base64url'),salt=randomBytes(16);
+  this.#tokens.set(id,{tenantId,subject,permissions:[...new Set(permissions)],expiresAt,salt,derived:keyHash(secret,salt)});
+  return {token:id+'.'+secret,id,expiresAt};
+ }
+ authenticate(token,{tenantId,permission,now=Date.now()}={}){
+  if(typeof token!=='string'||!Number.isSafeInteger(now)||now<0)throw new Error('Authentication failed');
+  const dot=token.indexOf('.');
+  if(dot<1)throw new Error('Authentication failed');
+  const id=token.slice(0,dot),secret=token.slice(dot+1),entry=this.#tokens.get(id);
+  if(!entry||!secret||!verifyHash(keyHash(secret,entry.salt),entry.derived)||now>=entry.expiresAt)throw new Error('Authentication failed');
+  if(tenantId!==undefined&&entry.tenantId!==tenantId)throw new Error('Access denied');
+  if(permission!==undefined&&!entry.permissions.includes(permission)&&!entry.permissions.includes('admin'))throw new Error('Permission denied');
+  return clone({tenantId:entry.tenantId,subject:entry.subject,permissions:entry.permissions,expiresAt:entry.expiresAt});
+ }
+ revoke(id){return this.#tokens.delete(id);}
+}
+
+/** Atomic local JSON snapshots; putTenant calls serialize within one process.
+ * Direct save callers and separate processes must coordinate externally. */
+export class FileStateStore {
+ static queues=new Map();
+ async exclusive(operation){
+  const previous=FileStateStore.queues.get(this.path)??Promise.resolve();
+  const current=previous.catch(()=>{}).then(operation);
+  FileStateStore.queues.set(this.path,current);
+  try{return await current;}finally{if(FileStateStore.queues.get(this.path)===current)FileStateStore.queues.delete(this.path);}
+ }
+ constructor(path,{codec}={}){
+  this.path=resolve(validate(path,'path'));
+  if(codec!==undefined&&(!codec||typeof codec.encode!=='function'||typeof codec.decode!=='function'))throw new TypeError('State codec requires encode and decode');
+  this.codec=codec;
+ }
+ async load(){
+  let raw;
+  try{raw=await readFile(this.path,'utf8');}catch(error){if(error.code==='ENOENT')return {version:1,tenants:{}};throw error;}
+  const encoded=JSON.parse(raw),state=this.codec?await this.codec.decode(encoded):encoded;
+  if(!state||state.version!==1||typeof state.tenants!=='object'||Array.isArray(state.tenants)||state.tenants===null)throw new Error('Invalid state schema');
+  return clone(state);
+ }
+ async save(state){
+  if(!state||state.version!==1||!state.tenants||typeof state.tenants!=='object'||Array.isArray(state.tenants))throw new Error('Invalid state schema');
+  const snapshot=clone(state),encoded=this.codec?await this.codec.encode(snapshot):snapshot;
+  const serialized=JSON.stringify(encoded);
+  if(serialized===undefined)throw new Error('State codec must return JSON');
+  const temp=this.path+'.'+randomBytes(12).toString('hex')+'.tmp';
+  await mkdir(dirname(this.path),{recursive:true});
+  let created=false;
+  try{
+   const handle=await open(temp,'wx',0o600);created=true;
+   try{await handle.writeFile(serialized+'\n','utf8');await handle.sync();}finally{await handle.close();}
+   await rename(temp,this.path);
+  }catch(error){
+   if(created){const {unlink}=await import('node:fs/promises');await unlink(temp).catch(()=>{});}
+   throw error;
+  }
+ }
+ async getTenant(id){validate(id,'tenant id');const state=await this.load();return Object.hasOwn(state.tenants,id)?clone(state.tenants[id]):null;}
+ async putTenant(id,data){validate(id,'tenant id');if(data===undefined)throw new Error('Tenant data required');return this.exclusive(async()=>{const state=await this.load();Object.defineProperty(state.tenants,id,{value:clone(data),enumerable:true,writable:true,configurable:true});await this.save(state);});}
+}
+

package/src/migrations.js

@@ -0,0 +1,92 @@
+const clone = value => structuredClone(value);
+
+function version(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error('Invalid ' + label);
+  return value;
+}
+
+function stableJson(value, label) {
+  const active = new Set();
+  const visit = item => {
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return;
+    if (typeof item === 'number' && Number.isFinite(item)) return;
+    if (typeof item !== 'object' || ArrayBuffer.isView(item) || item instanceof Date || active.has(item)) {
+      throw new Error(label + ' must be stable JSON');
+    }
+    active.add(item);
+    if (Array.isArray(item)) for (const child of item) visit(child);
+    else {
+      const prototype = Object.getPrototypeOf(item);
+      if (prototype !== Object.prototype && prototype !== null) throw new Error(label + ' must be stable JSON');
+      for (const child of Object.values(item)) visit(child);
+    }
+    active.delete(item);
+  };
+  visit(value);
+  let encoded;
+  try { encoded = JSON.stringify(value); } catch { throw new Error(label + ' must be stable JSON'); }
+  if (encoded === undefined) throw new Error(label + ' must be stable JSON');
+  const decoded = JSON.parse(encoded);
+  if (JSON.stringify(decoded) !== encoded) throw new Error(label + ' must be stable JSON');
+  return decoded;
+}
+
+function migrationMap(migrations) {
+  if (!Array.isArray(migrations)) throw new TypeError('Migrations must be an array');
+  const byVersion = new Map();
+  for (const entry of migrations) {
+    if (!entry || typeof entry !== 'object') throw new Error('Invalid migration');
+    const from = version(entry.from, 'migration version');
+    const to = version(entry.to, 'migration version');
+    if (to !== from + 1 || typeof entry.migrate !== 'function' || byVersion.has(from)) throw new Error('Invalid migration');
+    if (entry.name !== undefined && (typeof entry.name !== 'string' || !entry.name.trim())) throw new Error('Invalid migration name');
+    byVersion.set(from, entry);
+  }
+  return byVersion;
+}
+
+/** Return the exact one-version steps required without executing migration code. */
+export function planTenantMigration(currentVersion, targetVersion, migrations) {
+  const current = version(currentVersion, 'current schema version');
+  const target = version(targetVersion, 'target schema version');
+  if (current > target) throw new Error('Schema downgrades are not supported');
+  const byVersion = migrationMap(migrations), plan = [];
+  for (let from = current; from < target; from += 1) {
+    const entry = byVersion.get(from);
+    if (!entry) throw new Error('Missing migration from schema version ' + from);
+    plan.push({from: entry.from, to: entry.to, ...(entry.name && {name: entry.name})});
+  }
+  return plan;
+}
+
+/**
+ * Atomically migrate one tenant inside a TransactionalStateStore.
+ * Every callback runs under the store lock; the final snapshot commits only if
+ * the complete chain succeeds and each result advances exactly one version.
+ */
+export async function migrateTenant(store, tenantId, {targetVersion, migrations} = {}) {
+  if (!store || typeof store.updateTenant !== 'function') throw new TypeError('Transactional tenant store required');
+  if (typeof tenantId !== 'string' || !tenantId.trim()) throw new TypeError('Tenant id required');
+  const target = version(targetVersion, 'target schema version');
+  const byVersion = migrationMap(migrations);
+  let applied = [];
+  const state = await store.updateTenant(tenantId, async current => {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) throw new Error('Tenant state required');
+    const start = version(current.schemaVersion, 'tenant schema version');
+    const plan = planTenantMigration(start, target, migrations);
+    let next = stableJson(current, 'Tenant state');
+    applied = [];
+    for (const step of plan) {
+      const definition = byVersion.get(step.from);
+      const candidate = await definition.migrate(clone(next));
+      const checked = stableJson(candidate, 'Migrated tenant state');
+      if (!checked || typeof checked !== 'object' || Array.isArray(checked) || checked.schemaVersion !== step.to) {
+        throw new Error('Migration must return schema version ' + step.to);
+      }
+      next = checked;
+      applied.push(step);
+    }
+    return next;
+  });
+  return {state: clone(state), applied: clone(applied)};
+}