Evaluating Threadline

Copy Markdown View Source

Who this is for

This guide is for a technical evaluator or pilot host deciding whether Threadline fits a Phoenix + Ecto + PostgreSQL stack. It summarizes what maintainers prove in-repo and what you must prove in staging or production-like environments.

It is not a compliance procurement sign-off or legal attestation of your environment.

What Threadline 0.6.0 packages

Threadline 0.6.0 is the in-repo, doc, and Hex SSOT (mix.exs @version). See guides/adoption-pilot-backlog.md Distribution preflight for maintainer attestation and publish workflow evidence.

0.6.0 packages Evidence, Audit.transaction/3, and aligned operator surfaces that landed in-repo after 0.5.0; upgrade steps are semver-scoped in CHANGELOG.md and this guide.

Read CHANGELOG.md [0.6.0] for the Evidence plane (Threadline.Evidence, proof vocabulary, /audit/evidence), the blessed audited write path (Threadline.Audit.transaction/3), and operator/demo surfaces from the reference walkthrough.

Three layers (mental model)

Threadline separates concerns into three layers:

  • Capture — PostgreSQL trigger-backed row mutations (AuditTransaction, AuditChange).
  • Semantics — application-level actions binding actor, intent, correlation, and request/job context (AuditAction, ActorRef).
  • Exploration — timelines, exports, retention, redaction, and operator surfaces for investigation.

See guides/how-threadline-works.md for the full architecture narrative.

What maintainers prove in-repo (CI-class)

Maintainers exercise the library through named mix verify.* entrypoints and integration tests — not by citing ExUnit test counts as proof.

In-repo evidence includes:

  • Trigger capture and semantics APIs under test/threadline/.
  • Evidence plane vocabulary, Threadline.Evidence, and mix threadline.evidence.show.
  • mix verify.* ladder and mix verify.doc_contract — doc-contract tests lock public prose to code.
  • PgBouncer transaction-mode class via verify-pgbouncer-topology (mix verify.topology, mix verify.threadline through a transaction pooler).
  • Reference app CI-class HTTP paths via mix verify.example (examples/threadline_phoenix).
  • Hex-published install path via mix verify.hex_evaluator (priv/ci/hex_evaluator depends on {:threadline, "~> 0.6"} from hex.pm — not a path dep).

What integrators must prove (host-class)

Threadline does not operate your staging stack. Host-owned evidence covers:

  • Auth and tenancy — who may read audit data in your app.
  • Production or staging topology — app → pooler → Postgres chain, pool mode, and Ecto pool settings matching how you run.
  • Your HTTP and Oban (or job) audited paths — routes and workers that perform audited writes in your deployment.
  • Backups / PITR vs retention and redaction policy review — operational choices outside library CI.

Use guides/production-checklist.md for the checklist shape. For how maintainers accept short in-repo indexes (tables, redacted links) without vouching for third-party environments, read CONTRIBUTING.md § Host STG evidence.

How to verify (evaluator ladder)

  1. mix deps.get — resolve dependencies from the tree you are evaluating.
  2. Full contributor gate — DB_PORT=5433 MIX_ENV=test mix ci.all when Postgres is available (see CONTRIBUTING.md for Compose port 5433 and env setup). The chain runs: mix verify.format → mix verify.credo → mix compile --warnings-as-errors → mix verify.compile_no_optional → mix verify.test → mix verify.threadline → mix verify.example → mix verify.doc_contract.
  3. Targeted checks — mix verify.doc_contract, mix verify.example, and/or mix verify.hex_evaluator when you only need doc, reference-app, or Hex-install proof.
  4. Optional Track A (sigra-reference) — walk examples/threadline_phoenix per its README and walkthrough docs.
  5. Optional Track B automation — see guides/adoption-evidence-playbook.md for the full demo tour, ConnCase proofs (walkthrough_*_test.exs, track_a_golden_path_test.exs), and optional mix verify.example_browser (Playwright).

Cite entrypoint names only when recording evidence — do not substitute test counts for proof.

Explicit non-claims

Threadline is:

  • Not a SIEM or generic security analytics product.
  • Not a compliance platform, legal hold system, or immutable archive beyond your host runtime/storage contract.
  • Not a Threadline-owned RBAC or tenancy DSL — authorization stays in your app.
  • Not a claim that Threadline maintainers have validated your staging topology — maintainers prove CI-class library paths; integrators own STG realism for HTTP and job paths.

Pilot next step

When you are ready to run a staging pilot, copy the scaffolds in guides/adoption-pilot-backlog.md:

  • STG-HOST-TOPOLOGY-TEMPLATE — one row per environment (pooler chain, pool mode, sandbox note, evidence link).
  • STG-AUDITED-PATH-RUBRIC — HTTP and job paths with OK / Issue / N/A / Not run and reproducible pointers.

Fill templates in your repo or fork; open a modest PR if you want a short in-repo index merged here. Maintainers review modesty, redaction, and link hygiene only.

For lane and upgrade narrative, read guides/upgrade-path.md. For the phx-gen-auth-reference lane, read guides/integrations/phx-gen-auth.md. You prove auth and tenancy in staging; maintainers prove the phx.gen.auth reference path via root integration tests and the Sigra reference path via mix verify.example — neither auth integration is required to adopt Threadline capture and semantics.