@nullsquare/agent-authority 0.4.4 → 0.4.5

package/src/task-lease.js

@@ -24,6 +24,19 @@ function sameValue(a, b) {
   return hashObject(a) === hashObject(b);
 }
 
+function requiredString(value, code, message) {
+  if (typeof value !== 'string' || value.trim() === '') throw authorityError(code, message);
+  return value;
+}
+
+function validDate(value, code, message, { nullable = false } = {}) {
+  if ((value === null || value === undefined) && nullable) return value ?? null;
+  if (typeof value !== 'string' || Number.isNaN(new Date(value).getTime())) {
+    throw authorityError(code, message);
+  }
+  return value;
+}
+
 function validateBinding(binding) {
   if (!binding?.service) throw new Error('binding.service is required');
   if (!binding?.action) throw new Error('binding.action is required');
@@ -37,6 +50,201 @@ function validateBinding(binding) {
   };
 }
 
+function validateSnapshotFact(fact, leaseId) {
+  if (!fact || typeof fact !== 'object' || Array.isArray(fact)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease fact must be an object');
+  }
+  const factId = requiredString(
+    fact.fact_id,
+    'task_lease_snapshot_invalid',
+    'task lease fact_id is required'
+  );
+  if (fact.value === undefined) {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} is missing its value`);
+  }
+  requiredString(
+    fact.created_at,
+    'task_lease_snapshot_invalid',
+    `task lease fact ${factId} is missing created_at`
+  );
+  validDate(
+    fact.created_at,
+    'task_lease_snapshot_invalid',
+    `task lease fact ${factId} created_at is invalid`
+  );
+
+  const provenance = fact.provenance;
+  if (!provenance || typeof provenance !== 'object' || Array.isArray(provenance)) {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} is missing provenance`);
+  }
+
+  if (provenance.type === 'root') {
+    requiredString(
+      provenance.source,
+      'task_lease_snapshot_invalid',
+      `root fact ${factId} is missing its authority source`
+    );
+  } else if (provenance.type === 'derived') {
+    if (!['host-trusted', 'execution-evidence-v1'].includes(provenance.derivation_mode)) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} has an unsupported derivation mode`);
+    }
+    if (!Array.isArray(provenance.from) || provenance.from.length === 0) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} must retain parent lineage`);
+    }
+    for (const parentId of provenance.from) {
+      requiredString(
+        parentId,
+        'task_lease_snapshot_invalid',
+        `derived fact ${factId} contains an invalid parent fact id`
+      );
+    }
+    if (provenance.task_lease_id !== leaseId) {
+      throw authorityError('task_lease_snapshot_invalid', `derived fact ${factId} belongs to another task lease`);
+    }
+    for (const [field, label] of [
+      ['receipt_id', 'receipt id'],
+      ['receipt_hash', 'receipt hash'],
+      ['source_service', 'source service'],
+      ['source_action', 'source action'],
+      ['source_request_hash', 'source request hash'],
+      ['selector', 'selector']
+    ]) {
+      requiredString(
+        provenance[field],
+        'task_lease_snapshot_invalid',
+        `derived fact ${factId} is missing ${label}`
+      );
+    }
+
+    if (provenance.derivation_mode === 'execution-evidence-v1') {
+      for (const [field, label] of [
+        ['extractor_id', 'extractor id'],
+        ['source_output_hash', 'source output hash'],
+        ['execution_evidence_hash', 'execution evidence hash']
+      ]) {
+        requiredString(
+          provenance[field],
+          'task_lease_snapshot_invalid',
+          `evidence-derived fact ${factId} is missing ${label}`
+        );
+      }
+    }
+  } else {
+    throw authorityError('task_lease_snapshot_invalid', `task lease fact ${factId} has unknown provenance type`);
+  }
+
+  return structuredClone({
+    fact_id: factId,
+    kind: fact.kind ?? 'opaque',
+    value: fact.value,
+    provenance,
+    created_at: fact.created_at
+  });
+}
+
+function validateFactGraph(facts) {
+  const byId = new Map();
+  for (const fact of facts) {
+    if (byId.has(fact.fact_id)) {
+      throw authorityError('task_lease_snapshot_invalid', `duplicate authority fact ${fact.fact_id}`);
+    }
+    byId.set(fact.fact_id, fact);
+  }
+
+  for (const fact of facts) {
+    if (fact.provenance.type !== 'derived') continue;
+    for (const parentId of fact.provenance.from) {
+      if (!byId.has(parentId)) {
+        throw authorityError(
+          'task_lease_snapshot_invalid',
+          `derived fact ${fact.fact_id} references missing parent ${parentId}`
+        );
+      }
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(factId) {
+    if (visited.has(factId)) return;
+    if (visiting.has(factId)) {
+      throw authorityError('task_lease_snapshot_invalid', 'task lease fact lineage contains a cycle');
+    }
+    visiting.add(factId);
+    const fact = byId.get(factId);
+    if (fact?.provenance.type === 'derived') {
+      for (const parentId of fact.provenance.from) visit(parentId);
+    }
+    visiting.delete(factId);
+    visited.add(factId);
+  }
+  for (const factId of byId.keys()) visit(factId);
+  return byId;
+}
+
+function validateSnapshot(mission, snapshot) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot must be an object');
+  }
+  if (snapshot.version !== '0.1') {
+    throw authorityError('task_lease_snapshot_version_unsupported', `unsupported task lease snapshot version ${snapshot.version}`);
+  }
+
+  const leaseId = requiredString(
+    snapshot.lease_id,
+    'task_lease_snapshot_invalid',
+    'task lease snapshot lease_id is required'
+  );
+  if (snapshot.mission_id !== mission.mission_id) {
+    throw authorityError('task_lease_snapshot_mission_mismatch', 'task lease snapshot belongs to another mission');
+  }
+  if (snapshot.principal_id !== mission.principal.id || snapshot.agent_id !== mission.agent.id) {
+    throw authorityError('task_lease_snapshot_mission_mismatch', 'task lease snapshot principal or agent does not match mission');
+  }
+  if (snapshot.mission_hash !== hashObject(mission)) {
+    throw authorityError(
+      'task_lease_snapshot_mission_mismatch',
+      'task lease snapshot mission hash does not match the exact recovery mission'
+    );
+  }
+
+  if (!['active', 'completed'].includes(snapshot.status)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot status must be active or completed');
+  }
+  validDate(snapshot.created_at, 'task_lease_snapshot_invalid', 'task lease snapshot created_at is invalid');
+  validDate(snapshot.expires_at, 'task_lease_snapshot_invalid', 'task lease snapshot expires_at is invalid', { nullable: true });
+  validDate(snapshot.completed_at, 'task_lease_snapshot_invalid', 'task lease snapshot completed_at is invalid', { nullable: true });
+
+  if (snapshot.status === 'active' && snapshot.completed_at !== null) {
+    throw authorityError('task_lease_snapshot_invalid', 'active task lease snapshot cannot contain completed_at');
+  }
+  if (snapshot.status === 'completed' && snapshot.completed_at === null) {
+    throw authorityError('task_lease_snapshot_invalid', 'completed task lease snapshot must contain completed_at');
+  }
+  if (snapshot.completion_reason !== null && typeof snapshot.completion_reason !== 'string') {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease completion_reason must be a string or null');
+  }
+  if (!Array.isArray(snapshot.bindings) || !Array.isArray(snapshot.facts)) {
+    throw authorityError('task_lease_snapshot_invalid', 'task lease snapshot bindings and facts must be arrays');
+  }
+
+  const bindings = snapshot.bindings.map(validateBinding);
+  const facts = snapshot.facts.map((fact) => validateSnapshotFact(fact, leaseId));
+  const byId = validateFactGraph(facts);
+
+  return {
+    lease_id: leaseId,
+    request: structuredClone(snapshot.request),
+    created_at: snapshot.created_at,
+    expires_at: snapshot.expires_at,
+    status: snapshot.status,
+    completed_at: snapshot.completed_at,
+    completion_reason: snapshot.completion_reason,
+    bindings,
+    facts: byId
+  };
+}
+
 function taskReceipt(lease, request, result) {
   const base = createReceipt({ mission: lease.mission, request, result });
   const { receipt_hash: _oldHash, ...unsigned } = base;
@@ -82,6 +290,35 @@ export class TaskLease {
     for (const root of roots) this.addRoot(root);
   }
 
+  /**
+   * Restore an already-authenticated Task Lease snapshot.
+   *
+   * This method validates state shape, exact mission identity and lineage but
+   * does not authenticate where the snapshot came from. Persisted authority
+   * should be loaded through an authenticated store such as
+   * JsonFileTaskLeaseStore rather than from arbitrary caller-controlled JSON.
+   */
+  static restore({ mission, snapshot } = {}) {
+    const resolvedMission = assertMission(mission);
+    const state = validateSnapshot(resolvedMission, snapshot);
+    const lease = new TaskLease({
+      mission: resolvedMission,
+      lease_id: state.lease_id,
+      request: state.request,
+      roots: [],
+      bindings: state.bindings,
+      expires_at: state.expires_at,
+      created_at: state.created_at
+    });
+    lease.status = state.status;
+    lease.completed_at = state.completed_at;
+    lease.completion_reason = state.completion_reason;
+    lease.facts = new Map(
+      [...state.facts.entries()].map(([factId, fact]) => [factId, structuredClone(fact)])
+    );
+    return lease;
+  }
+
   addRoot({ fact_id, kind = 'opaque', value, source = 'human' } = {}) {
     if (!fact_id) throw new Error('root fact_id is required');
     if (value === undefined) throw new Error('root value is required');
@@ -245,9 +482,10 @@ export class TaskLease {
       version: '0.1',
       lease_id: this.lease_id,
       mission_id: this.mission.mission_id,
+      mission_hash: hashObject(this.mission),
       principal_id: this.mission.principal.id,
       agent_id: this.mission.agent.id,
-      request: this.request,
+      request: structuredClone(this.request),
       status: this.status,
       created_at: this.created_at,
       expires_at: this.expires_at,
@@ -341,3 +579,7 @@ export class TaskLease {
 export function createTaskLease(options) {
   return new TaskLease(options);
 }
+
+export function restoreTaskLease(options) {
+  return TaskLease.restore(options);
+}