Skip to content

workplan.md

Latest commit

 

History

History
118 lines (97 loc) · 12.2 KB

workplan.md

File metadata and controls

118 lines (97 loc) · 12.2 KB
Raw

Hypercode — Work Plan

Status snapshot and task backlog for the Hypercode language (.hc) and its cascade sheets (.hcs). Companion to the RFC and the syntax spec.

Legend: ✅ done · 🔜 in progress / next · ⬜ planned · 🅿️ deferred · ❓ decision needed

Guiding invariants

  • .hc stays deliberately simpler than YAML: structure / intent only, no values.
  • Values and context live in .hcs; swapping .hcs must never require touching .hc (white-label).
  • Source of truth = .hc + .hcs. Any YAML/JSON output is a generated artifact, not a source.
  • The resolved graph is the contract between Hypercode and any consumer. Consumers (Ontology, …) depend on Hypercode, never the reverse.
  • Target-specific compilation (DomainOntologyPackage, Terraform, …) is consumer-owned, downstream of the resolved graph.
  • Rules are executable specifications (SpecificationCore): grammar, validation and cascade resolution are composable Specification / DecisionSpec objects — the 0AL house style.
  • Values cascade; contracts accumulate and narrow (RFC §9.4). A more specific selector may override a value, never weaken an inherited contract — safety is not subject to specificity.

Open decisions

  • ✅ Adopt SpecificationCore (github.com/SoundBlaster/SpecificationCore). Decided: grammar, validation and cascade resolution are expressed as composable Specification / DecisionSpec objects. Zero external deps still holds — SpecificationCore is 0AL's own foundation.
  • ✅ Extract a shared grammar-core, but build it here in Hypercode first, then refactor Hyperprompt and Ontology onto it (see M6).
  • ✅ D1 — .hcs lexical syntax. Hand-rolled minimal subset for now; Yams is not pulled in until we actually consume real YAML input.
  • ❓ D2 — Resolution semantics form. The SpecificationCore specs are the executable rules. Open: how much extra prose / fixtures (and, later, Lean) to layer on top, and when.

