Skip to content

Matters: documents sharing terms, advancing one state - #31

Merged
tbrooke merged 1 commit into
mainfrom
feat/matters
Sep 26, 2026
Merged

tbrooke merged 1 commit into
mainfrom
feat/matters

Conversation

@tbrooke

@tbrooke tbrooke commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

Step 2 of the matters work (docs/design/matters.md, #29). Builds on the document store (#30).

What

  • com.trustblocks.xtdb.matter: a matter is anchored to its terms, the stored instance every one of its documents shares (for STR-27, the executed contract; for a proceeding, its own record). The matter's state is that instance's execute/trigger! state. So everything Read contract state as of the request's own time; refuse late state changes #19 established holds for the matter unchanged: a document dated before a recorded state change is refused as out of order, concurrent documents can't lose an update, and state as of any date is a query.
    • open!: anchored to an existing instance.
    • add-document!: a document instance joins with a role and an effective date, optionally naming the stored file it came from (Store documents by content: a hash-addressed file store with XTDB records #30).
    • documents / matter-of: membership, bitemporal.
    • trigger!: advance the matter from one of its own documents.
    • state / history: as of any date, and what moved it.
  • execute/trigger! takes :document and records it on the execution row, so a matter's history names the document behind each change.
  • Refusals (:trustblocks/error):
    • an unknown matter, instance or stored file
    • an id that's already open
    • a document already in another matter
    • a document used from another matter, or before it joined
    • two matters on one terms instance, which would otherwise silently share one state (caught while writing the tests)

Verification

  • matter_test uses a small fixture model (test/fixtures/matter-documents.cto, a WorkOrder document) with the snow-removal contract as terms. It checks: state advanced once per document and read as of a past date; history naming each document; membership as of a past date; a late document refused as out of order; a document pointing at its stored file; every refusal.
  • bin/clj -M:run code-quality: 74 tests, 281 assertions, 0 failures; lint clean. Existing tests are unaffected by the trigger! addition.

🤖 Generated with Claude Code

Step 2 of the matters work (docs/design/matters.md).

- com.trustblocks.xtdb.matter: a matter is anchored to its terms -- the
  stored instance every document shares (for STR-27 the executed
  contract) -- and its state is that instance's execute/trigger! state, so
  out-of-order refusal, lost-update protection and as-of reads hold for
  the matter unchanged.
- open!, add-document! (a role, an effective date, optionally the stored
  file the instance came from), documents and matter-of (bitemporal
  membership), trigger! (advance the matter from one of its documents),
  state and history.
- execute/trigger! takes :document and records it on the execution, so a
  matter's history names the document that moved it.
- Refused: unknown matter, instance or stored file; an id already open;
  a document already in another matter, or used before it joined or from
  another matter; and two matters on one terms instance, which would
  otherwise silently share one state.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@tbrooke
tbrooke merged commit 6a9324c into main Sep 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant