@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/process-data/store.ts

@@ -9,6 +9,9 @@ import type {
   RepairAction,
   RestCollectionEvidence,
   SnapshotManifest,
+  SnapshotManifestV1,
+  SnapshotManifestV2,
+  SnapshotOperations,
   StoredObjectEvidence
 } from './types.ts';
 
@@ -28,6 +31,18 @@ type PublishInput = {
   repairs: RepairAction[];
 };
 
+type PublishV2Input = PublishInput & {
+  snapshotKind: 'base' | 'delta';
+  parentSnapshotId: string | null;
+  checkpointBefore: string | null;
+  watermark: string;
+  window: SnapshotManifestV2['window'];
+  observation: SnapshotManifestV2['observation'];
+  coverage: SnapshotManifestV2['coverage'];
+  reconciliation: 'incremental' | 'full';
+  operations: SnapshotOperations;
+};
+
 type VerificationResult = {
   ok: boolean;
   snapshotId: string;
@@ -82,12 +97,32 @@ function canonicalJsonBytes(value: JsonValue | unknown): Buffer {
 }
 
 function ensurePrivateDirectory(directory: string): void {
-  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') fs.chmodSync(directory, 0o700);
+  const missing: string[] = [];
+  let current = path.resolve(directory);
+  while (!fs.existsSync(current)) {
+    missing.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) throw new Error(`cannot create directory tree: ${directory}`);
+    current = parent;
+  }
+  for (const target of missing.reverse()) {
+    fs.mkdirSync(target, { mode: 0o700 });
+    if (process.platform !== 'win32') fs.chmodSync(target, 0o700);
+    fsyncDirectory(path.dirname(target));
+  }
+}
+
+function fsyncDirectory(directory: string): void {
+  if (process.platform === 'win32') return;
+  const fd = fs.openSync(directory, 'r');
+  try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
 }
 
 function writeExclusive(filePath: string, bytes: Buffer): boolean {
-  ensurePrivateDirectory(path.dirname(filePath));
+  const directory = path.dirname(filePath);
+  const directoryExisted = fs.existsSync(directory);
+  ensurePrivateDirectory(directory);
+  if (!directoryExisted) fsyncDirectory(path.dirname(directory));
   try {
     const fd = fs.openSync(filePath, 'wx', 0o600);
     try {
@@ -96,6 +131,7 @@ function writeExclusive(filePath: string, bytes: Buffer): boolean {
     } finally {
       fs.closeSync(fd);
     }
+    fsyncDirectory(directory);
     return true;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
@@ -133,11 +169,17 @@ function jsonLine(value: JsonValue | unknown): string {
 }
 
 function writePrivateFile(filePath: string, content: string | Buffer): void {
-  fs.writeFileSync(filePath, content, { mode: 0o600, flag: 'wx' });
+  const fd = fs.openSync(filePath, 'wx', 0o600);
+  try {
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
   if (process.platform !== 'win32') fs.chmodSync(filePath, 0o600);
 }
 
-function manifestDigest(manifest: Omit<SnapshotManifest, 'manifestSha256'>): string {
+function manifestDigest(manifest: Record<string, unknown>): string {
   return sha256(canonicalJsonBytes(manifest));
 }
 
@@ -163,7 +205,7 @@ function publishSnapshot(root: string, input: PublishInput): { snapshotId: strin
   const identityDigest = sha256(canonicalJsonBytes(identity));
   const stamp = input.observedTo.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
   const snapshotId = `${stamp}-${identityDigest.slice(0, 12)}`;
-  const partialManifest: Omit<SnapshotManifest, 'manifestSha256'> = {
+  const partialManifest: Omit<SnapshotManifestV1, 'manifestSha256'> = {
     schema: 'raw-manifest/v1',
     snapshotId,
     ...identity,
@@ -200,9 +242,79 @@ function publishSnapshot(root: string, input: PublishInput): { snapshotId: strin
       const existing = fs.readFileSync(path.join(destination, 'manifest.json'), 'utf8');
       if (existing !== jsonLine(manifest)) throw new Error(`snapshot collision: ${snapshotId}`);
       fs.rmSync(staging, { recursive: true, force: true });
+      fsyncDirectory(stagingRoot);
       return { snapshotId, path: destination, created: false };
     }
+    fsyncDirectory(staging);
     fs.renameSync(staging, destination);
+    fsyncDirectory(stagingRoot);
+    fsyncDirectory(path.dirname(destination));
+    return { snapshotId, path: destination, created: true };
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function publishSnapshotV2(root: string, input: PublishV2Input): { snapshotId: string; path: string; created: boolean } {
+  ensurePrivateDirectory(root);
+  ensurePrivateDirectory(path.join(root, 'repairs'));
+  const date = new Date(input.observedTo);
+  if (!Number.isFinite(date.getTime())) throw new Error('observedTo must be an ISO timestamp');
+  const identity = {
+    scope: 'github' as const,
+    repository: input.repository,
+    observedFrom: input.observedFrom,
+    observedTo: input.observedTo,
+    objects: input.objects,
+    endpoints: input.endpoints,
+    excerptsEnabled: false,
+    dispositionCounts: dispositionCounts(input.objects),
+    recordCount: input.records.length,
+    findingCount: input.quality.length,
+    repairCount: input.repairs.length,
+    snapshotKind: input.snapshotKind,
+    parentSnapshotId: input.parentSnapshotId,
+    checkpointBefore: input.checkpointBefore,
+    watermark: input.watermark,
+    window: input.window,
+    observation: input.observation,
+    coverage: input.coverage,
+    reconciliation: input.reconciliation,
+    operations: input.operations
+  };
+  const snapshotId = `${input.watermark.replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')}-${sha256(canonicalJsonBytes(identity)).slice(0, 12)}`;
+  const partialManifest = {
+    schema: 'raw-manifest/v2' as const,
+    snapshotId,
+    ...identity,
+    observedFrom: input.observedFrom,
+    observedTo: input.observedTo,
+    privacyPolicyVersion: 'process-data-privacy/v1' as const
+  };
+  const manifest: SnapshotManifestV2 = { ...partialManifest, manifestSha256: manifestDigest(partialManifest) };
+  const stagingRoot = path.join(root, '.staging');
+  ensurePrivateDirectory(stagingRoot);
+  const staging = fs.mkdtempSync(path.join(stagingRoot, `${snapshotId}-`));
+  if (process.platform !== 'win32') fs.chmodSync(staging, 0o700);
+  try {
+    writePrivateFile(path.join(staging, 'manifest.json'), jsonLine(manifest));
+    writePrivateFile(path.join(staging, 'normalized.jsonl'), input.records.map((record) => jsonLine({ schema: 'normalized/v2', ...record })).join(''));
+    writePrivateFile(path.join(staging, 'quality.json'), jsonLine({ schema: 'quality/v1', findings: input.quality }));
+    writePrivateFile(path.join(staging, 'repair-manifest.jsonl'), input.repairs.map((repair) => jsonLine({ schema: 'repair/v1', ...repair })).join(''));
+    const destination = path.join(root, 'snapshots', String(date.getUTCFullYear()), String(date.getUTCMonth() + 1).padStart(2, '0'), String(date.getUTCDate()).padStart(2, '0'), snapshotId);
+    ensurePrivateDirectory(path.dirname(destination));
+    if (fs.existsSync(destination)) {
+      const existing = fs.readFileSync(path.join(destination, 'manifest.json'), 'utf8');
+      if (existing !== jsonLine(manifest)) throw new Error(`snapshot collision: ${snapshotId}`);
+      fs.rmSync(staging, { recursive: true, force: true });
+      fsyncDirectory(stagingRoot);
+      return { snapshotId, path: destination, created: false };
+    }
+    fsyncDirectory(staging);
+    fs.renameSync(staging, destination);
+    fsyncDirectory(stagingRoot);
+    fsyncDirectory(path.dirname(destination));
     return { snapshotId, path: destination, created: true };
   } catch (error) {
     fs.rmSync(staging, { recursive: true, force: true });
@@ -226,7 +338,181 @@ function findSnapshot(root: string, snapshotId: string): string | null {
   return null;
 }
 
-function verifySnapshot(root: string, snapshotId: string): VerificationResult {
+function verifyV2Snapshot(root: string, snapshotId: string, snapshotPath: string, manifest: SnapshotManifestV2, seen: Set<string>): VerificationResult {
+  const errors: string[] = [];
+  if (seen.has(snapshotId)) return { ok: false, snapshotId, snapshotPath, errors: ['snapshot lineage cycle detected'], manifest };
+  seen.add(snapshotId);
+  if (manifest.snapshotId !== snapshotId) errors.push('snapshot identity mismatch');
+  if (manifest.scope !== 'github') errors.push('v2 snapshot scope must be github');
+  if (manifest.snapshotKind === 'base' && manifest.parentSnapshotId !== null) errors.push('base snapshot must not have a parent');
+  if (manifest.snapshotKind === 'delta' && !manifest.parentSnapshotId) errors.push('delta snapshot must have a parent');
+  if (manifest.checkpointBefore !== manifest.parentSnapshotId) errors.push('checkpoint and parent lineage mismatch');
+  if (manifest.parentSnapshotId) {
+    const parentPath = findSnapshot(root, manifest.parentSnapshotId);
+    if (!parentPath) errors.push('parent snapshot is missing');
+    else {
+      const parentVerification = verifySnapshot(root, manifest.parentSnapshotId, seen);
+      if (!parentVerification.ok || !parentVerification.manifest) {
+        errors.push(`parent snapshot is invalid: ${parentVerification.errors.join('; ')}`);
+      } else if (parentVerification.manifest.schema !== 'raw-manifest/v2') {
+        errors.push('v2 snapshot parent is not v2');
+      } else {
+        const parent = parentVerification.manifest;
+        if (parent.repository !== manifest.repository) errors.push('parent repository mismatch');
+        if (new Date(parent.watermark).getTime() >= new Date(manifest.watermark).getTime()) errors.push('snapshot watermark is not monotonic');
+      }
+    }
+  }
+  if (manifest.watermark !== manifest.window.toExclusive) errors.push('watermark and window cutoff mismatch');
+  const watermark = new Date(manifest.watermark);
+  const from = manifest.window.fromInclusive ? new Date(manifest.window.fromInclusive) : null;
+  const queryAfter = manifest.window.queryAfter ? new Date(manifest.window.queryAfter) : null;
+  if (!Number.isFinite(watermark.getTime()) || (from && !Number.isFinite(from.getTime())) || (queryAfter && !Number.isFinite(queryAfter.getTime()))) {
+    errors.push('v2 observation window contains an invalid timestamp');
+  }
+  if (from && queryAfter && queryAfter.getTime() !== from.getTime() - 1000) errors.push('queryAfter does not equal watermark minus one second');
+  if (!from && queryAfter) errors.push('base/full window cannot have queryAfter without fromInclusive');
+  const strictSinceEndpoints = manifest.endpoints.filter((endpoint) => endpoint.queryMode === 'strict-since');
+  const expectedQueryAfter = from && Number.isFinite(from.getTime()) ? new Date(from.getTime() - 1000).toISOString() : null;
+  if (manifest.snapshotKind === 'base' && from) errors.push('base snapshot must not have fromInclusive');
+  if (queryAfter && strictSinceEndpoints.length === 0) errors.push('queryAfter requires a strict-since endpoint');
+  if (strictSinceEndpoints.length > 0 && (manifest.snapshotKind !== 'delta' || manifest.reconciliation !== 'incremental')) {
+    errors.push('strict-since is only valid for incremental delta snapshots');
+  }
+  if (strictSinceEndpoints.length > 0 && manifest.window.queryAfter !== expectedQueryAfter) {
+    errors.push('incremental strict-since queryAfter proof is invalid');
+  }
+  if (manifest.coverage.mode !== 'boundary-reread-with-full-reconcile' || manifest.coverage.absoluteCompleteness !== false) errors.push('coverage declaration is invalid');
+  const preflight = new Date(manifest.observation.preflightDate);
+  if (!Number.isFinite(preflight.getTime())) errors.push('preflight Date is invalid');
+  for (const responseDate of manifest.observation.responseDates) {
+    const parsed = new Date(responseDate);
+    if (!Number.isFinite(parsed.getTime()) || parsed.getTime() < preflight.getTime()) errors.push('response Date evidence is invalid');
+  }
+  for (const endpoint of manifest.endpoints) {
+    if (!endpoint.queryMode) errors.push(`endpoint query mode missing: ${endpoint.endpoint}`);
+    if (endpoint.queryMode !== 'strict-since' && endpoint.queryMode !== 'full-enumeration') {
+      errors.push(`endpoint query mode is invalid: ${endpoint.endpoint}`);
+    } else if (endpoint.queryMode === 'strict-since') {
+      if (endpoint.requestedSince !== expectedQueryAfter) errors.push(`endpoint since proof mismatch: ${endpoint.endpoint}`);
+    } else if (endpoint.requestedSince !== undefined) {
+      errors.push(`full-enumeration endpoint has requestedSince: ${endpoint.endpoint}`);
+    }
+    for (const page of endpoint.pages) {
+      if (page.queryMode !== 'strict-since' && page.queryMode !== 'full-enumeration') {
+        errors.push(`page query mode is invalid: ${endpoint.endpoint}#${page.index}`);
+      }
+      if (page.queryMode !== endpoint.queryMode) errors.push(`page query mode mismatch: ${endpoint.endpoint}#${page.index}`);
+      if (endpoint.queryMode === 'strict-since') {
+        if (page.requestedSince !== expectedQueryAfter) errors.push(`page since proof mismatch: ${endpoint.endpoint}#${page.index}`);
+      } else if (page.requestedSince !== undefined) {
+        errors.push(`full-enumeration page has requestedSince: ${endpoint.endpoint}#${page.index}`);
+      }
+      if (page.responseDate && new Date(page.responseDate).getTime() < preflight.getTime()) errors.push(`page Date precedes preflight: ${endpoint.endpoint}#${page.index}`);
+    }
+  }
+  for (const endpoint of manifest.endpoints) {
+    for (const page of endpoint.pages) {
+      const matches = manifest.objects.filter((object) => object.role === 'page-evidence'
+        && object.endpoint === endpoint.endpoint
+        && object.page === page.index
+        && object.sha256 === page.canonicalSha256);
+      if (matches.length !== 1) {
+        errors.push(`page evidence CAS reference is missing or ambiguous: ${endpoint.endpoint}#${page.index}`);
+        continue;
+      }
+      const object = matches[0]!;
+      if (object.queryMode !== 'strict-since' && object.queryMode !== 'full-enumeration') {
+        errors.push(`page evidence query mode is invalid: ${endpoint.endpoint}#${page.index}`);
+      }
+      if (object.queryMode !== page.queryMode
+        || object.requestedSince !== page.requestedSince
+        || object.responseDate !== page.responseDate) {
+        errors.push(`page evidence metadata mismatch: ${endpoint.endpoint}#${page.index}`);
+      }
+      if (endpoint.queryMode === 'strict-since' && object.requestedSince !== expectedQueryAfter) {
+        errors.push(`page evidence since proof mismatch: ${endpoint.endpoint}#${page.index}`);
+      }
+    }
+  }
+  const { manifestSha256, ...partial } = manifest;
+  if (manifestDigest(partial) !== manifestSha256) errors.push('manifest hash mismatch');
+  const checkMode = (target: string, expected: number, label: string) => {
+    if (process.platform === 'win32' || !fs.existsSync(target)) return;
+    const actual = fs.statSync(target).mode & 0o777;
+    if (actual !== expected) errors.push(`${label} permission mismatch: expected ${expected.toString(8)}, got ${actual.toString(8)}`);
+  };
+  checkMode(snapshotPath, 0o700, 'snapshot directory');
+  for (const file of ['manifest.json', 'normalized.jsonl', 'quality.json', 'repair-manifest.jsonl']) checkMode(path.join(snapshotPath, file), 0o600, file);
+  const store = createObjectStore(root);
+  const normalizedEvidence: Array<{ resourceIdentity: string; resourceSha256: string; pageSha256: string }> = [];
+  try {
+    const lines = fs.readFileSync(path.join(snapshotPath, 'normalized.jsonl'), 'utf8').split('\n').filter(Boolean);
+    const ids = new Set<string>();
+    const operationCounts: SnapshotOperations = { upsert: 0, supersede: 0, tombstone: 0, unavailable: 0 };
+    for (const line of lines) {
+      const record = JSON.parse(line) as {
+        schema?: string;
+        recordId?: string;
+        resourceIdentity?: string;
+        sourceSha256?: string;
+        operation?: keyof SnapshotOperations;
+        evidence?: Array<{ resourceIdentity?: string; resourceSha256?: string; pageSha256?: string }>;
+      };
+      if (record.schema !== 'normalized/v2' || typeof record.recordId !== 'string') errors.push('normalized v2 record schema is invalid');
+      if (typeof record.recordId === 'string' && ids.has(record.recordId)) errors.push(`duplicate normalized record: ${record.recordId}`);
+      if (typeof record.recordId === 'string') ids.add(record.recordId);
+      if (!record.operation || !(record.operation in operationCounts)) errors.push('normalized v2 operation is invalid');
+      else operationCounts[record.operation] += 1;
+      if ((record.operation === 'upsert' || record.operation === 'supersede')
+        && (!Array.isArray(record.evidence) || record.evidence.length !== 1)) {
+        errors.push(`resource evidence is required for ${record.operation}: ${record.recordId ?? 'unknown'}`);
+      }
+      for (const evidence of record.evidence ?? []) {
+        if (typeof evidence.resourceIdentity === 'string' && typeof evidence.resourceSha256 === 'string' && typeof evidence.pageSha256 === 'string') {
+          if (record.resourceIdentity !== evidence.resourceIdentity || record.sourceSha256 !== evidence.resourceSha256) {
+            errors.push(`normalized v2 evidence does not match record source: ${record.recordId ?? 'unknown'}`);
+          }
+          normalizedEvidence.push({ resourceIdentity: evidence.resourceIdentity, resourceSha256: evidence.resourceSha256, pageSha256: evidence.pageSha256 });
+        } else {
+          errors.push('normalized v2 evidence reference is invalid');
+        }
+      }
+    }
+    if (lines.length !== manifest.recordCount) errors.push('normalized record count mismatch');
+    if (canonicalJsonBytes(operationCounts).toString('utf8') !== canonicalJsonBytes(manifest.operations).toString('utf8')) errors.push('operation count mismatch');
+    const quality = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'quality.json'), 'utf8')) as { schema?: string; findings?: unknown[] };
+    if (quality.schema !== 'quality/v1' || !Array.isArray(quality.findings)) errors.push('quality schema is invalid');
+    else if (quality.findings.length !== manifest.findingCount) errors.push('quality finding count mismatch');
+    const repairLines = fs.readFileSync(path.join(snapshotPath, 'repair-manifest.jsonl'), 'utf8').split('\n').filter(Boolean);
+    if (repairLines.length !== manifest.repairCount) errors.push('repair manifest count mismatch');
+    for (const line of repairLines) if ((JSON.parse(line) as { schema?: string }).schema !== 'repair/v1') errors.push('repair manifest schema is invalid');
+  } catch {
+    errors.push('snapshot derived files are missing or invalid');
+  }
+  for (const object of manifest.objects) {
+    if (object.role !== 'page-evidence' && object.role !== 'resource') errors.push(`object role is invalid: ${object.sourceIdentity}`);
+    if (object.disposition?.state && object.disposition.state !== 'included') continue;
+    try {
+      const objectPath = store.pathFor(object.sha256);
+      const bytes = fs.readFileSync(objectPath);
+      if (sha256(bytes) !== object.sha256 || bytes.length !== object.bytes) errors.push(`object integrity mismatch: ${object.sourceIdentity}`);
+    } catch {
+      errors.push(`object missing: ${object.sourceIdentity}`);
+    }
+  }
+  for (const evidence of normalizedEvidence) {
+    const resources = manifest.objects.filter((object) => object.role === 'resource'
+      && object.resourceIdentity === evidence.resourceIdentity
+      && object.sha256 === evidence.resourceSha256);
+    const pages = manifest.objects.filter((object) => object.role === 'page-evidence' && object.sha256 === evidence.pageSha256);
+    if (resources.length !== 1) errors.push(`resource evidence reference is missing or ambiguous: ${evidence.resourceIdentity}`);
+    if (pages.length === 0) errors.push(`resource page evidence reference is missing: ${evidence.resourceIdentity}`);
+  }
+  return { ok: errors.length === 0, snapshotId, snapshotPath, errors, manifest };
+}
+
+function verifySnapshot(root: string, snapshotId: string, seen: Set<string> = new Set()): VerificationResult {
   const snapshotPath = findSnapshot(root, snapshotId);
   if (!snapshotPath) return { ok: false, snapshotId, snapshotPath: null, errors: ['snapshot not found'] };
   const errors: string[] = [];
@@ -239,13 +525,19 @@ function verifySnapshot(root: string, snapshotId: string): VerificationResult {
   for (const file of ['manifest.json', 'normalized.jsonl', 'quality.json', 'repair-manifest.jsonl']) {
     checkMode(path.join(snapshotPath, file), 0o600, file);
   }
-  let manifest: SnapshotManifest;
+  let rawManifest: { schema?: unknown };
   try {
-    manifest = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'manifest.json'), 'utf8')) as SnapshotManifest;
+    rawManifest = JSON.parse(fs.readFileSync(path.join(snapshotPath, 'manifest.json'), 'utf8')) as { schema?: unknown };
   } catch {
     return { ok: false, snapshotId, snapshotPath, errors: ['manifest is invalid JSON'] };
   }
-  if (manifest.schema !== 'raw-manifest/v1') errors.push(`unsupported manifest schema: ${manifest.schema}`);
+  if (rawManifest.schema === 'raw-manifest/v2') {
+    return verifyV2Snapshot(root, snapshotId, snapshotPath, rawManifest as SnapshotManifestV2, seen);
+  }
+  if (rawManifest.schema !== 'raw-manifest/v1') {
+    return { ok: false, snapshotId, snapshotPath, errors: [`unsupported manifest schema: ${String(rawManifest.schema)}`] };
+  }
+  const manifest = rawManifest as SnapshotManifestV1;
   if (manifest.snapshotId !== snapshotId) errors.push('snapshot identity mismatch');
   if (typeof manifest.excerptsEnabled !== 'boolean') errors.push('manifest excerpts opt-in is invalid');
   if (!manifest.dispositionCounts || canonicalJsonBytes(manifest.dispositionCounts).toString('utf8') !== canonicalJsonBytes(dispositionCounts(manifest.objects)).toString('utf8')) {
@@ -309,7 +601,8 @@ export {
   createObjectStore,
   findSnapshot,
   publishSnapshot,
+  publishSnapshotV2,
   sha256,
   verifySnapshot
 };
-export type { ObjectStore, ObjectWrite, PublishInput, VerificationResult };
+export type { ObjectStore, ObjectWrite, PublishInput, PublishV2Input, VerificationResult };

package/lib/process-data/types.ts

@@ -7,6 +7,9 @@ type Availability<T> =
 
 type SourceKind = 'local-file' | 'github-rest' | 'operational-report' | 'structured-telemetry';
 
+type CaptureObjectRole = 'page-evidence' | 'resource';
+type EndpointQueryMode = 'strict-since' | 'full-enumeration';
+
 type PrivacyDisposition =
   | { state: 'included' }
   | { state: 'excluded-sensitive'; ruleId: string }
@@ -19,14 +22,37 @@ type CapturedObject = {
   bytes: number;
   content?: string;
   disposition?: PrivacyDisposition;
+  role?: CaptureObjectRole;
+  resourceIdentity?: string;
+  routeNumber?: number;
+  eventTime?: string;
+  endpoint?: string;
+  page?: number;
+  queryMode?: EndpointQueryMode;
+  requestedSince?: string;
+  responseDate?: string;
+  pageSha256?: string;
+  parentIdentity?: string;
 };
 
 type StoredObjectEvidence = Omit<CapturedObject, 'content'>;
 
+type ResourceEvidenceRef = {
+  resourceIdentity: string;
+  resourceSha256: string;
+  pageSha256: string;
+};
+
 type RestPageEvidence = {
   index: number;
   itemCount: number;
   canonicalSha256: string;
+  queryMode?: EndpointQueryMode;
+  requestedSince?: string;
+  responseDate?: string;
+  overlapItemCount?: number;
+  acceptedItemCount?: number;
+  deferredItemCount?: number;
 };
 
 type RestCollectionEvidence = {
@@ -36,6 +62,8 @@ type RestCollectionEvidence = {
   itemCount: number;
   termination: 'short-page';
   pages: RestPageEvidence[];
+  queryMode?: EndpointQueryMode;
+  requestedSince?: string;
 };
 
 type NormalizedKind =
@@ -58,6 +86,10 @@ type NormalizedRecord = {
   binding?: string;
   observedAt?: Availability<string>;
   data?: JsonValue;
+  resourceIdentity?: string;
+  parentIdentity?: string;
+  evidence?: ResourceEvidenceRef[];
+  operation?: 'upsert' | 'supersede' | 'tombstone' | 'unavailable' | 'unchanged';
 };
 
 type QualityCategory =
@@ -88,10 +120,12 @@ type RepairAction = {
   preconditionSha256: string;
 };
 
-type SnapshotManifest = {
+type SnapshotScope = 'all' | 'local' | 'github';
+
+type SnapshotManifestV1 = {
   schema: 'raw-manifest/v1';
   snapshotId: string;
-  scope: 'all' | 'local' | 'github';
+  scope: SnapshotScope;
   repository: string;
   observedFrom: string;
   observedTo: string;
@@ -106,6 +140,80 @@ type SnapshotManifest = {
   manifestSha256: string;
 };
 
+type SnapshotWindow = {
+  fromInclusive: string | null;
+  queryAfter: string | null;
+  toExclusive: string;
+  precision: 'second';
+};
+
+type ObservationEvidence = {
+  cutoffSource: 'github-response-date';
+  preflightDate: string;
+  responseDates: string[];
+};
+
+type CoverageEvidence = {
+  mode: 'boundary-reread-with-full-reconcile';
+  absoluteCompleteness: false;
+};
+
+type SnapshotOperations = {
+  upsert: number;
+  supersede: number;
+  tombstone: number;
+  unavailable: number;
+};
+
+type SnapshotManifestV2 = Omit<SnapshotManifestV1, 'schema' | 'observedFrom' | 'observedTo'> & {
+  schema: 'raw-manifest/v2';
+  snapshotKind: 'base' | 'delta';
+  parentSnapshotId: string | null;
+  checkpointBefore: string | null;
+  watermark: string;
+  window: SnapshotWindow;
+  observation: ObservationEvidence;
+  coverage: CoverageEvidence;
+  reconciliation: 'incremental' | 'full';
+  operations: SnapshotOperations;
+  observedFrom: string;
+  observedTo: string;
+};
+
+type SnapshotManifest = SnapshotManifestV1 | SnapshotManifestV2;
+
+type CheckpointOwner = {
+  schema: 'checkpoint-owner/v1';
+  ownerId: string;
+  pid: number;
+  host: string;
+  processStartToken: string;
+  createdAt: string;
+};
+
+type GitHubCheckpoint = {
+  schema: 'github-checkpoint/v1';
+  repository: string;
+  snapshotId: string;
+  watermark: string;
+  manifestSha256: string;
+  committedAt: string;
+};
+
+type DeltaOperation = {
+  operation: 'upsert' | 'supersede' | 'tombstone' | 'unavailable';
+  resourceIdentity: string;
+  previousSha256?: string;
+  resourceSha256?: string;
+  reason?: string;
+};
+
+type RecoveryReport = {
+  recovered: boolean;
+  quarantined: string[];
+  reason?: string;
+};
+
 type ProcessDataError = {
   code: string;
   message: string;
@@ -127,9 +235,23 @@ export type {
   QualityCategory,
   QualityFinding,
   RepairAction,
+  CaptureObjectRole,
+  CheckpointOwner,
+  CoverageEvidence,
+  DeltaOperation,
+  EndpointQueryMode,
+  GitHubCheckpoint,
+  ObservationEvidence,
+  RecoveryReport,
+  ResourceEvidenceRef,
   RestCollectionEvidence,
   RestPageEvidence,
   SnapshotManifest,
+  SnapshotManifestV1,
+  SnapshotManifestV2,
+  SnapshotOperations,
+  SnapshotScope,
+  SnapshotWindow,
   SourceKind,
   StoredObjectEvidence
 };

package/lib/runtime/agent-runtime.ts

@@ -0,0 +1,76 @@
+import path from 'node:path';
+
+export type AgentRuntimeStore = 'capabilities' | 'lifecycle';
+
+type RuntimeResolutionOptions = Readonly<{
+  repoRoot?: string;
+  env?: NodeJS.ProcessEnv;
+  explicitRoot?: string;
+  client?: string;
+  store?: AgentRuntimeStore;
+}>;
+
+const CLIENT_NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/u;
+
+function runtimeError(code: string, message: string): Error {
+  const error = new Error(`${code}: ${message}`);
+  error.name = code;
+  return error;
+}
+
+function boundControlContext(env: NodeJS.ProcessEnv): boolean {
+  return [
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_EXECUTOR_MANIFEST',
+    'AGENT_INFRA_CODEX_CONTROLLER_CONTEXT'
+  ].some((key) => typeof env[key] === 'string' && env[key]!.length > 0);
+}
+
+function clientNamespace(client: string): string {
+  if (!CLIENT_NAMESPACE.test(client)) {
+    throw runtimeError('AGENT_INFRA_RUNTIME_CLIENT_INVALID', `invalid runtime client namespace '${client}'`);
+  }
+  return client;
+}
+
+export function resolveAgentRuntimeRoot(options: Readonly<{
+  repoRoot?: string;
+  env?: NodeJS.ProcessEnv;
+}> = {}): string {
+  const env = options.env ?? process.env;
+  const configured = env.AGENT_INFRA_RUNTIME_DIR;
+  if (configured !== undefined && configured.length > 0) {
+    if (!path.isAbsolute(configured)) {
+      throw runtimeError('AGENT_INFRA_RUNTIME_DIR_INVALID', 'runtime directory must be absolute');
+    }
+    return path.resolve(configured);
+  }
+  if (boundControlContext(env)) {
+    throw runtimeError(
+      'AGENT_INFRA_RUNTIME_DIR_REQUIRED',
+      'task-bound control context requires AGENT_INFRA_RUNTIME_DIR'
+    );
+  }
+  return path.join(path.resolve(options.repoRoot ?? process.cwd()), '.agents', 'workspace', '.runtime');
+}
+
+export function resolveAgentRuntimeStoreRoot(options: RuntimeResolutionOptions = {}): string {
+  const client = clientNamespace(options.client ?? 'codex');
+  if (options.explicitRoot) return path.resolve(options.explicitRoot);
+  const env = options.env ?? process.env;
+  const runtimeRoot = resolveAgentRuntimeRoot({ repoRoot: options.repoRoot, env });
+  if (env.AGENT_INFRA_RUNTIME_DIR) {
+    if (!options.store) {
+      throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required for task-bound runtime');
+    }
+    return path.join(runtimeRoot, 'clients', client, options.store);
+  }
+  if (client === 'codex' && options.store) {
+    return path.join(runtimeRoot, `codex-${options.store}`);
+  }
+  if (!options.store) {
+    throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required');
+  }
+  return path.join(runtimeRoot, 'clients', client, options.store);
+}