@milpa/comal 0.0.0-stage → 0.1.1

package/src/gemini-provider.mjs

@@ -0,0 +1,150 @@
+import { compileToolSchemas } from './tool-schema.mjs';
+import { normalizeUsage, bindUsageAccounting, accountingIdentity } from './usage-accounting.mjs';
+import { randomUUID } from 'node:crypto';
+import { sseEvents } from './provider.mjs';
+import { modelDeadline, modelTimingSettings } from './model-deadline.mjs';
+import { normalizeEffort, providerEffortWire } from './model-controls.mjs';
+
+const MAX_BODY = 8 * 1024 * 1024;
+const unsupported = capability => Object.assign(new Error(`El perfil no habilita la capacidad ${capability}.`), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+
+export function geminiBaseURL(value = 'https://generativelanguage.googleapis.com/v1beta') {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('URL Gemini inválida.');
+  if (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) throw new Error('Gemini requiere HTTPS excepto en localhost.');
+  let pathname = url.pathname.replace(/\/+$/, '');
+  if (!/\/v1(?:beta)?$/.test(pathname)) pathname += '/v1beta';
+  url.pathname = pathname;
+  return url.href.replace(/\/$/, '');
+}
+
+function mediaPart(block, capabilities) {
+  const source = block.source || block;
+  const mimeType = source.media_type || source.mimeType;
+  if (typeof mimeType !== 'string' || !/^(?:image|video)\/[a-z0-9.+-]+$/i.test(mimeType)) throw new Error('MIME de imagen/video inválido.');
+  const capability = mimeType.startsWith('video/') ? 'video' : 'vision';
+  if (!capabilities[capability]) throw unsupported(capability);
+  if (source.data !== undefined) {
+    if (typeof source.data !== 'string' || !source.data || source.data.length % 4 || !/^[a-zA-Z0-9+/]*={0,2}$/.test(source.data)) throw new Error('Contenido multimedia base64 inválido.');
+    return { inlineData: { mimeType, data: source.data } };
+  }
+  const fileUri = source.uri || source.file_uri;
+  const url = new URL(fileUri);
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error('El video remoto requiere URI HTTPS sin credenciales.');
+  return { fileData: { mimeType, fileUri: url.href } };
+}
+
+// Retain exact signed model parts. Gemini requires thoughtSignature alongside
+// functionCall when returning the corresponding functionResponse on later turns.
+export function toGeminiContents(messages, capabilities) {
+  const contents = [], calls = new Map();
+  for (const message of messages) {
+    if (!['assistant', 'user'].includes(message.role)) throw new Error(`Rol Gemini no soportado: ${message.role}`);
+    const parts = [];
+    for (const block of typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : message.content || []) {
+      if (message.role === 'assistant' && block.gemini_part) {
+        const part = structuredClone(block.gemini_part);
+        if (part.functionCall) calls.set(block.id, { name: part.functionCall.name, id: part.functionCall.id });
+        parts.push(part);
+      } else if (block.type === 'text') parts.push({ text: block.text });
+      else if (block.type === 'tool_use') {
+        calls.set(block.id, { name: block.name, id: block.id });
+        parts.push({ functionCall: { id: block.id, name: block.name, args: block.input } });
+      } else if (block.type === 'tool_result') {
+        const call = calls.get(block.tool_use_id);
+        if (!call) throw new Error('Resultado Gemini sin llamada previa.');
+        const result = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
+        parts.push({ functionResponse: { name: call.name, ...(call.id ? { id: call.id } : {}), response: block.is_error ? { error: result } : { result } } });
+      } else if (['image', 'video', 'media'].includes(block.type)) parts.push(mediaPart(block, capabilities));
+      else if (block.type === 'image_reference') throw new Error('Referencia visual sin resolver; no se envió al proveedor.');
+    }
+    if (!parts.length) continue;
+    const role = message.role === 'assistant' ? 'model' : 'user';
+    if (contents.at(-1)?.role === role) contents.at(-1).parts.push(...parts);
+    else contents.push({ role, parts });
+  }
+  return contents;
+}
+
+function normalize(parts, finishReason, usage, groundingMetadata, usage_accounting) {
+  if (finishReason === 'MAX_TOKENS') throw Object.assign(new Error('Respuesta Gemini truncada; no se ejecutaron herramientas.'), { code: 'OUTPUT_LENGTH', usage, usage_accounting });
+  if (finishReason !== 'STOP') throw new Error(`Respuesta Gemini incompleta (${finishReason || 'stream interrumpido'}); no se ejecutaron herramientas.`);
+  const content = [], ids = new Set();
+  for (const part of parts) {
+    const metadata = { gemini_part: structuredClone(part) };
+    if (typeof part.text === 'string') content.push(part.thought ? { type: 'thinking', thinking: part.text, ...metadata } : { type: 'text', text: part.text, ...metadata });
+    else if (part.functionCall) {
+      const call = part.functionCall, id = call.id || randomUUID(), input = call.args === undefined ? {} : call.args;
+      if (typeof call.name !== 'string' || !call.name || typeof id !== 'string' || !input || typeof input !== 'object' || Array.isArray(input) || ids.has(id)) throw Object.assign(new Error('Llamada Gemini inválida; no se ejecutaron herramientas.'), { code: 'TOOL_ARGUMENTS_INVALID' });
+      ids.add(id); content.push({ type: 'tool_use', id, name: call.name, input, ...metadata });
+    } else if (part.thoughtSignature) content.push({ type: 'thinking', thinking: '', ...metadata });
+    else throw new Error('Parte Gemini no soportada; no se ejecutaron herramientas.');
+  }
+  if (!content.some(block => block.type === 'text' || block.type === 'tool_use')) throw new Error('Gemini no devolvió texto ni herramientas.');
+  return { role: 'assistant', content, stop_reason: content.some(block => block.type === 'tool_use') ? 'tool_use' : 'end_turn', usage, usage_accounting, ...(groundingMetadata ? { grounding_metadata: groundingMetadata } : {}) };
+}
+
+export class GeminiProvider {
+  constructor({ apiKey = process.env.GEMINI_API_KEY, baseURL, model, maxTokens = 8192, effort = 'auto', capabilitiesConfigured, capabilities = {}, imageTokens = 4096, timeoutMs = 600000, idleTimeoutMs = 180000, fetchImpl = fetch } = {}) {
+    if (!apiKey) throw new Error('Define GEMINI_API_KEY o apiKeyEnv del perfil.');
+    if (typeof model !== 'string' || !/^(?:models\/)?[a-zA-Z0-9._-]+$/.test(model)) throw new Error('Especifica un modelo Gemini válido.');
+    this.protocol = 'gemini'; this.effort = normalizeEffort(effort); this.capabilitiesConfigured = { ...(capabilitiesConfigured ?? capabilities) }; this.configuredCapabilities = this.capabilitiesConfigured;
+    this.apiKey = apiKey; this.baseURL = geminiBaseURL(baseURL); this.model = model.replace(/^models\//, '');
+    this.maxTokens = maxTokens; this.fetch = fetchImpl; this.imageTokens = imageTokens;
+    this.capabilities = Object.freeze({ text: true, tools: true, vision: false, video: false, web_search: false, ...capabilities });
+    Object.assign(this, modelTimingSettings({ timeoutMs, idleTimeoutMs }, {}));
+  }
+  getCapabilities() { return { ...this.capabilities, ...(this.modelCapabilities && this.modelCapabilities.model === this.model ? Object.fromEntries(Object.entries(this.modelCapabilities.capabilities).filter(([,value]) => value !== null)) : {}) }; }
+  getVisionCapability() { return { supported: this.getCapabilities().vision, source: 'explicit_profile_configuration', model: this.model, imageTokens: this.imageTokens }; }
+  async complete({ system, messages, tools = [], schemaCatalog = [], contextIdentity, signal, onText = () => {}, onProgress = () => {}, maxTokens = this.maxTokens, purpose = 'worker', nativeSearch = false, stream = true }) {
+    const accountingRequest={system,messages,tools,maxTokens},identity={...accountingIdentity(this),projection_epoch:contextIdentity?.projection_epoch ?? null};
+    if (tools.length && !this.getCapabilities().tools) throw unsupported('tools');
+    if (nativeSearch && !this.getCapabilities().web_search) throw unsupported('web_search');
+    // Native grounding is isolated from user-defined functions for compatibility
+    // with models that reject that combination; tools remain available normally.
+    if (nativeSearch && tools.length) throw new Error('La búsqueda nativa se ejecuta separada de las funciones de la casa.');
+    const schemaFrame=compileToolSchemas(tools,{provider:this.protocol,capabilities:{...(this.getCapabilities?.() || {}),...(this.toolSchemaCapabilities?{tool_schema:this.toolSchemaCapabilities}:{})},catalogue:schemaCatalog}); tools=schemaFrame.tools;
+    const effortWire = await providerEffortWire(this, { signal });
+    const request = { contents: toGeminiContents(messages, this.getCapabilities()), generationConfig: { maxOutputTokens: maxTokens, ...effortWire },
+      ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}),
+      ...(nativeSearch ? { tools: [{ googleSearch: {} }] } : tools.length ? { tools: [{ functionDeclarations: tools.map(tool => ({ name: tool.name, description: tool.description, parametersJsonSchema: tool.input_schema })) }] } : {}) };
+    const body = JSON.stringify(request);
+    if (Buffer.byteLength(body) > MAX_BODY) throw new Error('La petición Gemini excede 8 MiB; usa un video remoto o un clip menor.');
+    const deadline = modelDeadline({ signal, timeoutMs: this.timeoutMs, idleTimeoutMs: this.idleTimeoutMs, purpose });
+    try {
+      const response = await this.fetch(`${this.baseURL}/models/${this.model}:${stream ? 'streamGenerateContent?alt=sse' : 'generateContent'}`, { method: 'POST', headers: { 'content-type': 'application/json', 'x-goog-api-key': this.apiKey }, body, signal: deadline.signal, redirect: 'error' });
+      if (!response.ok) { await response.body?.cancel(); throw new Error(`Gemini HTTP ${response.status}. Revisa modelo, endpoint y credenciales del perfil.`); }
+      const parts = []; let finish, grounding, usageRaw, usage = { input_tokens: 0, output_tokens: 0 };
+      const consume = event => {
+        if (event.error) throw new Error('Gemini devolvió un error; no se ejecutaron herramientas.');
+        const candidate = event.candidates?.find(item => item.index === 0) || event.candidates?.[0];
+        if (candidate?.finishReason) finish = candidate.finishReason;
+        if (candidate?.groundingMetadata) grounding = candidate.groundingMetadata;
+        if (event.usageMetadata) {usageRaw=event.usageMetadata; usage = { input_tokens: event.usageMetadata.promptTokenCount || 0, output_tokens: (event.usageMetadata.candidatesTokenCount || 0) + (event.usageMetadata.thoughtsTokenCount || 0) };}
+        for (const part of candidate?.content?.parts || []) {
+          parts.push(part); deadline.touch();
+          if (typeof part.text === 'string' && !part.thought) onText(part.text);
+        }
+        onProgress({ elapsed_ms: deadline.elapsedMs(), purpose });
+      };
+      if (response.headers.get('content-type')?.includes('text/event-stream')) { for await (const event of sseEvents(response.body)) { if (event.type !== 'stream_done') consume(event); } }
+      else consume(await response.json());
+      deadline.signal.throwIfAborted();
+      return {...normalize(parts, finish, usage, grounding,bindUsageAccounting(normalizeUsage('gemini',usageRaw),accountingRequest,identity,body)),schema_diagnostics:schemaFrame.diagnostics,schema_manifest:schemaFrame.manifest};
+    } catch (error) { throw deadline.error(error); }
+    finally { deadline.close(); }
+  }
+  async nativeSearch({ query, signal, maxTokens } = {}) {
+    if (!this.getCapabilities().web_search) throw unsupported('web_search');
+    if (typeof query !== 'string' || !query.trim() || query.length > 12000) throw new Error('Consulta de búsqueda inválida.');
+    const result = await this.complete({ messages: [{ role: 'user', content: query }], tools: [], nativeSearch: true, signal, maxTokens });
+    const grounding = result.grounding_metadata || {};
+    const sources = (Array.isArray(grounding.groundingChunks) ? grounding.groundingChunks : []).filter(item => typeof item?.web?.uri === 'string' && /^https?:\/\//i.test(item.web.uri)).map(item => ({ title: item.web.title, url: item.web.uri }));
+    return { answer: result.content.filter(block => block.type === 'text').map(block => block.text).join(''), grounded: sources.length > 0, sources, grounding, usage: result.usage };
+  }
+  async analyzeMedia({ prompt, media, signal, maxTokens } = {}) {
+    if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 12000 || !Array.isArray(media) || !media.length || media.length > 4) throw new Error('Solicitud multimedia inválida.');
+    const result = await this.complete({ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }, ...media.map(source => ({ type: 'media', source }))] }], signal, maxTokens });
+    return { answer: result.content.filter(block => block.type === 'text').map(block => block.text).join(''), usage: result.usage, model: this.model };
+  }
+}

