feat: HC-110 hypercode explain — full cascade trace

[SoundBlaster]

Summary

• New hypercode explain <file.hc> --hcs <file.hcs> [--ctx ...] <selector> [property] subcommand
• Prints the winning rule and all losing candidates for each resolved property, with selector, file, line, specificity, and source order
• Explainer in Sources/Hypercode/Explain/Explainer.swift walks the Command + ResolvedNode trees in parallel, reuses selectorSpec() for selector matching, and reads ResolvedValue.losers (added in PR-1) for the trace
• Exits 1 with a stderr message when no nodes match the selector
• CascadeSheetReader.parseSelector(fromString:) added as a public entry point for CLI use

Depends on PR-1 (feat/hc-112-substrate) for loser retention; depends on PR-2 (feat/hc-112-ir-v2) for branch ordering.

Test plan

• 60 tests green
• Dev context: single-property explain, no loser (sqlite only rule)
• Production context: winner=#main-db/postgres, loser=Database/sqlite
• Child selector APIServer > Listen port: winner=.int(8080)
• No-match: empty result from Explainer.explain
• All-properties: omitting property filter returns all keys
• Text rendering: WINNER/losing labels, values present

Example usage:

hypercode explain service.hc --hcs service.hcs --ctx env=production Database driver

Output:

Matched 1 node for selector 'Database'

Node: Service > Database#main-db
  driver
    WINNER   #main-db { value: postgres }
             file: service.hcs  line: 22  specificity: (1,0,0)  order: 6
    ────────────────────
    losing   Database { value: sqlite }
             file: service.hcs  line: 7  specificity: (0,0,1)  order: 2

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a9402b0708

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds an explain subcommand and expands the resolution/IR pipeline to retain full cascade traces (winner + losers), typed scalar values, and a v2 IR format (including node/document hashing) so users can introspect why each property resolved the way it did.

Changes:

• Introduce hypercode explain <file.hc> --hcs <file.hcs> [--ctx ...] <selector> [property] and an Explainer tree-walker that renders cascade traces.
• Add typed .hcs property parsing (TypedValue) and propagate file/line provenance into rule matches, resolved values, and IR v2.
• Extend emitter with --ir-version 1|2 (default v2) and add IR v2 JSON schema + SHA-256 hashing support.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
Tests/HypercodeTests/WhiteLabelTests.swift	Update expectations to compare against TypedValue values.
Tests/HypercodeTests/SHA256Tests.swift	Add SHA-256 test vectors for the hashing helper.
Tests/HypercodeTests/HCSReaderTests.swift	Update .hcs parsing tests for typed inference (string/int/bool).
Tests/HypercodeTests/ExplainTests.swift	Add unit tests covering Explainer traces and text rendering.
Tests/HypercodeTests/EmitterTests.swift	Add v2 IR structure + hash determinism assertions.
Tests/HypercodeTests/CascadeResolverTests.swift	Update expectations to typed values; add loser-retention coverage.
Sources/HypercodeCLI/main.swift	Add explain command; add --ir-version for emit; pass .hcs file paths into the reader.
Sources/Hypercode/HCS/Resolver.swift	Change resolved values to typed + retain winner/losers with provenance including file.
Sources/Hypercode/HCS/CascadeSheetReader.swift	Add read(_:file:), typed scalar inference, and public selector parsing for CLI use.
Sources/Hypercode/HCS/CascadeSheet.swift	Introduce TypedValue, add Rule.file, and add Match for cascade trace entries.
Sources/Hypercode/Explain/Explainer.swift	New explain engine + text rendering of winner/losers with provenance/specificity/order.
Sources/Hypercode/Emit/Emitter.swift	Add IR v2 emission (typed values, winner/losers, hashes, context echo) + legacy v1 path.
Sources/Hypercode/Crypto/SHA256.swift	Add SHA-256 helper used for v2 hashes.
Schema/hypercode-ir-v2.schema.json	Add JSON schema for the new hypercode.ir/v2 format.
DOCS/Workplan.md	Add workplan for HC-110..112; needs alignment with current implementation details.

---

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