Closes #206: harden portable recovery contract

Synchronize recovery documentation with the current portable export layout and record the separate artifact-binary backup-proof boundary.

Author: alexeygrigorev

backend/src/export/archive.ts

@@ -64,6 +64,7 @@ interface RestoreEvidenceReport {
   evidence_timestamp: string;
   smoke_check_checklist: Array<{ check: string; result: 'passed' | 'not_run' }>;
   production_write_gate: string;
+  artifact_binary_backup_proof: string;
 }
 
 interface RestoreEvidenceResult {
@@ -110,6 +111,8 @@ const RESTORE_SMOKE_CHECKS = [
   'List files for task',
   'Export target data and compare counts',
 ];
+const ARTIFACT_BINARY_BACKUP_PROOF =
+  'Not performed or verified by this drill; external artifact-binary backup proof remains the separate privately retained responsibility of the authorized artifact-storage operator.';
 
 function normalizeRestoreTarget(targetEnvironment: string): string {
   return targetEnvironment.trim().replace(/[A-Z]/g, (character) =>
@@ -560,6 +563,7 @@ async function writeRestoreEvidence(options: RestoreEvidenceOptions): Promise<Re
       result: options.smokeChecksPassed ? 'passed' : 'not_run',
     })),
     production_write_gate: 'No restore/import/write action is performed by this drill. Production writes require a separate human-approved command.',
+    artifact_binary_backup_proof: ARTIFACT_BINARY_BACKUP_PROOF,
   };
   const evidencePath = path.join(options.outputDir, `restore-evidence-${timestamp.replace(/[:.]/g, '-')}.json`);
   await fs.writeFile(evidencePath, JSON.stringify(report, null, 2) + '\n', 'utf8');

backend/tests/export-archive.test.ts

@@ -186,6 +186,14 @@ describe('offsite portable export archives', () => {
     assert.strictEqual(evidence.report.target_environment, 'Restore Drill');
     assert.ok(evidence.report.smoke_check_checklist.every((item) => item.result === 'passed'));
     assert.match(evidence.report.production_write_gate, /human-approved/);
+    assert.match(
+      evidence.report.artifact_binary_backup_proof,
+      /Not performed or verified by this drill/,
+    );
+    assert.match(
+      evidence.report.artifact_binary_backup_proof,
+      /authorized artifact-storage operator/,
+    );
     await fs.access(evidence.evidencePath);
   });
 

backend/tests/export-portable.test.ts

@@ -7,7 +7,19 @@ import path from 'path';
 import { DynamoDBDocumentClient, ScanCommand } from '@aws-sdk/lib-dynamodb';
 
 import { getClient } from '../src/db/client';
-import { TABLE_NOTIFICATIONS } from '../src/db/tableNames';
+import {
+  TABLE_ARTIFACTS,
+  TABLE_ASSISTANT_JOBS,
+  TABLE_AUDIT_EVENTS,
+  TABLE_CARDS,
+  TABLE_CONVERSATIONAL_STATE,
+  TABLE_FILES,
+  TABLE_INTAKE,
+  TABLE_NOTIFICATIONS,
+  TABLE_TASKS,
+  TABLE_TEMPLATES,
+  TABLE_USERS,
+} from '../src/db/tableNames';
 import { startLocal, stopLocal } from '../scripts/local-dynamodb';
 import { createTables } from '../scripts/local-dynamodb';
 import { appendAssistantJobEvent, createAssistantJob, updateAssistantJob } from '../src/db/assistantJobs';
@@ -27,6 +39,32 @@ import {
   writePortableExport,
 } from '../src/export/portable';
 
