v0.123.0: reliability and review workflows

This release follows v0.108.0, the previous verified repository tag. Version numbers v0.109–v0.122 are skipped to avoid reusing the historical proposal identifiers. The old v0.109–v0.122 recaps are retained as explicitly unverified historical proposals; this work does not retroactively certify their implementation or verification claims.

The change makes deployment choices explicit, adds durable recovery for interrupted writes and feedback, and connects acquisition and ranking investigation to review workflows.

What's new

Area	Surface	Why it matters
Release truth	Recaps, release health, version checks	Separates shipped code from unsupported historical claims
Deployment	Strict modes, /v1/backends, listener startup and shutdown	Prevents silent backend fallback and partial server startup; Compose explicitly selects Postgres
Recovery	PendingWrites, RecoverPendingWrites, REST /recovery/*	Persists write/feedback intent before side effects, records completed stages, and exposes interrupted work for explicit reconciliation
Idempotency	Go WriteRequest.IdempotencyKey and NodeID	Reuses stable identities and rejects conflicting request payloads; local keyed locks are reclaimed and Postgres leases serialize matching operations
Retrieval	DSL edge types and graph-hydrated ANN results	Enforces requested relations, reflects current feedback, and excludes retracted candidates
Maintainability	Client capability files and CLI command files	Preserves the public facade while separating writes, review, acquisition, snapshots, and operational commands
Ranking debugger	evaluation_id and retained evaluation graphs	Inspects the actual fixture evidence that produced a ranking result instead of looking for fixture IDs in the live database
Baselines	Bounded browser-local history	Selects and deletes prior ranking reports; handles corrupt or unavailable storage
Acquisition review	review_before_admission, candidate list/approve/reject	Keeps newly acquired evidence outside the graph until explicitly approved, with retry-safe admission and decision audit
Central review	contextdb worker review, cycle and run APIs	Provides conservative rules and server-configured webhook evaluation, explicit action allow-lists, bounded cycles, durable summaries, and a manual lane for ambiguous failures
Access control	Optional exact-token registry	Validates configured secrets, enforces permissions/tenants, and protects REST, gRPC, GraphQL, and admin surfaces
SDKs	TypeScript, Python sync/async	Exposes acquisition review and worker APIs plus optional bearer-token configuration

Operator flow

1. Verify /v1/backends reports the intended stores. Standard mode requires a Postgres DSN. Use embedded mode explicitly for local persistence or memory.
2. Execute acquisition with review_before_admission: true. Inspect /acquisition/review/candidates; approve or reject with an actor and note. Staged candidates cannot influence graph retrieval.
3. Run contextdb worker review --url "$CONTEXTDB_URL" --namespace production --once to inspect a dry-run cycle. Explicitly select allowed actions and --execute when applying reviewed policy.
4. Inspect /review/worker/runs for the evaluator, decisions, counts, errors, and final status. A failure after mutation intent stays assigned for manual inspection instead of automatically repeating feedback.
5. For interrupted persistence, inspect /recovery/pending, then explicitly reconcile. Conflicts with later graph/source state stop recovery; inspect history and resolve the operator task rather than blindly resubmitting mutations.

See REST workflows, review worker, access control, and the work-unit plan.

Verification

Passed during implementation:

• Full Go suite and go vet ./....
• Race checks across ingest, retrieval, client, and server packages.
• Memory/Badger feedback, retraction, recovery, and restart tests.
• Live Postgres write/retrieve, advisory lease contention, and authenticated acquisition → approval → worker HTTP flow, including repeated candidate execution.
• Real gRPC negative authentication and permission tests.
• TypeScript mocked contract tests/build and Python sync/async mocked contracts. Existing opt-in SDK live-server tests are separately identified as skipped.
• Admin and documentation builds.

Container smoke and interactive browser checks also passed: the image runs against Postgres and completes doctor write/retrieve plus a worker dry run; ranking inspection renders the correct fixture evidence, and baselines survive reload and deletion. Full evidence and operating limits are recorded in the work-unit plan.

Compatibility and operating limits

Standard mode without a DSN and unsupported scaled mode now return errors. This intentionally changes previously misleading fallback behavior. Enforcing DSL filters can reduce results that previously traversed unrelated relations.

Recovery provides eventual repair, not a cross-store transaction. Partial effects may be visible while an intent is pending. Explicit keyed lookups and recovery currently scan namespace event history; indexed lookup remains follow-up work. Recovery conflicts need operator judgment.

Workers default to dry run and never auto-approve acquisition candidates. Postgres leases coordinate worker cycles and candidate/idempotent-write operations across processes. Embedded persistence uses its existing exclusive database ownership. Execute remote worker cycles through the server API rather than opening a remote store client to run the worker locally.

With no token registry, the local unauthenticated mode remains available and must not be exposed to untrusted networks. Configured read/write tokens are tenant-scoped; write includes that tenant's review and recovery operations. Admin tokens additionally access global admin, GraphQL, and low-level store APIs.

No provider-specific evaluator adapters, Norn deployment, or Hermes deployment are claimed. Browser baseline reports persist locally, while retained evaluation graphs are limited to the last three server evaluations; rerun evaluation after eviction or restart.

Next steps

1. Index operation and pending-intent lookup. Replace full event-history scans with backend-native indexed queries and benchmark large namespaces.
2. Expand fault coverage. Add Postgres disconnect/crash cases, longer scheduled soak, and representative recovery backlog performance thresholds.
3. Build the reviewer UI. Surface acquisition decisions, worker summaries, assigned/manual tasks, and pending recovery together using the APIs added here.
4. Measure evaluator usefulness. Use real task corpora and calibrated feedback before adding provider-specific adapters or automatic acquisition schedules.
5. Keep release evidence current. Attach CI health artifacts to releases and verify deployed backend identities after upgrades.