feat(events): implement Emitter + event types against #505 interface (TDD against bash byte-oracle if central; disclose if scattered)

bosun commented

2026-07-25 21:03:45 +02:00

Owner

Implement internal/events package satisfying the Go interface landed in #505.

Motivation

Phase 2 continues contract-driven TDD-per-phase per ADR-0009 §3.1. internal/events is one of two Phase 2 packages (sibling: #527 config). Interface (Emitter, event types) is Surveyor-approved in #505; implementation lands here.

Scope

internal/events/*.go — implementation satisfying #505 interface (Emitter.Emit + typed event structs)
Bash byte-oracle: existing bash event emission (verify: might be printf statements in orchestrators, or a dedicated lib/events.sh if it exists). If bash emission is scattered rather than centralized, note it in PR body — Go impl may become the new authoritative surface.
TDD approach (contract-driven per ADR-0009 §3.1):
1. Test against interface first
2. Oracle harness case using internal/harness (reuse Phase-1 vehicle)
3. Implementation to green
Event taxonomy: names + payload shapes documented as C-adjacent (may earn a small contract doc under docs/architecture/contracts/ if the taxonomy is non-trivial; Engineer's judgment on whether to add or defer)

AC

internal/events implementation compiles + all #505 interface methods satisfied — verified in PR#531 4757790; never-abort #159 upheld (no sentinel, swallows nil/failing sink)
Unit tests green — verified in PR#531 gate run
Equivalence-harness cases against bash oracle green — events IS central (event_emit in 3.4K lib) so real byte-oracle. Surveyor REPRODUCED jq-byte-match claim across byte range + probed for undisclosed neighbors (b/f) which reproduction FALSIFIED, confirming boundary COMPLETE (not just accurate). Verdict-trailing byte-identity + ts-determinism seam verified (review 4557); mutation-verified teeth
Event taxonomy documented at docs/architecture/contracts/events.md per AC4 — verified in PR#531
go vet ./... + golangci-lint run clean — verified: gate own instrument fired, all clean

Depends on: #505 (interfaces), #503 (harness vehicle from Phase 1)
Sibling: #527 (config — parallelizable OR sequential Engineer continuation)
Refs ADR-0009 §3.1 (contract-driven TDD), §3.3 phase 2 row, §5 (fail-loud + trivalent-verdict discipline)

Anchor

Filed 2026-07-25 by Bosun on operator continuation direction for Phase 2 dispatch.

Implement `internal/events` package satisfying the Go interface landed in #505. ## Motivation Phase 2 continues contract-driven TDD-per-phase per ADR-0009 §3.1. `internal/events` is one of two Phase 2 packages (sibling: [[#527 config]]). Interface (`Emitter`, event types) is Surveyor-approved in #505; implementation lands here. ## Scope - `internal/events/*.go` — implementation satisfying #505 interface (Emitter.Emit + typed event structs) - **Bash byte-oracle**: existing bash event emission (verify: might be `printf` statements in orchestrators, or a dedicated `lib/events.sh` if it exists). If bash emission is scattered rather than centralized, note it in PR body — Go impl may become the new authoritative surface. - **TDD approach** (contract-driven per ADR-0009 §3.1): 1. Test against interface first 2. Oracle harness case using `internal/harness` (reuse Phase-1 vehicle) 3. Implementation to green - **Event taxonomy**: names + payload shapes documented as C-adjacent (may earn a small contract doc under `docs/architecture/contracts/` if the taxonomy is non-trivial; Engineer's judgment on whether to add or defer) ## AC - [x] `internal/events` implementation compiles + all `#505` interface methods satisfied — verified in PR#531 4757790; never-abort #159 upheld (no sentinel, swallows nil/failing sink) - [x] Unit tests green — verified in PR#531 gate run - [x] Equivalence-harness cases against bash oracle green — events IS central (event_emit in 3.4K lib) so real byte-oracle. Surveyor REPRODUCED jq-byte-match claim across byte range + probed for undisclosed neighbors (b/f) which reproduction FALSIFIED, confirming boundary COMPLETE (not just accurate). Verdict-trailing byte-identity + ts-determinism seam verified (review 4557); mutation-verified teeth - [x] Event taxonomy documented at `docs/architecture/contracts/events.md` per AC4 — verified in PR#531 - [x] `go vet ./...` + `golangci-lint run` clean — verified: gate own instrument fired, all clean ## Related - Depends on: #505 (interfaces), #503 (harness vehicle from Phase 1) - Sibling: #527 (config — parallelizable OR sequential Engineer continuation) - Refs ADR-0009 §3.1 (contract-driven TDD), §3.3 phase 2 row, §5 (fail-loud + trivalent-verdict discipline) ## Anchor Filed 2026-07-25 by Bosun on operator continuation direction for Phase 2 dispatch.

bosun added this to the Phase 2 — Config + events milestone

2026-07-25 21:03:45 +02:00

bosun added the

priority/high

size/M

kind/feature

labels

2026-07-25 21:03:45 +02:00

engineer referenced this issue

2026-07-25 21:29:24 +02:00

feat(config): implement Loader + Config against #505 interface + C1 schema (#527) #530

engineer self-assigned this

2026-07-25 21:32:35 +02:00

bosun referenced this issue

2026-07-25 21:38:41 +02:00

feat(config): implement Loader + Config against #505 interface + #504 C1 schema (TDD against bash byte-oracle) #527

bosun referenced this issue

2026-07-25 21:38:42 +02:00

feat(config): implement Loader + Config against #505 interface + #504 C1 schema (TDD against bash byte-oracle) #527

engineer referenced this issue from a commit

2026-07-25 21:44:44 +02:00

docs(config): correct frozen field-doc enum examples + harden #74 gate (#527 review 4555)

engineer referenced this issue from a commit

2026-07-25 21:44:44 +02:00

feat(events): implement Emitter + event types against #505 interface (#528)

engineer referenced this issue

2026-07-25 21:45:38 +02:00

feat(events): implement Emitter + event types against #505 interface (#528) #531

bosun closed this issue

2026-07-25 21:54:25 +02:00

bosun commented

2026-07-25 21:54:25 +02:00

Author

Owner

Closed by hand — PR#531 merged as 475779047964de3329a1c6ac7572759a8a651c03 on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above.

Two commits landed:

C1 (docs): S1 + nit-a + nit-b fold from #527/#530 Surveyor review 4555 (frozen Config field-doc enum corrections, ErrNotFound comment, gate Skipf→Errorf). Consolidated into #528 (not separate follow-up PR) — cleaner shape, disjoint files from events (config/interface.go+config_test.go vs events/*).
C2 (events): internal/events port byte-faithful to event_emit, Emit → {ts,kind,...fields[,verdict]} single JSON line, SetEscapeHTML(false)==jq -c byte-match verified across domain, DEL/U+2028/9 boundary disclosed + Surveyor probed for undisclosed neighbors (\b/\f) which reproduction falsified (boundary COMPLETE not just accurate).

Substrate landed:

events emission wire-format authoritative (Go impl is new authoritative surface since bash event_emit is 3.4K lib)
Verdict-trailing-field byte-identity verified
Never-abort #159 upheld (no sentinel; swallows nil/failing sink; #159 contract-captured)
ts-format contract pinned in events.md (Phase-6 producers job for gen)
Event taxonomy documented at docs/architecture/contracts/events.md

No must-fix, no should-consider — cleanest Phase 2 PR per Surveyor 3917.

Cross-references:

ADR-0009 §3.1 (contract-driven TDD), §3.3 phase 2 row, §5 (fail-loud + trivalent-verdict discipline)
Depends on: #505 (interfaces), #503 (harness vehicle from Phase 1)
Sibling: #527 (config — closed prior with substrate anchors)

Phase 2 core scope COMPLETE: 2/2 core trackers closed (#527 + #528). Follow-ups remain on milestone #74:

#529 (config.schema.json reconcile) — dispatchable Phase 2 hygiene continuation
#337 (broaden version-file basenames) — separate, coordinated bash+Go+schema change needed

Milestone #74 disposition: close alongside this tracker close (Phase 2 core done; #529 + #337 move off milestone as follow-ups per Engineer + Surveyor consensus in bus 63b6 + 3917).

**Closed by hand** — PR#531 merged as `475779047964de3329a1c6ac7572759a8a651c03` on v2/next (fast-forward). All 5 ACs ticked with substrate anchors above. **Two commits landed**: - **C1 (docs)**: S1 + nit-a + nit-b fold from #527/#530 Surveyor review 4555 (frozen Config field-doc enum corrections, ErrNotFound comment, gate Skipf→Errorf). Consolidated into #528 (not separate follow-up PR) — cleaner shape, disjoint files from events (config/interface.go+config_test.go vs events/*). - **C2 (events)**: `internal/events` port byte-faithful to `event_emit`, Emit → `{ts,kind,...fields[,verdict]}` single JSON line, `SetEscapeHTML(false)==jq -c` byte-match verified across domain, DEL/U+2028/9 boundary disclosed + Surveyor probed for undisclosed neighbors (`\b`/`\f`) which reproduction falsified (boundary COMPLETE not just accurate). **Substrate landed**: - events emission wire-format authoritative (Go impl is new authoritative surface since bash `event_emit` is 3.4K lib) - Verdict-trailing-field byte-identity verified - Never-abort #159 upheld (no sentinel; swallows nil/failing sink; #159 contract-captured) - ts-format contract pinned in `events.md` (Phase-6 producers job for gen) - Event taxonomy documented at `docs/architecture/contracts/events.md` **No must-fix, no should-consider** — cleanest Phase 2 PR per Surveyor 3917. **Cross-references**: - ADR-0009 §3.1 (contract-driven TDD), §3.3 phase 2 row, §5 (fail-loud + trivalent-verdict discipline) - Depends on: #505 (interfaces), #503 (harness vehicle from Phase 1) - Sibling: #527 (config — closed prior with substrate anchors) **Phase 2 core scope COMPLETE**: 2/2 core trackers closed (#527 + #528). Follow-ups remain on milestone #74: - #529 (config.schema.json reconcile) — dispatchable Phase 2 hygiene continuation - #337 (broaden version-file basenames) — separate, coordinated bash+Go+schema change needed Milestone #74 disposition: close alongside this tracker close (Phase 2 core done; #529 + #337 move off milestone as follow-ups per Engineer + Surveyor consensus in bus 63b6 + 3917).

bosun referenced this issue

2026-07-26 09:49:54 +02:00

feat(forgejo): implement Client (17-function surface) + typed request/response against #505 interface + #504 C7 contract #541

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

docs(config): correct frozen field-doc enum examples + harden #74 gate (#527 review 4555)

engineer referenced this issue from a commit

2026-07-26 21:48:40 +02:00

feat(events): implement Emitter + event types against #505 interface (#528)

engineer referenced this issue from a commit

2026-07-26 22:12:42 +02:00

docs(config): correct frozen field-doc enum examples + harden #74 gate (#527 review 4555)