+async function documentedRequiredLayouts(markdownPath: string): Promise<string[][]> {
+  const markdown = await fs.readFile(markdownPath, 'utf8');
+  const layouts = [...markdown.matchAll(/```text\n(manifest\.json\n(?:[a-z0-9_]+\.jsonl\n)+)```/g)]
+    .map((match) => match[1].trimEnd().split('\n'));
+
+  assert.ok(layouts.length > 0, `${markdownPath} must contain a required-layout block`);
+  return layouts;
+}
+
+function documentedDurableTableInventories(markdown: string): string[][] {
+  return markdown
+    .split(/\n\s*\n/)
+    .map((block) => [...block.matchAll(/^\s*- `<stack>-([a-z0-9-]+)`$/gm)].map((match) => match[1]))
+    .filter((tables) => tables.length > 0);
+}
+
+function documentedPostgresMappings(markdown: string): Array<[string, string]> {
+  const section = markdown
+    .split(/^## /m)
+    .find((candidate) => candidate.startsWith('Postgres Migration Path'));
+
+  assert.ok(section, 'execution data safety must contain Postgres Migration Path');
+  return [...section.matchAll(/^- `([a-z0-9_]+\.jsonl)` to `([a-z0-9_]+)`$/gm)]
+    .map((match) => [match[1], match[2]]);
+}
+
 describe('portable execution data export', () => {
   let client: DynamoDBDocumentClient;
   let exportDir: string;
@@ -1084,4 +1122,98 @@ describe('portable export timestamp anchoring', () => {
       await fs.rm(brokenDir, { recursive: true, force: true });
     }
   });
+
+  it('keeps recovery documentation synchronized with the generated export contract', async () => {
+    const expectedFiles = [
+      'manifest.json',
+      ...ENTITY_SPECS.map((spec) => spec.filename),
+    ];
+    assert.strictEqual(ENTITY_SPECS.length, 24);
+    assert.strictEqual(new Set(expectedFiles).size, expectedFiles.length);
+
+    const durableTableSuffixBySourceName = new Map<string, string>([
+      [TABLE_TASKS, 'tasks'],
+      [TABLE_CARDS, 'cards'],
+      [TABLE_TEMPLATES, 'templates'],
+      [TABLE_USERS, 'users'],
+      [TABLE_FILES, 'files'],
+      [TABLE_ARTIFACTS, 'artifacts'],
+      [TABLE_ASSISTANT_JOBS, 'assistant-jobs'],
+      [TABLE_AUDIT_EVENTS, 'audit-events'],
+      [TABLE_INTAKE, 'intake'],
+      [TABLE_NOTIFICATIONS, 'notifications'],
+      [TABLE_CONVERSATIONAL_STATE, 'conversational-state'],
+    ]);
+    const expectedDurableTables = [
+      'tasks',
+      'cards',
+      'templates',
+      'users',
+      'files',
+      'artifacts',
+      'assistant-jobs',
+      'audit-events',
+      'intake',
+      'notifications',
+      'conversational-state',
+    ];
+    const actualDurableTables = [
+      ...new Set(ENTITY_SPECS.map((spec) => {
+        const tableSuffix = durableTableSuffixBySourceName.get(spec.tableName);
+        assert.ok(tableSuffix, `unexpected portable-export source table ${spec.tableName}`);
+        return tableSuffix;
+      })),
+    ].sort();
+    assert.deepStrictEqual(actualDurableTables, expectedDurableTables.slice().sort());
+
+    const recoveryDocuments = [
+      path.join(__dirname, '..', '..', 'docs', 'restore-drill.md'),
+      path.join(__dirname, '..', '..', 'docs', 'v1-execution-data-safety.md'),
+    ];
+    for (const documentPath of recoveryDocuments) {
+      const layouts = await documentedRequiredLayouts(documentPath);
+      for (const layout of layouts) {
+        assert.deepStrictEqual(layout, expectedFiles);
+      }
+      const markdown = await fs.readFile(documentPath, 'utf8');
+      if (documentPath.endsWith('restore-drill.md')) {
+        const durableTableInventories = documentedDurableTableInventories(markdown);
+        assert.strictEqual(durableTableInventories.length, 2);
+        for (const inventory of durableTableInventories) {
+          assert.deepStrictEqual(inventory, expectedDurableTables);
+        }
+      }
+      assert.doesNotMatch(markdown, /npm --prefix work-engine/);
+    }
+
+    const safetyMarkdown = await fs.readFile(recoveryDocuments[1], 'utf8');
+    assert.deepStrictEqual(
+      documentedPostgresMappings(safetyMarkdown),
+      ENTITY_SPECS.map((spec) => [spec.filename, spec.name]),
+    );
+    assert.match(
+      await fs.readFile(recoveryDocuments[0], 'utf8'),
+      /byte-for-byte local copy[\s\S]*not infer it from bucket metadata/,
+    );
+
+    const outputDir = projectTmpDir('documented-layout-export');
+    try {
+      const result = await writePortableExport(client, outputDir, {
+        generatedAt: '2026-06-27T00:00:00.000Z',
+        sourceEnvironment: 'test',
+      });
+      assert.deepStrictEqual(Object.keys(result.manifest.entity_files).sort(), ENTITY_SPECS.map((spec) => spec.name).sort());
+      assert.deepStrictEqual(
+        Object.values(result.manifest.entity_files).sort(),
+        ENTITY_SPECS.map((spec) => spec.filename).sort(),
+      );
+      assert.deepStrictEqual((await fs.readdir(outputDir)).sort(), expectedFiles.slice().sort());
+
+      const validation = await validatePortableExport(outputDir);
+      assert.deepStrictEqual(validation.errors, []);
+      assert.strictEqual(validation.valid, true);
+    } finally {
+      await fs.rm(outputDir, { recursive: true, force: true });
+    }
+  });
 });

