8000 V0-15: Add the versioned Nodepad archive workflow · Issue #16 · kiran-brahma/nodepad-app · GitHub
[go: up one dir, main page]

Skip to content

V0-15: Add the versioned Nodepad archive workflow #16

Closed

Description

@kiran-brahma

Parent

Part of #1.

What to build

Add the V0 versioned Nodepad archive workflow. Export one complete Thinking Workspace as deterministic JSON and import a fully validated archive into a fresh Workspace with collision-safe identity remapping. Validation completes before the transaction begins; import commits all durable data or nothing.

Decisions

  • New V0 format only; no browser archive compatibility.
  • Root contains format identifier, integer version, exported timestamp, application version, and one Workspace payload.
  • Payload contains Workspace name/Assistance Policy reset target, Notes, Note Types, manual/AI provenance, Labels and memberships, symmetric Relationships, pending Syntheses and source mappings, bounded Synthesis novelty history, and safe source metadata.
  • Imported Assistance Policy always resets to Manual. Selected models and consent do not import.
  • Exclude provider keys, selected keychain references, transient AI state, view state, selection, undo, database metadata, paths, and backups.
  • Validate required fields, lengths, enums, unique source IDs, Label normalization, Relationship endpoints/pairs, Synthesis source IDs, and archive size before mutation.
  • Assign fresh Workspace, Note, Label, Relationship, and Synthesis IDs; remap internal references transactionally.
  • Name collisions append deterministic (2), (3) suffixes.
  • Use native open/save dialogs and atomic write semantics.

Acceptance criteria

  • Exported archive has explicit format/version and deterministic durable content.
  • Round-trip import preserves all intended domain meaning with fresh identities.
  • Imported Workspace is Manual regardless of exported Assistance Policy.
  • Malformed JSON, unknown version, oversize input, invalid enum, duplicate IDs/pairs, broken references, and limit violations fail before mutation.
  • Name and identity collisions cannot overwrite existing data.
  • Import rollback leaves the database unchanged on injected failure.
  • Secrets and transient state are 8000 absent from exported bytes.
  • Canceling either dialog is a successful no-op.
  • Imported data remains valid after restart and through every view.

Testing decisions

  • Round-trip fixtures cover Unicode, all Note Types, Labels, manual/AI provenance, Relationships, pending Syntheses, source mapping, empty Workspace, and large Notes within limits.
  • Negative fixtures cover each validator and confirm database row counts/state remain unchanged.
  • Scan archive bytes for sentinel key, paths, and transient markers.

Blocked by

Scope fence

Do not import legacy .nodepad, support partial import/merge, export multiple Workspaces, encrypt archives, or include local provider configuration.

Delivery workflow

Run prd-simplicity-audit, use a fresh implement session, then code-review, scoped fallow, focused tests and repository gates, and one PR against main.

Activity

  1. kiran-brahma commented on Jul 23, 2026

    @kiran-brahma
    OwnerAuthor

    PRD simplicity audit (pre-implementation)

    Ran the simplicity gate against issue #16 and the V0 codebase before implementation. Material decisions:

    Gate decision: Proceed.

    Where the knowledge lives

    • New archive.rs module owns the V0 format, serialization, and full validation. It is pure: no SQLite access, no Tauri. The durable layer (workspace.rs) owns the SQL extraction (archive_export_data) and the transactional import (import_archive). Format/version/schema decisions change in one place; SQL changes in the other. No information leakage.
    • Validators and length constants in workspace.rs were promoted to pub(crate) so the archive reuses the same durable rules (name/annotation/label/note-type bounds) instead of duplicating them — one source of truth for each limit.

    Complexity pulled downward

    • Validation completes entirely before the import transaction opens (parse_and_validate → Archive), so every malformed/unknown-version/oversize/broken-reference failure is a pure read that touches nothing. The store only ever receives a validated payload.
    • Import is one transaction: workspace → labels → notes (+ memberships) → relationships (re-canonicalized) → pending syntheses (+ sources/labels) → synthesis history → FTS refresh → commit. A failure at any point rolls back. Identities are remapped via in-transaction id maps; the imported Workspace is always Manual regardless of the exported policy.

    Decisions that simplified the spec

    • The archive stores the exported assistancePolicy for the reader but import always creates a Manual Workspace — the deliberate reset is preserved without losing the original record.
    • A pending Synthesis whose source was deleted or moved out of the Workspace is not archived, because its source mapping no longer resolves here and a broken reference is not archivable. Non-stale and edited-source syntheses travel; their source revision is derived from the preserved Note enrichment_revision on import so staleness is correct in the fresh Workspace.
    • Export excludes selected_model, cloud_consent_at, active-workspace preference, undo history, view state, provider keys, and paths — only durable domain content leaves the durable layer.
    • File extension .nodepad.json (filter json) avoids the legacy .nodepad format explicitly named in the scope fence.

    Risk surface reviewed

    • No new shallow pass-through; the command layer mirrors the existing MarkdownExportOutcome shape (ArchiveExportOutcome/ArchiveImportOutcome).
    • No temporal decomposition: archive knowledge is one module, persistence is one module.
    • Name collision suffixing ( (2), (3)) is deterministic and re-import-safe; fresh ids make identity collisions impossible.

    Proceeding to a fresh implementation session.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentDecision-complete and ready for an AFK agent

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0