Skip to content

docs(adr): land ADR-0027 and ADR-0028 — close oath-model design for Equity MVP#49

Merged
NotAProfDev merged 1 commit into
mainfrom
docs/adr-0027-0028-closeout
Jun 28, 2026
Merged

docs(adr): land ADR-0027 and ADR-0028 — close oath-model design for Equity MVP#49
NotAProfDev merged 1 commit into
mainfrom
docs/adr-0027-0028-closeout

Conversation

@NotAProfDev

@NotAProfDev NotAProfDev commented Jun 28, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Owner

Closes #48.

Lands the two ADRs from the 2026-06-28 grill-with-docs session, which resolved the
last four open oath-model design questions (B1–B4) and closes its design for the
Equity MVP.

ADR-0027 — wire representation

  • B1 Timestamp = u64 UnixNanos UTC; time crate demoted to the adapter/display boundary.
  • B2 Serialize is the universal bound; the zero-copy/POD bound is backend-specific (shared-memory family: iceoryx2 / Aeron-IPC / mmap log-replay) via zerocopy (core::mem::TransmuteFrom reserved as the future stable replacement). Schema versioning is deferred pre-1.0 but reserved on the IncarnationStarted marker, with model-wide bumps.
  • B3 InstrumentId = [u8; 32] fixed self-identifying name — binding constraint is the OCC 21-char option symbol; FIGI/ISIN/PermID verified to fit. Discharges ADR-0025's length TBD.

ADR-0028 — type placement

  • B4 Shared contracts (cross a process boundary, or read by ≥2 subsystems) live in oath-model; */api crates hold traits + single-process privates. Signal/Instrument/Position → model; Decision → core-api.

Also

  • Grilling tracker updated (B1–B4 marked resolved).
  • README oath-strategy-api Signal line corrected (payload is model; api keeps the trait + ergonomics).

Docs-only; no code change. just ci green locally (pre-push gate).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Clarified where shared data and behavior live across the codebase, including guidance for cross-process contracts and API-only traits.
    • Added a new architecture decision record covering zero-copy wire formats, timestamp handling, schema-versioning, and fixed-size identifier rules.
    • Updated architecture notes to reflect these decisions and resolve previously open design questions.

