@aetheros/kernel-runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hariprasath Thanarajah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@aetheros/kernel-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abigshana/AetherOS.git",
+    "directory": "packages/kernel-runtime"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./transactions": "./src/transactions.js",
+    "./migrations": "./src/migrations.js",
+    "./audit": "./src/audit.js",
+    "./connectors": "./src/connectors.js",
+    "./backups": "./src/backups.js",
+    "./encrypted-backups": "./src/encrypted-backups.js",
+    "./authenticated-connectors": "./src/authenticated-connectors.js",
+    "./authenticated-audit": "./src/authenticated-audit.js",
+    "./release-signatures": "./src/release-signatures.js",
+    "./encrypted-state": "./src/encrypted-state.js",
+    "./guarded-restore": "./src/guarded-restore.js",
+    "./envelope-migrations": "./src/envelope-migrations.js",
+    "./agent-memory": "./src/agent-memory.js",
+    "./effect-journal": "./src/effect-journal.js"
+  },
+  "scripts": {
+    "check": "node --check src/index.js && node --check src/transactions.js && node --check src/migrations.js && node --check src/audit.js && node --check src/connectors.js && node --check src/backups.js && node --check src/encrypted-backups.js && node --check src/authenticated-connectors.js && node --check src/authenticated-audit.js && node --check src/release-signatures.js && node --check src/encrypted-state.js && node --check src/canonical-json.js && node --check src/guarded-restore.js && node --check src/envelope-migrations.js && node --check src/agent-memory.js && node --check src/effect-journal.js",
+    "test": "node --test test/*.test.mjs"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin",
+    "templates",
+    "kits",
+    "README.md"
+  ]
+}

package/src/agent-memory.js

