lclang 0.3.0__tar.gz

lclang-0.3.0/.gitignore

@@ -0,0 +1,11 @@
+/.coverage
+/.mypy_cache/
+/.pytest_cache/
+/pytest-cache-files-*/
+/.ruff_cache/
+/build/
+/dist/
+/*.egg-info/
+**/__pycache__/
+*.py[cod]
+/.codex_tmp/

lclang-0.3.0/AGENTS.md

@@ -0,0 +1,66 @@
+# lclang Agent Handoff
+
+Read this file, `progress.md`, the active milestone specification, and both
+README files before changing the project.
+
+## Project identity
+
+- Distribution and import name: `lclang`.
+- Production package root: `src/lclang`.
+- Runtime: Python 3.14 or newer; no third-party runtime dependencies.
+- License: MIT.
+- Target: complete and verify the 0.4 release described in `progress.md`.
+- Security model: trusted configuration language, not a hostile-code sandbox.
+
+## Non-negotiable architecture
+
+- The parser is a pure-Python lexer plus Pratt/recursive-descent parser.
+- Execution uses the custom AST interpreter only. Do not add ANTLR, Java,
+  `eval`, `exec`, Python-AST compilation, or a bytecode backend.
+- Public evaluation is async-first. `evaluate_sync` is the only synchronous
+  convenience boundary.
+- No class or function name can start with an underscore.
+- A `Frame` is safe for concurrent tasks in one event loop, not across loops.
+- Cached values are snapshots. Recalculation never invalidates dependants.
+- Source files must stay below 200 lines, excluding docstrings and imports. Split modules by responsibility.
+- Every production docstring is English rST. All functions and methods (including private ones)
+  document how it works, and every parameter with `:param name:`, their result with `:returns:` unless no return or `None`,
+  every intentional exception with `:raises Type:`, and genuinely useful special
+  behaviour with an rST `.. note::`. Do not add notes that merely restate the
+  declaration, owning subsystem, or ordinary lifecycle. All value classes
+  (including private ones) document constructor fields
+  and edge cases with the same conventions.
+- A Comment for each constant values to describe it.
+- In unittest, mock any external connectivities, and use separated TemporaryDirectory to hold file input and outputs.
+- CLI unittest configuration sources are static fixtures declared with their test
+  cases. Every enabled log file is rooted in a per-test temporary directory that
+  is cleaned automatically.
+
+Runtime packages and tests follow `docs/architecture/module-layout.md`. Tests
+mirror production subsystem boundaries; reusable fixtures live in dedicated
+support modules rather than unrelated test files.
+
+## Required workflow
+
+For every implementation milestone:
+
+1. Write or update its English specification in `docs/specs/`.
+2. Add a behavioural test and run it to prove RED, test must include practical and meaningful sunny, rainy, composite-complex cases.
+3. Implement the smallest correct behaviour and prove GREEN.
+4. Refactor, then run milestone and full quality checks.
+5. Update `README.md`, `README_cn.md`, and `progress.md`.
+6. Mark `DONE` only with commands and evidence recorded in `progress.md`.
+
+For a bug, reproduce it with a failing test before fixing it. Documentation-only
+milestones use link, metadata, or structural checks rather than artificial unit
+test failures.
+
+## Sources of truth
+
+- `progress.md`: current work, status, evidence, and release gates.
+- `docs/specs/`: behaviour and public contracts.
+- `README.md` and `README_cn.md`: user-visible implemented capability only.
+- `pyproject.toml`: supported Python and tool configuration.
+
+Do not advertise planned behaviour as implemented. Preserve unrelated user
+changes. Update this file only when durable architecture or workflow changes.