@NotAProfDev @claude
docs(adr): land ADR-0027 and ADR-0028 for oath-model closeout
81e596d 
ADR-0027 fixes the wire representation: u64 UnixNanos Timestamp;
Serialize-universal with a backend-specific zero-copy bound via zerocopy
(TransmuteFrom reserved); deferred-but-reserved schema versioning on the
IncarnationStarted marker; InstrumentId = [u8; 32] self-identifying name
(discharges ADR-0025's length TBD). ADR-0028 sets the type-placement rule:
shared contracts live in oath-model, traits and single-process privates in
the */api crates (Signal/Instrument/Position placed; Decision stays in
core-api).

Updates the grilling tracker (B1-B4 resolved) and corrects the README
strategy-api Signal line. These four decisions close oath-model's design
for the Equity MVP; docs-only, no code change.

Closes #48

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7badceec-50c7-4599-8811-630ab29c26ee

📥 Commits

Reviewing files that changed from the base of the PR and between 1fff0f0 and 81e596d.

📒 Files selected for processing (4)
  • README.md
  • docs/adr/0027-wire-representation-zero-copy-layout-time-versioning.md
  • docs/adr/0028-type-placement-shared-contracts-in-model.md
  • docs/superpowers/specs/2026-06-23-from-scratch-architecture-grilling.md
📝 Walkthrough

Walkthrough

Adds two new ADRs: ADR-0027 formalizing wire representation rules (zero-copy families, zerocopy crate, Timestamp as u64 UnixNanos, InstrumentId as [u8; 32], deferred schema versioning via IncarnationStarted.schema_version), and ADR-0028 defining type placement rules (oath-model for shared payloads, */api for traits). Updates the architecture spec and corrects the README oath-strategy-api description.

Changes

Architecture docs and README correction

Layer / File(s) Summary
ADR-0028: Type placement rule and README correction
docs/adr/0028-type-placement-shared-contracts-in-model.md, README.md		 ADR-0028 defines that cross-process payloads and shared canonical records belong in oath-model while behavior traits stay in */api crates, with a placement matrix for Signal, Instrument, Position, Account, Source, and Decision. README row for oath-strategy-api is corrected to say "Signal ergonomics" with a note that the canonical Signal payload lives in oath-model.
ADR-0027: Wire representation, zero-copy, Timestamp, and InstrumentId
docs/adr/0027-wire-representation-zero-copy-layout-time-versioning.md		 Defines the two-tier binding model (universal Serialize/Deserialize vs. backend-specific zerocopy POD layout), splits zero-copy backends into shared-memory/in-place vs. stream/network families, specifies Timestamp as #[repr(transparent)] u64 UnixNanos UTC, InstrumentId as [u8; 32] NUL-padded ASCII, deferred schema versioning via IncarnationStarted.schema_version: u16, and enumerates rejected alternatives with consequences.
Architecture grilling spec resolutions
docs/superpowers/specs/2026-06-23-from-scratch-architecture-grilling.md		 Parked sub-questions updated with resolved entries for oath-model placement (ADR-0028), versioning/framing/zero-copy rules (ADR-0027), Timestamp representation, and InstrumentId fixed-length selection.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

Possibly related PRs

  • NotAProfDev/oath#47: ADR-0027 extends IncarnationStarted with schema_version for event-log versioning, which directly intersects with ADR-0026 from that PR defining IncarnationStarted-based boot generation for deterministic Order ID generation.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title follows Conventional Commits format and accurately summarizes the ADR-focused docs-only changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/adr-0027-0028-closeout

Comment @coderabbitai help to get the list of available commands.

@NotAProfDev NotAProfDev merged commit 52b1775 into main Jun 28, 2026
5 checks passed
@NotAProfDev NotAProfDev deleted the docs/adr-0027-0028-closeout branch June 28, 2026 11:33
NotAProfDev added a commit that referenced this pull request Jun 28, 2026
@NotAProfDev @claude
feat(model): numeric primitives (Price, Quantity, Side, ArithmeticErr…
85c79e3 
…or) (#51)

* docs(model): design oath-model numeric primitives (slice 1)

Approved brainstorming design for the first real oath-model content:
Price/Quantity/Side value types, checked exact-domain arithmetic, and
ArithmeticError. Reconciles the manifest (drop rust_decimal/uuid/time)
and aligns deferred work (zerocopy, Timestamp, symbology, notional) with
ADR-0023/0002/0020/0027.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(model): add oath-model numeric primitives implementation plan

Bite-sized TDD plan (6 tasks) for Price/Quantity/Side/ArithmeticError.
All code prototyped and verified against the workspace lints (clippy -D
warnings with pedantic/nursery), tests, doctests, cargo deny, and rustfmt.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(model): handle Cargo.lock in plan tasks 1 and 3

Removing/adding deps makes Cargo.lock stale; the pre-commit hook runs
cargo check --locked, which fails on a stale lock. Tasks 1 and 3 now
regenerate and commit Cargo.lock.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(model): drop rust_decimal, uuid, time deps (ADR-0023/0027)

* feat(model): add ArithmeticError

* feat(model): add Side direction enum

* feat(model): add Quantity magnitude newtype

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(model): add Price fixed-point newtype

* chore(gitignore): ignore cargo-mutants output

Running just mutants / mutants-diff leaves a mutants.out/ directory in the
working tree; ignore it (and mutants.out.old/) so it is never committed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(model): sharpen checked-op summaries and add Quantity doctest

Note both overflow and underflow in the Price/Quantity checked-op summaries
(the # Errors sections already did); 'rather than wrapping or panicking'
reflects overflow-checks=true. Add a Quantity checked_sub doctest, and
de-stale the spec's ADR-0027 reference now that #49 landed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(changelog): record oath-model numeric primitives

* test(model): drop needless String allocs in Side serde test

Use `.as_deref().ok()` to compare against `&str` literals instead of
allocating owned `String`s via `to_owned()`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs(adr): land ADR-0027 & ADR-0028 — close oath-model design for Equity MVP

1 participant

@NotAProfDev