Repository navigation
test+docs(dynamic): pin & document portable ruleset snapshots across environments (#76) - #82
Merged
Merged
Conversation
…environments (#76) The resolver already rewrites logical refs anywhere inside a dynamic ruleset to the per-host id before diffing (via collectRefs/deepMapRefs over the folded fields bag), and the resolved form normalizes byte-faithfully against CT. That made INLINE churchQuery rulesets portable, but the property was only tested for the inline form — the { ref: "./file.json" } snapshot path (what adopt captures) was uncovered, and nothing documented how to make a captured snapshot portable. - tests: two regression tests over the FILE path — a {__ctRef} marker embedded in a ruleset JSON file resolves to each host's campus id in the PUT (dev 42 vs prod 7), and once resolved diffs byte-faithfully (a matching instance is a no-op, no re-PUT). Locks the resolution/normalization behaviour #76's tooling will build on so a future refactor can't silently regress it. - docs: new 'Portable snapshot files across environments' section in docs/dynamic-groups.md — why captured snapshots embed instance-specific ids, the two ways to make one portable (re-author with q/churchQuery/ref, or drop a {__ctRef} marker into the JSON), the numeric-passthrough escape hatch for operational groups, and the interim 'documented, not silent' cross-env caveat. No engine change: this pins and documents existing behaviour. The adopt-time auto-rewrite of captured ids remains open on #76 (design posted there).
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Advances #76 (ruleset id portability) with the low-risk, unambiguous slice: pin and document the portability mechanism that already works, so the eventual adopt-time tooling has a tested, documented foundation. No engine change.
Background
The resolver already rewrites logical
refs embedded anywhere inside a dynamic ruleset to the per-host id before diffing (collectRefs/deepMapRefswalk the whole folded fields bag inbuild.ts, incl.dynamic.ruleset), and the resolved form normalizes byte-faithfully against CT. That makes an inlinechurchQuery(...)ruleset portable across environments.Two gaps:
{ ref: "./rulesets/<key>.json" }snapshot-file path — exactly whatct adopt group --with-dynamicproduces — was uncovered. A future refactor of the resolution/normalization pass could silently break cross-env rulesets.Changes
Tests (
tests/portable-refs.test.ts, +2) — over the FILE path, not just inline:{__ctRef}marker embedded in a ruleset JSON file resolves to each host's campus id in the PUT (dev42vs prod7) from one identical config + file.Docs (
docs/dynamic-groups.md) — new "Portable snapshot files across environments (#76)" section:q/churchQuery/ref, or drop a{ "__ctRef": true, "kind": "campus", "key": "mainz" }marker straight into the JSON file.What this does NOT do (still open on #76)
The adopt-time auto-rewrite —
ct adopt group --with-dynamicdetecting managed-entity ids in captured query positions and emitting{__ctRef}markers automatically (with the var→ref-kind catalog, reverse-resolution against managed state, and passthrough+warning for unmanaged ids). That's the substantial design work #76 flags; the implementation plan is posted on the issue. This PR makes that work land on tested, documented ground.Verification
npm run lint && npm run typecheck && npm test && npm run build— all green (535 tests, +2).