Align _meta envelope key order across Python/TS/Swift helper packages #4

New issue

Closed

opened 2026-07-02 07:30:44 +00:00 by piersdd · 2 comments

piersdd commented

2026-07-02 07:30:44 +00:00

(Migrated from github.com)

Migrated from the vault DEVFU register by the DD-422 sweep (frozen-index entry [242], DEVFU-2026-05-24-stallari-mcp-helpers-cross-lang-key-order).

Context (register entry, verbatim)

DEVFU-2026-05-24-stallari-mcp-helpers-cross-lang-key-order — DD-338 Phase E shipped 3 sister packages (Python v0.1.1, TS v0.1.0, Swift v0.1.0). Architect claim during sister-ships was "cross-language byte parity"; functional smoke during Phase E.swift wrap revealed minor key-order divergence: Python meta_envelope emits matched_total, returned, latency_ms, filtered_by, redactions, next_cursor[, error_notes]; TS formatMetaLine + Swift formatMetaLine both emit matched_total, returned, filtered_by, latency_ms, redactions, next_cursor[, error_notes] — latency_ms and filtered_by swapped between Python and TS+Swift. Impact: semantic parity (assembler-side regex \n\n_meta: (\{.*\})$ parses to dict, dict equality is order-agnostic) but NOT strict byte parity. Golden-file tests across languages would mismatch. Fix shape: pick a canonical order (Python's is the older; TS+Swift's matches what I wrote in the spec) and align all three. Per feedback_swift_jsonencoder_key_order the Swift impl hand-assembles + the TS impl uses object-literal-order — both can re-order trivially in a minor version bump. Python likewise (dict-literal order via json.dumps). Recommended canonical: TS+Swift order (matches my spec text + is the majority of consumer surface). Patch Python audit_envelope.py meta_envelope to swap latency_ms and filtered_by positions, bump v0.1.2 to PyPI. Sister TS + Swift stay v0.1.0 unchanged. Effort: ~15min Python patch + PyPI publish; 7 Python blade-mcps would see test fixture updates if their tests pin byte-level output (likely a few; same cleanup-sweep pattern as py.typed workarounds). Related: DD-338 Phase E architectural intent of "byte parity"; sister of feedback_swift_jsonencoder_key_order.

Acceptance criteria

Python audit_envelope.py meta_envelope emits the canonical order matching TS+Swift: matched_total, returned, filtered_by, latency_ms, redactions, next_cursor[, error_notes] (swap latency_ms/filtered_by)
Python package version bumped and published to PyPI (v0.1.2 relative to the v0.1.1 line; adjust to current)
Cross-language byte-parity asserted (golden-file or equivalent test); TS + Swift unchanged
Anchors DD-338 Phase E 'byte parity' intent; sister of feedback_swift_jsonencoder_key_order; Python blade test fixtures pinning byte-level output updated as needed

Blocked by

None - can start immediately

Migrated from the vault DEVFU register by the DD-422 sweep (frozen-index entry [242], DEVFU-2026-05-24-stallari-mcp-helpers-cross-lang-key-order). ## Context (register entry, verbatim) **DEVFU-2026-05-24-stallari-mcp-helpers-cross-lang-key-order** — DD-338 Phase E shipped 3 sister packages (Python v0.1.1, TS v0.1.0, Swift v0.1.0). Architect claim during sister-ships was "cross-language byte parity"; functional smoke during Phase E.swift wrap revealed minor key-order divergence: Python `meta_envelope` emits `matched_total, returned, latency_ms, filtered_by, redactions, next_cursor[, error_notes]`; TS `formatMetaLine` + Swift `formatMetaLine` both emit `matched_total, returned, filtered_by, latency_ms, redactions, next_cursor[, error_notes]` — `latency_ms` and `filtered_by` swapped between Python and TS+Swift. **Impact:** semantic parity (assembler-side regex `\n\n_meta: (\{.*\})$` parses to dict, dict equality is order-agnostic) but NOT strict byte parity. Golden-file tests across languages would mismatch. **Fix shape:** pick a canonical order (Python's is the older; TS+Swift's matches what I wrote in the spec) and align all three. Per [[feedback_swift_jsonencoder_key_order]] the Swift impl hand-assembles + the TS impl uses object-literal-order — both can re-order trivially in a minor version bump. Python likewise (dict-literal order via `json.dumps`). Recommended canonical: TS+Swift order (matches my spec text + is the majority of consumer surface). Patch Python `audit_envelope.py` `meta_envelope` to swap `latency_ms` and `filtered_by` positions, bump v0.1.2 to PyPI. Sister TS + Swift stay v0.1.0 unchanged. **Effort:** ~15min Python patch + PyPI publish; 7 Python blade-mcps would see test fixture updates if their tests pin byte-level output (likely a few; same cleanup-sweep pattern as `py.typed` workarounds). **Related:** DD-338 Phase E architectural intent of "byte parity"; sister of `feedback_swift_jsonencoder_key_order`. ## Acceptance criteria - Python `audit_envelope.py` `meta_envelope` emits the canonical order matching TS+Swift: `matched_total, returned, filtered_by, latency_ms, redactions, next_cursor[, error_notes]` (swap `latency_ms`/`filtered_by`) - Python package version bumped and published to PyPI (v0.1.2 relative to the v0.1.1 line; adjust to current) - Cross-language byte-parity asserted (golden-file or equivalent test); TS + Swift unchanged - Anchors [[DD-338]] Phase E 'byte parity' intent; sister of feedback_swift_jsonencoder_key_order; Python blade test fixtures pinning byte-level output updated as needed ## Blocked by None - can start immediately

