Design the deepened Store interface

[George-RD]

Part of #182

Question

The transaction and audit-pairing discipline moves inside the Store implementation: BEGIN IMMEDIATE (~40 convention sites) and audit-before-effect (~74 convention sites) become structural; the pub(crate) conn escape hatch closes (one production bypass in skill/review.rs, ~9 test files of raw SQL); the store's upward reach into telegram:: is cut. The design must leave room for disposition-driven settlement writes (Effect Truth track #173/#174) and the identity audit dimension.

Users: Auditor, Unattended workhorse, Lyra. Promise: Ledger. Evidence: review, candidate 2.

Resolve per the handoff shape: grill + domain-model, then to-spec; link the spec issue here.

Blocked by

• Design the typed owner identity #188

[coderabbitai]

Coding Plan

Summary

Treat this ticket as a design deliverable. Produce an OpenSpec change proposal that specifies the deepened Store interface. Defer the full call-site refactor to a linked downstream spec issue.

Run the "grill + domain-model, then to-spec" handoff. First resolve external references (the missing architecture-review evidence, #173/#174, and the W6 blocker). Record decisions and terms. Then write the OpenSpec artifacts.

Specify four seams: a Store-owned BEGIN IMMEDIATE combinator, a Store-owned audit-before-effect combinator, a private conn field with test-only hooks, and a channel-neutral owner-verification token that removes the store -> telegram dependency.

Leave explicit extension points for disposition-driven settlement writes (Effect Truth) and the identity audit dimension. Include the authority-sensitive verification tasks the conventions require.

Design Choices

Design Choice 1: Concrete deliverable of this ticket

Options Considered:

1. Produce the full Store refactor (code changes across ~74 files) directly in this ticket.
2. Produce an OpenSpec change proposal (proposal.md, design.md, tasks.md, delta specs) that specifies the deepened Store interface, and open/link a spec issue.

Chosen Option: 2

Rationale: The ticket text and repository conventions both require a design/spec artifact for authority-sensitive changes. The actual code refactor is downstream implementation work. Track this work through the linked spec issue.

Design Choice 2: Location of new Store requirements in the spec tree

Options Considered:

1. Add all new requirements as ## MODIFIED Requirements in audit-artifact-store/spec.md.
2. Create a new capability spec (for example store-interface) for the encapsulation, transaction, and layering requirements. Use ## MODIFIED Requirements in audit-artifact-store/spec.md only where an existing requirement (per-aggregate sequencing under the store lock) is extended.
3. Spread requirements across many existing sibling specs.

Chosen Option: 2

Rationale: The deepened Store interface is a new architectural contract. A dedicated capability spec keeps it coherent. Modify the one overlapping existing requirement in place, per delta-spec convention.

Design Choice 3: Introduction of the channel-neutral owner-verification token

Options Considered:

1. Define a channel-neutral proof token (for example OwnerVerifiedContext) in a neutral module. Have each channel adapter construct it after its own verification.
2. Replace the token with a runtime boolean or string checked inside the Store.

Chosen Option: 1

Rationale: A neutral capability token preserves the existing static "owner-verified" guarantee. It matches the already-adopted channel-neutral responsibility-review pattern. It removes the store -> telegram type dependency without weakening the proof.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Grounding, Domain Modeling, and External Resolution

This phase runs the "grill + domain-model" stage. It resolves external references, records new domain terms and design decisions, and confirms the blockers before any spec text is written. Do not draft the OpenSpec change until this phase is complete.

Task 1: Resolve external references and the W6 blocker

Confirm the inputs the design depends on, because several referenced artifacts do not exist in the repository.

• Use gh issue view in George-RD/openspine to read #182 (parent), #173, and #174 (Effect Truth track). Confirm the meaning of the W6 blocker.
• Confirm the status of the evidence document .raw/openspine-architecture-review-2026-08-20.md. This file is not present in the current repository snapshot. If it is missing, retrieve its content from the linked GitHub location or record its absence as a design risk.
• Record the "Effect Truth", "disposition-driven settlement write", and "settlement" definitions from #173/Provably pre-effect ConnectorUnavailable rejection permanently retains the scoped standing-rule reservation #174. These terms do not yet exist anywhere in the codebase.
• Confirm that the W6 blocker is resolved before the change proposal is finalized. If W6 is not resolved, hold the proposal in draft.

Task 2: Capture new domain terms and design decisions

Ground the new vocabulary and decisions against the repository domain layer, per docs/agents/domain.md.

• Add or update CONTEXT.md and docs/adr/ entries for the new terms: the transaction combinator, the audit-before-effect combinator, the channel-neutral owner-verification token, and the settlement-write extension point.
• Record the decision to make Store.conn private and to route all write paths through Store-owned combinators.
• Record the decision to forbid store -> telegram (and other channel adapter) dependencies as a new architectural constraint.
• Cite the relevant decision-log entries (for example the D-050 BEGIN IMMEDIATE TOCTOU precedent), so the design references existing canon rather than restating it.

Task 3: Define the four Store seams as concrete design decisions

Fix the shape of each seam before writing spec text, so the design.md decisions are unambiguous.

• Transaction seam: define a single private combinator on Store (for example with_immediate_tx) that locks conn, opens a TransactionBehavior::Immediate transaction, runs a closure, and commits. Route all roughly 40 write sites in store/ through it. The existing Deferred read path in store/audit_support.rs::verify_and_replay_aggregate stays a separate read combinator.
• Audit-before-effect seam: define combinator(s) that pair an effect mutation with an append_audit_conn call inside one Immediate transaction. Formalize the two shapes already used in code: (a) rollbackable effects commit the effect row and the audit row atomically; (b) non-rollbackable external effects commit state and audit first, then perform the external effect with an idempotent retry marker.
• Encapsulation seam: change conn to a private field. Provide test-only access through store/test_hooks.rs helpers. Migrate the production bypass in skill/review.rs::record_verdict to call the existing Store::insert_eval_verdict method. Migrate the roughly nine raw-SQL store/*_tests.rs files to the Store API or to explicit test hooks.
• Layering seam: replace crate::telegram::VerifiedOwnerContext with a channel-neutral owner-verified token in a neutral module. Remove the crate::telegram::telegram_chat_id call in store/worker_dispatch.rs by accepting a channel-neutral rendering reference (for example the existing OwnerSurfaceRef) instead of computing a Telegram chat id inside the store.
• Extension points: define how disposition-driven settlement writes (#173/Provably pre-effect ConnectorUnavailable rejection permanently retains the scoped standing-rule reservation #174) attach to the audit-before-effect combinator, and how an identity audit dimension (bootstrap, owner-config mismatch rejection, and optionally resolution outcomes) extends the current single identity.bound audit kind without violating the read-only resolution invariant and without persisting raw identifiers.

🤖 Prompt for AI agents

This phase produces no code. It produces grounding documentation and decisions
that inform the OpenSpec artifacts written in later phases.

- Use `gh issue view` in `George-RD/openspine` to read issues `#182`, `#173`, and
`#174`. Confirm the meaning of the `W6` blocker.
- Check for the evidence document
`.raw/openspine-architecture-review-2026-08-20.md`. If it is absent, retrieve
its content from the linked GitHub location, or record its absence as a design
risk in the output notes.
- Record definitions for "Effect Truth", "disposition-driven settlement write",
and "settlement" from `#173/`#174.
- Confirm whether `W6` is resolved. If not resolved, note that the proposal must
stay in draft.
- Update `CONTEXT.md` and add `docs/adr/` entries for these new terms: the
transaction combinator, the audit-before-effect combinator, the channel-neutral
owner-verification token, and the settlement-write extension point.
- Record the decision to make `Store.conn` private, with all write paths routed
through Store-owned combinators.
- Record the decision to forbid `store -> telegram` (and other channel adapter)
dependencies.
- Cite relevant decision-log entries, including the D-050 `BEGIN IMMEDIATE`
TOCTOU precedent.
- Define the four Store seams as concrete decisions, exactly as specified: (1) a
private `with_immediate_tx`-style transaction combinator covering all `store/`
write sites, distinct from the existing `Deferred` read combinator in
`store/audit_support.rs::verify_and_replay_aggregate`; (2) an
audit-before-effect combinator supporting both the rollbackable-effect shape and
the non-rollbackable external-effect shape with idempotent retry marker; (3) a
private `conn` field with test-only access via `store/test_hooks.rs`, migration
of `skill/review.rs::record_verdict` to `Store::insert_eval_verdict`, and
migration of the raw-SQL `store/*_tests.rs` files; (4) a channel-neutral
owner-verified token replacing `crate::telegram::VerifiedOwnerContext`, and a
channel-neutral rendering reference (for example `OwnerSurfaceRef`) replacing
the `telegram_chat_id` call in `store/worker_dispatch.rs`.
- Define extension points for disposition-driven settlement writes and the
identity audit dimension, preserving the read-only resolution invariant and
hash-only identifier posture.

Phase 2: Author the OpenSpec Change Proposal

This phase runs the "to-spec" stage. It produces proposal.md and design.md in a new OpenSpec change directory under openspec/changes/. This is an authority-sensitive change (audit and recovery), so the artifacts must follow the authority-sensitive conventions.

Task 1: Create the change directory and write proposal.md

State what changes and why, at the level openspec/conventions.md requires.

• Create a new change directory under openspec/changes/ (for example deepen-store-interface).
• Write proposal.md with the observed archived-proposal sections: ## Summary, ## What Changes, ## Why, ## Affected layer, ## Authority sensitivity, ## Goals, ## Non-goals, ## Decision-log check, and ## Dependencies.
• In ## Dependencies, record the W6 blocker and the Effect Truth track (#173/Provably pre-effect ConnectorUnavailable rejection permanently retains the scoped standing-rule reservation #174).
• In ## Non-goals, state that this change specifies the interface and does not perform the full call-site migration, which is downstream implementation work.
• In ## Authority sensitivity, mark the change as authority-sensitive because it governs audit ordering and recovery.

Task 2: Write design.md

Specify how the deepened Store interface works, with trade-offs and rejected alternatives.

• Use the de facto archived design.md structure: ## Context, ## Goals / Non-Goals, numbered ## Decisions, ## Risks / Trade-offs, and ## Rejected alternatives.
• Document each of the four seams from Task 1.3 as a numbered decision.
• Include authority, containment, audit, and failure-mode considerations for each seam, as required by openspec/config.yaml design rules.
• Document the extension points for disposition-driven settlement writes and the identity audit dimension, so downstream tracks do not need to re-open the interface.
• Cite the PRD and decision-log entries when adopting or modifying existing architecture (for example the BEGIN IMMEDIATE precedent and the archived add-channel-neutral-responsibility-review change).
• List rejected alternatives, including keeping conn pub(crate), and using a runtime flag instead of a neutral proof token.

🤖 Prompt for AI agents

This phase writes two OpenSpec artifacts, `proposal.md` and `design.md`, in a
new change directory under `openspec/changes/` (for example
`deepen-store-interface`). No implementation code is written in this phase.

- Create the change directory.
- Write `proposal.md` with these sections, following the observed
archived-proposal structure: `## Summary`, `## What Changes`, `## Why`, `##
Affected layer`, `## Authority sensitivity`, `## Goals`, `## Non-goals`, `##
Decision-log check`, and `## Dependencies`.
- In `## Dependencies`, record the `W6` blocker and the Effect Truth track
(`#173/`#174).
- In `## Non-goals`, state that this change specifies the interface only. State
that it does not perform the full call-site migration. State that the migration
is downstream implementation work.
- In `## Authority sensitivity`, mark the change as authority-sensitive, because
it governs audit ordering and recovery.
- Write `design.md` using the sections: `## Context`, `## Goals / Non-Goals`,
numbered `## Decisions`, `## Risks / Trade-offs`, and `## Rejected
alternatives`.
- Document each of the four seams (transaction, audit-before-effect,
encapsulation, layering) as a numbered decision.
- For each seam, include authority, containment, audit, and failure-mode
considerations, as required by `openspec/config.yaml` design rules.
- Document the extension points for disposition-driven settlement writes and the
identity audit dimension.
- Cite the PRD and decision-log entries where existing architecture is adopted
or modified, including the `BEGIN IMMEDIATE` precedent and the archived
`add-channel-neutral-responsibility-review` change.
- List rejected alternatives, including keeping `conn` as `pub(crate)`, and
using a runtime flag instead of a neutral proof token.

Phase 3: Author Delta Specs, Tasks, and Validation

This phase writes the normative delta specs and the verification tasks, then validates the change and links the spec issue.

Task 1: Write the delta specs

Encode the new Store contract as testable requirements.

• Create a new capability spec delta (for example openspec/changes/<id>/specs/store-interface/spec.md) using ## ADDED Requirements.
• Add a requirement that all Store write paths MUST open the write transaction through the Store-owned BEGIN IMMEDIATE combinator, with at least one #### Scenario: block.
• Add a requirement that every effect write MUST be paired with its audit append under the same transaction, or, for non-rollbackable external effects, MUST commit audit and state before the external effect and MUST use an idempotent retry marker.
• Add a requirement that the raw connection MUST NOT be reachable from outside the store module, and that non-store production code MUST use Store methods.
• Add a requirement that the store module MUST NOT depend on channel adapter modules (for example telegram), and that owner-verification MUST be carried by a channel-neutral token.
• Add a delta to openspec/specs/audit-artifact-store/spec.md under ## MODIFIED Requirements where it extends the existing "per-aggregate sequence under the store lock" requirement to name the Store-owned transaction combinator.
• Add a requirement (or reserve requirement space) for the identity audit dimension that extends the identity-store audit posture beyond identity.bound, preserving the read-only resolution invariant and the hash-only identifier posture.

Task 2: Write tasks.md with explicit verification tasks

Provide the downstream implementation checklist and the authority-sensitive verification tasks.

• Write tasks.md describing the downstream migration: introduce the transaction and audit combinators, make conn private, add test hooks, migrate skill/review.rs, migrate the raw-SQL test files, and cut the telegram dependency.
• Add explicit verification tasks, required for authority-sensitive changes: audit-chain still verifies, no effect can commit without an audit row, and no store -> telegram import remains.
• Include the concrete verification commands ./scripts/check.sh and openspec validate --changes <change-id> --strict.

Task 3: Validate the change and link the spec issue

Confirm the proposal passes OpenSpec validation and connect it back to the tracker.

• Run openspec validate --changes <change-id> --strict and fix any structural errors.
• Open (or identify) the spec issue in George-RD/openspine and link it on ticket #182 via gh issue comment, as the ticket requires ("link the spec issue here").

🤖 Prompt for AI agents

This phase writes the delta specs, `tasks.md`, and performs validation and
linking. No implementation code is written.

- Create a new capability spec delta at
`openspec/changes/<id>/specs/store-interface/spec.md` using `## ADDED
Requirements`, with these requirements, each with at least one `#### Scenario:`
block where specified:
- All Store write paths MUST open the write transaction through the Store-owned
`BEGIN IMMEDIATE` combinator.
- Every effect write MUST be paired with its audit append under the same
transaction; for non-rollbackable external effects, audit and state MUST commit
before the external effect, and an idempotent retry marker MUST be used.
- The raw connection MUST NOT be reachable from outside the `store` module;
non-`store` production code MUST use `Store` methods.
- The `store` module MUST NOT depend on channel adapter modules (for example
`telegram`); owner-verification MUST be carried by a channel-neutral token.
- Add a delta to `openspec/specs/audit-artifact-store/spec.md` under `##
MODIFIED Requirements`, extending the existing "per-aggregate sequence under the
store lock" requirement to name the Store-owned transaction combinator.
- Add a requirement (or reserve requirement space) for the identity audit
dimension, extending the identity-store audit posture beyond `identity.bound`,
while preserving the read-only resolution invariant and the hash-only identifier
posture.
- Write `tasks.md` describing the downstream migration steps: introduce the
transaction and audit combinators, make `conn` private, add test hooks, migrate
`skill/review.rs`, migrate the raw-SQL test files, and cut the telegram
dependency.
- Add explicit verification tasks to `tasks.md`: confirm the audit chain still
verifies, confirm no effect can commit without an audit row, and confirm no
`store -> telegram` import remains.
- Include the concrete verification commands `./scripts/check.sh` and `openspec
validate --changes <change-id> --strict` in `tasks.md`.
- Run `openspec validate --changes <change-id> --strict` and fix any structural
errors found.
- Open or identify the spec issue in `George-RD/openspine`, and link it on
ticket `#182` via `gh issue comment`.

Research

The openspine-kernel crate stores state in a single SQLite connection. The connection is wrapped as pub(crate) conn: Arc<Mutex<Connection>> on the Store struct in crates/openspine-kernel/src/store/mod.rs.

Because conn is pub(crate), any module in the crate can lock the connection and run raw SQL. This escape hatch is used across 74 files and 323 call sites. It includes a production bypass in crates/openspine-kernel/src/skill/review.rs and about nine store/*_tests.rs files that run raw SQL.

Two write conventions are repeated by hand at every call site:

• BEGIN IMMEDIATE transactions (58 occurrences in store/).
• Audit-before-effect ordering (65 append_audit_conn( call sites) built on the append_audit_conn primitive in store/audit_append.rs.

The store module also reaches up into the sibling telegram module:

• store/identity.rs imports crate::telegram::VerifiedOwnerContext.
• store/worker_dispatch.rs calls crate::telegram::telegram_chat_id.

The repository uses OpenSpec change proposals as the design deliverable format. This format is governed by openspec/conventions.md. The closest existing formal Store contract is openspec/specs/audit-artifact-store/spec.md.

Issues are tracked as GitHub Issues in George-RD/openspine. Use the gh CLI to work with these issues.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase produces no code. It produces grounding documentation and decisions
that inform the OpenSpec artifacts written in later phases.

- Use `gh issue view` in `George-RD/openspine` to read issues `#182`, `#173`, and
`#174`. Confirm the meaning of the `W6` blocker.
- Check for the evidence document
`.raw/openspine-architecture-review-2026-08-20.md`. If it is absent, retrieve
its content from the linked GitHub location, or record its absence as a design
risk in the output notes.
- Record definitions for "Effect Truth", "disposition-driven settlement write",
and "settlement" from `#173/`#174.
- Confirm whether `W6` is resolved. If not resolved, note that the proposal must
stay in draft.
- Update `CONTEXT.md` and add `docs/adr/` entries for these new terms: the
transaction combinator, the audit-before-effect combinator, the channel-neutral
owner-verification token, and the settlement-write extension point.
- Record the decision to make `Store.conn` private, with all write paths routed
through Store-owned combinators.
- Record the decision to forbid `store -> telegram` (and other channel adapter)
dependencies.
- Cite relevant decision-log entries, including the D-050 `BEGIN IMMEDIATE`
TOCTOU precedent.
- Define the four Store seams as concrete decisions, exactly as specified: (1) a
private `with_immediate_tx`-style transaction combinator covering all `store/`
write sites, distinct from the existing `Deferred` read combinator in
`store/audit_support.rs::verify_and_replay_aggregate`; (2) an
audit-before-effect combinator supporting both the rollbackable-effect shape and
the non-rollbackable external-effect shape with idempotent retry marker; (3) a
private `conn` field with test-only access via `store/test_hooks.rs`, migration
of `skill/review.rs::record_verdict` to `Store::insert_eval_verdict`, and
migration of the raw-SQL `store/*_tests.rs` files; (4) a channel-neutral
owner-verified token replacing `crate::telegram::VerifiedOwnerContext`, and a
channel-neutral rendering reference (for example `OwnerSurfaceRef`) replacing
the `telegram_chat_id` call in `store/worker_dispatch.rs`.
- Define extension points for disposition-driven settlement writes and the
identity audit dimension, preserving the read-only resolution invariant and
hash-only identifier posture.
===============================================================================

Task: 2

This phase writes two OpenSpec artifacts, `proposal.md` and `design.md`, in a
new change directory under `openspec/changes/` (for example
`deepen-store-interface`). No implementation code is written in this phase.

- Create the change directory.
- Write `proposal.md` with these sections, following the observed
archived-proposal structure: `## Summary`, `## What Changes`, `## Why`, `##
Affected layer`, `## Authority sensitivity`, `## Goals`, `## Non-goals`, `##
Decision-log check`, and `## Dependencies`.
- In `## Dependencies`, record the `W6` blocker and the Effect Truth track
(`#173/`#174).
- In `## Non-goals`, state that this change specifies the interface only. State
that it does not perform the full call-site migration. State that the migration
is downstream implementation work.
- In `## Authority sensitivity`, mark the change as authority-sensitive, because
it governs audit ordering and recovery.
- Write `design.md` using the sections: `## Context`, `## Goals / Non-Goals`,
numbered `## Decisions`, `## Risks / Trade-offs`, and `## Rejected
alternatives`.
- Document each of the four seams (transaction, audit-before-effect,
encapsulation, layering) as a numbered decision.
- For each seam, include authority, containment, audit, and failure-mode
considerations, as required by `openspec/config.yaml` design rules.
- Document the extension points for disposition-driven settlement writes and the
identity audit dimension.
- Cite the PRD and decision-log entries where existing architecture is adopted
or modified, including the `BEGIN IMMEDIATE` precedent and the archived
`add-channel-neutral-responsibility-review` change.
- List rejected alternatives, including keeping `conn` as `pub(crate)`, and
using a runtime flag instead of a neutral proof token.
===============================================================================

Task: 3

This phase writes the delta specs, `tasks.md`, and performs validation and
linking. No implementation code is written.

- Create a new capability spec delta at
`openspec/changes/<id>/specs/store-interface/spec.md` using `## ADDED
Requirements`, with these requirements, each with at least one `#### Scenario:`
block where specified:
- All Store write paths MUST open the write transaction through the Store-owned
`BEGIN IMMEDIATE` combinator.
- Every effect write MUST be paired with its audit append under the same
transaction; for non-rollbackable external effects, audit and state MUST commit
before the external effect, and an idempotent retry marker MUST be used.
- The raw connection MUST NOT be reachable from outside the `store` module;
non-`store` production code MUST use `Store` methods.
- The `store` module MUST NOT depend on channel adapter modules (for example
`telegram`); owner-verification MUST be carried by a channel-neutral token.
- Add a delta to `openspec/specs/audit-artifact-store/spec.md` under `##
MODIFIED Requirements`, extending the existing "per-aggregate sequence under the
store lock" requirement to name the Store-owned transaction combinator.
- Add a requirement (or reserve requirement space) for the identity audit
dimension, extending the identity-store audit posture beyond `identity.bound`,
while preserving the read-only resolution invariant and the hash-only identifier
posture.
- Write `tasks.md` describing the downstream migration steps: introduce the
transaction and audit combinators, make `conn` private, add test hooks, migrate
`skill/review.rs`, migrate the raw-SQL test files, and cut the telegram
dependency.
- Add explicit verification tasks to `tasks.md`: confirm the audit chain still
verifies, confirm no effect can commit without an audit row, and confirm no
`store -> telegram` import remains.
- Include the concrete verification commands `./scripts/check.sh` and `openspec
validate --changes <change-id> --strict` in `tasks.md`.
- Run `openspec validate --changes <change-id> --strict` and fix any structural
errors found.
- Open or identify the spec issue in `George-RD/openspine`, and link it on
ticket `#182` via `gh issue comment`.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!