lclang-0.3.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+## Unreleased
+
+- Renamed the distribution and import package to `lclang`, moved production
+  code to `src/lclang`, and migrated packaging, CI, tests, and documentation.
+- Added ordered workflow execution-status trees, shared sub-task manager cursors,
+  deterministic parent aggregation, subtree locking, and synchronous scoped
+  finalization that records exceptions without suppressing them.
+- Added scoped step handles that begin running, accept atomic description/status
+  updates, succeed on clean exit, and record errors without suppressing them.
+- Raised the enforced project gate to 100% branch coverage and added behavioral
+  assertions for every previously uncovered statement and branch.
+- Manually malformed call, dictionary-display, and dictionary-comprehension AST
+  wrapper values now fail explicitly instead of being silently ignored.
+
+## 0.3.0 release candidate — 2026-08-09
+
+- Added immutable CLI parameters, results, contexts, and logging configuration
+  through the focused `lclang.cli` public API without expanding the package root.
+- Added exact async command decorators, nested snake_case groups, full Python
+  executable/script argv parsing, command routing, and dependency-free structured help.
+- Added lazy preset/default/config/override/runtime Frame layering, strict as-of
+  dates, literal and deferred `LCL[...]` overrides, required presence checks,
+  handler-owned dryrun behavior, isolated UTF-8 logging, and deterministic cleanup.
+- Added executable English and Chinese Python-script CLI tutorials, static config
+  fixture guidance, temporary-log testing, platform cases, and clean-install CLI smokes.
+- Added `CliResult.success`/`fail` shortcuts and executable `python -m lclang.cli`
+  commands for non-evaluating `RESULT` inspection and lazy result evaluation.
+- Literal and malformed-marker CLI overrides now remain external-provided string
+  bindings; only successfully parsed `LCL[...]` values become lazy definitions.
+- Dependency inspection now classifies canonical reviewed builtins/namespaces as
+  `NativeProvided`, with stable address-free callable and concise namespace reprs.
+- Native inspection payloads now use uniform `Builtin Function: name` and
+  `Builtin Namespace: name` syntax. Structured evaluation failures include the
+  direct-to-failing variable owner stack, including lexical LCL function calls.
+- Valueless `-o/--override KEY` now stores boolean `True`, and a following
+  override option can no longer be consumed as a value. `parse_lcl -o EVAL`
+  evaluates `RESULT` first and renders either its successful or failed cache tree.
+- Dependency-tree values that are supported `LclAstNode` objects or evaluated
+  LCL function closures now render with canonical LCL expressions instead of
+  nested dataclass, closure, resolver, evaluator, and source-span reprs.
+- Added the native `recursive(builder)` builtin, a Python variadic eager Z
+  combinator for defining recursive LCL functions without supplying an LCL
+  combinator; its results use stable `Recursive Function: <source-or-name>`
+  reprs, and the original LCL Y/Z examples remain supported and documented.
+- Added `python -m lclang.cli builtins` with sorted one-line descriptions and
+  manifest-ordered, two-space-indented methods beneath builtin namespaces.
+- Iterable items are now recursively awaited at the shared sync/async iteration
+  boundary, fixing Python `map` with async LCL functions in starred displays,
+  comprehensions, call expansion, and reviewed iterable helpers.
+
+## 0.2.0 release candidate — 2026-08-08
+
+- `Frame` now accepts a string or omitted ID, defaulting direct construction to
+  `frame-<module name>`, and the complete subsystem now lives under
+  `lclang.runtime.frame`.
+- Added side-effect-free `Frame.inspect_variable()` trees with cache/host state,
+  selected definitions, exact lookup paths, owners, dependency branches,
+  finite cycle rendering, compact reprs, and markdown-style lines.
+- Inspection trees now collapse repeated direct dependency names in first-seen
+  order while retaining the same variable independently on separate branches;
+  graphs, traces, and snapshots remain occurrence-preserving.
+- Refined inspection's source-oriented repr to
+  `name@frame/path: [definition ](Status) typed-payload`: ASTs have clear status
+  spacing, external values omit definition text, values render as `type: repr`,
+  and errors render as `ErrorType: message`.
+- Made `lhs()` lexical inside LCL function values, so call arguments retain the
+  caller owner while function bodies retain their defining variable name.
+- `evaluate_sync` now accepts expression source text directly, and
+  `FrameFactory.create()` defaults its ID to `frame-<module name>`.
+- Added a complete dependency analytics tutorial and reorganized internal
+  analytics into `runtime/dependency/`, including nested Frame graph modules;
+  redundant evaluator/printer/config filenames now describe their contents.
+
+- Added definition-scoped `lhs()` in `LCL_ROOT` and strict locale-independent
+  `parse_ymd`/`to_ymd` calendar conversion in `LCL_BUILTINS`.
+- Extended dependency graph construction to accept a Frame and report qualified
+  definition/value bindings, exact lookup paths, and unresolved references
+  without evaluating or touching runtime traces.
+- Added reusable default-parent policy to `FrameFactory`; configuration-created
+  Frames now use the canonical root/builtin hierarchy by default.
+
+- Replaced the oversized user cheatsheet and legacy runtime quickstarts with an
+  English tutorial path covering installation, Modules and Frames, the complete
+  LCL feature gallery, fixed-point recursion, quicksort, and `.lclcfg`
+  integration through executable examples.
+
+- Added UTF-8 `.lclcfg` parsing with optional version metadata, colon
+  definitions, comments, explicit backslash continuation, and eager
+  source-file magic constants.
+- Added async path-backed `using` expansion with deterministic later-wins
+  precedence, complete shadow history, cycle detection, loading limits,
+  single-flight caching, cancellation isolation, and filesystem containment.
+- Added the curated `lclang.config` parsing/loading API and runtime Module,
+  FrameFactory, and guaranteed-cleanup evaluation bridge.
+
+- Added the preferred `define_module` and `define_frame` construction shortcuts
+  with the explicit `LCL_ROOT -> LCL_BUILTINS -> LCL_RUNTIME -> LCL_IMPORTS ->
+  user module` lookup hierarchy.
+- Added non-evaluating `Frame.has` and `Frame.get_definition` inspection backed
+  by the same recursive owner-selection rule as `Frame.get`.
+- Added `Frame.derive` as the preferred concise constructor for independent
+  child Frames with detached local values.
+- Added atomic right-biased `Frame.mixin` host-value updates while preserving
+  cached definition snapshots until explicit recalculation.
+
+## 0.1.0 release candidate — 2026-08-06
+
+The first released `lclang` language/runtime surface includes:
+
+- a pure-Python, versioned expression grammar with immutable AST values,
+  canonical printing, comprehensions, functions, closures, errors, and context
+  management;
+- an async-first evaluator with a synchronous convenience boundary, hierarchical
+  Frame caching, dependency inspection, recalculation, limits, cancellation
+  isolation, and deterministic cleanup;
+- immutable modules, presets, reusable Frame factories, dependency graphs, and
+  a reviewed standard preset with `iter`, `text`, `data`, and `json` namespaces;
+- bilingual tutorials, API guidance, and executable examples;
+- zero-dependency runtime packaging for Python 3.14+ with a platform-independent
+  wheel and source distribution release gate.
+
+`lclang` is intended for trusted application configuration. It is not a hostile-
+code sandbox; host-provided values and callables retain ordinary Python powers.