package/src/goals.mjs

@@ -0,0 +1,169 @@
+import { randomUUID } from 'node:crypto';
+import { estimateRequest } from './compaction.mjs';
+import {acquireProcessLock} from './process-lock.mjs';
+
+export const GOAL_DEFAULTS = { maxIterations: 20, maxCalls: 80, maxTokens: 100000 };
+export class GoalBudgetExceeded extends Error {
+  constructor(message) { super(message); this.code = 'GOAL_BUDGET'; }
+}
+
+function validLimits(limits) {
+  for (const [key, value] of Object.entries(limits)) if (!Number.isSafeInteger(value) || value < 1 || value > (key === 'maxTokens' ? 10000000 : 10000)) throw new Error(`Límite de /goal inválido: ${key}`);
+}
+
+export class GoalManager {
+  constructor(store, sessionId, { onEvent = () => {} } = {}) { this.store = store; this.sessionId = sessionId; this.onEvent = onEvent; }
+  async read() { return (await this.store.load(this.sessionId)).goal; }
+  async budgetTransaction(run) {
+    const lock=await acquireProcessLock(this.store.file(this.sessionId)+'.budget.lock',{waitMs:5000,validate:()=>this.store.validateForRecovery(this.sessionId)});
+    try{return await run();}finally{await lock.release();}
+  }
+  async write(goal,{withinBudgetLock=false}={}) {
+    if(!withinBudgetLock)return this.budgetTransaction(async()=>{const current=await this.read();return this.write(current?.id===goal.id?{...goal,calls:current.calls,tokens:current.tokens,estimatedTokens:current.estimatedTokens,...(current.budget_reservations?{budget_reservations:current.budget_reservations}:{}),...(current.budget_estimated_spend!==undefined?{budget_estimated_spend:current.budget_estimated_spend}:{})}:goal,{withinBudgetLock:true});});
+    const value = { ...goal, updatedAt: new Date().toISOString() };
+    await this.store.append(this.sessionId, { type: 'goal', goal: value });
+    await this.onEvent({ type: 'goal_status', goal: value }); return value;
+  }
+  async start(condition, limits = {}) {
+    if (!condition.trim() || condition.length > 4000) throw new Error('/goal requiere una condición de 1 a 4000 caracteres.');
+    const configured = { ...GOAL_DEFAULTS, ...limits }; validLimits(configured);
+    const release = await this.store.lock(this.sessionId, { kind: 'goal' });
+    try {
+      const session = await this.store.load(this.sessionId), messageBaseline = session.historyMessages.length, receiptBaseline = session.rows.length;
+      await this.store.append(this.sessionId, { type: 'intent', text: condition });
+      return await this.write({ id: randomUUID(), condition, status: 'active', iterations: 0, calls: 0, tokens: 0, estimatedTokens: false, stalls: 0, messageBaseline, receiptBaseline, limits: configured, startedAt: new Date().toISOString(), lastReason: 'Objetivo establecido.', lastVerdict: null });
+    } finally { await release(); }
+  }
+  async change(status, reason) {
+    const release = await this.store.lock(this.sessionId, { kind: 'goal' });
+    try {
+      const goal = await this.read(); if (!goal) throw new Error('No hay objetivo establecido.');
+      if (status === 'paused' && ['met', 'failed', 'cleared', 'budget'].includes(goal.status)) throw new Error('El objetivo ya terminó; sólo un objetivo activo puede pausarse.');
+      if (status === 'active' && ['met', 'failed', 'cleared', 'budget'].includes(goal.status)) throw new Error('Ese objetivo terminó o agotó su presupuesto. Establece uno nuevo con /goal <condición>.');
+      return await this.write({ ...goal, status, pauseReason: undefined, lastReason: reason });
+    } finally { await release(); }
+  }
+}
+
+// Count context input once, including protocol cache semantics. Unknown usage is
+// conservative; an observed zero from a normalized adapter is still a measurement.
+function reportedSpend(answer) {
+  const normalized=answer?.usage_accounting;
+  const value=normalized?.version===1 ? [normalized.context_input_tokens,normalized.output_tokens] : [answer?.usage?.input_tokens,answer?.usage?.output_tokens];
+  return value.every(n=>Number.isSafeInteger(n)&&n>=0)?value[0]+value[1]:null;
+}
+// Budget accounting covers worker, classifier and evaluator. Reserve before sending.
+export class GoalBudget {
+  constructor(manager, provider, {goalId}={}) { this.manager = manager; this.provider = provider; this.goalId=goalId; this.accounting = Promise.resolve(); this.pendingRequests = 0; this.estimated = undefined; }
+  get model() { return this.provider.model; }
+  get maxTokens() { return this.provider.maxTokens; }
+  get contextWindow() { return this.provider.contextWindow; }
+  async exclusive(operation) {
+    const previous = this.accounting; let release;
+    this.accounting = new Promise(resolve => release = resolve);
+    await previous; try { return await this.manager.budgetTransaction(operation); } finally { release(); }
+  }
+  async complete(options, execute = request => this.provider.complete(request)) {
+    const reservation = await this.exclusive(async () => {
+      options.signal?.throwIfAborted(); const goal = await this.manager.read();
+      if(!goal || this.goalId && goal.id!==this.goalId)throw new GoalBudgetExceeded('El presupuesto pertenece a otro objetivo; no se envió la petición.');
+      this.goalId??=goal.id;
+      if (goal.status !== 'active') throw new GoalBudgetExceeded('El objetivo ya no está activo.');
+      if (goal.calls >= goal.limits.maxCalls) throw new GoalBudgetExceeded('Se agotó el límite de llamadas del objetivo.');
+      const extra=options.inputTokenReserve ?? 0;
+      if(!Number.isSafeInteger(extra) || extra<0)throw new Error('Reserva adicional de entrada inválida.');
+      const inputReserve = estimateRequest(options) + extra;
+      const remaining = goal.limits.maxTokens - goal.tokens - inputReserve;
+      const maxTokens = options.maxTokens || this.provider.maxTokens || 4096;
+      if (remaining < maxTokens) throw new GoalBudgetExceeded('El presupuesto de tokens restante no cubre entrada y salida completas; se conserva el checkpoint sin reducir la respuesta.');
+      const reserved = inputReserve + maxTokens;
+      this.estimated = Boolean(this.estimated || (goal.budget_estimated_spend ?? (goal.estimatedTokens && !goal.budget_reservations?.length)));
+      const reservationId=randomUUID();
+      const pending = await this.manager.write({ ...goal, calls: goal.calls + 1, tokens: goal.tokens + reserved, estimatedTokens: true,budget_estimated_spend:Boolean(this.estimated),budget_reservations:[...(goal.budget_reservations || []),{id:reservationId,reserved,purpose:options.purpose || 'worker'}] },{withinBudgetLock:true});
+      this.pendingRequests++;
+      return { goal, pending, maxTokens, reserved, inputReserve,reservationId };
+    });
+    const { goal, pending, maxTokens, reserved, inputReserve,reservationId } = reservation;
+    let answer;
+    try { answer = await execute({ ...options, maxTokens }); }
+    catch (error) {
+      await this.exclusive(async () => {
+        this.pendingRequests--; this.estimated = true;
+        const current = await this.manager.read();
+        if (current.id === pending.id) {
+          const usage = reportedSpend(error);
+          const tokens = usage!==null ? current.tokens - reserved + usage : current.tokens;
+          await this.manager.write({ ...current, tokens, estimatedTokens: true,budget_estimated_spend:true,budget_reservations:(current.budget_reservations || []).filter(item=>item.id!==reservationId) },{withinBudgetLock:true});
+          if (tokens > goal.limits.maxTokens) throw new GoalBudgetExceeded('El servidor reportó un gasto superior al presupuesto; se detuvo el objetivo.');
+        }else await this.manager.store.append(this.manager.sessionId,{type:'goal_request_settlement',source:'budget_host',goal_id:pending.id,reservation_id:reservationId,reserved,usage:error.usage || null,usage_accounting:error.usage_accounting || null,applied_to_current_goal:false,reason:'goal_changed_in_failed_request'});
+      });
+      throw error;
+    }
+    const usage = reportedSpend(answer);
+    const spend = usage ?? inputReserve + Math.ceil(Buffer.byteLength(JSON.stringify(answer.content ?? answer)) / 3);
+    await this.exclusive(async () => {
+      this.pendingRequests--; this.estimated ||= usage===null;
+      const current = await this.manager.read();
+      if (current.id !== pending.id) {
+        await this.manager.store.append(this.manager.sessionId,{type:'goal_request_settlement',source:'budget_host',goal_id:pending.id,reserved,usage:answer.usage || null,usage_accounting:answer.usage_accounting || null,spend,applied_to_current_goal:false,reason:'goal_changed_in_flight'});
+        const error=new GoalBudgetExceeded('El objetivo cambió durante la petición; el gasto quedó atribuido al original y no se ejecutan sus herramientas.');error.usage=answer.usage;error.usage_accounting=answer.usage_accounting;throw error;
+      }
+      const pendingReservations=(current.budget_reservations || []).filter(item=>item.id!==reservationId),estimatedSpend=Boolean(current.budget_estimated_spend || this.estimated);
+      await this.manager.write({ ...current, tokens: current.tokens - reserved + spend, estimatedTokens: estimatedSpend || pendingReservations.length>0,budget_estimated_spend:estimatedSpend,budget_reservations:pendingReservations },{withinBudgetLock:true});
+      if(current.status!=='active'){const error=new GoalBudgetExceeded('El objetivo dejó de estar activo durante la petición; gasto asentado, herramientas descartadas.');error.usage=answer.usage;error.usage_accounting=answer.usage_accounting;throw error;}
+      if (current.tokens - reserved + spend > goal.limits.maxTokens) throw new GoalBudgetExceeded('El servidor reportó un gasto superior al presupuesto; se detuvo el objetivo.');
+    });
+    return answer;
+  }
+}
+
+export class GoalRunner {
+  constructor({ manager, agent, evaluator, getReceipts }) { Object.assign(this, { manager, agent, evaluator, getReceipts }); }
+  async run({ signal, shouldYield = () => false } = {}) {
+    const release = await this.manager.store.lock(this.manager.sessionId, { kind: 'goal' });
+    let lastResult;
+    try {
+      let goal = await this.manager.read();
+      if (!goal || goal.status !== 'active') throw new Error('No hay objetivo activo para ejecutar.');
+      while (goal.status === 'active') {
+        signal?.throwIfAborted();
+        if (goal.iterations >= goal.limits.maxIterations) throw new GoalBudgetExceeded('Se agotó el límite de turnos del objetivo.');
+        // Reserve an iteration before the worker, so crashes do not reset the limit.
+        goal = await this.manager.write({ ...goal, iterations: goal.iterations + 1 });
+        const before = (await this.manager.store.load(this.manager.sessionId)).historyMessages.length;
+        const directive = goal.iterations === 1 ? goal.condition : `Continúa con el objetivo autorizado: ${goal.condition}\nÚltima evaluación (orientación, no autorización): ${goal.lastReason}\nRealiza una comprobación observable. Mantén los permisos y alcance del usuario.`;
+        lastResult = await this.agent.turn(directive, { signal, source: 'goal', withinGoal: true, shouldYield });
+        if (lastResult.yielded && shouldYield()) {
+          goal = await this.manager.write({ ...await this.manager.read(), status: 'paused', pauseReason: 'queued-message', lastReason: 'Checkpoint conservado para procesar el mensaje en cola. Usa /goal resume para continuar.' }); break;
+        }
+        if (lastResult.work_stop_reason === 'no_progress') {
+          goal = await this.manager.write({ ...await this.manager.read(), status: 'paused', pauseReason: 'no-progress', lastReason: 'La casa detectó llamadas repetidas sin avance. Encargo sin juzgar; corrige la acción siguiente antes de /goal resume.' }); break;
+        }
+        const session = await this.manager.store.load(this.manager.sessionId);
+        const recent = session.historyMessages.slice(before).flatMap(m => Array.isArray(m.content) ? m.content : []);
+        goal = await this.manager.read();
+        const delegatedDenied = recent.some(block => {
+          if (block.type !== 'tool_result') return false;
+          try { return JSON.parse(block.content).agents?.some(child => child.evidence?.some(item => item.is_error && /Permission denied|Permiso denegado/.test(item.output))) || false; } catch { return false; }
+        });
+        if (delegatedDenied || recent.some(b => b.type === 'tool_result' && b.is_error && /Permission denied|Permiso denegado/.test(b.content))) {
+          goal = await this.manager.write({ ...goal, status: 'paused', lastReason: 'Se requiere autorización para una herramienta; revisa los permisos y usa /goal resume.' }); break;
+        }
+        const verdict = await this.evaluator.evaluate({ condition: goal.condition, messages: session.historyMessages.slice(goal.messageBaseline || 0), signal, receipts: this.getReceipts ? await this.getReceipts(session, goal) : undefined });
+        goal = await this.manager.read();
+        const stalls = recent.some(b => b.type === 'tool_result' && !b.is_error) ? 0 : goal.stalls + 1;
+        let status = verdict.verdict === 'met' ? 'met' : verdict.verdict === 'impossible' ? 'failed' : 'active';
+        if (status === 'active' && stalls >= 3) status = 'paused';
+        goal = await this.manager.write({ ...goal, status, stalls, lastVerdict: verdict.verdict, lastReason: status === 'paused' ? 'Tres turnos sin evidencia nueva de herramientas. ' + verdict.reason : verdict.reason, evidenceIds: verdict.evidence_ids, evaluationScope: verdict.scope || 'model_goal_evaluation', evaluationAuthority: 'advisory' });
+        if (goal.status === 'active' && shouldYield()) goal = await this.manager.write({ ...goal, status: 'paused', pauseReason: 'queued-message', lastReason: 'Objetivo pausado al final del turno para procesar el mensaje en cola. Usa /goal resume para continuar.' });
+      }
+      return this.result(goal, lastResult);
+    } catch (error) {
+      const goal = await this.manager.read();
+      if (!goal) throw error;
+      const updated = await this.manager.write({ ...goal, status: error.code === 'GOAL_BUDGET' ? 'budget' : 'paused', lastReason: signal?.aborted ? 'Objetivo pausado por interrupción; usa /goal resume.' : error.message });
+      return this.result(updated, lastResult);
+    } finally { await release(); }
+  }
+  result(goal, last) { return { type: 'result', session_id: this.manager.sessionId, result: last?.result || goal.lastReason, goal, ...(last?.house ? { house: last.house } : {}), is_error: goal.status !== 'met', yielded: goal.status === 'paused' && goal.pauseReason === 'queued-message' }; }
+}

