Epic — Establish governed, privacy-correct local security records and policy state

[knytcomics-ui]

Outcome

Replace ad hoc local arrays with a versioned, validated, concurrency-safe subsystem for decision history, trusted policy, diagnostics, export, retention, deletion, and migration, with privacy documentation matching executable behavior.

Audit evidence and problem

• src/lib/history.ts persists destination, asset, score, decision, tier, and exact timestamp.
• PRIVACY.md incorrectly says nothing is written to Chrome/local storage.
• readHistory() trusts any array and recordDecision() uses a race-prone read-modify-write.
• background.ts records only scores[0], even when another or multiple targets drove the warning.
• Records omit network, adapter, digest, provenance, coverage, policy version, and terminal reason; UI recomputes historical tier under current code.
• Storage errors are swallowed.
• storageHelper.ts stores unbounded arbitrary trusted strings without validation, network/type scope, provenance, expiry, or schema version.
• The trusted manager is disconnected: production never adds addresses and signing never consults them.
• No complete data inventory, export, clear-all, migration, or retention workflow exists.

Non-negotiable invariants

• Policy/docs enumerate every persisted field, purpose, retention, and deletion path.
• Concurrent writes cannot silently lose records or policy changes.
• Stored data is untrusted and schema-validated.
• Historical records retain their original evidence/policy meaning.
• Multi-target decisions are never reduced to a misleading first target.
• Trust is network/type-aware and cannot make unassessed semantics safe.
• Per-class clearing is isolated; clear-all deletes every documented class.
• Corruption cannot grant trust, inject UI, or crash the extension.
• Export is explicit, bounded, versioned, and privacy-labeled.
• Storage failure never changes the actual signing outcome.

Required scope

A. Governance and storage boundary

Inventory ephemeral state, history, trust, cache, diagnostics, and configuration. Define sensitivity, retention, migration, deletion, and export. Implement one versioned storage boundary with runtime schemas, revisions, typed errors, corruption handling, and bounded reads/writes.

B. Faithful audit records

Use Epic 3’s canonical review schema to retain the actual reviewed targets/findings, network, adapter, evidence provenance/freshness, displayed state, policy version, decision, and terminal reason while deliberately minimizing identifiers and time precision.

C. Trusted-target policy

Define whether trust adds context or alters assessment; validate target types, scope by network/type, support labels/provenance/expiry, and never suppress opaque/admin/authority/unavailable findings. Integrate it or remove the misleading surface until implemented.

D. Retention/export/deletion

Provide per-class counts, retention controls, separate exports and clears, clear-all, sensitivity notices, and storage failure UI. Do not bundle diagnostics with transaction history by default.

E. Restart-safe migration

Migrate legacy arrays idempotently without inventing missing network/provenance. Define rollback/recovery across worker termination and interrupted upgrades.

Deliverables

• Data-governance ADR, inventory, corrected privacy policy, and data-management UI.
• Versioned schemas/repository and concurrency-safe mutations.
• Legacy migrations and corruption handling.
• Faithful multi-target audit schema.
• Network-aware trusted-target policy.
• Retention, export, per-class clear, and clear-all workflows.
• Migration, concurrency, privacy, accessibility, and large-data tests.

Acceptance criteria

• Policy/UI enumerate every production key, field category, purpose, retention, and deletion control.
• Fifty concurrent record writes preserve all accepted records up to the limit.
• Concurrent trust add/remove follows revision semantics and cannot resurrect removed entries.
• Multi-target records retain all targets and the finding driving the displayed state.
• History uses stored policy version and is not silently re-tiered.
• Malformed/oversized/future/prototype-shaped data cannot grant trust or crash rendering.
• Trust never crosses network or target type.
• Trust cannot suppress opaque Soroban, signer/admin changes, or unavailable evidence.
• Legacy migration is idempotent and marks missing facts unknown.
• Killing the worker at every migration checkpoint yields old-readable or fully migrated state, never mixed authority.
• Per-class clear operations are isolated and clear-all removes every documented class.
• Export is explicit, versioned, warned, and does not combine diagnostics/history by default.
• Disabling history prevents new records without changing signing behavior.
• Quota/write failure is visible but cannot reverse, duplicate, or alter a decision.
• Maximum retained data remains responsive and accessible on the supported low-end baseline.

Required verification

Adversarial schema tests, property-based migration/retention tests, deterministic interleaving tests, worker-restart migration tests, real Chrome storage integration, documentation-to-key privacy checks, export redaction/round-trip tests, large-data performance, accessibility, and trusted-policy security review. Simple mocked one-record tests are insufficient.

Out of scope

Cloud sync, remote telemetry/upload, blockchain settlement history, uninstall recovery, and pending-request state.

Dependencies and sequencing

Privacy correction and storage foundation can begin now. Final records depend on Epic 2 evidence and Epic 3 review schemas; trust uses Epic 3 typed targets; diagnostics uses Epic 4 taxonomy.

Complexity

Very High

Impact

High — current state can lose records, misstate multi-target reviews, apply unscoped trust, and contradict published privacy claims.

Suggested labels

epic privacy data-integrity storage security migration ux-correctness

[Neziahtech]

Hello,

I’d love to take this issue on. I’m a full-stack developer with experience across Drips Waves 3–7, and the GrantFox oficiall 1 and2 campaign.

My stack includes Rust, Soroban, Solidity, and TypeScript. I can deliver a clean, tested, and well-documented solution within 24 hours of assignment.

Happy to start immediately.

[yunus-dev-codecrafter]

Hi! I've carefully reviewed the entire task description and fully understand the requirements and expected outcome.
I have experience working on similar tasks and I'm confident I can complete this within about an hour. I'd be happy to take ownership of this issue and submit a clean, well-tested solution promptly.
If it's available, please assign it to me. Thank you!

[grantfox-oss]

🦊 GrantFox — @OxDev-max has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #127)
2. Your PR will be reviewed by the Gryd-lock maintainers

Good luck! Track your progress on GrantFox.