M0 — Spec foundation

  • HC-001 .hc BNF syntax spec, incl. INDENT/DEDENT block rule — EBNF/Hypercode_Syntax.md (PR #5, open)
  • HC-002 ANTLR reference grammar + .hc test suite — EBNF/
  • HC-003 CI running the grammar tests — .github/workflows/ci.yml (PR #5, open)
  • HC-004 Merge PR #5 into main (merged by maintainer)

M1 — Swift reference implementation: parsing ✅

  • HC-010 .hc lexer with indent/dedent (off-side rule) — Sources/Hypercode/Lexer.swift
  • HC-011 .hc recursive-descent parser → Command AST — Sources/Hypercode/Parser.swift
  • HC-012 hypercode CLI: parse + print tree — Sources/HypercodeCLI/
  • HC-013 Lexer/parser tests ported from fixtures (15 green) — Tests/
  • HC-014 Adopt SpecificationCore + seed the Specifications/ layer (IdentifierSpec) — Sources/Hypercode/Specifications/

M2 — Cascade resolution ✅ core (on SpecificationCore)

  • HC-020 Resolution semantics — EBNF/Hypercode_Resolution.md (operational semantics narrating the executable specs; conformance = Examples + CascadeResolverTests)
  • HC-021 .hcs reader → cascade-sheet model (selectors, rules, @dimension[value] blocks) — Sources/Hypercode/HCS/CascadeSheet*.swift
  • HC-022 Selector matching as Specifications over nodes: type / .class / #id / child (>) — HCS/SelectorSpecs.swift
  • HC-023 Specificity + cascade as a DecisionSpec: (specificity, source-order) → value + provenance — HCS/Resolver.swift (origin/importance deferred until there's syntax for it)
  • HC-024 Context activation: @dimension[value] guards (env / client) via Rule.isActive(in:)
  • HC-025 Resolver: .hc + .hcs + context → resolved graph with provenance — HCS/Resolver.swift
  • HC-026 Resolver tests: RFC §5 web-service example (dev + production + provenance), reader & selector tests — Tests/
  • HC-027 CLI: hypercode resolve app.hc --hcs config.hcs [--ctx key=value] — prints the resolved tree with provenance; Examples/service.{hc,hcs} — Sources/HypercodeCLI/

M3 — Emit & validation

  • HC-030 Generic emit: resolved graph → canonical IR hypercode.ir/v1 (JSON/YAML), schema-agnostic, hand-rolled — Sources/Hypercode/Emit/, CLI emit
  • HC-031 hypercode validate: id uniqueness (.hc) + dangling-selector warnings (.hcs vs .hc) — Sources/Hypercode/Validation/, CLI validate
  • HC-032 Versioned resolved-graph schema (cross-impl contract) + fixtures — Schema/hypercode-ir-v1.schema.json (automated schema-validation in CI deferred)

M4 — Consumers & compilation (downstream)

  • HC-040 White-label example: one .hc, swap --ctx client=… → different brand builds — Examples/whitelabel/ + WhiteLabelTests
  • HC-041 Backends/adapters pattern doc: resolved graph → target language/format — DOCS/Backends.md
  • 🅿️ HC-042 Ontology path (in the Ontology repo): ontologyc import-hypercode maps resolved graph → DomainOntologyPackage YAML; --schema stays consumer-side (blocked: awaiting decision on Ontology application areas)

M5 — Formal verification 🅿️

  • HC-050 Lean 4 cascade oracle — SPEC/lean/HypercodeOracle.lean: executable model, machine-checked agreement with the Swift service example (native_decide), kernel-checked order facts, and a cascade_total theorem (generic order-independence proof = future)

M6 — Shared grammar-core (sequenced: Hypercode first, then refactor consumers)

  • HC-060 Canonical .hc grammar-core as layered Specifications — Sources/Hypercode/Specifications/ (Lexical: IdentifierSpec; Syntactic: CommandSpec, line specs; Decisions: LineKindDecision). Indentation stays in the hand-rolled lexer front.
  • HC-061 Dialect analysis (core vs Hyperprompt quotes/references/paths) + extraction proposal — DOCS/Dialects.md (core-vs-dialect surface decision flagged for you)
  • 🅿️ HC-062 Hyperprompt lives as an independent dialect (decision A: core stays minimal, Hyperprompt not refactored) (closed by design — Hyperprompt's grammar is a different language, not a duplicate)
  • 🅿️ HC-063 Refactor Ontology's Hypercode import path onto the shared grammar-core (blocked: awaiting Ontology application decision)

M7 — Diagnostics & LSP (VS Code)

  • HC-100 Structured diagnostics: unified Diagnostic (severity, code, source range), LSP-shaped JSON + editor-parseable text, CLI --diagnostics text|json — Sources/Hypercode/Diagnostics/
  • HC-101 Minimal Swift LSP server (hypercode lsp): JSON-RPC over stdio, initialize, document sync (didOpen/didChange/didSave/didClose), live publishDiagnostics — Sources/HypercodeCLI/LSPServer.swift + shared diagnostics(for:text:) in the library
  • HC-102 Thin VS Code extension on vscode-languageclient launching hypercode lsp — editors/vscode/ (languages .hc/.hcs, hypercode.serverPath setting); compiled in CI (.github/workflows/vscode-extension.yml)
  • HC-103 Completion (type/class/id from AST, . and # triggers) + hover (Markdown: type/class/id/children) — LSPServer.swift

(Aim straight for LSP — the standard for VS Code & editor-agnostic. Hyperprompt's custom CLI+JSON-RPC was a documented MVP stopgap; see its ADR-001.)

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; shipped in 0.5.0: #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; value enforcement (HC2104): #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 + #20

P1 — built on v2:

  • 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)
  • HC-114 Runtime resolver boundary — decided: build/generation-time only, embedded runtime resolver out of scope with revisit conditions; resolver stays an embeddable pure function with no runtime API commitments — DOCS/RuntimeBoundary.md, RFC §9.8/§10
  • 🅿️ HC-115 OpenFeature bridge for the runtime mode — parked by the HC-114 decision (runtime mode out of scope); runtime flags compose by targeting resolved anchors instead
  • HC-116 @import for .hcs — sheet modularity: depth-first expansion at the directive position (importer wins ties), import-once for diamonds, cycle detection, cross-file provenance; contracts compose across imports — normative semantics EBNF/Hypercode_Resolution.md §5.1

M9 — Validation & adoption (DOCS/Positioning.md)

  • HC-120 Kustomize comparison demo — Examples/kustomize-comparison/: 3 tenants × 3 envs maintained twice (idiomatic Kustomize components vs .hc + @imported tenant sheets); computed metrics (28 files/278 lines/86% duplication vs 5/57/30%), "why is this value here" via explain, affected-target precision via hypercode diff, and the own failure mode (specificity beats source order) diagnosed via explain; metrics.py --check validates all 9 targets in CI
  • HC-121 Dogfooding as the primary adoption path — Ontology examcalc round-trips through IR v2 (Examples/ontology-backend/: kind defaults via selectors, @stage lifecycle context, contracts, consumer adapter; semantic match with the original verified in CI); consumer-side closure added in Ontology (ontologyc import-hypercode accepts IR v2 ontology-shaped package graphs, keeps imports draft-only, and semantically matches canonical examcalc) and Hyperprompt (runnable core-Hypercode compile-configuration exercise); friction log F1–F5 in DOCS/Dogfooding.md
  • ⬜ HC-122 SLSA-like generation attestation chain — planned contract in DOCS/IntegrityChain.md: signed .hc/.hcs → IR hash → generator identity/version → artifact hashes → validator report (RFC §8, §9.8); not a 0.6.0 blocker
  • 🅿️ HC-123 Agent Passport / 0AL integration — attestation chain plugs into 0AL's signed-agent model
  • HC-124 End-to-end AI codegen demo — Examples/codegen-demo/: service spec → IR v2 → Claude-generated module per node (embedded node hash + provenance comments) → check.py validates artifacts against the same contracts (HC2104-gen) and scopes regeneration by node hash; generate.sh regenerates stale modules via claude -p; checked in CI on every push
  • ⬜ HC-125 Type-system depth: list scalars — planned in DOCS/TypeSystemDepth.md; driven by dogfooding F1 (implements, appliesTo, states, oneOf, compatibility lists); requires IR/schema/contract tests and at least one workaround removal
  • ⬜ HC-126 Type-system depth: unions or pattern constraints — planned in DOCS/TypeSystemDepth.md; driven by dogfooding F2 (cardinality.max: int | "*"); must preserve monotonic contracts

Cross-cutting

  • HC-090 Swift CI workflow (build + test) — .github/workflows/swift.yml
  • HC-091 Repo layout documented (root Swift package) — DOCS/Architecture.md
  • HC-092 Usage guide with real CLI outputs (contexts, contracts as a CI gate, explain, IR v2, AI-codegen pipeline) — DOCS/Usage.md; Examples/service.hcs gained a @contract: block so the reference fixture exercises HC-111 (PR #23)
  • HC-092 ANTLR/Java relabeled as a conformance oracle — DOCS/Architecture.md