package/src/governance.mjs

@@ -0,0 +1,81 @@
+import { digest, immutable } from './operations.mjs';
+
+const fail = message => Object.assign(new Error(message), { code: 'GOVERNANCE_INVALID' });
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value);
+
+// Deliberately bounded Node contract, not a claim of Milpa hash/API compatibility.
+// The host supplies implementation identities separately from the declared law.
+export function compileGovernance({ decisions, profile }, mechanisms = []) {
+  if (!Array.isArray(decisions) || decisions.length > 64 || !identifier(profile?.name) || !identifier(profile?.version) || !Array.isArray(profile.decisionIds)) throw fail('Invalid governance corpus/profile.');
+  const byId = new Map(), statuses = new Set(['accepted', 'proposed', 'rejected', 'deprecated']);
+  for (const decision of decisions) {
+    if (!identifier(decision.id) || byId.has(decision.id) || !statuses.has(decision.status) || typeof decision.title !== 'string' || !Array.isArray(decision.gates)) throw fail('Invalid or duplicate governance decision.');
+    byId.set(decision.id, structuredClone(decision));
+  }
+  const visiting = new Set(), visited = new Set();
+  const visit = decision => {
+    if (visiting.has(decision.id)) throw fail('Governance supersession cycle.');
+    if (visited.has(decision.id)) return;
+    visiting.add(decision.id);
+    if (decision.supersedes != null) { const previous = byId.get(decision.supersedes); if (!previous) throw fail('Dangling governance supersession.'); visit(previous); }
+    visiting.delete(decision.id); visited.add(decision.id);
+  };
+  for (const decision of byId.values()) visit(decision);
+  const superseded = new Set([...byId.values()].filter(d => d.status === 'accepted' && d.supersedes).map(d => d.supersedes));
+  if (new Set(profile.decisionIds).size !== profile.decisionIds.length) throw fail('Duplicate profile decision.');
+  const active = profile.decisionIds.map(id => {
+    const decision = byId.get(id);
+    if (!decision || decision.status !== 'accepted' || superseded.has(id)) throw fail('Profile refers to an absent or inactive decision.');
+    return decision;
+  }).sort((a, b) => a.id.localeCompare(b.id));
+  const available = new Set(mechanisms), seen = new Set(), gates = [];
+  for (const decision of active) for (const gate of decision.gates) {
+    if (!identifier(gate.id) || seen.has(gate.id) || !['enforced','advisory','convention','deferred'].includes(gate.tier) || !Array.isArray(gate.operations) || !gate.operations.length || gate.operations.some(name => name !== '*' && !identifier(name))) throw fail('Invalid/duplicate governance gate.');
+    if (gate.tier === 'enforced' && (!identifier(gate.boundTo) || !available.has(gate.boundTo))) throw fail(`Unbound enforcement mechanism: ${gate.id}.`);
+    seen.add(gate.id); gates.push({ ...gate, decision_id: decision.id, operations: [...new Set(gate.operations)].sort() });
+  }
+  gates.sort((a, b) => a.id.localeCompare(b.id));
+  const core = { schema: 'comal-governance/v1', compiler: 'comal-node/1', profile: { name: profile.name, version: profile.version },
+    corpus_digest: digest([...byId.values()].sort((a,b) => a.id.localeCompare(b.id))),
+    decisions: active.map(d => ({ id: d.id, content_digest: digest(d) })), gates };
+  return immutable({ ...core, plan_hash: digest(core) });
+}
+
+export function bindGovernance(plan, bindings) {
+  const { plan_hash, ...core } = plan || {};
+  if (core.schema !== 'comal-governance/v1' || digest(core) !== plan_hash || !Array.isArray(core.gates)) throw fail('Compiled governance plan hash is invalid.');
+  const selected = new Map();
+  for (const gate of core.gates.filter(gate => gate.tier === 'enforced')) {
+    const binding = bindings[gate.boundTo];
+    if (!binding || typeof binding.check !== 'function' || !identifier(binding.revision) || !Array.isArray(binding.operations) || gate.operations.some(op => !binding.operations.includes(op))) throw fail(`Mechanism does not implement the gate scope: ${gate.id}.`);
+    selected.set(gate.id, Object.freeze({ ...binding, operations: Object.freeze([...binding.operations]) }));
+  }
+  return { plan: immutable(structuredClone(plan)), bindings: selected,
+    stamp: digest({ plan_hash, bindings: [...selected].map(([id,b]) => [id,b.revision,b.operations,b.configuration_digest || null]) }) };
+}
+
+// Offline consistency of recorded law -> mechanism -> decision -> receipt.
+// This does not attest the executable, remote effects or an external trust root.
+export function auditGovernance(rows) {
+  const activations = new Map(), decisions = new Map(), proposals = new Map(), violations = [];
+  let active = null, receipts = 0;
+  const fault = (row, reason) => violations.push({ invocation_id: row.invocation_id, operation: row.operation, reason });
+  for (const row of rows) {
+    if (row.type === 'governance_activated') {
+      const { plan_hash, ...core } = row.plan || {};
+      if (row.source !== 'governance_host' || core.schema !== 'comal-governance/v1' || digest(core) !== plan_hash || !Array.isArray(row.mechanisms) || digest({ plan_hash, bindings: row.mechanisms }) !== row.mechanism_stamp) { fault(row, 'governance_activation_invalid'); continue; }
+      activations.set(row.activation_id, row); active = row;
+    }
+    if (row.type === 'house_proposal') proposals.set(row.invocation_id, row);
+    if (row.type === 'governance_decision') { const list = decisions.get(row.invocation_id) || []; list.push(row); decisions.set(row.invocation_id, list); }
+    if (row.type !== 'house_receipt' || !row.governance_plan_hash) continue;
+    receipts++;
+    const activation = activations.get(row.governance_activation_id), proposal = proposals.get(row.invocation_id);
+    if (!activation || activation.plan.plan_hash !== row.governance_plan_hash || activation.mechanism_stamp !== row.mechanism_stamp || !proposal || ['governance_plan_hash','mechanism_stamp','governance_activation_id'].some(key => proposal[key] !== row[key])) { fault(row, 'governance_receipt_binding_mismatch'); continue; }
+    if (row.status === 'returned') for (const gate of activation.plan.gates.filter(g => g.tier === 'enforced' && (g.operations.includes('*') || g.operations.includes(row.operation)))) {
+      if (!(decisions.get(row.invocation_id) || []).some(d => d.allowed === true && d.gate_id === gate.id && d.decision_id === gate.decision_id && d.governance_activation_id === activation.activation_id && d.governance_plan_hash === row.governance_plan_hash && d.mechanism_stamp === row.mechanism_stamp && d.arguments_digest === row.arguments_digest && d.operation === row.operation)) fault(row, 'returned_without_governance_decision');
+    }
+  }
+  return { scope: 'recorded_governance_bindings', active_plan_hash: active?.plan.plan_hash || null, activations: activations.size, receipts, violations,
+    consistent: !violations.length, external_attestation: false };
+}