lclang-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lclang contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lclang-0.3.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: lclang
+Version: 0.3.0
+Summary: A typed, async-first configuration expression language
+Project-URL: Documentation, https://jihulab.com/midnightprotocol/lclang/-/tree/main/docs
+Project-URL: Issues, https://jihulab.com/midnightprotocol/lclang/-/work_items
+Project-URL: Source, https://jihulab.com/midnightprotocol/lclang
+Author: RuntimeRomance
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# lclang
+
+[中文说明](README_cn.md)
+
+`lclang` is a pure-Python, async-first configuration expression language for
+Python 3.14+. The 0.3.0 language, runtime, `.lclcfg`, and typed CLI release candidate is
+verified; publication is a separate maintainer action. See
+[CHANGELOG.md](CHANGELOG.md).
+
+The distribution and import name is `lclang`; production code lives under
+`src/lclang`.
+
+## Project status
+
+- Target: 0.4.0 development release
+- Latest completed milestone: M008 — `lclang` identity and `src` package layout
+- Next planned milestone: M100 — trusted-input security boundary audit
+- Implemented: foundation, enforced English rST API docs, source-aware lexer,
+  immutable AST, complete expression/comprehension parsing, all planned V1
+  expression forms, deterministic AST-to-source rendering, semantic f-string
+  parsing, stable root parse/print APIs, async expression evaluation with
+  recursively awaited sync/async iterable items, lexical
+  closures, structured failures, assertions, try recovery, finalization, and
+  synchronous/asynchronous context management, semantic f-string evaluation,
+  immutable runtime modules, and hierarchical single-flight Frame caching with
+  structured cycle detection, cancellation isolation, and atomic targeted
+  recalculation without dependant invalidation, plus task-local depth, work, and
+  materialized-collection limits, deterministic Frame close/resource cleanup,
+  scope-aware eager/conditional/deferred dependency analysis, immutable module
+  dependency graphs, filtered queries, deterministic topological ordering,
+  bounded runtime lookup tracing, static/dynamic edge reconciliation, and
+  owner-aware immutable Frame dependency snapshots with atomic refresh semantics,
+  plus shallow immutable host presets, reusable independent Frame factories,
+  manifest-driven read-only attribute namespaces, and reviewed async iterable,
+  text, immutable data, and strict JSON helpers in a standard preset, exposed
+  through a focused root API for the complete runtime workflow, plus preferred
+  source-string `define_module`/`define_frame` shortcuts and the canonical
+  `LCL_ROOT -> LCL_BUILTINS -> LCL_RUNTIME -> LCL_IMPORTS -> user` hierarchy,
+  preferred `Frame.derive` child construction, non-evaluating `has` and
+  `get_definition` lookup inspection, side-effect-free `inspect_variable`
+  dependency trees with first-seen direct-name deduplication and source-oriented
+  one-line representations with typed value/error payloads, including canonical
+  `<node-type>: <LCL expression>` payloads for AST values and canonical source
+  reprs for evaluated LCL function closures, plus controlled
+  right-biased `Frame.mixin`
+  host-value updates, definition-scoped `lhs()`, strict `YYYYMMDD` date builtins,
+  the native variadic fixed-point builtin `recursive`,
+  and non-evaluating Frame-qualified dependency graphs with value terminals and
+  lookup paths, lexical closure ownership for `lhs()`, source-string
+  `evaluate_sync`, deterministic direct/FrameFactory IDs, and a dependency
+  analytics tutorial backed by audited nested dependency and Frame packages,
+  plus immutable CLI values, exact async command decorators, nested snake_case
+  groups, full-argv parsing, structured help, lazy preset/default/config/override
+  Frame layering, handler-owned dryrun, isolated logging, result/cleanup mapping,
+  concise `CliResult.success`/`fail` constructors, valueless override keys as
+  boolean `True`, and built-in `parse_lcl` with optional evaluated inspection,
+  lazy `eval_lcl`, and deterministic nested `builtins` module commands, with canonical lclang
+  builtins and standard namespaces identified as `NativeProvided` and rendered
+  uniformly as `Builtin Function` or `Builtin Namespace`, plus structured
+  failures carrying direct-to-failing variable evaluation stacks, plus ordered
+  workflow execution-status trees, shared sub-task manager cursors, deterministic
+  parent aggregation, subtree locking, exception-transparent `with` finalization,
+  and scoped steps with atomic description/status updates and clean auto-success,
+  packaged with the `lclang` identity from the `src/lclang` source tree
+- Test status: 844 tests pass at 100.00% branch coverage; strict mypy, Ruff,
+  exhaustive source/docstring policy, executable documentation, and artifact
+  gates pass
+
+The authoritative milestone ledger is in [progress.md](progress.md). Planned
+features are deliberately not presented as implemented features.
+
+## Quickstart
+
+Run from a checkout with its development environment installed. The example is
+extracted and executed by the test suite.
+
+```python
+import asyncio
+
+import lclang
+
+
+async def main() -> None:
+    module = lclang.define_module(
+        "quickstart",
+        {"result": 'json.encode({"message": "hello lclang"})'},
+    )
+    frame = lclang.define_frame(module)
+    try:
+        print(await frame.get("result"))
+        snapshot = frame.dependency_snapshot("result")
+        print(",".join(str(edge.target) for edge in snapshot.dynamic_edges))
+    finally:
+        await frame.close()
+
+
+asyncio.run(main())
+```
+
+Inspect an override-defined result without evaluating it, or evaluate it through
+the same lazy Frame pipeline:
+
+```console
+python -m lclang.cli builtins
+python -m lclang.cli parse_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"
+python -m lclang.cli eval_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"
+```
+
+The first command lists canonical builtins and nested namespace methods. The
+second prints the static `RESULT -> a, b` inspection tree. The third prints
+`100200` because ordinary CLI override values are literal strings.
+
+Continue with the [tutorial index](docs/tutorials/README.md), then choose the
+[runtime guide](docs/tutorials/runtime.md),
+[LCL examples gallery](docs/tutorials/lcl_examples.md), or
+[configuration-file guide](docs/tutorials/config_file.md). Use the
+[dependency analytics tutorial](docs/tutorials/dependency-analytics.md) for
+static graphs, Frame paths, runtime traces, and reconciliation. The
+[CLI tutorial](docs/tutorials/cli.md) shows how to build a configuration-driven
+Python script. The [workflow-status tutorial](docs/tutorials/workflow-status.md)
+explains task/step trees, aggregation, descriptions, locking, and scoped error
+capture for both tasks and steps. The
+[runtime API guide](docs/reference/runtime-api.md) remains the detailed
+reference.
+
+## Intended capability
+
+The 0.4 target comprises:
+
+- a versioned Python-like expression grammar with a custom AST;
+- an async-first interpreter and cached hierarchical runtime frames;
+- dependency analysis with eager, conditional, deferred, and dynamic edges;
+- UTF-8 `.lclcfg` files with versioned `using` expansion and source-aware diagnostics;
+- a typed framework for building configuration-driven command-line tools;
+- strict typing, branch coverage, parser differential tests, stress tests,
+  memory-leak checks, and portable package verification.
+
+## Engineering policy
+
+Development is documentation-first and test-driven. Every implementation
+milestone starts with an executable behavioural contract, demonstrates a
+failing test, implements the behaviour, passes the complete quality gate, and
+then updates both README files and the progress ledger. Production and unit-test
+submodules mirror one another as defined in
+[the module-layout specification](docs/architecture/module-layout.md).
+
+The language is intended for trusted application configuration. It is not a
+security sandbox for hostile expressions.
+
+## Documentation
+
+- Durable development rules: [AGENTS.md](AGENTS.md)
+- Progress and verification evidence: [progress.md](progress.md)
+- English specifications: `docs/specs/`
+- Complete LCL syntax: [docs/lcl-lang.md](docs/lcl-lang.md)
+- English tutorial index: [docs/tutorials/README.md](docs/tutorials/README.md)
+- Runtime tutorial: [docs/tutorials/runtime.md](docs/tutorials/runtime.md)
+- LCL examples gallery: [docs/tutorials/lcl_examples.md](docs/tutorials/lcl_examples.md)
+- Configuration-file tutorial: [docs/tutorials/config_file.md](docs/tutorials/config_file.md)
+- Dependency analytics tutorial: [docs/tutorials/dependency-analytics.md](docs/tutorials/dependency-analytics.md)
+- Python-script CLI tutorial: [docs/tutorials/cli.md](docs/tutorials/cli.md)
+- Workflow-status tutorial: [docs/tutorials/workflow-status.md](docs/tutorials/workflow-status.md)
+- Chinese CLI tutorial: [doc_cn/cli_cn.md](doc_cn/cli_cn.md)
+- Chinese tutorials: `doc_cn/`
+
+## License
+
+MIT. Version 0.3.0 requires Python 3.14+ and has no runtime dependencies.

