arch: replace hardcoded STATE_DIRS/STATE_FILES in externalize.ts with discoverable manifest #863

Activity

1. diberry

   added

   enhancementNew feature or improvementNew feature or improvement

   on Apr 5, 2026
2. diberry commented on Apr 6, 2026

   

   diberry

   on Apr 6, 2026

   ContributorAuthor

   More actions

   ✈️ Flight — Issue-Level PRD

   Summary

   externalize.ts hardcodes STATE_DIRS and STATE_FILES arrays that must be manually updated whenever new state artifacts are added. This creates silent data loss risk during externalization. This PRD replaces the hardcoded lists with a discoverable manifest that state managers register into, plus atomic copy-verify-delete operations.

   Problem Statement

   • New state artifacts added after deployment are silently orphaned during externalization
   • No mechanism for state managers to register their artifacts
   • If externalization fails mid-copy, state ends up split between old and new locations
   • No audit trail or validation that all state was migrated successfully

   Proposed Approach

   Phase 1 — State Artifact Registry (P0)

   • Define a StateArtifact interface: { path: string, type: 'dir' | 'file', owner: string, critical: boolean }
   • Each state manager exports a getArtifacts(): StateArtifact[] function
   • externalize.ts discovers artifacts by calling each manager's getArtifacts() instead of reading hardcoded arrays
   • CI test: compare discovered artifacts vs actual .squad/ contents — fail if any unregistered artifacts exist

   Phase 2 — Atomic Externalization (P1)

   • Replace current copy-in-place with copy-verify-delete pattern
   • Copy all artifacts to new location, verify checksums/existence, then delete originals
   • On verification failure: rollback (delete copies, preserve originals), surface error
   • Add --force flag to skip verification for emergency recovery

   Phase 3 — Operator Visibility (P2)

   • squad doctor reports registered vs actual state artifacts
   • Externalization produces a migration manifest (JSON log of what moved where)
   • Rollback instructions included in error output

   Acceptance Criteria

   • STATE_DIRS and STATE_FILES hardcoded arrays removed from externalize.ts
   • State managers register artifacts via getArtifacts() interface
   • CI test catches unregistered state artifacts
   • Externalization uses copy-verify-delete pattern
   • Verification failure triggers rollback with clear error message
   • squad doctor reports state artifact registration completeness
   • Migration manifest (JSON) produced on each externalization

   Architecture Notes

   • Relates to PRD: Versioned file layout manifest - single source of truth for directory structure #670 (versioned file layout manifest) — the layout manifest could eventually subsume this registry
   • Consider whether getArtifacts() should be part of the StorageProvider interface
   • Keep Phase 1 independent of PRD: Versioned file layout manifest - single source of truth for directory structure #670 — this is a safety fix, not a feature
3. diberry

   added 5 commits that reference this issue on Apr 7, 2026

   fix(sdk): replace hardcoded state dirs with discoverable manifest

   ...

   This issue will close once commit cbac697 is merged into the 'dev' branch.

   cbac697

   fix(sdk): replace hardcoded state dirs with discoverable manifest

   ...

   This issue will close once commit bc9d88e is merged into the 'dev' branch.

   bc9d88e

   fix(cli): replace hardcoded state lists with dynamic directory scan

   ...

   This issue will close once commit b9a3bc2 is merged into the 'dev' branch.

   b9a3bc2

   fix(cli): replace hardcoded state lists with dynamic directory scan

   ...

   This issue will close once commit 93c6be3 is merged into the 'dev' branch.

   93c6be3

   fix(cli): replace hardcoded state lists with dynamic directory scan

   ...

   This issue will close once commit a01fd71 is merged into the 'dev' branch.

   a01fd71
4. diberry commented on Apr 10, 2026

   

   diberry

   on Apr 10, 2026

   ContributorAuthor

   More actions

   🔒 On hold — high-touch architecture work (PR #908 exists but blocked on SDK republish).
5. tamirdresher

   closed this as completedin #908on Apr 12, 2026
6. jazz127

   added a commit that references this issue on Apr 12, 2026

   fix(cli): replace hardcoded state lists with dynamic directory scan (g…

   ...

   This issue will close once commit f50bbc8 is merged into the 'dev' branch.

   f50bbc8
7. tamirdresher

   added a commit that references this issue on Apr 21, 2026

   fix(cli): replace hardcoded state lists with dynamic directory scan (#…

   ...

   This issue will close once commit ae46701 is merged into the 'dev' branch.

   ae46701