The foundational document of the TCSL language — why every decision in the grammar, type system, and parser architecture exists
From dimensional type safety to four-zone architecture, from LLM-first grammar design to industry-neutral scaling
From existential purpose to industry scaling strategy and foundational commitments
A language that can describe everything
can guarantee nothing.
A language that describes exactly what’s needed
guarantees exactly what it promises.
— TCSL Manifest, §VII
This document captures the fundamental principles, philosophy, and commitments of the TCSL language. The manifest does not replace the specification — it explains why the specification is designed the way it is. Every decision in the grammar, type system, and parser architecture traces back to the principles stated here. When ambiguity or conflict arises between possible decisions, the manifest serves as the arbiter.
Between an engineer’s intent and a 3D model in a CAD system lies a chasm. Traditionally it is bridged in two ways: manual modeling (slow, non-parametric) or Python scripting (powerful, but requires developer expertise). TCSL was created so that a third participant — a language model — can bridge this chasm by generating code from a textual product description.
TCSL is a universal contract between human, machine, and geometry kernel. The human sets parameters. The machine computes derivatives and builds geometry. The kernel guarantees the result. The contract works only if each party can verify its part before handing off to the next. That is why the parser exists — an independent arbiter that validates the contract in milliseconds, without launching any specific CAD program.
TCSL is designed as an industry-agnostic language for describing physical products. Cabinet furniture is the first proving ground, because furniture rules are strict, understandable, and easily verifiable. But the language architecture is designed for scaling from the start: metal fabrication, mechanical engineering, retail fixtures, aerospace parts, building structures — any industry where material becomes a physical object. Industry-specific logic plugs in through modular rule sets without touching the language core.
Sets parameters via input
Computes let and builds geometry
Guarantees the 3D result
Every design choice in TCSL derives from one of these principles. When principles conflict, the lower-numbered one prevails.
A number without a unit is not a length. 100 is not 100 mm — it is a dimensionless scalar. TCSL does not allow adding millimeters to degrees, or multiplying volume by length to produce a non-existent L⁴ dimension. The type system is closed over the range L⁰–L³ plus a separate angle axis, and this closure is checked before a single polygon is rendered.
This is not pedantry — it is protection against a class of errors that are impossible to detect visually in a finished model. A part offset by 100 instead of 100 mm looks correct until it enters an assembly. This principle is equally critical for a furniture shelf, a milled engine part, and a structural building element.
A TCSL program flows in one direction: from parameters to geometry, from geometry to export. The zones INPUT → LET → GEOMETRY → EXPORT follow strictly in that order, and the transition is irreversible. This is not a limitation of expressiveness — it is an architectural decision reflecting the real engineering process in any industry.
INPUT is what the customer changes. LET is what the engineer computes. GEOMETRY is what the machine builds. EXPORT is what the cost estimator reads. Mixing these responsibilities means losing the ability to automate each one independently.
If the parameter total_width changes, every dependent value updates automatically. In TCSL there is no way to “forget” to update a derived parameter, because derived parameters are formulas, not numbers. let inner_width = total_width - 2 * board is a live relationship, not a dead record.
The separation into input (literals, overridable externally) and let (formulas, computed automatically) guarantees that a GUI configurator shows exactly what needs changing and hides what must not be changed.
TCSL is a single-line language. Every instruction occupies exactly one line. Line continuation is not supported. The pipeline |> is the only way to express a complex operation, and it stays on the same line.
This is a deliberate sacrifice of compactness for unambiguity. The parser synchronizes on line boundaries. The LLM generates code line by line. The human reads code line by line. An error is localized to one line. A diagnostic points to one line.
A variable in TCSL is not just a memory address. The name corpus_left_side describes the part for a human. The name Bok_LDSP16mm_1 after export ... as describes the same part for a cost estimator. Both names live on one line, and both are validated by the parser.
TCSL bridges the world of engineering design (readable variable names) and the world of production accounting (codified part names) through a single syntactic bridge — the export ... as construct. The export naming convention adapts to each industry: for furniture it is element-material-thickness; for metal fabrication — profile-grade-length; for mechanical engineering — part-tolerance-operation.
TCSL defines 32 diagnostic codes not because the language is complex, but because every error deserves its own explanation. TCSL_E015 is not “type error” — it is “dimensional result exceeds the L⁰–L³ range.” TCSL_R008 is not “runtime error” — it is “division by zero.” Each code is an address in the specification where one can find explanation, example, and fix.
The parser must detect everything it can detect without launching the geometry kernel. Two errors (R005 — empty selector result, R006 — type mismatch on runtime override) are deliberately left to runtime — they require execution. Everything else is checked statically.
TCSL is designed so that an LLM can generate it step by step, without backtracking. Four zones correspond to four generation phases: first base parameters (LLM extracts from the brief), then formulas (LLM computes dependencies), then geometry (LLM builds parts), then export (LLM assigns cost estimator names).
The absence of user-defined functions, nested blocks, conditionals, and loops is not a limitation — it is a requirement. Each of these constructs expands the state space in which an LLM can err. TCSL narrows that space to the minimum sufficient for describing a product. As new industries are onboarded, the language grows not through syntax complexity but through expanding the library of built-in constructors and production rules.
Between code generation and code execution stands the parser. It runs in milliseconds, requires no specific CAD system, consumes no GPU tokens, and creates no files. Its only job is to say “yes” or “no, and here’s why.”
The parser verifies everything that can be verified without geometry: lexics, syntax, zone ordering, dimensional algebra, pipeline type compatibility, operation arity, export uniqueness, positive constructor parameters, integer counts, division by zero. That is 30 checks out of 32 — the parser covers 94% of the specification.
Parser behavior is defined by specification v1.5, not by the implementation. If the implementation diverges from the specification — that is an implementation bug, not a specification bug. The EBNF grammar v1.5 with 62 productions and 25 semantic constraints is a formal contract by which an alternative implementation can be written and produce identical behavior.
The parser is a reference implementation, but not the standard. The standard is the specification text. The parser is its executable embodiment.
TCSL v1.5 contains 62 grammar rules, 23 functions, 5 enumerations, 17 units of measurement, and 32 error codes. That is not much. It is enough to describe products of arbitrary complexity within the current domain. As new industries are onboarded, the constructor library and rule sets grow, but the syntactic complexity of the core does not. Every element of the language must justify its existence with a task that cannot be solved without it.
A proposal to add a new construct must answer three questions: what task is impossible with existing facilities, how much it will complicate LLM generation, and how much it will complicate error diagnostics. If the answer to any of the three is unsatisfactory — the construct is not added.
Non-negotiable guarantees that every TCSL implementation must honor
The TCSL parser runs on the Python 3.11+ standard library and nothing else. This guarantees it can run anywhere Python exists: CI server, Docker container, developer laptop, Jupyter notebook, cloud function. External dependencies are debt that must eventually be paid with updates, version conflicts, and lost reproducibility.
The lexer handles characters and tokens. The parser handles structure and grammar. The analyzer handles types and semantics. Each phase receives the output of the previous one with no reverse dependencies. This allows testing each phase in isolation, swapping an implementation without affecting the rest, and debugging problems starting from the lowest level.
The parser must collect the maximum number of errors in a single pass. Upon discovering an error on line 5, it synchronizes on the line boundary and continues from line 6. The semantic analyzer runs even with syntactic errors — on those AST parts that were successfully parsed. This is critical for LLM agents that receive all errors in one batch and fix them in a single iteration.
Every token, every AST node, every diagnostic contains a Span — a precise reference to file, line, start column, and end column. This is not a luxury but a requirement for three consumers: IDE (error underlining), CI (machine-readable report), and LLM (automatic fix by position).
An identical input file always produces an identical AST, an identical symbol table, and an identical list of diagnostics. Diagnostic ordering is determined by file position, not by AST traversal order. This enables snapshot testing and guarantees reproducibility in CI.
The language core — grammar, type system, dimensional algebra, four-zone structure, parser — contains no industry-specific logic. All specifics are encapsulated in pluggable modules: constructor libraries, production rule sets, and export name templates. Onboarding a new industry requires no changes to the parser, analyzer, or core specification.
| Verification Layer | Checks Performed | Coverage |
|---|---|---|
| Static (Parser) | Lexics, syntax, zone ordering, dimensional algebra, pipeline types, operation arity, export uniqueness, positive params, integer counts, division by zero | 30 / 32 — 94% |
| Runtime (Kernel) | R005: empty selector result, R006: type mismatch on override | 2 / 32 — 6% |
These are not missing features. They are architectural decisions that protect the simplicity of the language.
| Excluded Construct | Why It’s Excluded | What Replaces It |
|---|---|---|
| User-defined functions | Introduces abstraction requiring return type systems, scoping rules, and call mechanisms — unjustified complexity for a product-description DSL | Built-in functions with fixed signatures |
| Conditionals & loops | Turns a declarative description into an imperative program with branches the LLM must anticipate | linear_pattern, circular_pattern |
| Nested blocks & scopes | Complicates name resolution and makes code less predictable for LLMs | Single flat symbol table |
| String literals | TCSL operates on numbers, units, identifiers, and enumerations — strings are unnecessary | Identifiers and as-names |
| Imports & modularity | Each .tcsl file is self-contained — inter-file dependencies create resolution, versioning, and caching burdens | One file = one product |
| Industry lock-in | TCSL is not “a language for furniture” — furniture is the first proving ground | Pluggable constructor libraries & rule sets |
These boundaries are not technical debt. They are architectural decisions protecting the simplicity and universality of the language. If a task demands constructs beyond TCSL, the solution is not to extend TCSL — it is to use a Python wrapper around the generated code.
Five stakeholders, five promises
TCSL reads like a product specification — in any industry. Variable names are meaningful, comments are explanatory, structure is sequential. A TCSL program can be shown to a colleague unfamiliar with the language, and they will understand what is described — whether it’s a cabinet, a welded frame, or a milled housing.
TCSL is generated in a single pass, without backtracking, with a predictable structure. Four zones map to four prompt steps. Errors are returned with precise positions and codes suitable for automatic correction. When switching between industries, the set of available constructors and rules changes, but not the generation logic.
Every exported part has a name from which element, material, thickness, and sequence number can be extracted. The name format is validated by the parser (warning W001), not after the fact during import into the estimator. The format template adapts per industry.
The AST is typed, the symbol table is complete, all checks are done. The transpiler can trust the input data and focus on generating code for a specific CAD system (FreeCAD, KOMPAS-3D, SolidWorks, Fusion 360) without duplicating validation logic.
Validation takes milliseconds. Exit code is unambiguous (0 — no errors, 1 — errors). Output is available in text and JSON formats. TCSL validation integrates into a pipeline as naturally as a linter or type checker.
Versioning, change governance, and the stable-core/growing-periphery architecture
TCSL is versioned as <major>.<minor>. A minor version (1.4 → 1.5) adds new constructs, error codes, and clarifies semantics. It is backward-compatible: a program valid in v1.4 remains valid in v1.5 (except for specification errata). A major version (1.x → 2.0) permits incompatible changes: removal of constructs, semantic changes to existing ones, zone restructuring.
What real-world task is impossible to solve with current facilities?
How much will LLM generation be complicated? Will the error rate increase?
Can the new construct be checked statically? What error codes are needed?
Will the change break existing programs?
If any filter yields a negative answer — the change is deferred or rejected.
Grammar, type system, dimensional algebra, zone structure, and parser remain unchanged when onboarding a new industry. The core is a constitution that cannot be amended for every new law.
Each module comprises three components: a constructor library (geometric primitives and operations specific to the industry), a production rule set (constraints validated during model verification), and an export name template (naming convention for production accounting in that industry).
Industry onboarding priority is determined by rule maturity and training data availability: cabinet furniture (current proving ground), metal fabrication and sheet metal (next step), retail fixtures, mechanical engineering, aerospace, and construction/BIM (long-term horizon).
Integration with the CAD ecosystem is achieved through the STEP standard format, eliminating vendor lock-in and allowing TCSL to work with any CAD program that supports this format.
TCSL is not a general-purpose programming language. It is a universal tool for a single class of tasks: turning a textual description of a physical product into a parametric 3D model with names suitable for production accounting. Every decision in the language — from dimensional typing to four-zone structure, from the prohibition of user-defined functions to mandatory units of measurement — serves this class of tasks.
Cabinet furniture is the first proving ground, not the end goal. TCSL’s architecture has been industry-neutral from the start: a stable core, pluggable industry modules, standard integration formats. The team is building not “a program for designing furniture,” but a universal bridge between human language and real production — for any industry where material becomes a physical object.
The simplicity of TCSL is not an initial state from which the language will “grow.” It is a target property that must be defended with every change. A language that can describe everything can guarantee nothing. A language that describes exactly what’s needed guarantees exactly what it promises. As the language expands to new industries, the periphery grows — constructor libraries and rule sets — but the core remains compact, strict, and predictable.
TCSL describes not furniture, but physical objects. Industry rules plug in modularly — the core remains unified.