release: 0.5.0 — spec-layer hardening

CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] — 2026-06-12
+
+Spec-layer hardening: the resolver becomes a verifiable pipeline — typed IR
+with full provenance, monotonic contracts, cascade explanation, semantic diff,
+and a runnable AI-codegen loop. (PRs
+[#19](https://github.com/0al-spec/Hypercode/pull/19)–[#25](https://github.com/0al-spec/Hypercode/pull/25).)
+
+### Added
+- **`hypercode.ir/v2`** (HC-112, breaking; now the default `emit` output):
+  typed values (int/float/bool/string instead of strings-only), the winning
+  rule *and* every losing rule per property with `file:line`, specificity and
+  source order, applicable contracts echoed per property, per-node SHA-256
+  Merkle hashes over the stable resolved content plus a `documentHash`,
+  context echo, and `resolver.name`/`version`. JSON Schema in `Schema/`;
+  v1 remains available via `--ir-version 1`.
+- **Monotonic selector contracts** (HC-111): `@contract:` blocks in `.hcs`
+  attach property schemas (type, bounds, required) to selectors. Values
+  cascade; contracts accumulate by intersection and may only narrow —
+  weakening an inherited contract is a build error (RFC §9.4, normative).
+  Diagnostics HC2101–HC2103, plus context-dependent value validation HC2104
+  (`validate --ctx`): a production override that violates a bound fails the
+  build instead of shipping.
+- **`hypercode explain <selector> [property]`** (HC-110) — the full cascade
+  trace: why a value is what it is, the winner and every loser with
+  specificity and source order.
+- **`hypercode diff <old.ir> <new.ir>`** (HC-113) — semantic diff over IR v2:
+  hash-driven (unchanged subtrees skipped), selector-identity node matching
+  with content-hash pairing for duplicate siblings, added/removed/modified/
+  reordered changes with old/new winning rules. `--format json` emits
+  `hypercode.diff/v1` (schema in `Schema/`); exit codes 0/1/2 (`diff`-like).
+- **End-to-end AI codegen demo** (HC-124, `Examples/codegen-demo/`): spec →
+  IR v2 → one generated Python module per node with embedded node hash and
+  per-value provenance; `check.py` verifies freshness (node hashes) and
+  contract conformance of the artifacts (required/bounds/type/drift);
+  `generate.sh` regenerates only stale modules via Claude. Runs in CI.
+- **Usage guide** (`DOCS/Usage.md`) with real CLI outputs for every command;
+  `OVERVIEW.md` rewritten to the current positioning (context-resolved
+  specification layer). RFC v0.2; `.hcs` grammar and resolution semantics
+  formalized in `EBNF/` 0.2.
+- CI validates emitted IR and diff output against their JSON Schemas (ajv).
+
+### Changed
+- SHA-256 via **swift-crypto** instead of CryptoKit (Linux-capable).
+- Hardened boundaries: emitted JSON escapes object keys; `--ctx` keys must be
+  identifiers; the diff JSON parser is strict RFC 8259 (number grammar,
+  control characters); unreadable `diff` input exits 2, never 1.
+- Single version constant `HypercodeVersion.current`, echoed as
+  `resolver.version` in IR v2.
+
 ## [0.4.0] — 2026-06-02
 
 First release with a **reference implementation**.

DOCS/Usage.md

@@ -144,7 +144,7 @@ $ hypercode emit Examples/service.hc --hcs Examples/service.hcs --ctx env=produc
 {
   "version": "hypercode.ir/v2",
   "context": { "env": "production" },          // echo of --ctx
-  "resolver": { "name": "hypercode-swift", "version": "0.5.0-dev" },
+  "resolver": { "name": "hypercode-swift", "version": "0.5.0" },
   "documentHash": "3be098179523f21c…",
   "nodes": [ /* … each node: */
     {

DOCS/Workplan.md

@@ -82,7 +82,7 @@ Cascade semantics are **unchanged** — only retention of losing matches is adde
 
 ### Package bump
 
-`Package.swift` version comment: `0.5.0-dev`.
+`Package.swift` version comment: `0.5.0-dev` *(historical — released as `0.5.0` in [#26](https://github.com/0al-spec/Hypercode/pull/26))*.
 
 ---
 
@@ -287,7 +287,7 @@ All findings reproduced against `feat/hc-111-contracts` (69a38f0). R1–R8 block
 - ✅ **R8 — undelivered plan items.** Root `workplan.md` M8: HC-110/111/112 still ⬜
   (mark only on merge); `RFC/Hypercode.md` not bumped (PR-4 promised v0.2; §Limitations
   "untyped strings in IR v1" needs a v2 note); IR `contracts[]` not sorted by ascending
-  specificity as specified; `Package.swift` `0.5.0-dev` version comment missing (PR-1);
+  specificity as specified; `Package.swift` `0.5.0-dev` version comment (the pre-release string) missing (PR-1);
   CI `ajv` schema-validation step missing (PR-2); EBNF v0.2: `<scalar>` wrongly requires
   quoted strings (bare `driver: sqlite` is valid), header `Date:` stale, and the HC21xx
   semantics table belongs in `Hypercode_Resolution.md`.

Package.swift

@@ -1,7 +1,7 @@
 // swift-tools-version: 5.9
 import PackageDescription
 
-// Package version: 0.5.0-dev (the IR v2 emitter echoes 0.5.0 as resolver.version)
+// Package version: 0.5.0 (echoed by the IR v2 emitter as resolver.version)
 let package = Package(
     name: "Hypercode",
     platforms: [

Sources/Hypercode/Version.swift

@@ -2,5 +2,5 @@
 /// (`resolver.version`) and available to tooling. Bump together with
 /// `CHANGELOG.md` and the `Package.swift` version comment.
 public enum HypercodeVersion {
-    public static let current = "0.5.0-dev"
+    public static let current = "0.5.0"
 }

workplan.md

@@ -91,9 +91,9 @@ cascade sheets (`.hcs`). Companion to the [RFC](RFC/Hypercode.md) and the
 ## M8 — Spec-layer hardening (RFC §9 follow-through)
 
 P0 — what makes the novelty claim defensible:
-- ⬜ HC-110 `hypercode explain <selector> [property] [--ctx …]` — full cascade trace: winner *and* losing rules with specificity/source-order; in review: [#21](https://github.com/0al-spec/Hypercode/pull/21) (stacked on #19/#20)
-- ⬜ HC-111 Monotonic selector contracts — property schemas attached via selectors; values cascade, contracts accumulate by intersection & narrow; weakening = resolution error (normative: RFC §9.4 + `EBNF/Hypercode_Resolution.md` §7); in review: [#22](https://github.com/0al-spec/Hypercode/pull/22); value enforcement (HC2104) follows as PR-5
-- ⬜ HC-112 `hypercode.ir/v2` (breaking) — typed values (v1 is strings-only), `file` alongside `line`, specificity + source order, losing rules, contract results, per-node and per-document hashes, context echo, resolver name/version — `Schema/`; in review: [#19](https://github.com/0al-spec/Hypercode/pull/19) + [#20](https://github.com/0al-spec/Hypercode/pull/20)
+- ✅ HC-110 `hypercode explain <selector> [property] [--ctx …]` — full cascade trace: winner *and* losing rules with specificity/source-order; shipped in 0.5.0: [#21](https://github.com/0al-spec/Hypercode/pull/21)
+- ✅ HC-111 Monotonic selector contracts — property schemas attached via selectors; values cascade, contracts accumulate by intersection & narrow; weakening = resolution error (normative: RFC §9.4 + `EBNF/Hypercode_Resolution.md` §7); shipped in 0.5.0: [#22](https://github.com/0al-spec/Hypercode/pull/22); value enforcement (HC2104): [#23](https://github.com/0al-spec/Hypercode/pull/23)
+- ✅ HC-112 `hypercode.ir/v2` (breaking) — typed values (v1 is strings-only), `file` alongside `line`, specificity + source order, losing rules, contract results, per-node and per-document hashes, context echo, resolver name/version — `Schema/`; shipped in 0.5.0: [#19](https://github.com/0al-spec/Hypercode/pull/19) + [#20](https://github.com/0al-spec/Hypercode/pull/20)
 
 P1 — built on v2:
 - [x] HC-113 `hypercode diff <old.ir> <new.ir>` — affected nodes/properties with reasons (old/new winner rule), node-hash short-circuit (unchanged subtrees skipped), selector-identity node matching, added/removed/reordered detection, `--format json` = `hypercode.diff/v1` feed, exit 1 on change — `Sources/Hypercode/Diff/` (Foundation-free JSON parser with exact number lexemes)