lclang-0.3.0/README.md

@@ -0,0 +1,168 @@
+# lclang
+
+[中文说明](README_cn.md)
+
+`lclang` is a pure-Python, async-first configuration expression language for
+Python 3.14+. The 0.3.0 language, runtime, `.lclcfg`, and typed CLI release candidate is
+verified; publication is a separate maintainer action. See
+[CHANGELOG.md](CHANGELOG.md).
+
+The distribution and import name is `lclang`; production code lives under
+`src/lclang`.
+
+## Project status
+
+- Target: 0.4.0 development release
+- Latest completed milestone: M008 — `lclang` identity and `src` package layout
+- Next planned milestone: M100 — trusted-input security boundary audit
+- Implemented: foundation, enforced English rST API docs, source-aware lexer,
+  immutable AST, complete expression/comprehension parsing, all planned V1
+  expression forms, deterministic AST-to-source rendering, semantic f-string
+  parsing, stable root parse/print APIs, async expression evaluation with
+  recursively awaited sync/async iterable items, lexical
+  closures, structured failures, assertions, try recovery, finalization, and
+  synchronous/asynchronous context management, semantic f-string evaluation,
+  immutable runtime modules, and hierarchical single-flight Frame caching with
+  structured cycle detection, cancellation isolation, and atomic targeted
+  recalculation without dependant invalidation, plus task-local depth, work, and
+  materialized-collection limits, deterministic Frame close/resource cleanup,
+  scope-aware eager/conditional/deferred dependency analysis, immutable module
+  dependency graphs, filtered queries, deterministic topological ordering,
+  bounded runtime lookup tracing, static/dynamic edge reconciliation, and
+  owner-aware immutable Frame dependency snapshots with atomic refresh semantics,
+  plus shallow immutable host presets, reusable independent Frame factories,
+  manifest-driven read-only attribute namespaces, and reviewed async iterable,
+  text, immutable data, and strict JSON helpers in a standard preset, exposed
+  through a focused root API for the complete runtime workflow, plus preferred
+  source-string `define_module`/`define_frame` shortcuts and the canonical
+  `LCL_ROOT -> LCL_BUILTINS -> LCL_RUNTIME -> LCL_IMPORTS -> user` hierarchy,
+  preferred `Frame.derive` child construction, non-evaluating `has` and
+  `get_definition` lookup inspection, side-effect-free `inspect_variable`
+  dependency trees with first-seen direct-name deduplication and source-oriented
+  one-line representations with typed value/error payloads, including canonical
+  `<node-type>: <LCL expression>` payloads for AST values and canonical source
+  reprs for evaluated LCL function closures, plus controlled
+  right-biased `Frame.mixin`
+  host-value updates, definition-scoped `lhs()`, strict `YYYYMMDD` date builtins,
+  the native variadic fixed-point builtin `recursive`,
+  and non-evaluating Frame-qualified dependency graphs with value terminals and
+  lookup paths, lexical closure ownership for `lhs()`, source-string
+  `evaluate_sync`, deterministic direct/FrameFactory IDs, and a dependency
+  analytics tutorial backed by audited nested dependency and Frame packages,
+  plus immutable CLI values, exact async command decorators, nested snake_case
+  groups, full-argv parsing, structured help, lazy preset/default/config/override
+  Frame layering, handler-owned dryrun, isolated logging, result/cleanup mapping,
+  concise `CliResult.success`/`fail` constructors, valueless override keys as
+  boolean `True`, and built-in `parse_lcl` with optional evaluated inspection,
+  lazy `eval_lcl`, and deterministic nested `builtins` module commands, with canonical lclang
+  builtins and standard namespaces identified as `NativeProvided` and rendered
+  uniformly as `Builtin Function` or `Builtin Namespace`, plus structured
+  failures carrying direct-to-failing variable evaluation stacks, plus ordered
+  workflow execution-status trees, shared sub-task manager cursors, deterministic
+  parent aggregation, subtree locking, exception-transparent `with` finalization,
+  and scoped steps with atomic description/status updates and clean auto-success,
+  packaged with the `lclang` identity from the `src/lclang` source tree
+- Test status: 844 tests pass at 100.00% branch coverage; strict mypy, Ruff,
+  exhaustive source/docstring policy, executable documentation, and artifact
+  gates pass
+
+The authoritative milestone ledger is in [progress.md](progress.md). Planned
+features are deliberately not presented as implemented features.
+
+## Quickstart
+
+Run from a checkout with its development environment installed. The example is
+extracted and executed by the test suite.
+
+```python
+import asyncio
+
+import lclang
+
+
+async def main() -> None:
+    module = lclang.define_module(
+        "quickstart",
+        {"result": 'json.encode({"message": "hello lclang"})'},
+    )
+    frame = lclang.define_frame(module)
+    try:
+        print(await frame.get("result"))
+        snapshot = frame.dependency_snapshot("result")
+        print(",".join(str(edge.target) for edge in snapshot.dynamic_edges))
+    finally:
+        await frame.close()
+
+
+asyncio.run(main())
+```
+
+Inspect an override-defined result without evaluating it, or evaluate it through
+the same lazy Frame pipeline:
+
+```console
+python -m lclang.cli builtins
+python -m lclang.cli parse_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"
+python -m lclang.cli eval_lcl -o a 100 -o b 200 -o RESULT "LCL[a+b]"
+```
+
+The first command lists canonical builtins and nested namespace methods. The
+second prints the static `RESULT -> a, b` inspection tree. The third prints
+`100200` because ordinary CLI override values are literal strings.
+
+Continue with the [tutorial index](docs/tutorials/README.md), then choose the
+[runtime guide](docs/tutorials/runtime.md),
+[LCL examples gallery](docs/tutorials/lcl_examples.md), or
+[configuration-file guide](docs/tutorials/config_file.md). Use the
+[dependency analytics tutorial](docs/tutorials/dependency-analytics.md) for
+static graphs, Frame paths, runtime traces, and reconciliation. The
+[CLI tutorial](docs/tutorials/cli.md) shows how to build a configuration-driven
+Python script. The [workflow-status tutorial](docs/tutorials/workflow-status.md)
+explains task/step trees, aggregation, descriptions, locking, and scoped error
+capture for both tasks and steps. The
+[runtime API guide](docs/reference/runtime-api.md) remains the detailed
+reference.
+
+## Intended capability
+
+The 0.4 target comprises:
+
+- a versioned Python-like expression grammar with a custom AST;
+- an async-first interpreter and cached hierarchical runtime frames;
+- dependency analysis with eager, conditional, deferred, and dynamic edges;
+- UTF-8 `.lclcfg` files with versioned `using` expansion and source-aware diagnostics;
+- a typed framework for building configuration-driven command-line tools;
+- strict typing, branch coverage, parser differential tests, stress tests,
+  memory-leak checks, and portable package verification.
+
+## Engineering policy
+
+Development is documentation-first and test-driven. Every implementation
+milestone starts with an executable behavioural contract, demonstrates a
+failing test, implements the behaviour, passes the complete quality gate, and
+then updates both README files and the progress ledger. Production and unit-test
+submodules mirror one another as defined in
+[the module-layout specification](docs/architecture/module-layout.md).
+
+The language is intended for trusted application configuration. It is not a
+security sandbox for hostile expressions.
+
+## Documentation
+
+- Durable development rules: [AGENTS.md](AGENTS.md)
+- Progress and verification evidence: [progress.md](progress.md)
+- English specifications: `docs/specs/`
+- Complete LCL syntax: [docs/lcl-lang.md](docs/lcl-lang.md)
+- English tutorial index: [docs/tutorials/README.md](docs/tutorials/README.md)
+- Runtime tutorial: [docs/tutorials/runtime.md](docs/tutorials/runtime.md)
+- LCL examples gallery: [docs/tutorials/lcl_examples.md](docs/tutorials/lcl_examples.md)
+- Configuration-file tutorial: [docs/tutorials/config_file.md](docs/tutorials/config_file.md)
+- Dependency analytics tutorial: [docs/tutorials/dependency-analytics.md](docs/tutorials/dependency-analytics.md)
+- Python-script CLI tutorial: [docs/tutorials/cli.md](docs/tutorials/cli.md)
+- Workflow-status tutorial: [docs/tutorials/workflow-status.md](docs/tutorials/workflow-status.md)
+- Chinese CLI tutorial: [doc_cn/cli_cn.md](doc_cn/cli_cn.md)
+- Chinese tutorials: `doc_cn/`
+
+## License
+
+MIT. Version 0.3.0 requires Python 3.14+ and has no runtime dependencies.