docs/restore-drill.md

@@ -27,8 +27,23 @@ AWS-native backups and portable exports.
 Before any restore, make sure both layers are active:
 
 1. **DynamoDB PITR** - point-in-time recovery is enabled on all durable
-   execution tables (tasks, cards, templates, users, files, notifications).
-   This protects against accidental deletes and bad updates.
+   execution tables:
+
+   - `<stack>-tasks`
+   - `<stack>-cards`
+   - `<stack>-templates`
+   - `<stack>-users`
+   - `<stack>-files`
+   - `<stack>-artifacts`
+   - `<stack>-assistant-jobs`
+   - `<stack>-audit-events`
+   - `<stack>-intake`
+   - `<stack>-notifications`
+   - `<stack>-conversational-state`
+
+   This protects against accidental deletes and bad updates. Ephemeral session
+   state is excluded. Separately governed bookkeeping, sponsor-CRM, calendar,
+   and newsletter-slot domains are outside the portable execution boundary.
 2. **Portable export archive** - an application-level JSONL snapshot bundled as
    a retained offsite archive that does not depend on DynamoDB internals. This
    is the migration path to Postgres or another store.
@@ -40,19 +55,32 @@ scripts, or risky releases:
 
 ```bash
 aws dynamodb create-backup \
-  --table-name dataops-v1-tasks \
-  --backup-name dataops-v1-tasks-pre-migration-$(date +%Y%m%d%H%M%S)
+  --table-name <stack>-tasks \
+  --backup-name <stack>-tasks-pre-migration-$(date +%Y%m%d%H%M%S)
 ```
 
-Repeat for each durable table: `cards`, `templates`, `users`, `files`,
-`notifications`. Tag or name backups with the environment, date, and reason.
+Repeat for each durable execution table:
+
+- `<stack>-tasks`
+- `<stack>-cards`
+- `<stack>-templates`
+- `<stack>-users`
+- `<stack>-files`
+- `<stack>-artifacts`
+- `<stack>-assistant-jobs`
+- `<stack>-audit-events`
+- `<stack>-intake`
+- `<stack>-notifications`
+- `<stack>-conversational-state`
+
+Tag or name backups with the environment, date, and reason.
 
 ## Portable Export
 
 Create a portable export:
 
 ```bash
-npm --prefix work-engine run export:data -- .tmp/exports/dataops-export
+npm --prefix backend run export:data -- .tmp/exports/dataops-export
 ```
 
 Or trigger the scheduled export route:
@@ -73,14 +101,30 @@ cards.jsonl
 templates.jsonl
 recurring_configs.jsonl
 files.jsonl
-notifications.jsonl
 artifacts.jsonl
 assistant_jobs.jsonl
 audit_events.jsonl
+intake_items.jsonl
+notifications.jsonl
+identity_bindings.jsonl
+identity_binding_audits.jsonl
+conversations.jsonl
+channel_bindings.jsonl
+conversation_events.jsonl
+summary_checkpoints.jsonl
+plugin_drafts.jsonl
+proposal_versions.jsonl
+proposal_presentations.jsonl
+execution_attempts.jsonl
+conversation_audit_events.jsonl
+result_notifications.jsonl
+conversational_private_payloads.jsonl
 ```
 
-Password hashes and session tokens are redacted. File binaries are excluded;
-only metadata is exported.
+All 24 JSONL families are required even when a snapshot contains zero records,
+so an empty JSONL file is valid. Password hashes and session tokens are redacted.
+The portable export excludes file and artifact binaries; it contains metadata
+only.
 
 Offsite archives are gzip-compressed tar files stored under:
 
@@ -89,7 +133,7 @@ Offsite archives are gzip-compressed tar files stored under:
 ```
 
 The deployed SAM stack sets `DATAOPS_EXPORT_ARCHIVE_BUCKET`,