package/src/house.mjs

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { OperationRegistry, digest, immutable } from './operations.mjs';
+import { bindGovernance } from './governance.mjs';
+import { processIdentity } from './process-lock.mjs';
+
+export class House {
+  #context = new AsyncLocalStorage();
+  #active = new Set();
+  #observers = new Map();
+  #guards = new Map();
+  #contracts = new Set();
+  #governance = new Map();
+  #recoveries = new Map();
+  constructor({ cwd, registry = new OperationRegistry(), record }) { this.cwd = cwd; this.registry = registry; this.hasRecorder = Boolean(record); this.record = record || (async () => {}); }
+  snapshot(rows) { return houseSnapshot(rows, { active: this.#active, exclude: this.#context.getStore()?.id }); }
+  stateContext() { return { active: new Set(this.#active), exclude: this.#context.getStore()?.id }; }
+  recoveryAdapter(sessionId,name) {return this.#recoveries.get(`${sessionId}:${name}`);}
+  registerRecovery(sessionId,name,handler) {const key=`${sessionId}:${name}`;this.#recoveries.set(key,handler);return ()=>{if(this.#recoveries.get(key)===handler)this.#recoveries.delete(key);};}
+  watch(listener) { const key = Symbol(); this.#observers.set(key, listener); return () => this.#observers.delete(key); }
+  guard(id, check) { const key = Symbol(); this.#guards.set(key, { id, check }); return () => this.#guards.delete(key); }
+  async activateGovernance({ sessionId, plan, bindings }) {
+    if (!this.hasRecorder) throw Object.assign(new Error('Governance requires a durable host recorder.'), { code: 'GOVERNANCE_INVALID' });
+    const bound = bindGovernance(plan, bindings);
+    bound.activation_id = randomUUID();
+    await this.record({ type: 'governance_activated', source: 'governance_host', house: this.cwd, session_id: sessionId,
+      actor: { id: 'local-user', kind: 'human' }, surface: 'internal', plan: bound.plan, mechanism_stamp: bound.stamp, activation_id: bound.activation_id,
+      mechanisms: [...bound.bindings].map(([id,b]) => [id,b.revision,b.operations,b.configuration_digest || null]) });
+    this.#governance.set(sessionId, bound);
+    return bound.stamp;
+  }
+  governance(sessionId) { const value = this.#governance.get(sessionId); return value ? { plan_hash: value.plan.plan_hash, mechanism_stamp: value.stamp, activation_id: value.activation_id } : null; }
+  retireGovernance(sessionId) { this.#governance.delete(sessionId); }
+  async govern(context, op, input, state) {
+    const bound = this.#governance.get(context.sessionId);
+    if (!bound) return;
+    for (const gate of bound.plan.gates.filter(gate => gate.tier === 'enforced' && (gate.operations.includes('*') || gate.operations.includes(op.contract.name)))) {
+      const view = immutable(structuredClone({ operation: op.contract.name, input, actor: context.actor, surface: context.surface,
+        session_id: context.sessionId, invocation_id: state.id, parent_invocation_id: state.parentId,
+        parent_operation: state.parentOperation, contract_digest: op.digest }));
+      let result; try { result = await bound.bindings.get(gate.id).check(view); }
+      catch { result = { allowed: false, reason: 'Governance mechanism unavailable.' }; }
+      const allowed = result === true || result?.allowed === true;
+      await this.emit(context, { type: 'governance_decision', invocation_id: state.id, operation: op.contract.name,
+        arguments_digest: digest(input),
+        governance_plan_hash: bound.plan.plan_hash, mechanism_stamp: bound.stamp, governance_activation_id: bound.activation_id, gate_id: gate.id, decision_id: gate.decision_id,
+        allowed, reason: result?.reason || (allowed ? 'Bound mechanism passed.' : 'Bound mechanism refused.') });
+      if (!allowed) throw Object.assign(new Error(`Governance refused ${op.contract.name}: ${result?.reason || gate.id}`), { code: 'GOVERNANCE_REFUSED' });
+    }
+  }
+  async fact(context, event) { const row = { ...event, house: this.cwd, session_id: context.sessionId, actor: context.actor, surface: context.surface }; await this.record(row, context); return row; }
+  // Bind identities in host code, never in model-supplied operation arguments.
+  bind({ actor, sessionId, policy, surface = 'agent', onPermission = async () => {}, record, resources = {}, allowed, select = () => true, frontier, capture, unavailable }) {
+    if (!actor?.id || !['human', 'agent', 'subagent'].includes(actor.kind) || !policy?.authorize) throw new Error('The house requires a host-bound actor and policy.');
+    const context = Object.freeze({ actor: Object.freeze(structuredClone(actor)), get sessionId() { return typeof sessionId === 'function' ? sessionId() : sessionId; }, policy, surface, onPermission, record, resources, frontier, unavailable });
+    const names = allowed ? new Set(allowed) : null;
+    const snapshot = () => new Map([...this.registry.snapshot(context)].filter(([name]) => (!names || names.has(name)) && select(name,context)));
+    const frame = () => Object.freeze({ ...context, surfaceStamp: capture?.(context) });
+    const execute = (catalog, name, input, options = {}, captured = frame()) => this.execute(captured, catalog, name, input, options);
+    return {
+      setContext: value => policy.setContext?.(value), getMode: () => policy.mode,
+      execute: (name, input, options) => execute(snapshot(), name, input, options),
+      snapshot: () => { const catalog = snapshot(), captured = frame(); return { setContext: value => policy.setContext?.(value), execute: (name, input, options) => execute(catalog, name, input, options, captured), definitions: () => [...catalog.values()].map(op => op.tool()), catalogue: () => [...catalog.values()].map(op => ({ ...op.contract, contract_digest: op.digest })) }; },
+      definitions: () => [...snapshot().values()].map(op => op.tool()),
+      catalogue: () => [...snapshot().values()].map(op => ({ ...op.contract, contract_digest: op.digest })),
+      judge: (name, input, options) => {const active=this.#context.getStore()?.context;return this.judge(active && active.sessionId===context.sessionId && active.actor.id===context.actor.id && active.actor.kind===context.actor.kind ? active : context,name,input,options);},
+    };
+  }
+  async emit(context, event) {
+    const copy = structuredClone(event), row = { ...copy, house: this.cwd, session_id: context.sessionId, actor: context.actor, surface: context.surface };
+    await (context.record ? context.record(row) : this.record(row, context));
+    for (const listener of [...this.#observers.values()]) {
+      try { Promise.resolve(listener(immutable(structuredClone(row)))).catch(() => {}); } catch {}
+    }
+  }
+  async guardOperation(context, op, args, signal) {
+    const view = immutable(structuredClone({ operation: op.contract.name, contract_digest: op.digest, actor: context.actor, session_id: context.sessionId, surface: context.surface, input: args }));
+    for (const { id, check } of this.#guards.values()) {
+      signal?.throwIfAborted(); let result;
+      try { result = await check(view); }
+      catch (error) { if (signal?.aborted) throw error; result = { allowed: false, reason: `Guard unavailable: ${error.message}` }; }
+      if (result === false || result?.allowed === false) {
+        await this.emit(context, { type: 'house_decision', invocation_id: this.#context.getStore()?.id, contract_digest: op.digest, operation: op.contract.name, arguments_digest: digest(args), allowed: false, reason: result?.reason || `Additional veto from ${id}`, source: 'plugin_guard', guard: id, mode: context.policy.mode });
+        throw Object.assign(new Error(`Permission denied: ${result?.reason || `additional veto from ${id}`}`), { code: 'HOUSE_GUARD' });
+      }
+    }
+  }
+  authority(context) { return digest({ mode: context.policy.mode, allowed: [...(context.policy.allowed || [])].sort(), denied: [...(context.policy.denied || [])].sort(), intentions: context.policy.context?.intentions, governance: this.governance(context.sessionId) }); }
+  async judge(context, name, input, { signal } = {}) {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      signal?.throwIfAborted(); const before = this.authority(context);
+      const decision = await context.policy.authorize(name, structuredClone(input), { signal, onWaiting: event => this.emit(context, { ...event, invocation_id: this.#context.getStore()?.id ?? null, parent_invocation_id: this.#context.getStore()?.parentId ?? null, operation: name, arguments_digest: digest(input) }) });
+      if (before !== this.authority(context)) continue;
+      const result = await this.#decision(context, name, input, signal, decision);
+      if (before === this.authority(context)) { const active = this.#context.getStore(); if (active) active.authorityStamp = before; return result; }
+    }
+    throw Object.assign(new Error('Permission denied: authority changed during judgment; propose again.'), { code: 'HOUSE_AUTHORITY_CHANGED' });
+  }
+  async #decision(context, name, input, signal, decision) {
+    await context.onPermission({ name, input, ...decision });
+    const active = this.#context.getStore();
+    await this.emit(context, { type: 'house_decision', invocation_id: active?.id ?? null, contract_digest: active?.contractDigest ?? null, operation: name, arguments_digest: digest(input), allowed: Boolean(decision.allowed), reason: decision.reason, mode: context.policy.mode });
+    if (active) active.decisions.push(Boolean(decision.allowed));
+    if (!decision.allowed) { const error = new Error(`Permission denied: ${name}: ${decision.reason}`); error.code = 'HOUSE_REFUSED'; throw error; }
+    signal?.throwIfAborted(); return decision;
+  }
+  async execute(context, catalog, name, input, { signal, callId, work, beforeEffect, modelProposed = false } = {}) {
+    const id = randomUUID(), op = catalog.get(name), candidateParent = this.#context.getStore();
+    // Invocation nesting belongs to one book and actor. A child session has its
+    // own execution roots; its durable run retains delegation genealogy.
+    const parent = candidateParent && candidateParent.context.sessionId === context.sessionId && candidateParent.context.actor.id === context.actor.id && candidateParent.context.actor.kind === context.actor.kind ? candidateParent : undefined;
+    const governance = this.governance(context.sessionId);
+    const base = { invocation_id: id, parent_invocation_id: parent?.id ?? null, call_id: callId ?? null, operation: name, execution_process:processIdentity, contract_digest: op?.digest ?? null, origin: op?.contract.origin ?? null, ...(governance ? { governance_plan_hash: governance.plan_hash, mechanism_stamp: governance.mechanism_stamp, governance_activation_id: governance.activation_id } : {}), ...(work ? { work: structuredClone(work) } : {}) };
+    context = Object.freeze({ ...context });
+    const state = { id, parentId: parent?.id ?? null, parentOperation: parent?.operation ?? null, operation: name, decisions: [], observations: [], context, contractDigest: op?.digest }; let entered = false, args;
+    try {
+      args = structuredClone(input); base.arguments_digest = digest(args);
+      const contractKey = `${context.sessionId}:${op?.digest}`;
+      if (op && !this.#contracts.has(contractKey)) { await this.emit(context, { type: 'house_contract', contract_digest: op.digest, contract: op.contract }); this.#contracts.add(contractKey); }
+      await this.emit(context, { type: 'house_proposal', ...base });
+      if (!op && this.registry.get(name)?.visible(context)) {
+        const recovery = context.unavailable?.(name,context);
+        if (recovery) throw Object.assign(new Error(recovery.message), {code:recovery.code});
+      }
+      if (!op || !op.visible(context)) throw Object.assign(new Error(`Permission denied: operation ${name} is unavailable to this actor/surface.${context.actor.kind === 'subagent' ? ' Recursive delegation and tools outside the scope are disabled.' : ''}`), { code: 'HOUSE_REFUSED' });
+      if (this.registry.get(name) !== op) throw Object.assign(new Error('The operation contract changed after this proposal; it was not executed.'), { code: 'HOUSE_STALE' });
+      op.validate(args); signal?.throwIfAborted();
+      if (modelProposed && name === 'Edit' && args.old_string === args.new_string) throw Object.assign(new Error('Edit has no changes: old_string and new_string are identical. It was not executed or sent to the classifier; skip this step or propose a real correction.'), { code: 'MODEL_NO_CHANGE' });
+      if (modelProposed && ((name === 'Write' && args.content.length > 6000) || (name === 'Edit' && (args.old_string.length > 3000 || args.new_string.length > 6000)))) throw Object.assign(new Error('File proposal is too large for one model step. Use a focused Edit (old_string <=3000, new_string <=6000), or WorkDraft append with a stable part_id followed by publish. The edit was not executed.'), {code:'MODEL_STEP_TOO_LARGE'});
+      return await this.#context.run(state, async () => {
+        if((op.contract.steps || op.contract.permission!==name) && context.policy.denied?.has(name))await this.#decision(context,name,args,signal,{allowed:false,reason:'Explicit operation denial; composition and aliases cannot widen authority.'});
+        if (op.contract.permission === null) await this.#decision(context, name, args, signal, { allowed: !context.policy.denied?.has(name), reason: 'Explicit user control; does not grant authority to the model.' });
+        else if (!op.contract.steps) await this.judge(context, op.contract.permission, args, { signal });
+        if (op.contract.permission !== null) await this.guardOperation(context, op, args, signal);
+        await this.govern(context, op, args, state);
+        if (beforeEffect) await beforeEffect();
+        // Permission callbacks may reload the catalogue. Revalidate at the effect frontier.
+        if (this.registry.get(name) !== op) throw Object.assign(new Error('The contract changed during judgment; it was not executed.'), { code: 'HOUSE_STALE' });
+        signal?.throwIfAborted(); await this.emit(context, { type: 'house_started', ...base });
+        this.#active.add(id);
+        signal?.throwIfAborted();
+        if (this.registry.get(name) !== op) throw Object.assign(new Error('The contract changed before the effect; it was not executed.'), { code: 'HOUSE_STALE' });
+        if (!op.contract.steps && op.contract.permission !== null && state.authorityStamp !== this.authority(context)) throw Object.assign(new Error('Permission denied: authority changed before the effect.'), { code: 'HOUSE_AUTHORITY_CHANGED' });
+        if (beforeEffect) await beforeEffect(); signal?.throwIfAborted();
+        // A work-state check can await persistence. Contracts and authority must
+        // still match after that await, immediately before entering the handler.
+        if (this.registry.get(name) !== op) throw Object.assign(new Error('The contract changed before the effect; it was not executed.'), { code: 'HOUSE_STALE' });
+        if (!op.contract.steps && op.contract.permission !== null && state.authorityStamp !== this.authority(context)) throw Object.assign(new Error('Permission denied: authority changed before the effect.'), { code: 'HOUSE_AUTHORITY_CHANGED' });
+        if (context.frontier && await context.frontier(name, context) === false) throw Object.assign(new Error('Permission denied: the tool lease changed before the effect.'), { code: 'HOUSE_SURFACE_CHANGED' });
+        signal?.throwIfAborted();
+        if (this.registry.get(name) !== op) throw Object.assign(new Error('The contract changed before the effect; it was not executed.'), { code: 'HOUSE_STALE' });
+        if (!op.contract.steps && op.contract.permission !== null && state.authorityStamp !== this.authority(context)) throw Object.assign(new Error('Permission denied: authority changed before the effect.'), { code: 'HOUSE_AUTHORITY_CHANGED' });
+        if (digest(governance) !== digest(this.governance(context.sessionId))) throw Object.assign(new Error('Governance changed before the effect; propose again.'), { code: 'HOUSE_AUTHORITY_CHANGED' });
+        entered = true;
+        const output = await op.run(args, { ...context.resources, invocation_id:id, sessionId: context.sessionId, actor: context.actor, mode: context.policy.mode, catalogue: [...catalog.values()].map(item => ({ ...item.contract, contract_digest: item.digest })), signal,
+          recordWork: event => this.emit(context, { ...event, invocation_id: id }),
+          invoke: (operation, arguments_, options) => this.execute(context, catalog, operation, arguments_, options),
+          observe: fact => state.observations.push(structuredClone(fact)) });
+        if (state.observations.some(fact => fact.kind === 'file_write' && fact.matches_requested === false)) throw Object.assign(new Error('The written surface does not match the requested result; inspect before repeating.'), { code: 'HOUSE_POSTCONDITION' });
+        op.validateOutput(output);
+        const text = typeof output === 'string' ? output : JSON.stringify(output) ?? '(no output)';
+        await this.emit(context, { type: 'house_receipt', ...base, status: 'returned', disposition: state.decisions.includes(false) ? 'basket' : 'serve', judgment_scope: 'house_execution', authority: op.contract.permission === null ? 'human_control' : op.contract.steps ? (state.decisions.includes(false) ? 'step_refused' : state.decisions.length ? 'steps_judged' : 'no_permission_step') : 'allowed', permission_steps: { allowed: state.decisions.filter(Boolean).length, refused: state.decisions.filter(value => !value).length }, output_digest: digest(text), output: text, output_truncated: false, observations: state.observations, effects: op.contract.effects, asked: 'unjudged' });
+        return text;
+      });
+    } catch (error) {
+      await this.emit(context, { type: 'house_receipt', ...base, status: entered ? 'failed' : 'refused', disposition: ['HOUSE_STALE', 'HOUSE_POSTCONDITION', 'HOUSE_AUTHORITY_CHANGED', 'HOUSE_SURFACE_CHANGED'].includes(error.code) ? 'repeat' : 'basket', judgment_scope: 'house_execution', code: error.code, error: error.message, effects_observed: entered ? 'unknown_or_partial' : 'none', observations: state.observations, asked: 'unjudged' });
+      throw error;
+    } finally { this.#active.delete(id); }
+  }
+}
+
+// Derive closure from executor events, never from tool JSON saying verified=true.
+export function houseSnapshot(rows, { active = new Set(), exclude } = {}) {
+  const started = new Map(), receipts = [];
+  for (const row of rows) {
+    if (row.invocation_id === exclude && exclude) continue;
+    if (row.type === 'house_started') started.set(row.invocation_id, row);
+    if (row.type === 'house_receipt') { receipts.push(row); started.delete(row.invocation_id); }
+  }
+  const counts = Object.fromEntries(['returned', 'failed', 'refused'].map(status => [status, receipts.filter(r => r.status === status).length]));
+  const permissionRefusals = rows.filter(row => row.type === 'house_decision' && !row.allowed).length;
+  const unresolved = [...started.keys()].filter(id => !active.has(id)), running = [...started.keys()].filter(id => active.has(id));
+  return { scope: 'house_execution', asked: 'unjudged', status: unresolved.length ? 'interrupted' : running.length ? 'running' : counts.failed || counts.refused || permissionRefusals ? 'needs_review' : receipts.length ? 'recorded' : 'no_receipts', counts, permission_refusals: permissionRefusals, unresolved, running, receipts: receipts.slice(-40).map(({ output, ...row }) => row), receipt_total: receipts.length, integrity: 'local_journal_not_signed' };
+}