@@ -0,0 +1,88 @@
+import {randomBytes} from 'node:crypto';
+import {TokenAuthority} from './index.js';
+import {createEncryptedStateStore} from './encrypted-state.js';
+
+const MAX_ENTRIES = 1000, MAX_TEXT_BYTES = 16384, MAX_TOTAL_BYTES = 1048576;
+const validId = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+const revision = value => typeof value === 'string' && /^[a-f0-9]{32}$/.test(value);
+const textBytes = text => Buffer.byteLength(text, 'utf8');
+const scope = ({agentId, shared = false}) => {
+  if (typeof shared !== 'boolean' || (shared ? agentId !== undefined : !validId(agentId))) throw new TypeError('Select one agent or shared memory');
+  return shared ? null : agentId;
+};
+const keyOf = entry => JSON.stringify([entry.agentId, entry.id]);
+function checkedMemory(value) {
+  if (value === null) return {schemaVersion: 1, entries: []};
+  if (!value || value.schemaVersion !== 1 || !Array.isArray(value.entries) || value.entries.length > MAX_ENTRIES) throw new Error('Invalid memory state');
+  const seen = new Set(); let bytes = 0;
+  for (const entry of value.entries) {
+    if (!entry || !validId(entry.id) || (entry.agentId !== null && !validId(entry.agentId)) || !revision(entry.revision) || typeof entry.text !== 'string' || !entry.text.trim() || textBytes(entry.text) > MAX_TEXT_BYTES) throw new Error('Invalid memory record');
+    if (seen.has(keyOf(entry))) throw new Error('Duplicate memory record');
+    seen.add(keyOf(entry)); bytes += textBytes(entry.text);
+  }
+  if (bytes > MAX_TOTAL_BYTES) throw new Error('Memory capacity exceeded');
+  // Return only the declared fields; internal/unknown fields never escape the facade.
+  return {schemaVersion: 1, entries: value.entries.map(({id, agentId, revision, text}) => ({id, agentId, revision, text}))};
+}
+
+/** Dedicated encrypted tenant memory. Hosts explicitly authorize every agent/shared scope. */
+export function createEncryptedAgentMemory(path, authority, {tenantId, key, keyId, readKeys, authorize} = {}) {
+  if (!(authority instanceof TokenAuthority) || typeof tenantId !== 'string' || !tenantId.trim() || typeof authorize !== 'function') throw new TypeError('Tenant authority and explicit memory authorization policy required');
+  const store = createEncryptedStateStore(path, {tenantId, key, keyId, readKeys});
+  async function allow(token, operation, agentId) {
+    const authenticate = () => authority.authenticate(token, {tenantId, permission: operation === 'get' || operation === 'list' ? 'read' : 'write'});
+    const identity = authenticate();
+    // No record text or bearer credential is supplied to policy callbacks.
+    if (await authorize(structuredClone({identity, operation, agentId, shared: agentId === null})) !== true) throw new Error('Memory access denied');
+    authenticate();
+  }
+  function selected(request, needsId = true) {
+    const agentId = scope(request);
+    if (needsId && !validId(request.id)) throw new TypeError('Invalid memory id');
+    return agentId;
+  }
+  return Object.freeze({
+    async list(request = {}) {
+      const agentId = selected(request, false), {token, limit = 100} = request;
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_ENTRIES) throw new TypeError('Invalid memory limit');
+      await allow(token, 'list', agentId);
+      const memory = checkedMemory(await store.getTenant(tenantId));
+      await allow(token, 'list', agentId);
+      return memory.entries.filter(entry => entry.agentId === agentId).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).slice(0, limit);
+    },
+    async get(request = {}) {
+      const agentId = selected(request), {token, id} = request;
+      await allow(token, 'get', agentId);
+      const memory = checkedMemory(await store.getTenant(tenantId));
+      await allow(token, 'get', agentId);
+      return memory.entries.find(entry => entry.agentId === agentId && entry.id === id) ?? null;
+    },
+    async put(request = {}) {
+      const agentId = selected(request), {token, id, text, expectedRevision} = request;
+      if (typeof text !== 'string' || !text.trim() || textBytes(text) > MAX_TEXT_BYTES || (expectedRevision !== null && !revision(expectedRevision))) throw new TypeError('Memory text and expected revision required (null to create)');
+      await allow(token, 'put', agentId);
+      let result;
+      await store.updateTenant(tenantId, async previous => {
+        await allow(token, 'put', agentId);
+        const memory = checkedMemory(previous), index = memory.entries.findIndex(entry => entry.agentId === agentId && entry.id === id);
+        if ((index < 0 ? null : memory.entries[index].revision) !== expectedRevision) throw new Error('Memory revision conflict');
+        result = {id, agentId, text, revision: randomBytes(16).toString('hex')};
+        if (index < 0) memory.entries.push(result); else memory.entries[index] = result;
+        return checkedMemory(memory);
+      });
+      return structuredClone(result);
+    },
+    async remove(request = {}) {
+      const agentId = selected(request), {token, id, expectedRevision} = request;
+      if (!revision(expectedRevision)) throw new TypeError('Expected memory revision required');
+      await allow(token, 'remove', agentId);
+      await store.updateTenant(tenantId, async previous => {
+        await allow(token, 'remove', agentId);
+        const memory = checkedMemory(previous), index = memory.entries.findIndex(entry => entry.agentId === agentId && entry.id === id);
+        if (index < 0 || memory.entries[index].revision !== expectedRevision) throw new Error('Memory revision conflict');
+        memory.entries.splice(index, 1); return memory;
+      });
+      return {removed: true};
+    }
+  });
+}

package/src/audit.js