-`DATAOPS_EXPORT_ARCHIVE_PREFIX`, and `DATAOPS_ENV` for the private work-engine.
+`DATAOPS_EXPORT_ARCHIVE_PREFIX`, and `DATAOPS_ENV` for the backend.
 The archive bucket is retained, private, encrypted, versioned, tagged for backup
 selection, and configured with noncurrent-version lifecycle retention.
 
@@ -98,7 +142,7 @@ selection, and configured with noncurrent-version lifecycle retention.
 Validate the export:
 
 ```bash
-npm --prefix work-engine run validate:export -- .tmp/exports/dataops-export
+npm --prefix backend run validate:export -- .tmp/exports/dataops-export
 ```
 
 This checks manifest schema version, file presence, entity counts, checksums,
@@ -110,7 +154,7 @@ Run a dry-run import to see what a restore would write without mutating any
 data:
 
 ```bash
-npm --prefix work-engine run dry-run:import -- .tmp/exports/dataops-export
+npm --prefix backend run dry-run:import -- .tmp/exports/dataops-export
 ```
 
 Output:
@@ -137,12 +181,21 @@ Exits zero when valid, non-zero when validation fails.
 Generate local restore evidence from an archive without writing production data:
 
 ```bash
-npm --prefix work-engine run restore:drill -- \
+# Download or copy the selected remote archive byte-for-byte to
+# .tmp/exports/selected-archive.tar.gz before computing its checksum.
+s3_archive_checksum=$(
+  sha256sum .tmp/exports/selected-archive.tar.gz | awk '{print "sha256:"$1}'
+)
+npm --prefix backend run restore:drill -- \
   --archive s3://<archive-bucket>/<archive-key> \
+  --archive-checksum "$s3_archive_checksum" \
   --target-environment staging-drill \
   --output-dir .tmp/exports/restore-drill
 ```
 
+The checksum must come from that byte-for-byte local copy of the selected remote
+archive. Do not infer it from bucket metadata.
+
 For local tests, pass a `file://` archive URI returned by the scheduled export
 route. The command extracts the archive under `.tmp/exports/restore-drill`, runs
 `validate:export`, runs `dry-run:import`, and writes
@@ -160,6 +213,9 @@ The evidence report includes:
 - target environment
 - evidence timestamp
 - smoke-check checklist result
+- generic statement that artifact-binary backup proof was not performed or
+  verified by this drill and remains the separate privately retained
+  responsibility of the authorized artifact-storage operator
 
 `restore:drill` rejects `production` and `prod` as target environments. It does
 not restore, import, overwrite, delete, or repair production DynamoDB records.
@@ -174,8 +230,8 @@ backups:
 
 ```bash
 aws dynamodb restore-table-to-point-in-time \
-  --source-table-name dataops-v1-tasks \
-  --target-table-name dataops-v1-tasks-restored \
+  --source-table-name <stack>-tasks \
+  --target-table-name <stack>-tasks-restored \
   --restore-date-time 2026-06-27T10:00:00Z
 ```
 
@@ -211,8 +267,10 @@ Run this sequence end-to-end before production data becomes critical:
 
 - `generated_at` is the logical snapshot anchor. The export scans tables
   sequentially; there is no multi-table transactional snapshot guarantee.
-- File export covers metadata only; binary backup requires S3 versioning or
-  a separate artifact archive.
+- Portable export validation, dry-run analysis, restore evidence, and passed
+  smoke checks do not prove that externally stored file or artifact binaries
+  remain recoverable. Artifact-binary backup proof is retained privately by the
+  authorized artifact-storage operator under a separate process.
 - The dry-run import validates and counts but does not write to a target
   database. A full import tool (for Postgres migration) is a follow-up.
 - Production restore/import/write behavior is human-gated. Automated cron