Nexuscone - OUTSTANDING.txt
Local-only. The roadmap from current state (v0.1.0 shipped to GitHub, not
yet on PyPI) through v0.2.0 (the engineering-genius release) to v1.0.0
(feature-complete audit primitive).

================================================================================
CURRENT STATE (last verified 2026-05-13)
================================================================================

v0.1.0 shipped 2026-05-11 to github.com/nexuscone/nexuscone under Apache 2.0.
24 pytest passing, ruff clean, mypy --strict clean, CI on Python 3.10
through 3.13. Tamper-evident audit ledger with SHA-256 hash chain plus
optional Ed25519 signing.

Distribution status:
  - GitHub: live, main branch clean, commit 27af873
  - PyPI: NOT released. `pip install nexuscone` currently fails with 404.
  - Internal consumers (TypeScript ports of the same canonical-JSON
    rules, byte-for-byte): Aperintel-AI-Gateway (lib/audit/), Rallova
    (apps/api/src/lib/audit/), HydroFlow (app/lib/audit/).

================================================================================
RELEASE CADENCE (the three-step plan)
================================================================================

  Week 1: ship v0.1.0 to PyPI as-is. The PyPI release is the single
          biggest distribution lever and there is no point delaying it
          for the v0.2.0 features. Announce with a LinkedIn post under
          the Osi (engineering) byline.

  Week 3: ship v0.2.0 with OpenTimestamps anchoring + SQLite append-only
          triggers. This is the engineering-genius release that takes
          Nexuscone from "competent audit library" to "uniquely positioned
          audit library". Announce with a second LinkedIn post explaining
          what Bitcoin-anchored audit timestamps mean for the trust model.

  Week 7: ship v1.0.0 with Merkle inclusion proofs + selective disclosure
          with redaction proofs + Postgres pluggable backend. This is the
          feature-complete primitive that earns its place as the
          reference Python audit library. Announce with a Substack
          technical essay rather than a LinkedIn post.

Each release becomes its own marketing moment. The cadence itself
(initial release this week, exceptional feature in two weeks, v1.0 in a
month) is the rhythm that signals serious engineering to anyone watching.

================================================================================
v0.1.0 PyPI RELEASE (paused mid-flow 2026-05-13, resume from "Step A" below)
================================================================================

PROGRESS SO FAR (verified 2026-05-13):

  [x] Python 3.14.3 verified at
        C:\Users\juliu\AppData\Local\Programs\Python\Python314\python.exe
      pip 26.0.1 available via `& $python -m pip`.
  [x] build 1.5.0 and twine 6.2.0 installed via
        & $python -m pip install --upgrade build twine
  [x] dist artefacts built from C:/Projects/nexuscone/:
        dist/nexuscone-0.1.0-py3-none-any.whl  (14,896 bytes)
        dist/nexuscone-0.1.0.tar.gz            (27,771 bytes)
  [x] Both passed `twine check dist/*` (returned PASSED on both files).
  [!] PAUSED here on Julius's request. Resume below when ready.

