-
Notifications
You must be signed in to change notification settings - Fork 1
feat(zeta-id): C# oracle integration — 2nd peer oracle (12/12 cross-verify with TS) + Rust/Python backlog rows #4522
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
AceHack
merged 11 commits into
main
from
feat/zeta-id-csharp-oracle-integration-2026-05-21
May 21, 2026
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
ab920ce
feat(zeta-id): C# oracle integration + Rust/Python backlog rows
AceHack 74b8773
fix(zeta-id): address 6 Codex+CodeQL review findings on PR #4522
AceHack 9594bd5
fix(zeta-id): address 2 more Copilot review findings on PR #4522
AceHack 28368c7
fix(zeta-id): CodeQL Path.Combine→Path.Join refactor (final 2 threads…
AceHack e4d9ad4
fix(zeta-id): bounds-check Authority.Raw + Timestamp + drop unused us…
AceHack b5e20dd
fix(ci): markdownlint MD007/MD018 in B-0681 + grandfather 2 new pre-e…
AceHack a9c113d
fix(zeta-id): validate narrow enum fields before bit-packing (Codex P…
AceHack 4af6eca
docs(backlog): file B-0684 — clock-protocol negotiation stack sequenc…
AceHack cb21e72
fix(zeta-id): address 7 Codex+Copilot review findings on PR #4522 (po…
AceHack b114571
fix(zeta-id): reject Authority.Raw / Momentum.Raw values that alias n…
AceHack edaa8bd
docs(research): preserve Aaron-Kestrel 2026-05-21 ZetaId V1 review tr…
AceHack File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
87 changes: 87 additions & 0 deletions
87
docs/backlog/P2/B-0679-zeta-id-rust-implementation-2026-05-21.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| --- | ||
| id: B-0679 | ||
| priority: P2 | ||
| status: open | ||
| title: ZetaId V1 — Rust implementation as full peer oracle | ||
| tier: research-grade | ||
| effort: M | ||
| ask: maintainer Aaron + Mika 2026-05-21 | ||
| created: 2026-05-21 | ||
| last_updated: 2026-05-21 | ||
| depends_on: [] | ||
| composes_with: [B-0635, B-0636, B-0644, B-0665, B-0666] | ||
| tags: [zeta-id, multi-oracle, rust, cross-verification] | ||
| type: feature | ||
| --- | ||
|
|
||
| # ZetaId V1 — Rust implementation as full peer oracle | ||
|
|
||
| ## Context | ||
|
|
||
| The V1 ZetaId 128-bit canonical observation contract landed via PR #4517 | ||
| (constitutional substrate + TS oracle) + PR #4519 (review-finding fixes) + | ||
| the in-flight C# integration (PR after this row files). | ||
|
|
||
| Per `.claude/rules/m-acc-multi-oracle-end-user-moral-invariants.md`, all | ||
| implementations are FULL PEER ORACLES — no single language is source of | ||
| truth; multi-oracle agreement IS the verification. Rust joins as the 4th | ||
| oracle after the F# + TS + C# trio is stable. | ||
|
|
||
| ## Scope | ||
|
|
||
| Add a Rust crate at `src/Core.Rust.ZetaId/` (or similar layout matching | ||
| Zeta's existing Rust conventions, if any): | ||
|
|
||
| - `Cargo.toml` | ||
| - `src/lib.rs` — `Authority` enum (with `Raw(u8)` variant), `Momentum` | ||
| enum (with `Raw(u8)` variant), `ZetaObservation` struct, `IdVersion` | ||
| / `Chromosome` / `Category` / `Firefly` / `Persona` / `Location` enums | ||
| - `src/bit_layout.rs` — computed offsets with reserved-bits at offset 69 | ||
| + offsets 32-34 (per `docs/zeta-id-v1-layout.yaml`) | ||
| - `src/zeta_id.rs` — `pack(obs, env)` requires `&dyn SimulationEnvironment` | ||
| (or trait); `unpack(id)` inverse; same canonical hex as TS + F# + C# | ||
| - `tests/cross_verify.rs` — reads `tests/cross-verification/zeta-id/vectors.yaml` | ||
| via `serde_yaml` + writes `rust-output.json` to the same directory | ||
| - `compare.ts` becomes 4-way deep-equal across `ts-output.json` + | ||
| `cs-output.json` + `fsharp-output.json` + `rust-output.json` | ||
|
|
||
| ## Acceptance | ||
|
|
||
| - `cargo build --release` clean (0 warnings, 0 errors) | ||
| - `cargo test cross_verify --release` produces `rust-output.json` with | ||
| 12/12 `roundtrip_ok: true` AND 12/12 `matches_expected: true` | ||
| - `bun tests/cross-verification/zeta-id/compare.ts` reports 4-way agreement | ||
| - F# Authority cases (HumanVerified=31, TrustedAgent=20, Standard=15, | ||
| BestEffort=8, Simulated=3) + Momentum cases (Background=32, Normal=96, | ||
| Elevated=160, High=224, Critical=248) match exactly | ||
| - Test paste-verified in commit message (compile-and-test-first per the | ||
| V1 V8→V9 lesson) | ||
|
|
||
| ## Discipline reminders (from V1 cycle) | ||
|
|
||
| - **Compile-and-test-first**: do not claim "verified locally" without | ||
| pasting actual `cargo test` output. The V1 cycle proved 8 rounds of | ||
| speculative review missed bugs that empirical compile caught first try. | ||
| - **Reserved bits in BitLayout**: 1 bit at offset 69 (between Chromosome | ||
| and Category), 3 bits at offsets 32-34 (between Location and Randomness). | ||
| Don't pack contiguously — that's the exact bug C# V8 hit before fix-up. | ||
| - **No silent-zero fallback on randomness**: `pack` requires an explicit | ||
| environment parameter. Provide `DETERMINISTIC_ENV` (always 0, for | ||
| cross-verify) and `DEFAULT_ENV` (cryptographic, for production). | ||
| - **Cross-verify exits non-zero on mismatch**: `process::exit(1)` when any | ||
| hex or roundtrip mismatches. No silent-non-enforcing harness. | ||
|
|
||
| ## Non-goals | ||
|
|
||
| - Smart deserialization + anchors (separate B-NNNN once TS prototypes it) | ||
| - CloudEvents envelope wrapping (separate B-NNNN; rich layer, not the | ||
| bit-packed core) | ||
| - `registry/locations.yaml` provider-mapping (separate B-NNNN per `Location.cs` | ||
| inline note) | ||
| - Performance benchmarking (Phase 2 follow-up; correctness first) | ||
|
|
||
| ## Why P2 | ||
|
|
||
| Important for multi-oracle resilience but doesn't block V1 substrate | ||
| landing. Implementation work waits until F# V9 + smart-deser TS prototype | ||
| land cleanly. |
88 changes: 88 additions & 0 deletions
88
docs/backlog/P2/B-0680-zeta-id-python-implementation-2026-05-21.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| --- | ||
| id: B-0680 | ||
| priority: P2 | ||
| status: open | ||
| title: ZetaId V1 — Python implementation as full peer oracle | ||
| tier: research-grade | ||
| effort: M | ||
| ask: maintainer Aaron + Mika 2026-05-21 | ||
| created: 2026-05-21 | ||
| last_updated: 2026-05-21 | ||
| depends_on: [B-0679] | ||
| composes_with: [B-0635, B-0636, B-0644, B-0665, B-0666] | ||
| tags: [zeta-id, multi-oracle, python, cross-verification] | ||
| type: feature | ||
| --- | ||
|
|
||
| # ZetaId V1 — Python implementation as full peer oracle | ||
|
|
||
| ## Context | ||
|
|
||
| 5th peer oracle for the V1 ZetaId 128-bit canonical observation contract. | ||
| Per `.claude/rules/m-acc-multi-oracle-end-user-moral-invariants.md`, Python | ||
| is a full peer oracle (same canonical vectors, same hex contract, same | ||
| exit-on-mismatch discipline) — no carve-out as "scripting reference." | ||
|
|
||
| Python's role: ecosystem reach for agents/data/tooling/scripting. Python | ||
| slower than Rust/C# is fine; correctness is the contract, not performance. | ||
|
|
||
| ## Scope | ||
|
|
||
| Add a Python package at `src/Core.Python.zeta_id/` (or per repo Python | ||
| conventions, if any): | ||
|
|
||
| - `pyproject.toml` (using `uv` per Zeta convention if applicable) | ||
| - `src/zeta_id/__init__.py` — public API | ||
| - `src/zeta_id/types.py` — `Authority` + `Momentum` as discriminated | ||
| unions (PEP 695 / typing.Union[NamedTuple, ...] or dataclasses with | ||
| `kind` discriminator); `ZetaObservation` dataclass; `IdVersion` / | ||
| `Chromosome` / `Category` / `Firefly` / `Persona` / `Location` enums | ||
| - `src/zeta_id/bit_layout.py` — computed offsets with reserved bits per | ||
| `docs/zeta-id-v1-layout.yaml` (1 bit at offset 69, 3 bits at offsets 32-34) | ||
| - `src/zeta_id/codec.py` — `pack(obs, env)` requires explicit env; | ||
| `unpack(id)` inverse; uses Python's arbitrary-precision int for the | ||
| 128-bit value (no UInt128 in stdlib) | ||
| - `tests/test_cross_verify.py` — reads `tests/cross-verification/zeta-id/vectors.yaml` | ||
| via `pyyaml` or `ruamel.yaml`; writes `python-output.json` to same dir | ||
| - `compare.ts` becomes 5-way deep-equal: TS + F# + C# + Rust + Python | ||
|
|
||
| ## Acceptance | ||
|
|
||
| - `uv sync && uv run pytest tests/test_cross_verify.py -v` clean | ||
| (1 pass, 0 fail) | ||
| - `python-output.json` shows 12/12 `roundtripOk: true` + 12/12 | ||
| `matchesExpected: true` | ||
| - `bun tests/cross-verification/zeta-id/compare.ts` reports 5-way | ||
| agreement across all oracles | ||
| - Test output paste-verified in commit message | ||
| - Authority + Momentum byte values match the F# AuthorityValue / | ||
| MomentumValue exact constants (31/20/15/8/3 + 32/96/160/224/248) | ||
|
|
||
| ## Discipline reminders | ||
|
|
||
| Same as B-0679 (Rust): compile-and-test-first, reserved-bit gap at 69, | ||
| no silent-zero randomness, exit non-zero on mismatch. Python's loose | ||
| typing makes empirical verification MORE important, not less. | ||
|
|
||
| ## Why depends_on B-0679 | ||
|
|
||
| Sequencing: Rust lands 4th, Python lands 5th. Rust's compile-time | ||
| discipline (similar to F#/C# strictness) catches more bugs early; Python | ||
| benefits from Rust having already shaken out any spec-drift not caught | ||
| by the V1 cycle's TS+C# pair. | ||
|
|
||
| If Rust hits unexpected issues that change the spec interpretation, | ||
| Python adopts the corrected interpretation; doing them in sequence | ||
| avoids 2x rework. | ||
|
|
||
| ## Non-goals | ||
|
|
||
| Same as B-0679 — smart deser, CloudEvents wrapping, registry/locations.yaml | ||
| all separate B-NNNNs. | ||
|
|
||
| ## Why P2 | ||
|
|
||
| Same reasoning as B-0679 — important for multi-oracle resilience but | ||
| doesn't block V1 substrate landing. Python's ecosystem reach makes this | ||
| high-leverage once Rust validates the spec interpretation across one more | ||
| strict-typed language. |
110 changes: 110 additions & 0 deletions
110
docs/backlog/P2/B-0681-zeta-id-v2-spec-hardening-2026-05-21.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| id: B-0681 | ||
| priority: P2 | ||
| status: open | ||
| title: ZetaId v2 — entropy budget + HLC monotonicity + Firefly bit drop + vocabularies DRAFT marker | ||
| tier: research-grade | ||
| effort: M | ||
| ask: maintainer Aaron + Kestrel-claude.ai 2026-05-21 | ||
| created: 2026-05-21 | ||
| last_updated: 2026-05-21 | ||
| depends_on: [] | ||
| composes_with: [B-0635, B-0666, B-0679, B-0680] | ||
| tags: [zeta-id, v2-spec, kestrel-sharpening] | ||
| type: feature | ||
| --- | ||
|
|
||
| # ZetaId v2 — spec hardening from Kestrel review | ||
|
|
||
| ## Context | ||
|
|
||
| Kestrel (claude.ai) provided substantive ZetaId V1 review 2026-05-21 | ||
| covering entropy budget, semantic-vs-identity, draft vocabularies, | ||
| Firefly bit, ordering, location ambiguity, and version width. Aaron | ||
| acknowledged each + resolved most via design clarification. Items | ||
| below need to land in the v2 spec. | ||
|
|
||
| Verbatim conversation: `docs/research/2026-05-21-aaron-kestrel-claudeai-zeta-id-v1-review-entropy-hlc-tier-causality-sleep-pivot-aaron-forwarded.md` | ||
| (preserved separately). | ||
|
|
||
| ## Scope | ||
|
|
||
| ### 1. Entropy budget gap (P0 in v1; load-bearing in v2) | ||
|
|
||
| 32 bits/ms of randomness → ~65K IDs/ms = 50% collision probability | ||
| per Kestrel's birthday math. Snowflake handles via machine-ID + | ||
| sequence counter; UUIDv7 reserves 74 bits. ZetaId v1 has neither. | ||
|
|
||
| Fix in v2 (Aaron's instinct): bake node-ID semantics into Location | ||
| field. Either: | ||
|
|
||
| - Split Location into 4-bit geographic-tag + 4-bit node-sub-ID | ||
| - OR keep 8 bits and steal bits from over-allocated Persona (8→5 | ||
| bits = 32 personas, plenty; 3 freed bits → node-ID in Location) | ||
| - Document explicitly: Location field IS the generator-ID partition | ||
|
|
||
| Kestrel's caveat: be deliberate. "Hoping location closes it" without | ||
| making the math explicit is the kind of thing that bites in production. | ||
|
|
||
| ### 2. HLC monotonicity scheme (was implicit, must be explicit in v2) | ||
|
|
||
| Current v1 spec calls ZetaId "time-sortable" but provides no | ||
| within-millisecond ordering guarantee. Riak/CockroachDB use Hybrid | ||
| Logical Clocks (HLC) — wall-clock ms + small logical counter that | ||
| bumps wall-clock forward on overflow. | ||
|
|
||
| Fix: 48-bit ms + 10-12 bit logical counter (steal bits from same | ||
| over-allocated fields as #1). Document the bump-on-overflow rule. | ||
| This gives strict per-generator monotonicity + reasonable | ||
| cross-generator ordering without atomic clocks (Spanner) or a | ||
| coordinator (TiDB TSO). | ||
|
|
||
| ### 3. Drop Firefly bit | ||
|
|
||
| Aaron explicit: "Directive" concept doesn't exist in the system. | ||
| Always-1 bit doesn't remind anyone of anything (Kestrel's | ||
| correction). Drop the bit; shift everything else up; reclaim | ||
| toward #1 entropy. | ||
|
|
||
| ### 4. Vocabularies DRAFT marker | ||
|
|
||
| Current v1 spec reads as if Chromosome (5 bits, 2 values) / Persona | ||
| (8 bits, 2 values) / Authority (5 bits, 5 values + Raw) / Location | ||
| (8 bits, 11 values per the in-flight C# enum) are final. Aaron: | ||
| "draft, just placeholders." Add explicit `status: DRAFT — | ||
| vocabularies subject to expansion before v2 lock` header. | ||
|
|
||
| Also document the rough cardinality each field expects long-term; | ||
| if any field is over-allocated by more than ~2x, reclaim toward | ||
| the entropy gap in section 1. | ||
|
|
||
| ### 5. Authority/Momentum spacing | ||
|
|
||
| V1 values are unevenly spaced (Authority: 31/20/15/8/3; Momentum: | ||
| 32/96/160/224/248). Looks ordinal-with-room-to-grow but not documented. | ||
| v2 spec: either (a) document the ordinal contract + insertion convention | ||
| or (b) renumber to dense compact values if ordinality isn't load-bearing. | ||
|
|
||
| ### 6. Location dual-mode discriminator | ||
|
|
||
| V1 docs say "logical or geographic" — two addressing schemes sharing | ||
| one field with no discriminator. Either split into separate fields, | ||
| add a discriminator bit, or pick one. v2 should pick. | ||
|
|
||
| ## Acceptance | ||
|
|
||
| - `docs/zeta-id-v2-layout.yaml` shipped with all six fixes | ||
| - Migration guide v1→v2 (how to read v1 IDs after v2 rollout per | ||
| Aaron's deprecation-schedule plan) | ||
| - TS / F# / C# / Rust / Python implementations updated in parallel | ||
| - Cross-verification harness extended to test v2 + v1 vectors | ||
| side-by-side | ||
| - Empirical: collision probability table at typical generation rates | ||
| + benchmark showing HLC monotonicity holds within a millisecond | ||
|
|
||
| ## Composes with | ||
|
|
||
| - B-0679 / B-0680 (Rust + Python multi-oracle — adopt v2 spec) | ||
| - Tier-deferred causality (B-0683) — separate but related | ||
| - Kestrel sharpening trajectory (preserved separately in docs/research/) | ||
| - `.claude/rules/m-acc-multi-oracle-end-user-moral-invariants.md` |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.