docs: No-Unlearning Invariant + route construct design - #565
Conversation
Codify the beginner-to-expert gradient rule that governs WFL's dual goal of being both a first language and production-capable. Every feature's beginner form and expert form must be the same form, or connected by a smooth path with nothing to unlearn. Added to the foundation doc and to CLAUDE.md as a design law that takes precedence when principles conflict. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MQ2S4bPNRchun4Fj2PFdq
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 14 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Adds a “No-Unlearning Invariant” as an overarching design law for WFL, intended to act as a precedence rule when principles conflict and to keep the beginner-to-expert experience continuous (“no cliffs”).
Changes:
- Introduces a new invariant section in
Docs/wfl-foundation.md, including rationale and a small set of application guidelines. - Adds a condensed invariant reference to
CLAUDE.mdfor quick use during language/docs/tooling work.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| Docs/wfl-foundation.md | Adds the full invariant definition, rationale, and application checklist. |
| CLAUDE.md | Adds a short, review-friendly summary of the invariant with a pointer to the full doc. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Goal: Innovate language design to align with natural communication and modern needs. | ||
|
|
||
| The No-Unlearning Invariant (Overarching Design Law) | ||
| WFL is deliberately both a "my first language" and a language strong enough for production. That dual goal only works as a *gradient*, not a *compromise*: the beginner path must be a strict subset of the expert path, with one continuous rope between them and no cliffs. The invariant that protects this — and that takes precedence when principles appear to conflict — is: |
Design specification for a natural-language 'route'/'when' dispatch construct (flagship: web-server routing). Grounds the design in existing internals — actions are already first-class Value::Function and the interpreter calls function values via FunctionCall — so Level 1 lowers to the existing check-if chain with no runtime changes, and Level 2 dispatch reuses machinery that already exists. Includes No-Unlearning Invariant analysis, pattern table, desugaring, security notes, and a phased TDD plan. Adds TestPrograms/route_interim_pattern.wfl demonstrating the ships-today pattern (allowlist + content_type_for helper) that collapses repetitive asset routes using only existing features. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MQ2S4bPNRchun4Fj2PFdq
…c syntax Ran the interim example under the release binary and fixed real syntax issues the initial draft assumed but that do not hold under the full pipeline: - 'ends with' / 'starts with' get swallowed as multi-word identifiers at statement level and fault in analysis; replaced with 'contains'. - 'substring of X from N' fails type checking (substring needs 3 args); key the allowlist on the full path instead, and document the 3-arg 'substring of X and 1 and length of X' form where stripping is needed. - removed an invalid 'as text' return annotation from the action header. Example now runs clean (exit 0) with verified expected output. Design doc records the operator-status finding as motivation and a prerequisite for the route construct's prefix/suffix pattern heads. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MQ2S4bPNRchun4Fj2PFdq
| Dispatching on a value is one of the most common shapes in real WFL programs, | ||
| and today the only tool for it is a long `otherwise check if` chain. A typical | ||
| web server's request handler looks like this: |
| check if contains of name and ".css": | ||
| return "text/css" | ||
| otherwise check if contains of name and ".svg": | ||
| return "image/svg+xml" | ||
| otherwise check if contains of name and ".json": | ||
| return "application/json" | ||
| otherwise: | ||
| return "text/html" | ||
| end check |
| # Design: The `route` Construct | ||
|
|
||
| **Status:** Proposed (design/spec — not yet implemented) | ||
| **Author:** WFL design discussion | ||
| **Applies to:** Language + parser; flagship use is web-server request routing. |
- Remove duplicated markdown table header in the route design doc's pattern table (rendered incorrectly). - Soften 'strict subset' to 'subset' in the No-Unlearning Invariant text in both CLAUDE.md and the foundation doc: the invariant explicitly allows the beginner and expert forms to be identical, which a strict (proper) subset would exclude. - Link the operator-status finding to tracking issue #566. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012MQ2S4bPNRchun4Fj2PFdq
logbie
changed the title
route construct design
Summary
This PR started as the No-Unlearning Invariant design law and grew, through the same design discussion, into a worked application of it: a design for a natural-language
routeconstruct plus a validated interim pattern. Scope is documentation + one example WFL program (no compiler changes yet).Changes
1. The No-Unlearning Invariant (overarching design law)
Docs/wfl-foundation.md: New section establishing the invariant — for every feature, the beginner form and the expert form must be the same form, or connected by a smooth path with nothing to unlearn — with rationale (the gradient-vs-compromise framing), four application guidelines, and how it refines principles 11 and 16.CLAUDE.md: Condensed, authoritative reference to the invariant that takes precedence when principles conflict.2.
routeconstruct design (application of the invariant)Docs/development/route-construct-design.md: Design/spec (status: proposed, not yet implemented) for aroute/whendispatch construct, flagship use being web-server routing. Grounded in real internals (actions are already first-classValue::Function; the interpreter already calls function values viaFunctionCall), so Level 1 lowers onto the existingcheck ifchain with no runtime changes. Includes invariant analysis, pattern table, desugaring strategy, security notes, and a phased TDD plan.3. Validated interim pattern
TestPrograms/route_interim_pattern.wfl: A release-build-validated example (runs clean, exit 0) showing how to collapse repetitive asset routes today using only confirmed-working features (allowlist + acontains-based content-type helper).Findings surfaced
Validating the example against the release binary revealed that
starts with/ends withdon't work end-to-end (swallowed as multi-word identifiers) and thatsubstring … from Ndoesn't type-check. These are documented in the design doc and tracked in #566.🤖 Generated with Claude Code
https://claude.ai/code/session_012MQ2S4bPNRchun4Fj2PFdq