================================================================================
RESUME STEPS (everything from here is the remaining work)
================================================================================

  Step A. Julius's browser part (5 minutes):
    [ ] Create PyPI account at pypi.org. Suggested username: osiabu.
        Email: osi@aperintel.com (public-facing alias; forwards to
        abuj07@gmail.com via ImprovMX). Set up 2FA when prompted
        (Google Authenticator, Authy, or 1Password). Save recovery codes.
    [ ] Generate API token at Account Settings -> API tokens ->
        Add API token. Name: `nexuscone-first-upload-2026-05`.
        Scope: "Entire account" (project scope is not available
        until after the first upload). Copy the pypi-AgEIcHl...
        token string somewhere temporary.

  Step B. Twine upload from PowerShell:
        $python = "C:\Users\juliu\AppData\Local\Programs\Python\Python314\python.exe"
        Set-Location "C:\Projects\nexuscone"
        & $python -m twine upload dist/*
      When prompted for username, type literally: __token__
      When prompted for password, paste the pypi-... token.
      Success looks like:
        View at: https://pypi.org/project/nexuscone/0.1.0/
      Once that line appears, `pip install nexuscone` works globally.

  Step C. Lock down credentials:
    [ ] Go back to pypi.org Account Settings -> API tokens.
    [ ] Revoke the "nexuscone-first-upload-2026-05" all-account token.
    [ ] Create a new token scoped just to the `nexuscone` project
        (it is now selectable because the project exists on PyPI).
        Name: `nexuscone-uploads`. Save somewhere durable (1Password).

  Step D. Repo cleanup (Claude handles, 5 minutes):
    [ ] Update README.md install instruction from
          pip install git+https://github.com/nexuscone/nexuscone.git
        to
          pip install nexuscone
    [ ] Add PyPI version badge to README:
          [![PyPI](https://img.shields.io/pypi/v/nexuscone)](https://pypi.org/project/nexuscone/)
    [ ] Add downloads badge:
          [![Downloads](https://img.shields.io/pypi/dm/nexuscone)](https://pypi.org/project/nexuscone/)
    [ ] Commit the README update with message:
          docs: switch install instruction to PyPI now that nexuscone 0.1.0 is published
    [ ] git tag -a v0.1.0 -m "Initial release: tamper-evident audit ledger with SHA-256 hash chain and optional Ed25519 signing"
    [ ] git push origin main && git push origin v0.1.0

  Step E. LinkedIn announcement (Claude drafts, Julius publishes):
    [ ] Draft post-25 at C:/Projects/linkedin posts/post-25-nexuscone-launch/
        following the existing post-XX folder convention (caption.md,
        first-comment.md, how-to-deliver.md).
    [ ] Julius publishes the day AFTER the upload, once a clean
        `pip install nexuscone` from a fresh terminal confirms the
        package installs and the verifier runs.

================================================================================
v0.2.0 RELEASE (the engineering-genius features, 2 weeks after v0.1.0)
================================================================================

FEATURE 1: OpenTimestamps anchoring
-----------------------------------

  WHY:
    Right now the timestamps in the audit ledger are whatever the server's
    clock says. OpenTimestamps anchors the chain head, periodically, to
    Bitcoin's blockchain via a free public calendar service, so anyone in
    the world can verify (against Bitcoin's proof-of-work) that the chain
    head existed before block N was mined. Moves the trust assumption out
    of Aperintel's infrastructure entirely. No other Python audit-chain
    library on PyPI does this. Maps directly onto regulator language:
    "we can prove these entries existed by this time, independently of
    our own systems". The single highest-leverage feature you can add to
    Nexuscone before the PyPI announcement.

  IMPLEMENTATION (1-2 days):
    [ ] Add `opentimestamps-client` to optional `[ots]` extras in
        pyproject.toml.
    [ ] Add an `AnchorSchedule` config to the Ledger: anchor every N
        entries OR every M minutes (configurable, default 1000 entries
        or 60 minutes whichever comes first).
    [ ] Implement Ledger.anchor() that takes the current chain head hash,
        submits to a configurable OpenTimestamps calendar server (default
        list: alice.btc.calendar.opentimestamps.org, bob.btc.calendar.opentimestamps.org,
        finney.calendar.eternitywall.com), receives back a `.ots` proof
        file, stores it in a new `anchors` table (id, chain_head_hash,
        ots_proof_blob, submitted_at, confirmed_at NULL until Bitcoin
        confirms).
    [ ] Background poller that periodically re-submits the `.ots` proofs
        for upgrade once Bitcoin has confirmed the block (the OTS protocol
        provides incomplete proofs initially; the calendar server upgrades
        them after Bitcoin confirms).
    [ ] Extend `nexuscone-verify` CLI to verify the OTS proofs against
        Bitcoin: `nexuscone-verify --check-anchors <db_path>`.
    [ ] Tests: anchor submission, proof storage, proof upgrade, proof
        verification (with a mock Bitcoin block as fixture), behaviour
        when calendar servers are unreachable (graceful degradation, not
        a hard failure).
    [ ] Documentation pass: explain the trust model shift, the
        AnchorSchedule config, the verification flow, what "incomplete"
        vs "complete" OTS proof means.

  REGULATOR-FACING CLAIM after this lands:
    "Audit timestamps are anchored to Bitcoin's proof-of-work via
    OpenTimestamps. Any party with the audit database and the .ots
    proof files can independently verify, against the Bitcoin
    blockchain, that the chain head existed before a given block
    height, regardless of whether they trust Aperintel's
    infrastructure or server clocks."

FEATURE 2: SQLite append-only triggers
--------------------------------------

  WHY:
    Currently tamper-evidence is detected on read. A database
    administrator with shell access can UPDATE or DELETE rows in the
    audit table, and the chain only flags the tampering when somebody
    runs verification. Compliance people hate this because their threat
    model includes the DBA, the offshore contractor with prod access,
    and the disgruntled engineer. SQLite triggers physically prevent the
    UPDATE and DELETE at the SQL layer, so tampering becomes a deliberate
    multi-step act (modify the trigger first) rather than a single SQL
    command. Belt-and-braces with the cryptographic chain.

  IMPLEMENTATION (2-3 hours):
    [ ] On schema creation, add three triggers to the audit_log table:
          CREATE TRIGGER audit_log_no_update BEFORE UPDATE ON audit_log
            BEGIN SELECT RAISE(ABORT, 'audit_log is append-only'); END;
          CREATE TRIGGER audit_log_no_delete BEFORE DELETE ON audit_log
            BEGIN SELECT RAISE(ABORT, 'audit_log is append-only'); END;
          (DROP TABLE protection via a `protected_tables` registry is
           SQLite-version-dependent; document the limitation rather than
           pretend to solve it.)
    [ ] Add a `Ledger.unlock_for_redaction()` context manager (used by
        the v1.0 redaction feature) that temporarily drops the triggers,
        applies the redaction (which is itself an audit-logged event),
        and re-installs the triggers. This is the ONE legitimate way to
        modify the table, and it is itself an audit event.
    [ ] Tests: attempted UPDATE raises, attempted DELETE raises, INSERT
        still works, the redaction unlock path works and re-installs
        triggers afterwards.

================================================================================
v1.0.0 RELEASE (feature-complete audit primitive, 4 weeks after v0.2.0)
================================================================================

FEATURE 3: Merkle tree + inclusion proofs
-----------------------------------------

  WHY:
    Hash chain proves the chain is internally consistent end-to-end.
    A Merkle tree on top lets a holder of one entry plus a small
    Merkle proof verify that entry was in the chain at a given size,
    WITHOUT seeing the rest of the chain. This is what Certificate
    Transparency does, what Sigstore Rekor does, what blockchain light
    clients do. Genuinely useful for compliance: a regulator gets only
    the entries they are cleared to see, plus a cryptographic proof
    that those entries were in the chain at a given size. Also the
    single feature that puts Nexuscone in the same conceptual class as
    CT and Sigstore, which are the gold-standard trust systems in the
    industry.

  IMPLEMENTATION (3-5 days):
    [ ] Maintain a Merkle tree alongside the hash chain. Each new entry
        adds a leaf; the tree root is computed on every insert.
    [ ] Store the Merkle root at every entry (extra column on audit_log).
    [ ] Implement `Ledger.get_inclusion_proof(entry_id, tree_size)` that
        returns the Merkle proof (the sibling hashes needed to recompute
        the root from the entry).
    [ ] Implement `verify_inclusion_proof(entry, proof, expected_root)`
        as a standalone function that does NOT need access to the chain
        database; a holder of just the entry, the proof, and the
        published root can verify offline.
    [ ] Implement `Ledger.get_consistency_proof(tree_size_old, tree_size_new)`
        for proving the chain at size N is a prefix of the chain at size
        M (the CT-style consistency proof). Useful when publishing chain
        roots externally and needing to prove no entries were retroactively
        inserted between publications.
    [ ] Tests: inclusion proof for every entry in a 1000-entry chain,
        forged proof rejected, consistency proof for chain growth from
        size N to size M, attempted retroactive insertion detected by
        consistency proof.
    [ ] Documentation: explain the trust model (chain integrity vs
        position proofs vs consistency proofs), worked examples with
        small trees, references to CT and Sigstore.

FEATURE 4: Selective disclosure with redaction proofs
-----------------------------------------------------

  WHY:
    GDPR Right to Erasure (Article 17) conflicts with immutable audit
    chains by default. Replacing an entry's payload with a structured
    redaction marker (rather than nulling the row) lets the chain
    remain intact, the original payload is gone, and the redaction
    itself becomes an audit-logged event. Makes Nexuscone the first
    Python audit library that is genuinely GDPR-compatible without
    compromising the audit trail. Real compliance differentiator,
    especially for the UK and EU market.

  IMPLEMENTATION (1 day):
    [ ] Implement `Ledger.redact(entry_id, reason, redacted_by)`:
          - Reads the original entry, computes its original payload hash.
          - Uses the SQLite append-only unlock path (see v0.2 Feature 2)
            to temporarily drop the triggers.
          - Replaces the entry's payload with:
              {
                "redacted": true,
                "original_payload_hash": "<hex>",
                "redacted_at": "<iso8601>",
                "redacted_by": "<actor>",
                "reason": "<string>"
              }
          - Recomputes the entry's entry_hash from the new canonical JSON.
          - The chain integrity is preserved because the new entry_hash
            is computed correctly from the new (redacted) payload.
          - Inserts a NEW chain entry recording the redaction itself
            (actor: "ledger", action: "redact", payload: {entry_id,
            reason, redacted_by, original_payload_hash}).
          - Re-installs the triggers.
    [ ] Add a `Ledger.is_redacted(entry_id)` helper.
    [ ] Add `Ledger.get_redaction_history(entry_id)` returning every
        redaction event linked to the entry.
    [ ] Tests: redact entry preserves chain integrity, redaction event
        itself is in the chain, re-verification passes after redaction,
        attempted redaction outside the unlock path raises.
    [ ] Documentation: when to use redaction vs deletion (never use
        deletion), the GDPR Article 17 mapping, the trade-off (the fact
        of redaction is permanently visible, only the original content
        is gone).

FEATURE 5: Postgres pluggable backend
-------------------------------------

  WHY:
    SQLite has real scaling limits (single-writer, file-based,
    concurrent-access pain) that production deployments will hit
    around 100k-1M entries depending on write pattern. Postgres
    supports much higher write concurrency, replication for read
    scaling, and is the database that regulated firms actually run.
    Adding Postgres support without forking the API makes Nexuscone
    suitable for production deployment, not just development and
    small-scale audit logs.

  IMPLEMENTATION (1-2 days):
    [ ] Refactor the storage layer behind a thin `StorageBackend`
        protocol (async interface, four methods: append, get_entry,
        get_entries, verify_chain).
    [ ] Implement `SqliteBackend` as the current behaviour, no changes
        for existing users.
    [ ] Implement `PostgresBackend` using `asyncpg`. Same canonical-JSON
        rules, same hash chain, same Ed25519 signing, same Merkle tree,
        same redaction support. Different schema for SERIAL primary
        keys and JSONB payload column.
    [ ] Move append-only enforcement from SQLite triggers to Postgres
        equivalents (BEFORE UPDATE / BEFORE DELETE triggers in plpgsql,
        which is more sophisticated than SQLite's RAISE).
    [ ] Tests: every existing test runs against both backends (parametrise
        the test suite on backend selection).
    [ ] Documentation: when to choose SQLite vs Postgres, migration path
        from one to the other (export to JSONL, replay on the new
        backend, verify chain matches).

================================================================================
DEFERRED (the existing items, still valid, not on the v0.1-v0.2-v1.0 path)
================================================================================

  [ ] Sister TypeScript package `nexuscone-ts`: extract the audit-chain
      code from Aperintel-AI-Gateway's lib/audit/, Rallova's
      apps/api/src/lib/audit/, and HydroFlow's app/lib/audit/ into a
      unified packages/nexuscone-ts (or a sibling repo nexuscone-ts at
      github.com/nexuscone/nexuscone-ts). Currently each repo has its own
      near-identical copy of canonical.ts and chain.ts. Consolidation
      lets every TypeScript surface import a single source of truth
      and inherit bug fixes uniformly. Estimated 1-2 hours including
      tests, tsc clean, CI matrix.

  [ ] Cross-language conformance test: a small fixture suite that runs
      the same audit-chain inputs through both the Python and
      TypeScript ports and asserts identical entry_hash output.
      Catches drift between the implementations. ~1 hour. Should
      land alongside or immediately after nexuscone-ts.

  [ ] Documentation pass: extend the README with the canonical-JSON
      spec, the genesis-sentinel rule, the hash-chain pattern, the
      Merkle tree shape (post v1.0), the OpenTimestamps trust model
      (post v0.2), and worked examples for every public API surface.
      Currently the README is a quick-start; the spec lives only in
      code comments. ~2 hours.

  [ ] Add CONTRIBUTING.md outlining the bar for accepting changes
      (canonical-JSON byte-for-byte preservation is non-negotiable,
      every change must preserve verification against the existing
      test fixtures, breaking changes require a major version bump).

  [ ] Add SECURITY.md with the disclosure email (security@aperintel.com
      or osi@aperintel.com), the supported-versions policy, and the
      response-time commitment.

  [ ] Add badges to the README: PyPI version, build status, license,
      Python versions, downloads (post-PyPI), security audit (if one
      is ever commissioned).

  [ ] Consider a small landing page at nexuscone.aperintel.com if
      adoption picks up. Static site, single page, install command,
      quick-start, link to GitHub. Built only if PyPI download count
      exceeds 1,000 in a month.

================================================================================
ADOPTION TRACKING (internal consumers, current)
================================================================================

  - Aperintel-AI-Gateway: TypeScript port at lib/audit/
  - Rallova: TypeScript port at apps/api/src/lib/audit/
  - HydroFlow: TypeScript port at app/lib/audit/

Once nexuscone-ts ships, retire the three local ports in favour of
the shared package. Each retirement is a small PR per repo.

================================================================================
DO NOT BOTHER LIST (features explicitly out of scope)
================================================================================

  - WebAuthn or hardware-key signing (real but niche, Ed25519 layer
    is already strong).
  - Distributed / replicated mode across multiple nodes (out of scope
    for a primitive library; Nexus the commercial product handles this).
  - Audit-event taxonomy or pre-baked schemas (auth events, AI inference
    events, data-access events). Useful but does not differentiate
    cryptographically; adding it now risks turning Nexuscone from "the
    cryptographic primitive" into "an opinionated framework", which is
    the wrong shape for an open-core distribution.
  - TUF-style multi-key delegation. Useful but adds significant
    complexity; revisit only if a real enterprise customer requests it.