piersdd commented

2026-07-08 23:42:56 +00:00

(Migrated from github.com)

spec-verify-dispatch Half A for gh#4 align-meta-envelope-key-order-across-python-ts-swift-helper: clean after 1 rework round(s).

Spec: /Users/piers/master-ai/atlas/utilities/agent-harness/specs/2026-07-09-align-meta-envelope-key-order-across-python-ts-swift-helper.md
Blocking defects: 0
State: awaiting architect approval before dispatch
Next: codex-svd dispatch --args '<same-json>' --approved-spec-path /Users/piers/master-ai/atlas/utilities/agent-harness/specs/2026-07-09-align-meta-envelope-key-order-across-python-ts-swift-helper.md

spec-verify-dispatch Half A for gh#4 align-meta-envelope-key-order-across-python-ts-swift-helper: clean after 1 rework round(s). - Spec: `/Users/piers/master-ai/atlas/utilities/agent-harness/specs/2026-07-09-align-meta-envelope-key-order-across-python-ts-swift-helper.md` - Blocking defects: 0 - State: awaiting architect approval before dispatch - Next: `codex-svd dispatch --args '<same-json>' --approved-spec-path /Users/piers/master-ai/atlas/utilities/agent-harness/specs/2026-07-09-align-meta-envelope-key-order-across-python-ts-swift-helper.md`

piersdd commented

2026-07-16 12:43:46 +00:00

(Migrated from github.com)

spec-verify-dispatch Half B for gh#4 align-meta-envelope-key-order-across-python-ts-swift-helper completed integration verify.

PR: https://github.com/Groupthink-dev/stallari-mcp-helpers/pull/5
Build: green
Test: green
Reader audit clean: True
Spec fidelity: True
Ready for merge: True
Checks: PR #5 is clean and merge-ready: standalone package build green, 51/51 filtered tests green, Ruff green, reader/spec audits clean, and all 3 GitHub CI lanes green.
Warning: GitHub reports no formally required checks because main is not branch-protected; all three relevant CI contexts are nevertheless green.
Warning: uv run mypy src tests reports the three disclosed pre-existing errors in untouched test files. This is non-blocking under the specified local policy.

spec-verify-dispatch Half B for gh#4 align-meta-envelope-key-order-across-python-ts-swift-helper completed integration verify. - PR: https://github.com/Groupthink-dev/stallari-mcp-helpers/pull/5 - Build: green - Test: green - Reader audit clean: True - Spec fidelity: True - Ready for merge: True - Checks: PR #5 is clean and merge-ready: standalone package build green, 51/51 filtered tests green, Ruff green, reader/spec audits clean, and all 3 GitHub CI lanes green. - Warning: GitHub reports no formally required checks because main is not branch-protected; all three relevant CI contexts are nevertheless green. - Warning: `uv run mypy src tests` reports the three disclosed pre-existing errors in untouched test files. This is non-blocking under the specified local policy.

This discussion has been locked. Commenting is limited to contributors.