Skip to content

docs(rfc-0001): extend §5 with OTLP-receiver acceptance criteria - #25

Merged
jensholdgaard merged 2 commits into
mainfrom
docs/rfc-0001-otlp-receiver-acceptance-criteria
May 14, 2026
Merged

docs(rfc-0001): extend §5 with OTLP-receiver acceptance criteria#25
jensholdgaard merged 2 commits into
mainfrom
docs/rfc-0001-otlp-receiver-acceptance-criteria

Conversation

@jensholdgaard

Copy link
Copy Markdown
Owner

Summary

The §6.1 amendment (#21) and §6.2 algorithm rewrite (#23) moved the miner's contract to consume OtlpLogRecord and introduced the body.kind fork plus the (severity_number, scope_name, …) template-key tuple — but no §5 acceptance criteria covered those commitments. RFC 0003 (#24) settled the receiver side; this PR closes the corresponding gap on the miner side. Wave 3 of the OTLP-alignment sequence (#20#21#22#23#24 → this).

Changes

Added six scenarios under the existing §5 structure (no new subsection, no new ID namespace):

  • §5.1 H1.4severity_number is part of the template key; no silent INFO/ERROR merge.
  • §5.1 H1.5scope_name is part of the template key; no cross-scope merge; None is its own bucket.
  • §5.2 §3.7.3 — Tenant derivation runs per ResourceLogs, not per export batch.
  • §5.3 RFC0001.9body_kind = Structured short-circuits to a structured-template id (locks the §6.2 step-0 fork).
  • §5.3 RFC0001.10time_unix_nano preserved verbatim from the wire (gates docs/benchmarks.md B1).
  • §5.3 RFC0001.11severity_number = 0 and scope_name = None are distinct key buckets.

Scenario IDs follow the H<n>.<m> / §3.<n>.<m> / RFC0001.<m> grammar already specified in docs/rfcs/README.md.

Invariant / hazard touch

  • H1 (template-merge correctness): H1.4 and H1.5 lock the new severity/scope discrimination — without them a future widening could silently coalesce across severity levels or scopes.
  • §3.7 (multi-tenancy not bolted on): §3.7.3 closes the per-ResourceLogs derivation rule; previously §3.7 only had cross-tenant scenarios at the cluster level.

H3 / §3.4 (WAL-before-ack) intentionally not added to RFC 0001's hazards-in-scope: the miner crate does not enforce H3 — RFC 0003 §6.5 (receiver) and the future ourios-wal RFC do.

Test plan

  • mdbook build clean locally
  • CI green
  • No code change — §6.x design content unchanged; only §5 normative scenarios added

🤖 Generated with Claude Code

The §6.1 amendment (PR #21) and §6.2 algorithm rewrite (PR #23)
moved the miner's contract to consume `OtlpLogRecord` and added
the `body.kind` fork plus the `(severity_number, scope_name, ...)`
template-key tuple — but no §5 acceptance criteria covered the
new commitments. RFC 0003 (PR #24) settled the receiver side; this
PR closes the corresponding gap on the miner side.

Added scenarios:

- §5.1 H1.4 — `severity_number` is part of the template key; no
  silent INFO/ERROR merge.
- §5.1 H1.5 — `scope_name` is part of the template key; no
  cross-scope merge; `None` is its own bucket.
- §5.2 §3.7.3 — Tenant derivation runs per `ResourceLogs`, not
  per export batch.
- §5.3 RFC0001.9 — `body_kind = Structured` short-circuits to a
  structured-template id (locks the §6.2 step-0 fork).
- §5.3 RFC0001.10 — `time_unix_nano` preserved verbatim from the
  wire (gates `docs/benchmarks.md` B1).
- §5.3 RFC0001.11 — `severity_number = 0` and `scope_name = None`
  are distinct key buckets.

Scenario IDs follow the existing `H<n>.<m>` / `§3.<n>.<m>` /
`RFC0001.<m>` grammar from `docs/rfcs/README.md` (no new
namespace introduced).

§6.x design content unchanged; this is purely §5 acceptance
criteria.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@jensholdgaard
jensholdgaard force-pushed the docs/rfc-0001-otlp-receiver-acceptance-criteria branch from f1adcf8 to 4141b89 Compare May 14, 2026 15:58
@jensholdgaard
jensholdgaard requested a review from Copilot May 14, 2026 16:03

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates RFC 0001’s §5 acceptance criteria to cover miner-side commitments introduced by the OTLP alignment work (severity/scope in the template key, structured-body short-circuit, per-ResourceLogs tenancy fan-out, and timestamp carry-through).

Changes:

  • Add hazard scenarios ensuring severity_number and scope_name participate in the template key (preventing silent cross-bucket merges).
  • Add an invariant scenario pinning tenant derivation to per-ResourceLogs semantics (not per export batch).
  • Add RFC-internal scenarios for the structured-body fork, verbatim time_unix_nano preservation, and edge buckets (severity_number=0, scope_name=None).
Comments suppressed due to low confidence (1)

docs/rfcs/0001-template-miner.md:577

  • Scenarios RFC0001.9–RFC0001.11 add new acceptance-criteria ids, but there are no matching test stubs yet (e.g. crates/ourios-miner/tests/rfc_internal.rs currently stops at RFC0001.8). To preserve the documented grep -R "RFC0001.9" . bidirectional mapping (RFC §5 preface / docs/verification.md §2.3), please add ignored test stubs for RFC0001.9–.11 (and update the §8 testing-strategy coverage lists accordingly).
> **Scenario RFC0001.9 — `body_kind = Structured` short-circuits to a structured-template id**
> - **Given** an `OtlpLogRecord` whose `body` is `AnyValue::Kvlist`
>   (or any non-`String` `AnyValue` variant)
> - **When** the record is ingested
> - **Then** the §6.2 algorithm skips tokenize/mask/descend per
>   step 0 and allocates or reuses the structured-template id
>   for `(severity_number, scope_name, BodyKind::Structured)`
> - **And** the emitted record has `body_kind = Structured`
> - **And** the `body` column carries the OTLP-canonical JSON
>   encoding produced upstream per RFC 0003 §6.4
> - **And** `params` and `separators` are empty

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/rfcs/0001-template-miner.md
Comment thread docs/rfcs/0001-template-miner.md
Addresses PR #25 review (verification.md §2.3 greppability):
every scenario id must appear in a test doc comment so
`grep -R "<id>" .` resolves bidirectionally between RFC and tests.

New stubs (all `#[ignore]` per the existing Red-gate pattern,
each with a `todo!()` pointing at the §6 section the
implementation lives in):

- crates/ourios-miner/tests/hazards.rs
  - H1.4 — `severity_number` is part of the template key
  - H1.5 — `scope_name` is part of the template key

- crates/ourios-miner/tests/invariants.rs
  - §3.7.3 — Tenant derivation runs per `ResourceLogs`. The
    test's doc comment also clarifies the layer split: this
    stub asserts the miner-side contract (per-record
    `tenant_id` correctness once records arrive); the
    receiver-side derivation test belongs to RFC 0003 §6.3.

- crates/ourios-miner/tests/rfc_internal.rs
  - RFC0001.9  — body_kind = Structured short-circuit
  - RFC0001.10 — time_unix_nano preserved verbatim
  - RFC0001.11 — severity = 0 / scope_name = None edge buckets

RFC 0001 §8 (Testing strategy) extended with two bullets so the
new ids are mapped to techniques in the same place §3.7.1/§3.7.2
and the existing scenarios are mapped:

- "Per-`ResourceLogs` tenant derivation (miner-side stub)" —
  covers §3.7.3, calls out the receiver-side ownership split.
- "OTLP-aligned template-key tests" — covers H1.4, H1.5,
  RFC0001.9, RFC0001.10, RFC0001.11.

Verified locally: `cargo fmt --check`, `cargo clippy --all-targets
--all-features -- -D warnings`, `cargo test --all-features`
(3 passed, 10 ignored, 0 failed), `mdbook build`, and
`grep -RIn <id>` resolves to RFC + test + §8 mapping for each
new id.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@jensholdgaard
jensholdgaard merged commit 5a5c389 into main May 14, 2026
7 checks passed
jensholdgaard added a commit that referenced this pull request May 22, 2026
* docs(roadmap): refresh §3 — Phase 2 closed, Phase 3 unblocked

Brings the "current state" snapshot up to date now that
PR-D through PR-G have landed `ourios-parquet` end-to-end.

- Date stamp bumped 2026-05-13 → 2026-05-22.
- RFC 0001 §5 scenarios green: 6 / 29 → 18 / 35 (the +6 is
  RFC 0001's OTLP scenarios added in PR #25; the +12 green is
  Phase 1's miner work — widening, type expansion, degenerate
  guard, three-zone confidence, reconstruct, OVERFLOW).
- Test-count headline: 48 / 23 → 225 / 18.
- Adds an `ourios-parquet` block listing the §3.2 / §3.7 /
  §3.4 / §3.9 surfaces actually in place: schemas, writer,
  reader, audit writer, audit reader, partition derivation,
  atomic publish + poisoning contract.
- Updates the per-crate `ourios-core` and `ourios-miner` blocks
  for the additions since the last snapshot (TenantConfig
  per-tenant overrides, AuditEvent / ParamType::Unknown,
  best-candidate attach, OVERFLOW, reconstruct).
- Updates the "blockers for thesis gates" table: A1/B1/B2
  now name `ourios-bench` and `ourios-querier` as the
  remaining pieces; the Parquet writer and reader are no
  longer blockers.
- Notes RFC 0005's status frontmatter is still `drafted`
  while 10 / 11 acceptance criteria are green — a follow-up
  maintainer sign-off bumps it to `green` once RFC0005.6's
  corpus fixture lands (or is explicitly deferred via §7's
  open question on slow-test CI cadence).

§4 (phase scope) and §5 (deferred capabilities) are
unchanged — WAL durability and OTLP wire endpoints stay
post-MVP per the existing deferral rationale.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fixup! docs(roadmap): refresh §3 — Phase 2 closed, Phase 3 unblocked

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.

2 participants