fix: reconcile legacy snapshot byte totals

[Lucenx9]

Summary

Fixes the v0.2.0 compatibility boundary for valid pre-v0.2.0 imported snapshots whose stored decoded_bytes used the historical payload definition rather than the canonical revision-JSON definition.

• Adds forward-only migration 011 with transactional, observation-scoped reconciliation.
• Records immutable evidence for every snapshot without changing hashes, provenance, revisions, resources, dependencies, classifications, advisories, accounts, API keys, or repository memory.
• Rejects arbitrary totals, malformed or missing objects, duplicate revision accounting, overflow, stale pre-011 writers, and fabricated direct-SQL evidence at commit.
• Makes current publication totals follow the authoritative stored revision when immutable content is reused across mutable provenance changes.
• Keeps restore validation schema-aware: exact legacy-or-canonical derivation before 011; canonical projection plus exact reconciliation/control evidence at and after 011.
• Propagates migration 011 through schema compatibility, readiness, upgrade recovery, release components, manifest schema, and release payload construction.

Historical compatibility semantics

Before migration 011, native ingestion recorded UTF-8 instruction bytes plus resource bytes. The v0.2.0 canonical projection is the UTF-8 byte length of each exact observed immutable canonical revision JSON object. Migration 011 accepts only either exact derived representation, records which representation was found, and stores the canonical total.

Protected-backup rehearsal

The existing protected PostgreSQL 17.10 custom archive was copied read-only into an explicitly isolated Docker daemon and disposable PostgreSQL 17.10 environment.

• Before: schema 009.
• mattpocock/skills: recorded/legacy 183475, canonical 250784.
• obra/superpowers: recorded/legacy 91537, canonical 118322.
• One empty snapshot remained 0 in both representations.
• Migration runner reached 011 and a second run was idempotent.
• After: the two legacy snapshots contain their exact canonical totals and all three snapshots have exact reconciliation evidence.
• Authoritative counts remained unchanged: 2 sources, 2 registrations, 3 snapshots, 40 candidates, 37 observations, 37 revisions, 23 resources, 45 dependencies, 62 content objects, 80 candidate-classification events, 40 candidate classifications, 37 revision classifications, 0 advisory events, 1 account, 1 API key, 3 repository-memory rows, and 0 erasure-audit rows.
• Catalog/advisory integrity and an exact MCP search_skills → load_skill → read_skill_resource journey passed.
• The isolated container, volume, daemon, socket, database, runtime and temporary credential files were destroyed. The protected archive was unchanged.

Validation

• Complete bounded offline suite: 923 passed, 9 expected environment-gated skips.
• Focused migration/restore/release group: 76 passed, 1 expected skip.
• GitHub synchronization and compatibility regressions: 22 passed.
• Feature 004 aggregate: 414 passed, 8 expected skips.
• Feature 003 activation: 98 passed.
• Feature 003 adapter: 65 passed.
• Real disposable PostgreSQL backup/restore integration: 9 passed.
• Clean migrations 001–011 and idempotent rerun passed under PostgreSQL 17.10.
• Formatting, ESLint, strict TypeScript, build, catalog, advisory, package integrity, all Compose renderings, Actionlint syntax, secret scan, wrapper scan and git diff --check passed.
• Fresh exact-patch Codex Security diff scan: complete coverage, zero unresolved findings.

Scope boundary

• Package version remains 0.2.0.
• Features 001–003 and the Feature 003 package identity are unchanged.
• T161 remains unchecked.
• No persistent database was migrated or repaired.
• No tag, release, signature, production asset, source registration, user profile, credential store, or system Docker resource was created or changed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62eaae3226

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Enforce the projection when child rows are inserted

This constraint fires only when external_source_snapshots itself is inserted or updated, but the totals it validates also depend on observations, resources, dependencies, candidates, and classifications. Those tables reject updates/deletes but still permit inserts, so after a snapshot commits, direct SQL can insert an additional observation or resource referencing it without retriggering this check, leaving decoded_bytes and the immutable reconciliation ledger inconsistent. Add corresponding deferred checks on projection-affecting child inserts, or prevent additions once the snapshot is finalized.

Useful? React with 👍 / 👎.