@@ -0,0 +1,88 @@
+import {canonicalJson} from './canonical-json.js';
+import {createHash,randomUUID} from 'node:crypto';
+import {TransactionalStateStore} from './transactions.js';
+
+const OUTCOMES = new Set(['success','denied','failed']);
+const GENESIS = 'GENESIS';
+const clone = value => structuredClone(value);
+const digest = value => createHash('sha256').update(value.hashVersion===2?canonicalJson(value):JSON.stringify(value)).digest('hex');
+const validText = (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),decoded=JSON.parse(encoded);
+  if(JSON.stringify(decoded)!==encoded)throw new Error(label+' must be stable JSON');
+  return decoded;
+}
+
+function validateLog(log,maxEntries) {
+  if(!log||log.schemaVersion!==1||log.maxEntries!==maxEntries||typeof log.anchorHash!=='string'||!Array.isArray(log.entries)||log.entries.length>maxEntries)throw new Error('Invalid audit log');
+  return log;
+}
+
+/** Bounded, hash-linked local audit records. Hashes detect changes but do not authenticate the writer. */
+export class FileAuditLog {
+  constructor(path,{maxEntries=1000,clock=()=>new Date().toISOString(),ids=randomUUID,stateStore}={}) {
+    if(!Number.isSafeInteger(maxEntries)||maxEntries<1||maxEntries>100000)throw new Error('Invalid audit retention');
+    if(typeof clock!=='function'||typeof ids!=='function')throw new TypeError('Audit clock and id source required');
+    const base=new TransactionalStateStore(path);
+    if(stateStore!==undefined&&(!(stateStore instanceof TransactionalStateStore)||stateStore.path!==base.path))throw new TypeError('Matching transactional audit state store required');
+    this.state=stateStore??base;this.maxEntries=maxEntries;this.clock=clock;this.ids=ids;
+  }
+  key(tenantId){return 'security.audit/'+validText(tenantId,'tenantId');}
+  async append({tenantId,actor,action,outcome='success',metadata={}}) {
+    validText(actor,'actor');validText(action,'action');
+    if(!OUTCOMES.has(outcome))throw new Error('Invalid audit outcome');
+    const safeMetadata=stableJson(metadata,'Audit metadata');
+    const id=validText(this.ids(),'audit id'),at=validText(this.clock(),'audit time');
+    const parsedTime=new Date(at);
+    if(Number.isNaN(parsedTime.valueOf())||parsedTime.toISOString()!==at)throw new Error('Invalid audit time');
+    let appended;
+    await this.state.updateTenant(this.key(tenantId),current=>{
+      const log=current??{schemaVersion:1,maxEntries:this.maxEntries,anchorHash:GENESIS,entries:[]};
+      validateLog(log,this.maxEntries);
+      const previousHash=log.entries.at(-1)?.hash??log.anchorHash;
+      const payload={hashVersion:2,id,at,tenantId,actor,action,outcome,metadata:safeMetadata,previousHash};
+      appended={...payload,hash:digest(payload)};
+      log.entries.push(appended);
+      if(log.entries.length>this.maxEntries){const removed=log.entries.splice(0,log.entries.length-this.maxEntries);log.anchorHash=removed.at(-1).hash;}
+      return log;
+    });
+    return clone(appended);
+  }
+  async list(tenantId,{limit=this.maxEntries}={}) {
+    if(!Number.isSafeInteger(limit)||limit<0||limit>this.maxEntries)throw new Error('Invalid audit limit');
+    const log=await this.state.getTenant(this.key(tenantId));
+    if(!log)return [];
+    validateLog(log,this.maxEntries);
+    return clone(limit===0?[]:log.entries.slice(-limit));
+  }
+  async verify(tenantId) {
+    const log=await this.state.getTenant(this.key(tenantId));
+    if(!log)return {valid:true,count:0,anchorHash:GENESIS,tailHash:GENESIS};
+    try{
+      validateLog(log,this.maxEntries);
+      let previous=log.anchorHash;
+      for(const entry of log.entries){
+        if(!entry||(entry.hashVersion!==undefined&&entry.hashVersion!==2)||entry.previousHash!==previous||typeof entry.hash!=='string')return {valid:false,count:log.entries.length};
+        const {hash,...payload}=entry;
+        if(digest(payload)!==hash)return {valid:false,count:log.entries.length};
+        previous=hash;
+      }
+      return {valid:true,count:log.entries.length,anchorHash:log.anchorHash,tailHash:previous};
+    }catch{return {valid:false,count:Array.isArray(log?.entries)?log.entries.length:0};}
+  }
+}

package/src/authenticated-audit.js

@@ -0,0 +1,24 @@
+import {TokenAuthority} from './index.js';
+import {FileAuditLog} from './audit.js';
+
+/** Read-only host facade; append and file access remain privileged host APIs. */
+export class AuthenticatedAuditReader {
+  constructor(log, authority, {tenantId} = {}) {
+    if (!(log instanceof FileAuditLog) || !(authority instanceof TokenAuthority)) throw new TypeError('Audit log and token authority required');
+    if (typeof tenantId !== 'string' || !tenantId.trim()) throw new TypeError('Audit tenant required');
+    this.log = log; this.authority = authority; this.tenantId = tenantId;
+  }
+  authenticate(token) { return this.authority.authenticate(token, {tenantId: this.tenantId, permission: 'audit'}); }
+  async list({token, limit} = {}) {
+    this.authenticate(token);
+    const entries = await this.log.list(this.tenantId, {limit});
+    this.authenticate(token);
+    return entries;
+  }
+  async verify({token} = {}) {
+    this.authenticate(token);
+    const result = await this.log.verify(this.tenantId);
+    this.authenticate(token);
+    return result;
+  }
+}

package/src/authenticated-connectors.js

@@ -0,0 +1,261 @@
+import {randomUUID} from 'node:crypto';
+import {TokenAuthority} from './index.js';
+import {FileAuditLog} from './audit.js';
+import {ConnectorRegistry} from './connectors.js';
+import {FileEffectJournal} from './effect-journal.js';
+import {snapshotEffectBinding} from './effect-binding.js';
+import {canonicalJson} from './canonical-json.js';
+
+export class ConnectorInvocationError extends Error {
+  constructor(code, effectMayHaveOccurred) {
+    super(code === 'CONNECTOR_DENIED' ? 'Connector invocation denied' : code === 'CONNECTOR_AUDIT_FAILED' ? 'Connector outcome could not be audited' : 'Connector invocation failed');
+    this.name = 'ConnectorInvocationError'; this.code = code;
+    this.effectMayHaveOccurred = effectMayHaveOccurred;
+  }
+}
+
+/**
+ * Host-configured adapter boundary. Request actor/tenant assertions are ignored.
+ * Optional effectJournal enables durable write recovery; without it the legacy
+ * invocation contract is unchanged. Journal lock contention fails closed. Hosts
+ * keep result receipts free of secrets and enforce Review in authorize.
+ * All ambiguous writes stay blocked, including remotely idempotent operations.
+ */
+export class AuthenticatedConnectorRegistry {
+  #definitions = new Map();
+  #catalog = new ConnectorRegistry();
+  #authority; #audit; #tenantId; #authorize; #effectJournal; #requireEffectBinding;
+  #authorizeClaimRecovery; #authorizeReconciliation; #verifyReconciliation; #authorizeReceiptLookup; #lookupRemoteReceipt;
+  constructor(authority, audit, {tenantId, authorize, effectJournal, requireEffectBinding = false, authorizeReconciliation, verifyReconciliation, authorizeReceiptLookup, lookupRemoteReceipt, authorizeClaimRecovery} = {}) {
+    if (!(authority instanceof TokenAuthority) || !(audit instanceof FileAuditLog)) throw new TypeError('Token authority and file audit log required');
+    if (typeof tenantId !== 'string' || !tenantId.trim()) throw new TypeError('Connector tenant required');
+    if (authorize !== undefined && typeof authorize !== 'function') throw new TypeError('Invalid connector policy');
+    if (effectJournal !== undefined && !(effectJournal instanceof FileEffectJournal)) throw new TypeError('File effect journal required');
+    if (typeof requireEffectBinding !== 'boolean' || (requireEffectBinding && !effectJournal)) throw new TypeError('Effect binding requires a journal');
+    for (const policy of [authorizeReconciliation, verifyReconciliation, authorizeReceiptLookup, lookupRemoteReceipt, authorizeClaimRecovery]) if (policy !== undefined && typeof policy !== 'function') throw new TypeError('Invalid reconciliation policy');
+    this.#authorizeClaimRecovery = authorizeClaimRecovery;
+    this.#authorizeReceiptLookup = authorizeReceiptLookup; this.#lookupRemoteReceipt = lookupRemoteReceipt;
+    this.#authorizeReconciliation = authorizeReconciliation; this.#verifyReconciliation = verifyReconciliation;
+    this.#requireEffectBinding = requireEffectBinding;
+    this.#effectJournal = effectJournal;
+    this.#authority = authority; this.#audit = audit; this.#tenantId = tenantId; this.#authorize = authorize;
+  }
+  register(definition) {
+    this.#catalog.register(definition);
+    this.#definitions.set(definition.id, definition.operations.map(({id, effect, execute, description}) => ({id, effect, execute, ...(description && {description})})));
+    return this;
+  }
+  list() { return this.#catalog.list(); }
+  /** Review a prepared-only generation handoff. Never dispatches or recovers an uncertain write. */
+  async recoverPreparedClaim({token, expectedEntry, nextGeneration, decisionId, signal} = {}) {
+    const authenticate = () => this.#authority.authenticate(token, {tenantId:this.#tenantId, permission:'admin'});
+    const identity = authenticate(), requestId = randomUUID(), metadata = {requestId};
+    const record = (outcome, phase) => this.#audit.state.exclusive(() => this.#audit.append({
+      tenantId:identity.tenantId, actor:identity.subject, action:'connector.claim-recovery', outcome,
+      metadata:{...metadata, phase},
+    }));
+    try {
+      signal?.throwIfAborted();
+      if (!this.#effectJournal || typeof this.#authorizeClaimRecovery !== 'function') throw new Error('Claim recovery not configured');
+      const snapshot = JSON.parse(canonicalJson({expectedEntry, nextGeneration, decisionId}));
+      const entry = snapshot.expectedEntry;
+      if (!entry || entry.tenantId !== identity.tenantId || entry.status !== 'prepared' || !snapshotEffectBinding(entry.binding) ||
+          !Number.isSafeInteger(snapshot.nextGeneration) || snapshot.nextGeneration <= entry.binding.generation ||
+          typeof snapshot.decisionId !== 'string' || !snapshot.decisionId.trim()) throw new Error('Invalid prepared claim recovery');
+      const operation = this.#definitions.get(entry.connectorId)?.find(value => value.id === entry.operationId);
+      if (operation?.effect !== 'write') throw new Error('Unknown write operation');
+      Object.assign(metadata, {connectorId:entry.connectorId, operationId:entry.operationId, decisionId:snapshot.decisionId,
+        previousGeneration:entry.binding.generation, nextGeneration:snapshot.nextGeneration});
+      const request = {...snapshot, identity:structuredClone(identity)};
+      const guard = async () => {
+        authenticate(); signal?.throwIfAborted();
+        // Host verifies fresh Review and authoritative claim ownership/generation for this exact snapshot.
+        if (await this.#authorizeClaimRecovery(structuredClone(request)) !== true) throw new Error('Claim recovery denied');
+        authenticate(); signal?.throwIfAborted();
+        return true;
+      };
+      await guard();
+      await record('success', 'authorized');
+      const updated = await this.#effectJournal.advancePreparedClaim({...snapshot, subject:identity.subject, beforeCommit:guard});
+      await record('success', 'advanced');
+      authenticate(); signal?.throwIfAborted();
+      return updated;
+    } catch {
+      try { await record('failed', 'claim-recovery'); } catch { /* A generation may already be durable; inspect before retry. */ }
+      // A competing writer could have dispatched since the supplied snapshot. Never imply absence.
+      throw new ConnectorInvocationError('CONNECTOR_RECONCILIATION_REQUIRED', true);
+    }
+  }
+  /** Read-only host lookup. A found candidate still needs a fresh result-bound reconciliation Review. */
+  async lookupReceipt({token, expectedEntry, signal} = {}) {
+    const authenticate = () => this.#authority.authenticate(token, {tenantId:this.#tenantId, permission:'admin'});
+    const identity = authenticate(), requestId = randomUUID();
+    const metadata = {requestId};
+    const record = (outcome, phase) => this.#audit.state.exclusive(() => this.#audit.append({
+      tenantId:identity.tenantId, actor:identity.subject, action:'connector.receipt-lookup', outcome,
+      metadata:{...metadata, phase},
+    }));
+    try {
+      signal?.throwIfAborted();
+      if (!this.#effectJournal || typeof this.#authorizeReceiptLookup !== 'function' || typeof this.#lookupRemoteReceipt !== 'function') throw new Error('Lookup not configured');
+      const entry = JSON.parse(canonicalJson(expectedEntry));
+      if (!entry || entry.tenantId !== identity.tenantId || !['dispatched', 'reconciliation_required'].includes(entry.status) ||
+          !snapshotEffectBinding(entry.binding)) throw new Error('Bound uncertain effect required');
+      const operation = this.#definitions.get(entry.connectorId)?.find(value => value.id === entry.operationId);
+      if (operation?.effect !== 'write') throw new Error('Unknown write operation');
+      Object.assign(metadata, {connectorId:entry.connectorId, operationId:entry.operationId});
+      const request = {expectedEntry:entry, identity:structuredClone(identity)};
+      const guard = async () => {
+        authenticate(); signal?.throwIfAborted();
+        if (await this.#authorizeReceiptLookup(structuredClone(request)) !== true) throw new Error('Lookup denied');
+        authenticate(); signal?.throwIfAborted();
+        const current = await this.#effectJournal.get({tenantId:entry.tenantId, effectKey:entry.effectKey});
+        if (canonicalJson(current) !== canonicalJson(entry)) throw new Error('Effect changed');
+        authenticate(); signal?.throwIfAborted();
+      };
+      await guard();
+      await record('success', 'authorized');
+      await guard();
+      // The trusted host chooses the service and credentials; no caller URL or receipt is accepted.
+      // No journal lock is held during network I/O, and no journal mutation follows lookup.
+      const response = JSON.parse(canonicalJson(await this.#lookupRemoteReceipt({...structuredClone(request), signal})));
+      let candidate;
+      if (response?.status === 'found' && Object.keys(response).sort().join(',') === 'evidence,result,status') {
+        candidate = response;
+      } else if (response?.status === 'unknown' && Object.keys(response).join(',') === 'status') {
+        candidate = {status:'unknown'};
+      } else throw new Error('Invalid remote lookup outcome');
+      await guard();
+      await record('success', candidate.status);
+      await guard();
+      return structuredClone(candidate);
+    } catch {
+      try { await record('failed', 'lookup'); } catch { /* No outcome authorizes dispatch. */ }
+      throw new ConnectorInvocationError('CONNECTOR_RECONCILIATION_REQUIRED', true);
+    }
+  }
+  /** Confirm an observed outcome only. This endpoint never executes an adapter or enables retry. */
+  async reconcile({token, expectedEntry, decisionId, result, evidence, signal} = {}) {
+    const authenticate = () => this.#authority.authenticate(token, {tenantId:this.#tenantId, permission:'admin'});
+    const identity = authenticate();
+    let snapshot, request;
+    const actionMetadata = {};
+    const requestId = randomUUID();
+    const record = (outcome, phase) => this.#audit.state.exclusive(() => this.#audit.append({
+      tenantId:identity.tenantId, actor:identity.subject, action:'connector.reconcile', outcome,
+      metadata:{requestId, phase, ...actionMetadata},
+    }));
+    try {
+      signal?.throwIfAborted();
+      if (!this.#effectJournal || typeof this.#authorizeReconciliation !== 'function' || typeof this.#verifyReconciliation !== 'function') throw new Error('Reconciliation not configured');
+      snapshot = JSON.parse(canonicalJson({expectedEntry, decisionId, result, evidence}));
+      const entry = snapshot.expectedEntry;
+      if (!entry || entry.tenantId !== identity.tenantId || !['dispatched', 'reconciliation_required'].includes(entry.status) ||
+          !snapshotEffectBinding(entry.binding) || typeof decisionId !== 'string' || !decisionId.trim()) throw new Error('Invalid reviewed effect');
+      const operation = this.#definitions.get(entry.connectorId)?.find(value => value.id === entry.operationId);
+      if (operation?.effect !== 'write') throw new Error('Unknown write operation');
+      Object.assign(actionMetadata, {connectorId:entry.connectorId, operationId:entry.operationId, decisionId:snapshot.decisionId});
+      request = {...snapshot, identity:structuredClone(identity)};
+      const guard = async () => {
+        authenticate(); signal?.throwIfAborted();
+        if (await this.#authorizeReconciliation(structuredClone(request)) !== true) throw new Error('Reconciliation denied');
+        authenticate(); signal?.throwIfAborted();
+        return true;
+      };
+      await guard();
+      // Only a host callback can validate remote evidence against the exact reviewed action/result.
+      if (await this.#verifyReconciliation(structuredClone(request)) !== true) throw new Error('Remote outcome unverified');
+      await guard();
+      await record('success', 'verified');
+      await this.#effectJournal.confirmReconciled({expectedEntry:entry, decisionId:snapshot.decisionId,
+        subject:identity.subject, receipt:{source:'authenticated-connector-result-v1', result:snapshot.result}, beforeCommit:guard});
+      await record('success', 'confirmed');
+      authenticate(); signal?.throwIfAborted();
+      return structuredClone(snapshot.result);
+    } catch {
+      try { await record('failed', 'reconciliation'); } catch { /* Outcome may already be durable; never dispatch. */ }
+      throw new ConnectorInvocationError('CONNECTOR_RECONCILIATION_REQUIRED', true);
+    }
+  }
+  async invoke({token, connectorId, operationId, input, idempotencyKey, signal, binding} = {}) {
+    signal?.throwIfAborted();
+    const identity = this.#authority.authenticate(token, {tenantId: this.#tenantId});
+    const operations = this.#definitions.get(connectorId), selected = operations?.find(operation => operation.id === operationId);
+    if (!selected) throw new Error('Unknown connector operation');
+    const safeBinding = snapshotEffectBinding(binding);
+    if ((safeBinding && (selected.effect !== 'write' || !this.#effectJournal)) ||
+        (selected.effect === 'write' && this.#requireEffectBinding && !safeBinding)) throw new ConnectorInvocationError('CONNECTOR_DENIED', false);
+    const requestId = randomUUID();
+    const metadata = phase => ({requestId, connectorId, operationId, effect: selected.effect, phase});
+    const record = (outcome, phase) => this.#audit.state.exclusive(() => this.#audit.append({tenantId: identity.tenantId, actor: identity.subject, action: 'connector.invoke', outcome, metadata: metadata(phase)}));
+    const authenticate = () => this.#authority.authenticate(token, {tenantId: this.#tenantId, permission: selected.effect});
+    let permitted = false, denied = false, dispatched = false, auditingResult = false, recovered = false, uncertain = false;
+    const journal = selected.effect === 'write' ? this.#effectJournal : undefined;
+    const effect = {tenantId: identity.tenantId, effectKey: idempotencyKey, ...(safeBinding && {binding: safeBinding})};
+    let policyRequest;
+    const recheckBindingPolicy = async () => {
+      if (!safeBinding) return;
+      authenticate(); signal?.throwIfAborted();
+      if (await this.#authorize(structuredClone(policyRequest)) !== true) {
+        denied = true; throw new Error('Connector binding denied');
+      }
+      authenticate(); signal?.throwIfAborted();
+    };
+    try {
+      authenticate(); permitted = true;
+      const registry = new ConnectorRegistry({authorize: async request => {
+        authenticate();
+        policyRequest = {...structuredClone(request), identity: structuredClone(identity), ...(safeBinding && {binding: structuredClone(safeBinding)})};
+        if (typeof this.#authorize !== 'function' || await this.#authorize(structuredClone(policyRequest)) !== true) {
+          denied = true; return false;
+        }
+        authenticate();
+        // Persist intent before external dispatch; an unavailable audit store fails closed.
+        await record('success', journal ? 'authorization' : 'dispatch');
+        authenticate();
+        return true;
+      }});
+      registry.register({id: connectorId, operations: operations.map(operation => ({...operation, execute: async request => {
+        authenticate(); signal?.throwIfAborted();
+        if (journal) {
+          const entry = await journal.prepare({...effect, subject: identity.subject, connectorId, operationId, input: request.input});
+          uncertain = entry.status !== 'prepared'; // Existing intent remains ambiguous even if a fresh policy recheck fails.
+          authenticate(); signal?.throwIfAborted();
+          await recheckBindingPolicy();
+          if (entry.status === 'confirmed') {
+            if (entry.receipt?.source !== 'authenticated-connector-result-v1') { uncertain = true; throw new Error('EFFECT_REPLAY_BLOCKED'); }
+            recovered = true; uncertain = false;
+            return structuredClone(entry.receipt.result);
+          }
+          if (entry.status !== 'prepared') {
+            uncertain = true;
+            throw new Error('EFFECT_REPLAY_BLOCKED');
+          }
+          await journal.markDispatched(effect);
+          uncertain = true; // Durable dispatch intent already blocks replay, even before adapter entry.
+          // Recheck after durable I/O; a revoked or cancelled attempt stays blocked.
+          authenticate(); signal?.throwIfAborted();
+          await recheckBindingPolicy();
+        }
+        dispatched = true; uncertain = false;
+        return operation.execute(request);
+      }}))});
+      const result = await registry.invoke({connectorId, operationId, input, actor: identity.subject, tenantId: identity.tenantId, idempotencyKey, signal});
+      if (journal && !recovered) await journal.confirm({...effect, receipt: {source: 'authenticated-connector-result-v1', result}});
+      auditingResult = true;
+      await record('success', recovered ? 'recovered-result' : 'result');
+      auditingResult = false;
+      authenticate();
+      return result;
+    } catch (error) {
+      if (journal && dispatched) {
+        try { await journal.requireReconciliation(effect); } catch { /* Confirmed results and unavailable stores remain fail-closed. */ }
+      }
+      if (['EFFECT_REPLAY_BLOCKED', 'EFFECT_BINDING_CONFLICT'].includes(error?.message)) uncertain = true;
+      const isDenied = denied || !permitted;
+      try { await record(isDenied ? 'denied' : 'failed', dispatched ? 'effect-or-result' : 'pre-dispatch'); } catch { /* Never dispatch or retry because recording a failure also failed. */ }
+      throw new ConnectorInvocationError(uncertain ? 'CONNECTOR_RECONCILIATION_REQUIRED' : isDenied ? 'CONNECTOR_DENIED' : auditingResult ? 'CONNECTOR_AUDIT_FAILED' : 'CONNECTOR_FAILED', (dispatched || uncertain || recovered) && selected.effect === 'write');
+    }
+  }
+}
+

package/src/backups.js

@@ -0,0 +1,44 @@
+import {canonicalJson as canonical} from './canonical-json.js';
+import {createHash, timingSafeEqual} from 'node:crypto';
+import {TransactionalStateStore} from './transactions.js';
+
+const LIMIT = 16 * 1024 * 1024;
+
+function snapshot(state) {
+  const encoded = canonical(state);
+  if (!state || state.version !== 1 || !state.tenants || typeof state.tenants !== 'object' || Array.isArray(state.tenants) || Object.keys(state).sort().join(',') !== 'tenants,version') throw new Error('Invalid backup state schema');
+  if (Buffer.byteLength(encoded) > LIMIT) throw new Error('Backup exceeds size limit');
+  return {state: JSON.parse(JSON.stringify(state)), digest: createHash('sha256').update(encoded).digest('hex')};
+}
+
+/** Digest is byte-integrity evidence, not a signature or writer authentication. */
+export function verifyStateBackup(backup) {
+  canonical(backup);
+  if (!backup || backup.format !== 'aetheros-state-backup' || backup.version !== 1 || Object.keys(backup).sort().join(',') !== 'digest,format,state,version') throw new Error('Invalid backup envelope');
+  if (typeof backup.digest !== 'string' || !/^[a-f0-9]{64}$/.test(backup.digest)) throw new Error('Invalid backup digest');
+  const checked = snapshot(backup.state);
+  if (!timingSafeEqual(Buffer.from(backup.digest, 'hex'), Buffer.from(checked.digest, 'hex'))) throw new Error('Backup integrity check failed');
+  return checked;
+}
+
+/** Capture one atomically loaded file snapshot; the host stores the returned JSON. */
+export async function createStateBackup(store) {
+  if (!store || typeof store.load !== 'function') throw new TypeError('State store required');
+  const checked = snapshot(await store.load());
+  return {format: 'aetheros-state-backup', version: 1, ...checked};
+}
+
+/** Replace the entire local store only if it still matches the reviewed digest. */
+export async function restoreStateBackup(store, backup, {expectedCurrentDigest, beforeCommit} = {}) {
+  if (!(store instanceof TransactionalStateStore)) throw new TypeError('Transactional state store required');
+  if (typeof expectedCurrentDigest !== 'string' || !/^[a-f0-9]{64}$/.test(expectedCurrentDigest)) throw new Error('Expected current digest required');
+  if (beforeCommit !== undefined && typeof beforeCommit !== 'function') throw new TypeError('Invalid restore commit policy');
+  const checked = verifyStateBackup(backup);
+  await store.transaction(async current => {
+    const previous = snapshot(current);
+    if (previous.digest !== expectedCurrentDigest) throw new Error('State changed since restore approval');
+    if (beforeCommit && await beforeCommit({current: structuredClone(previous.state), currentDigest: previous.digest, backup: structuredClone(checked.state), backupDigest: checked.digest}) !== true) throw new Error('Restore commit policy denied');
+    return checked.state;
+  });
+  return {digest: checked.digest};
+}

package/src/canonical-json.js

@@ -0,0 +1,22 @@
+// Canonical JSON rejects values that JSON.stringify would silently discard.
+export function canonicalJson(value, active = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (typeof value !== 'object' || active.has(value)) throw new Error('Backup requires plain JSON');
+  const prototype = Object.getPrototypeOf(value);
+  if (Array.isArray(value) && prototype !== Array.prototype) throw new Error('Backup requires plain JSON arrays');
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new Error('Backup requires plain JSON');
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (Reflect.ownKeys(value).some(key => typeof key !== 'string' || (!(Array.isArray(value) && key === 'length') && (!descriptors[key].enumerable || !Object.hasOwn(descriptors[key], 'value'))))) throw new Error('Backup requires plain JSON');
+  active.add(value);
+  let encoded;
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length || Object.keys(value).some((key, i) => key !== String(i))) throw new Error('Backup requires dense JSON arrays');
+    encoded = '[' + Array.prototype.map.call(value, item => canonicalJson(item, active)).join(',') + ']';
+  } else {
+    encoded = '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonicalJson(value[key], active)).join(',') + '}';
+  }
+  active.delete(value);
+  return encoded;
+}
+