T2S Specification Text Defined System (T2S) Language Specification Author: Gabor Soos Version: v2026.08.04-1400 Language: en Status: RC3 Comments: Rust, Zig, Python, namespaces, versioning, and generalized root schematics. 0. Introduction Text2System (T2S) is a Text-Defined Systems Engineering language for describing software and embedded systems using a single human-readable, machine-readable plain-text source. A T2S System Model completely describes a software system from architectural definition through packaging and intended deployment while remaining independent of implementation language, runtime technology, and deployment technology. T2S defines what a system is. Programming languages define how the system behaves. Deployment technologies define how the system is realized and operated. Unlike traditional Model-Based Systems Engineering, T2S treats text as the canonical definition of the system. Documentation, architecture views, implementation skeletons, interface definitions, validation reports, tests, deployment artifacts, diagrams, and other engineering artifacts are not part of the language itself; they are projections of the Canonical System Model. This document is the normative specification of T2S Language 1.0. T2S combines: - T2D narrative for human-readable documentation. - T2S semantic declarations for machine-readable system definition. A conforming T2S processor performs the following normative stages: - Region scanning. - Narrative parsing into a Narrative AST. - Semantic parsing into a Source AST. - Semantic validation. - Construction of the Canonical System Model. The Canonical System Model is the only canonical semantic representation defined by the language. Projectors transform the Canonical System Model into implementation languages, documentation, interface definitions, package descriptions, deployment descriptions, tests, diagrams, and other engineering artifacts. T2S 1.0 defines three reference projectors: - Rust - Zig - Python Reference projectors are part of the reference toolchain and are not part of the language semantics. The portable meaning of a T2S source shall never depend on a particular projector. The normative processing pipeline is: T2S Source ↓ Region Scan ↓ Narrative AST + Source AST ↓ Canonical System Model Construction ↓ Semantic Validation ↓ Validated Canonical System Model ↓ Projector ↓ Projection Model ↓ Renderer ↓ Artifacts Additional projectors may be developed independently without modifying the T2S language specification. requirement: id: T2S-GEN-001 statement: A T2S source shall be readable as a human-oriented system specification. requirement: id: T2S-GEN-002 statement: A T2S source shall define deterministic machine-readable system semantics. requirement: id: T2S-GEN-003 statement: T2S shall define the system independently of algorithm implementation. requirement: id: T2S-GEN-004 statement: A core T2S construct shall describe a portable property of a system rather than a feature of a particular implementation language, runtime environment, or deployment technology. requirement: id: T2S-GEN-005 statement: Package and deployment descriptions are part of the System Model and shall remain independent of deployment technologies. requirement: id: T2S-GEN-006 statement: Projectors shall preserve the portable semantics of the Canonical System Model. requirement: id: T2S-GEN-007 statement: A Realization Profile may refine realization but shall not alter the portable semantics of the Canonical System Model. T2S defines the system from design through distribution and intended deployment. Implementation languages, build systems, package formats, deployment technologies, and operational tooling realize that definition but do not redefine it. 1. Scope T2S 1.0 defines a portable system description and implementation-contract language. T2S 1.0 is intended to support: - Software architecture. - Embedded-system architecture. - Module boundaries. - APIs and callable operations. - Portable data types. - Explicit error contracts. - Synchronous, asynchronous, and one-way operations. - Rust, Zig, and Python code generation or validation. - Requirement and test traceability. - Packaging and deployment descriptions. T2S 1.0 does not define: - Algorithm bodies. - General-purpose expressions. - Language-specific generics. - Rust lifetimes or traits as core semantics. - Zig comptime constructs as core semantics. - C preprocessor macros as core semantics. - Concrete thread, lock, allocator, or async-runtime implementations. 2. Language Composition Text2System is composed of two independently parseable source forms. T2D narrative source describes the system for human readers. T2S semantic source defines the formal system model. A mixed T2S document contains both forms in one source file. relationship: subject: Text2System predicate: embeds object: Text2Doc relationship: subject: Text2System predicate: contains object: T2SSemanticSource requirement: id: T2S-LANG-001 statement: The T2D parser shall parse narrative regions independently of the T2S semantic parser. requirement: id: T2S-LANG-002 statement: The T2S semantic parser shall parse standalone semantic source independently of a T2D document. 3. Source Regions The T2S cover follows the existing T2D cover rules. Within the document body, an unindented non-empty line belongs to T2D narrative source. Within the document body, a non-empty line beginning with two SPACE (U+0020) characters belongs to T2S semantic source. The two leading spaces form the semantic envelope. The envelope is not part of the semantic source and shall be removed before semantic parsing. requirement: id: T2S-SRC-001 statement: In the T2D body, a non-empty line beginning at column one shall be interpreted as T2D narrative source. requirement: id: T2S-SRC-002 statement: In the T2D body, a non-empty line beginning with two SPACE (U+0020) characters shall be interpreted as T2S semantic source. requirement: id: T2S-SRC-003 statement: The region scanner shall remove exactly two leading two SPACE (U+0020) characters from every semantic source line before semantic parsing. requirement: id: T2S-SRC-004 statement: Leading spaces in the T2D cover shall retain their existing T2D meaning and shall not introduce T2S semantics. A semantic region continues while subsequent non-empty lines begin with at least two spaces. Blank lines may occur within a semantic region. The region ends before the next non-empty body line beginning at column one. 4. Semantic Notation T2S semantic source uses the T2S YAML Profile. The T2S YAML Profile is a deterministic subset of YAML used exclusively as the concrete notation of T2S semantic declarations. The T2S YAML Profile defines the concrete syntax of semantic source. YAML itself does not define T2S semantics. Allowed notation: - mappings - sequences - string scalars - decimal integer scalars - decimal floating-point scalars - boolean scalars - null scalars - folded block strings (>) - literal block strings (|) - comments Mapping keys shall be strings. Duplicate mapping keys are forbidden. Indentation shall use SPACE (U+0020) characters only. Tab characters shall not be used for indentation. The only boolean scalar spellings are: - true - false The only null scalar spelling is: - null Integer scalars may use: - decimal notation - hexadecimal notation - binary notation - octal notation Floating-point scalars may use: - decimal notation - scientific notation NaN and infinite floating-point values are forbidden. Single-line scalar values may be represented using ordinary YAML scalars. Scalar values spanning multiple physical lines shall use either: - folded block strings (>) for ordinary prose - literal block strings (|) for verbatim text Single-line scalar values may be represented using ordinary YAML scalars. Multi-line plain scalars are forbidden. Implementation-dependent scalar forms, including timestamps, alternative boolean or null spellings, and implementation-defined numeric representations, are forbidden. Forbidden notation: - anchors - aliases - merge keys - custom tags - executable constructors - complex mapping keys - duplicate mapping keys - multiple YAML documents in one semantic compilation unit - implementation-dependent implicit scalar conversions - multi-line plain scalars Comments and presentation details shall not alter T2S semantics. Mapping order shall be preserved in the Source AST for deterministic processing, diagnostics, formatting, and projection. requirement: id: T2S-YAML-001 statement: > T2S semantic source shall conform to the T2S YAML Profile. requirement: id: T2S-YAML-002 statement: > A conforming T2S implementation shall reject YAML features forbidden by the T2S YAML Profile. requirement: id: T2S-YAML-003 statement: > Scalar interpretation shall be deterministic across conforming implementations. requirement: id: T2S-YAML-004 statement: > Duplicate mapping keys shall be rejected. requirement: id: T2S-YAML-005 statement: > Mapping order shall be preserved in the Source AST. requirement: id: T2S-YAML-006 statement: > Scalar values spanning multiple physical lines shall use folded block strings (>) or literal block strings (|). YAML is notation only. YAML structure shall not independently define T2S semantics. 5. Processing and Semantic Model A conforming T2S processor transforms a source document through a sequence of well-defined representations. The Source AST records the parsed structure of the source document together with its source locations. The Canonical System Model records implementation-independent semantics constructed from the Source AST. A Canonical System Model becomes valid for projection only after successful semantic validation. A Projection Model records the target-specific semantic representation produced by a Projector. Projection Models are target dependent and are outside the core language. type: name: T2SModelLayer kind: enum values: - source_ast - canonical_system_model - projection_model requirement: id: T2S-MODEL-001 statement: Every conforming processor shall construct a Canonical System Model from a valid Source AST. requirement: id: T2S-MODEL-002 statement: Validators shall operate exclusively on the Canonical System Model. requirement: id: T2S-MODEL-003 statement: A Projector shall derive one Projection Model from one Canonical System Model and one Realization Profile. requirement: id: T2S-MODEL-004 statement: A Projection Model shall preserve the portable semantics of the Canonical System Model. requirement: id: T2S-MODEL-005 statement: A Projector shall report unsupported semantics explicitly and shall not silently modify or discard portable semantics. 6. Core Ontology The Canonical System Model is composed of a small, orthogonal set of fundamental semantic element kinds. These element kinds define the portable structure of a system and are independent of implementation language, runtime environment, and deployment platform. type: name: T2SElementKind kind: enum values: - system - module - interface - function - type - constant - configuration - requirement - constraint - implementation - test - package - deployment - relationship requirement: id: T2S-ONTOLOGY-001 statement: Every semantic element shall have exactly one element kind. requirement: id: T2S-ONTOLOGY-002 statement: Every semantic element shall define exactly one stable identifier. requirement: id: T2S-ONTOLOGY-003 statement: Every semantic element shall belong to exactly one Canonical System Model. requirement: id: T2S-ONTOLOGY-004 statement: > The order of T2SElementKind values is descriptive only and shall not define declaration order, processing order, ownership, or semantic precedence. The fundamental architectural organization of a Canonical System Model is: System ├── Subsystem(s) ├── Module(s) ├── Package(s) └── Deployment(s) Module ├── Interface(s) │ └── Function(s) ├── Type(s) ├── Constant(s) ├── Configuration(s) ├── Requirement(s) ├── Constraint(s) ├── Implementation(s) └── Test(s) Relationship is a first-class semantic element. Relationships connect semantic elements throughout the Canonical System Model and are not constrained by the hierarchical organization shown above. The responsibilities of the core semantic element kinds are: - System defines the architectural boundary of a software system. - Module groups related semantic elements into cohesive architectural units. - Interface defines externally visible contracts. - Function defines callable behavior belonging to an interface. - Type defines structured or primitive data. - Constant defines immutable values. - Configuration defines configurable properties. - Requirement defines normative system requirements. - Constraint defines semantic or architectural rules. - Implementation defines language-specific realization bindings. - Test defines verification artifacts. - Package defines distribution units. - Deployment defines runtime realization. - Relationship defines explicit semantic connections between elements. Documentation is represented exclusively by the Narrative AST and is not part of the Canonical System Model. Projection concerns, including Projectors, Projection Models, and Realization Profile, are defined separately and are not part of the Core Ontology. 7. Relationships Relationships define explicit semantic connections between elements of the Canonical System Model. A relationship connects one subject element to one object element through one predicate. Relationships are first-class semantic elements. They may be validated, queried, documented, and projected independently of the elements they connect. type: name: T2SRelationshipKind kind: enum values: - contains - depends_on - uses - provides - implements - realizes - extends - specializes - references - includes - hosts - deploys - verifies - configures - communicates_with - exposes - binds requirement: id: T2S-REL-001 statement: Every relationship shall reference exactly one existing subject element. requirement: id: T2S-REL-002 statement: Every relationship shall reference exactly one existing object element. requirement: id: T2S-REL-003 statement: Every relationship shall specify exactly one predicate. requirement: id: T2S-REL-004 statement: A relationship predicate shall be compatible with the kinds of its subject and object elements. Example relationship: id: org.text2system.example.s07.rel.system-contains-module subject: org.text2system.example.s07.system predicate: contains object: org.text2system.example.s07.module relationship: id: org.text2system.example.s07.rel.module-provides-interface subject: org.text2system.example.s07.module predicate: provides object: org.text2system.example.s07.interface 8. Source AST The Source AST is the parsed representation of T2S semantic source. A Source AST preserves the syntactic structure of semantic source before semantic interpretation and validation. The Source AST represents semantic declarations, compilation-unit metadata, imports, scalar values, mapping order, sequence order, and source locations. The Source AST is an implementation artifact. It is not part of the Canonical System Model and does not independently define portable system semantics. Semantic references may remain unresolved in the Source AST. A Source AST may contain declarations that are structurally valid but semantically invalid. The internal representation of the Source AST is implementation-defined. requirement: id: T2S-SOURCE-AST-001 statement: A conforming parser shall construct a Source AST from valid T2S semantic source. requirement: id: T2S-SOURCE-AST-002 statement: Every Source AST node shall preserve its originating source location. requirement: id: T2S-SOURCE-AST-003 statement: Mapping and sequence order shall be preserved in the Source AST. requirement: id: T2S-SOURCE-AST-004 statement: The Source AST shall preserve compilation-unit metadata and semantic declarations. requirement: id: T2S-SOURCE-AST-005 statement: Source AST structure shall not independently define portable semantics. requirement: id: T2S-SOURCE-AST-006 statement: Semantic validation shall consume a Source AST and construct a Canonical System Model. Processing pipeline: T2S Semantic Source ↓ Semantic Parser ↓ Source AST ↓ Semantic Interpretation ↓ Canonical System Model 9. Canonical System Model The Canonical System Model is the normative semantic representation defined by T2S. The Canonical System Model defines the portable meaning of a T2S source independently of source-file organization, implementation language, runtime environment, realization profile, projector, and generated artifacts. The Canonical System Model contains only the semantic element kinds defined by the Core Ontology. Documentation, Source AST nodes, source locations, projection models, generated artifacts, and implementation-specific metadata are not part of the Canonical System Model. Implementations may retain source locations and traceability information provided they do not alter portable semantics. A Canonical System Model that has successfully completed semantic validation is a Validated Canonical System Model. The semantic element kinds of the Canonical System Model are defined by the Core Ontology. Conceptual model: Source AST -> Canonical System Model -> Validated Canonical System Model 10. Compilation Units A T2S source file is processed as a compilation unit. A compilation unit is a source-level container for language metadata, imports, narrative, and semantic declarations. A compilation unit exists only during source processing and is not part of the Canonical System Model. Every semantic compilation unit shall define exactly one root schematic. The root schematic is the primary semantic subject of the compilation unit. Any T2S semantic element kind may serve as the root schematic. The root schematic does not imply architectural ownership, containment, composition, or semantic precedence. If a compilation unit contains exactly one top-level semantic declaration, that declaration is the implicit root semantic. If a compilation unit contains multiple top-level semantic declarations, the compilation-unit metadata shall explicitly identify the root schematic. Compilation-unit membership shall not imply semantic ownership. requirement: id: T2S-UNIT-001 statement: Every semantic compilation unit shall define exactly one root semantic. requirement: id: T2S-UNIT-002 statement: Any T2S semantic element kind may serve as the root schematic. requirement: id: T2S-UNIT-003 statement: > If exactly one top-level semantic declaration exists, that declaration shall be the implicit root semantic. requirement: id: T2S-UNIT-004 statement: > If multiple top-level semantic declarations exist, compilation-unit metadata shall explicitly identify the root schematic. requirement: id: T2S-UNIT-005 statement: Compilation-unit membership shall not imply semantic ownership. requirement: id: T2S-UNIT-006 statement: > The declared root semantic shall resolve to a semantic element contained in or imported by the compilation unit. Example t2s: language: "1.0" namespace: org.text2system.example.storage root: org.text2system.example.storage system: id: org.text2system.example.storage module: id: org.text2system.example.storage.core interface: id: org.text2system.example.storage.api 10.1 Schematic Scopes A schematic scope is a semantic element that may contain or compose other semantic elements. T2S 1.0 defines the following schematic scopes: - system - module A schematic scope provides architectural organization independent of source files. A schematic scope may define canonical members and composed inclusions. members identifies elements owned by the scope. includes identifies independently defined schematic scopes or semantic elements participating in the composed system. requirement: id: T2S-SCOPE-001 statement: System and module shall be schematic scopes. requirement: id: T2S-SCOPE-002 statement: A schematic scope shall not be inferred from the compilation-unit structure. requirement: id: T2S-SCOPE-003 statement: The members relation shall define canonical ownership. requirement: id: T2S-SCOPE-004 statement: The includes relation shall define semantic composition. Example module: id: org.text2system.example.s10.1.module members: - org.text2system.example.s10.1.input_record - org.text2system.example.s10.1.interface system: id: org.text2system.example.s10.1.system members: - org.text2system.example.s10.1.subsystem includes: - org.text2system.example.s10.1.module 11. Identifiers and References Every semantic element shall have exactly one stable identifier. A semantic element may additionally define a human-readable name. Identifiers uniquely identify semantic elements within the Canonical System Model and shall remain stable across revisions whenever practical. Names are intended for presentation and documentation and need not be unique outside their enclosing semantic scope. Identifiers and names are case-sensitive. The lexical grammar of an identifier is: [A-Za-z_][A-Za-z0-9_.-]* References shall resolve by identifier. Qualified names are a presentation form and shall not participate in semantic resolution. requirement: id: T2S-ID-001 statement: Every semantic element shall define exactly one identifier. requirement: id: T2S-ID-002 statement: No two semantic elements within a Canonical System Model shall share the same identifier. requirement: id: T2S-ID-003 statement: Duplicate names within the same semantic scope shall be rejected. requirement: id: T2S-ID-004 statement: Every non-external semantic reference shall resolve to exactly one compatible semantic element. requirement: id: T2S-ID-005 statement: Identifier matching shall be case-sensitive. 12. System A system is the highest-level architectural entity defined by T2S. A system represents a coherent software or software-controlled system boundary. A system may contain subsystems and other core semantic elements through explicit relationships. A subsystem is a system that is contained by another system. Subsystem status is therefore contextual and does not require a separate semantic element kind. A system may serve as the root declaration of a compilation unit. system: id: org.text2system.example.s12.system name: RootSystem version: "1.0.0" description: Example system used by this specification. system: id: org.text2system.example.s12.subsystem name: ChildSystem version: "1.0.0" relationship: id: org.text2system.example.s12.rel.system-contains-subsystem subject: org.text2system.example.s12.system predicate: contains object: org.text2system.example.s12.subsystem requirement: id: T2S-SYS-001 statement: A system shall define exactly one stable identifier. requirement: id: T2S-SYS-002 statement: A system may contain zero or more systems as subsystems through explicit contains relationships. requirement: id: T2S-SYS-003 statement: A system shall not contain itself directly or transitively. requirement: id: T2S-SYS-004 statement: Compilation-unit structure shall not imply system containment. requirement: id: T2S-SYS-005 statement: A contained system shall remain an independently identifiable semantic element. System ├── System(s) ├── Module(s) ├── Package(s) └── Deployment(s) Module ├── Interface(s) │ └── Function(s) ├── Type(s) ├── Constant(s) ├── Configuration(s) ├── Requirement(s) ├── Constraint(s) ├── Implementation(s) └── Test(s) 13. Module A module is a logical architectural subdivision of a system. A module groups related semantic elements into a cohesive unit and establishes a stable architectural boundary within a system. A module is independent of implementation language, compilation strategy, and deployment topology. A module may contain interfaces, functions through interfaces, types, constants, configurations, requirements, constraints, implementations, and tests. requirement: id: T2S-MOD-001 statement: Every module shall define exactly one stable identifier. requirement: id: T2S-MOD-002 statement: In a complete Canonical System Model, every module shall belong to exactly one system. requirement: id: T2S-MOD-003 statement: Module membership shall be expressed explicitly. Example module: id: org.text2system.example.s13.module name: CoreModule interface: id: org.text2system.example.s13.interface name: MainInterface relationship: id: org.text2system.example.s13.rel.module-contains-interface subject: org.text2system.example.s13.module predicate: contains object: org.text2system.example.s13.interface relationship: id: org.text2system.example.s13.rel.module-provides-interface subject: org.text2system.example.s13.module predicate: provides object: org.text2system.example.s13.interface Module │ ├──contains── Interface ├──contains── Type ├──contains── Requirement ├──contains── Test └──contains── ... 14. Interface An interface defines an explicit interaction contract between a system and an external or internal entity. An interface specifies the functions, data types, and other semantic elements that constitute the interaction contract. An interface defines the portable semantics of an interaction. Communication technologies, programming languages, binary interfaces, and transport mechanisms are realization concerns outside the core language. requirement: id: T2S-IF-001 statement: Every interface shall define exactly one stable identifier. requirement: id: T2S-IF-002 statement: An interface may expose zero or more functions. requirement: id: T2S-IF-003 statement: An interface shall remain independent of communication technology, programming language, binary interface, and transport protocol. Example interface: id: org.text2system.example.s14.interface name: MainInterface functions: - start - stop The following realization examples describe possible projections of the same portable interface: - Rust library API - C ABI - REST API - Command-line interface (CLI) - gRPC service - HTTP service - Message-based protocol The choice of interface realization is defined by projectors and realization profile and does not alter the portable semantics of the interface. 15. Function A function defines a callable interaction contract. A function belongs to exactly one interface and defines one operation of that interface. A function may declare: - Parameters. - Return type. - Error type. - Invocation semantics. - Requirement traceability. function: id: org.text2system.example.s15.function name: execute parameters: - name: request direction: input type: org.text2system.example.s15.input_record returns: type: org.text2system.example.s15.output_record errors: type: org.text2system.example.s15.error_enum invocation: synchronous 16. Type System The T2S Type System defines portable data contracts that are independent of programming language, runtime environment, processor architecture, binary representation, and deployment technology. The semantic meaning of a type shall remain identical across all conforming implementations and projectors. T2S defines the following primitive types: - bool - i8 - i16 - i32 - i64 - u8 - u16 - u32 - u64 - f32 - f64 - string - bytes T2S 1.0 intentionally does not define implementation-dependent integer types, including usize, isize, long, unsigned long, intptr_t, or pointer-sized integers. T2S defines the following composite type kinds: - record - enum - sequence - array - option - union - variant - alias - opaque An option represents either the absence of a value or the presence of exactly one value of its declared element type. A union represents one value selected from several possible member types. The active member is determined by the surrounding semantic contract and is not intrinsically represented by the union itself. A variant represents one value selected from several named alternatives. A variant intrinsically identifies its active alternative. An alias defines an alternative name for another type while preserving its portable semantics. An opaque type defines a portable semantic identity whose internal representation is intentionally hidden. requirement: id: T2S-TYPE-001 statement: Primitive types shall have identical semantic meaning across all conforming implementations. requirement: id: T2S-TYPE-002 statement: Every user-defined type shall declare exactly one type kind. requirement: id: T2S-TYPE-003 statement: Every referenced type shall resolve to a declared primitive type or user-defined type. requirement: id: T2S-TYPE-004 statement: A projector shall preserve the semantic meaning of every declared type. requirement: id: T2S-TYPE-005 statement: An option shall contain either no value or exactly one value of its declared element type. requirement: id: T2S-TYPE-006 statement: A union value shall conform to exactly one declared member type. requirement: id: T2S-TYPE-007 statement: A variant value shall contain exactly one declared alternative and shall identify that alternative. requirement: id: T2S-TYPE-008 statement: An alias shall preserve the semantics of its referenced type. requirement: id: T2S-TYPE-009 statement: The internal representation of an opaque type shall not be required for portable semantic validation. Example type: id: org.text2system.example.s16.input_record kind: record fields: data: type: bytes label: type: option: string type: id: org.text2system.example.s16.output_record kind: record fields: value: type: string score: type: f32 type: id: org.text2system.example.s16.error_enum kind: enum underlying_type: u32 values: invalid_input: 1 unavailable: 2 internal_failure: 3 type: id: org.text2system.example.s16.byte_sequence kind: sequence element: type: bytes type: id: org.text2system.example.s16.fixed_array kind: array element: type: f64 length: 9 type: id: org.text2system.example.s16.optional_text kind: option element: type: string type: id: org.text2system.example.s16.number_union kind: union members: - type: i32 - type: i64 - type: f32 - type: f64 type: id: org.text2system.example.s16.result_variant kind: variant alternatives: value: type: org.text2system.example.s16.output_record error: type: org.text2system.example.s16.error_enum type: id: org.text2system.example.s16.text_alias kind: alias target: type: string type: id: org.text2system.example.s16.handle kind: opaque Primitive Types ├── bool ├── integers ├── floating-point ├── string └── bytes Composite Types ├── record ├── enum ├── sequence ├── array ├── option ├── union ├── variant ├── alias └── opaque 17. Record Types A record defines a composite type consisting of an ordered set of uniquely named fields. Each field shall declare exactly one type. Field order is preserved by the Canonical System Model to ensure deterministic processing and projection. Field order alone does not define binary layout, memory representation, serialization, or calling convention. A field may additionally declare: - option. - default. - documentation. A field whose type is an option may be absent according to the semantics of the selected projection. Binary layout, alignment, padding, serialization, and calling conventions are realization concerns defined by implementations, realization profiles, or projectors and are outside the core language. requirement: id: T2S-RECORD-001 statement: Every record field shall define a unique name within its enclosing record. requirement: id: T2S-RECORD-002 statement: Every record field shall declare exactly one type. requirement: id: T2S-RECORD-003 statement: Record field order shall be preserved by the Canonical System Model. requirement: id: T2S-RECORD-004 statement: A projector shall preserve declared field order unless an explicitly selected realization defines an alternative representation. Example type: id: org.text2system.example.s17.record kind: record fields: data: type: bytes label: type: option: string timeout: type: u32 default: 1000 enabled: type: bool default: false type: id: org.text2system.example.s17.settings kind: record fields: label: type: string scale: type: f64 offset_x: type: f64 offset_y: type: f64 values: type: sequence: f64 18. Enum Types An enum defines a closed set of named values. Each enum value represents a distinct semantic alternative. An enum may declare an underlying integer type to support deterministic projection into implementation languages and binary interface definitions. The permitted underlying integer types are: - u8 - u16 - u32 - u64 If an underlying integer type is declared, every enum value shall define an explicit, unique integer value. The choice of underlying integer type does not alter the portable semantics of an enum. Binary representation, alignment, and ABI compatibility are realization concerns defined by implementations, realization profiles, or projectors. requirement: id: T2S-ENUM-001 statement: Every enum value shall define a unique name. requirement: id: T2S-ENUM-002 statement: If an underlying integer type is declared, every enum value shall define a unique explicit integer value. requirement: id: T2S-ENUM-003 statement: An enum shall not contain duplicate value names or duplicate integer values. requirement: id: T2S-ENUM-004 statement: A projector shall preserve the semantic meaning of every enum value. Example type: id: org.text2system.example.s18.status kind: enum underlying_type: u32 values: invalid_input: 1 unavailable: 2 internal_failure: 3 19. Sequence, Array, String, and Bytes A sequence defines an ordered collection of zero or more values of the same element type. The length of a sequence is determined at runtime. An array defines an ordered collection of a fixed number of values of the same element type. The length of an array is part of its type definition. A string defines an ordered sequence of Unicode scalar values. A bytes value defines an ordered sequence of uninterpreted octets. The portable type system defines the semantic meaning of these types and does not prescribe: - memory layout - ownership - allocation strategy - binary representation - character encoding - null termination These realization properties are defined by implementations, realization profiles, and projectors. requirement: id: T2S-COLLECTION-001 statement: Every sequence shall declare exactly one element type. requirement: id: T2S-COLLECTION-002 statement: Every array shall declare exactly one element type and a fixed length. requirement: id: T2S-COLLECTION-003 statement: The declared length of an array shall be greater than zero. requirement: id: T2S-COLLECTION-004 statement: A string shall represent Unicode text independently of its projected encoding. requirement: id: T2S-COLLECTION-005 statement: A bytes value shall not imply any character encoding or interpretation. Example type: id: org.text2system.example.s19.byte_sequence kind: sequence element: type: u8 type: id: org.text2system.example.s19.fixed_array kind: array element: type: f64 length: 9 type: id: org.text2system.example.s19.text_alias kind: alias target: type: string type: id: org.text2system.example.s19.bytes_alias kind: alias target: type: bytes 20. Option Type An option type represents either the absence of a value or exactly one value of its declared element type. An option defines portable semantic presence or absence. It does not prescribe a nullable pointer, sentinel value, tagged union, or any other implementation representation. The realization of an option type is defined by implementations, realization profiles, and projectors. requirement: id: T2S-OPTION-001 statement: An option shall contain either no value or exactly one value of its declared element type. requirement: id: T2S-OPTION-002 statement: The semantic meaning of an option shall be preserved by every conforming projector. Example type: id: org.text2system.example.s20.optional_text kind: option element: type: string 21. Union Types A union defines a value that may conform to exactly one of several declared member types. A union does not intrinsically identify its active member. The surrounding semantic contract shall provide sufficient information to determine the active member. The realization of a union is defined by implementations, realization profiles, and projectors. requirement: id: T2S-UNION-001 statement: A union shall declare one or more member types. requirement: id: T2S-UNION-002 statement: A union value shall conform to exactly one declared member type. requirement: id: T2S-UNION-003 statement: A projector shall preserve the semantic meaning of every union member. Example type: id: org.text2system.example.s21.number_union kind: union members: - type: i32 - type: i64 - type: f32 - type: f64 22. Variant Types A variant defines a value that may assume exactly one of several named alternatives. Unlike a union, a variant intrinsically identifies its active alternative. The realization of a variant is defined by implementations, realization profiles, and projectors. requirement: id: T2S-VARIANT-001 statement: A variant shall declare one or more named alternatives. requirement: id: T2S-VARIANT-002 statement: A variant value shall identify exactly one active alternative. requirement: id: T2S-VARIANT-003 statement: A projector shall preserve the semantic identity of every variant alternative. Example type: id: org.text2system.example.s22.result_variant kind: variant alternatives: success: type: org.text2system.example.s22.output_record failure: type: org.text2system.example.s22.error_enum 23. Alias Types An alias defines an alternative semantic name for an existing type. An alias introduces no new portable data semantics. The aliased type and its alias are semantically equivalent. The realization of an alias is defined by implementations and projectors. requirement: id: T2S-ALIAS-001 statement: An alias shall reference exactly one existing type. requirement: id: T2S-ALIAS-002 statement: An alias shall preserve the complete semantics of its referenced type. Example type: id: org.text2system.example.s23.text_alias kind: alias target: type: string 24. Opaque Types An opaque type defines a semantic identity whose internal representation is intentionally hidden from consumers of the type. An opaque type represents a resource whose internal structure is outside the Canonical System Model. Opaque types are suitable for representing: - runtime resources - implementation-defined objects - external library objects - operating system resources - device resources - implementation handles Consumers of an opaque type may store, compare, and transfer opaque values but shall not depend upon their internal representation. The realization of an opaque type is defined by implementations, realization profiles, and projectors. requirement: id: T2S-OPAQUE-001 statement: The internal representation of an opaque type shall not be required for portable semantic validation. requirement: id: T2S-OPAQUE-002 statement: An opaque type shall be treated as an indivisible semantic value. requirement: id: T2S-OPAQUE-003 statement: A projector shall preserve the identity semantics of an opaque type. Example type: id: org.text2system.example.s24.handle kind: opaque type: id: org.text2system.example.s24.device kind: opaque type: id: org.text2system.example.s24.connection kind: opaque 25. Constants A constant defines an immutable named value with a declared type. A constant represents a portable semantic value whose meaning shall remain identical across all conforming implementations and projectors. The representation and storage of a constant are realization concerns defined by implementations, realization profiles, and projectors. requirement: id: T2S-CONSTANT-001 statement: Every constant shall define exactly one stable identifier. requirement: id: T2S-CONSTANT-002 statement: Every constant shall declare exactly one type. requirement: id: T2S-CONSTANT-003 statement: Every constant shall define exactly one value compatible with its declared type. requirement: id: T2S-CONSTANT-004 statement: The value of a constant shall be immutable. requirement: id: T2S-CONSTANT-005 statement: A projector shall preserve the semantic value of every constant. Example constant: id: org.text2system.example.s25.max_count type: u32 value: 128 constant: id: org.text2system.example.s25.default_ratio type: f32 value: 0.85 constant: id: org.text2system.example.s25.empty_bytes type: bytes value: [] constant: id: org.text2system.example.s25.optional_text type: option: string value: null 26. Error Contracts A function may declare an error type that defines the portable contract for expected operation failures. An error type shall normally be defined as an enum, variant, or another declared type whose semantics are appropriate for the operation. An error contract defines expected failure conditions that are part of the function's portable semantics. Unexpected implementation failures, process termination, panic, exceptions, undefined behavior, or other abnormal execution mechanisms are not part of a function's declared error contract. The realization of an error contract is defined by implementations, realization profiles, and projectors. requirement: id: T2S-ERROR-001 statement: A function shall declare at most one error type. requirement: id: T2S-ERROR-002 statement: Every declared error type shall resolve to an existing type. requirement: id: T2S-ERROR-003 statement: A projector shall preserve the semantic distinction between successful completion and every declared error condition. Example type: id: org.text2system.example.s26.error kind: enum values: invalid_input: 1 unavailable: 2 internal_failure: 3 function: id: org.text2system.example.s26.function parameters: input: type: org.text2system.example.s26.input_record returns: type: org.text2system.example.s26.output_record errors: type: org.text2system.example.s26.error 27. Configuration A configuration defines a named set of configurable properties that influence system behavior without modifying the portable semantics of the system. A configuration defines the configuration contract. Runtime configuration values are supplied by deployments, implementations, or operational environments. Each configuration property shall declare a type. A configuration property may additionally declare: - default - documentation requirement: id: T2S-CONFIG-001 statement: Every configuration shall define exactly one stable identifier. requirement: id: T2S-CONFIG-002 statement: Every configuration property shall declare exactly one type. requirement: id: T2S-CONFIG-003 statement: Default values shall be compatible with the declared property type. requirement: id: T2S-CONFIG-004 statement: A projector shall preserve the semantic meaning of every configuration property. Example configuration: id: org.text2system.example.s27.configuration properties: address: type: string default: "0.0.0.0" port: type: u16 default: 8080 threshold: type: f32 default: 0.75 Configuration -> Configuration Schema -> Deployment 28. Requirements A requirement defines a normative, verifiable statement about the system. Requirements express functional, non-functional, architectural, safety, performance, interoperability, or other system obligations. Every requirement shall define exactly one stable identifier. A requirement may additionally declare: - priority - category - rationale - verification - documentation Requirements participate in traceability and may be referenced by functions, interfaces, types, tests, deployments, implementations, relationships, and other semantic elements. requirement: id: T2S-REQ-001 statement: Every requirement shall define exactly one stable identifier. requirement: id: T2S-REQ-002 statement: Every requirement shall define exactly one normative statement. requirement: id: T2S-REQ-003 statement: Requirement identifiers shall be unique within the Canonical System Model. requirement: id: T2S-REQ-004 statement: A requirement may be referenced by any semantic element. requirement: id: T2S-REQ-005 statement: Every requirement intended for verification should identify one or more verification artifacts. Example requirement: id: org.text2system.example.s28.requirement statement: Every accepted request shall produce either a result or a declared error. priority: high verification: - org.text2system.example.s28.test relationship: id: org.text2system.example.s28.rel.function-satisfies-requirement subject: org.text2system.example.s28.function predicate: satisfies object: org.text2system.example.s28.requirement 29. Tests A test defines a verification activity that demonstrates one or more semantic elements satisfy their intended contracts. A test is a first-class semantic element of the Canonical System Model. A test may verify: - requirements - systems - modules - interfaces - functions - types - configurations - implementations - deployments The execution, framework, automation, and reporting of a test are realization concerns defined by implementations, realization profiles, and projectors. requirement: id: T2S-TEST-001 statement: Every test shall define exactly one stable identifier. requirement: id: T2S-TEST-002 statement: A test shall verify one or more semantic elements. requirement: id: T2S-TEST-003 statement: A test shall not prescribe implementation-specific execution semantics. requirement: id: T2S-TEST-004 statement: A projector shall preserve traceability between tests and the semantic elements they verify. type: id: org.text2system.example.s29.test_level kind: enum values: unit integration system acceptance performance regression Example test: id: org.text2system.example.s29.test name: IntegrationTest level: org.text2system.example.s29.test_level.integration relationship: id: org.text2system.example.s29.rel.test-verifies-requirement subject: org.text2system.example.s29.test predicate: verifies object: org.text2system.example.s29.requirement relationship: id: org.text2system.example.s29.rel.test-verifies-module subject: org.text2system.example.s29.test predicate: verifies object: org.text2system.example.s29.module relationship: id: org.text2system.example.s29.rel.test-verifies-function subject: org.text2system.example.s29.test predicate: verifies object: org.text2system.example.s29.function 30. Packages A package defines a distributable unit of a system. A package groups one or more semantic elements for distribution while preserving their portable semantics. A package defines what is distributed. It does not prescribe a packaging technology, archive format, installer, repository format, or distribution mechanism. Packaging technologies and installation mechanisms are realization concerns defined by implementations, realization profiles, and projectors. requirement: id: T2S-PACKAGE-001 statement: Every package shall define exactly one stable identifier. requirement: id: T2S-PACKAGE-002 statement: A package shall include one or more semantic elements. requirement: id: T2S-PACKAGE-003 statement: Package membership shall not imply architectural ownership. requirement: id: T2S-PACKAGE-004 statement: A projector shall preserve package composition. Example package: id: org.text2system.example.s30.package name: Example Package relationship: id: org.text2system.example.s30.rel.package-includes-system subject: org.text2system.example.s30.package predicate: includes object: org.text2system.example.s30.system relationship: id: org.text2system.example.s30.rel.package-includes-module subject: org.text2system.example.s30.package predicate: includes object: org.text2system.example.s30.module System -> Package -> Projector -> DEB / RPM / MSI / OCI / ZIP / ... 31. Deployments A deployment defines the intended execution topology of one or more packaged system elements. A deployment specifies what is deployed and the target environment in which it is intended to execute. A deployment does not prescribe an orchestration technology, virtualization technology, container format, installation procedure, or operational tooling. Execution technologies are realization concerns defined by implementations, realization profiles, and projectors. requirement: id: T2S-DEPLOY-001 statement: Every deployment shall define exactly one stable identifier. requirement: id: T2S-DEPLOY-002 statement: A deployment shall reference one or more packages. requirement: id: T2S-DEPLOY-003 statement: Every deployment shall reference exactly one realization profile. requirement: id: T2S-DEPLOY-004 statement: A projector shall preserve deployment intent. Example deployment: id: org.text2system.example.s31.deployment name: Example Deployment relationship: id: org.text2system.example.s31.rel.deployment-deploys-package subject: org.text2system.example.s31.deployment predicate: deploys object: org.text2system.example.s31.package relationship: id: org.text2system.example.s31.rel.deployment-targets-environment subject: org.text2system.example.s31.deployment predicate: targets object: org.text2system.example.s31.native_profile System -> Package -> Deployment -> Realization Profile -> Projector 32. Implementations An implementation defines a realization of one or more portable semantic elements in an implementation language or external realization technology. An implementation connects the Canonical System Model to handwritten, generated, or externally maintained realization artifacts. Algorithms and implementation-internal behavior remain outside the Canonical System Model and are defined in the implementation language or realization technology. An implementation may declare: - implementation language - realization profile - artifact references - source locations - generated status - version information Source locations and artifact references identify realization resources. They do not become part of the portable semantics of the elements being realized. requirement: id: T2S-IMPLEMENTATION-001 statement: Every implementation shall define exactly one stable identifier. requirement: id: T2S-IMPLEMENTATION-002 statement: An implementation shall realize one or more semantic elements through explicit relationships. requirement: id: T2S-IMPLEMENTATION-003 statement: Every implementation shall declare its implementation language or realization technology. requirement: id: T2S-IMPLEMENTATION-004 statement: An implementation shall not alter the portable semantics of the elements it realizes. requirement: id: T2S-IMPLEMENTATION-005 statement: Implementation source locations and artifact references shall not participate in portable semantic identity. requirement: id: T2S-IMPLEMENTATION-006 statement: A generated implementation shall identify the projector or generation profile responsible for its realization. Example implementation: id: org.text2system.example.s32.implementation name: Example Implementation language: example realization_profile: org.text2system.example.s32.native_profile generated: false artifacts: - kind: source location: src/example relationship: id: org.text2system.example.s32.rel.implementation-realizes-interface subject: org.text2system.example.s32.implementation predicate: realizes object: org.text2system.example.s32.interface Portable Element │ │ realized by ▼ Implementation │ ├── language ├── profile └── artifacts 33. Realization Profiles A realization profile defines deterministic lowering rules from the Canonical System Model into one realization family. A realization family identifies an implementation language, binary interface, serialization model, documentation format, or other concrete realization domain. T2S 1.0 defines the following reference realization profile families: - rust - zig - python Additional realization profile families, including C ABI, C++, Java, Lua, documentation, serialization, and diagram formats, may be defined independently of the core language. A realization profile shall declare: - stable identifier - family - compatible version or version range, when applicable - operating system, when applicable - architecture, when applicable - representation policies - supported semantic constructs Representation policies may define realization rules for: - errors - strings - bytes - sequences - arrays - options - unions - variants - opaque types - functions - packages - deployments A realization profile may refine the representation of portable semantics but shall not alter their meaning. requirement: id: T2S-PROFILE-001 statement: Every realization profile shall define exactly one stable identifier. requirement: id: T2S-PROFILE-002 statement: A realization profile shall identify exactly one realization family. requirement: id: T2S-PROFILE-003 statement: A realization profile shall define a deterministic mapping for every portable type and function form it accepts. requirement: id: T2S-PROFILE-004 statement: A realization profile shall explicitly reject unsupported portable constructs rather than silently approximate, discard, or modify them. requirement: id: T2S-PROFILE-005 statement: A realization profile shall preserve the portable semantics of the Canonical System Model. requirement: id: T2S-PROFILE-006 statement: Operating system and architecture constraints shall be declared only when they affect realization compatibility or representation. requirement: id: T2S-PROFILE-007 statement: Representation policies shall not participate in the portable semantic identity of the elements they realize. Example realization_profile: id: org.text2system.example.s33.native_profile family: native compatibility: ">=1.0" operating_system: example-os conventions: error_model: explicit_result string_model: unicode_text sequence_model: sequence option_model: tagged_option variant_model: tagged_variant opaque_model: hidden_value realization_profile: id: org.text2system.example.s33.managed_profile family: managed compatibility: ">=1.0" operating_system: example-os conventions: error_model: explicit_error string_model: unicode_text sequence_model: sequence option_model: tagged_optional variant_model: tagged_variant opaque_model: hidden_value Informative example realization_profile: id: org.text2system.example.s33.binary_profile family: binary operating_system: example-os conventions: error_model: status_value string_model: data_length sequence_model: data_length option_model: presence_value union_model: untagged_union variant_model: tagged_variant opaque_model: opaque_handle Canonical System Model -> Realization Profile -> Projector -> Projection Model -> Artifacts Canonical System Model │ ├── Rust Projector ├── Zig Projector ├── Python Projector ├── C ABI Projector ├── Documentation Projector ├── Diagram Projector └── Future Projectors The some of the following chapters are informative. They describe the reference projectors distributed with the T2S 1.0 reference implementation. They do not extend or modify the normative semantics defined by this specification. 34. Rust Projector (Informative) The Rust Projector transforms the Canonical System Model into Rust source code according to a selected Rust realization profile. The Rust Projector shall preserve the portable semantics of the Canonical System Model. Typical mappings include: - record → struct - enum → enum - sequence → Vec or slice - array → [T; N] - option → Option - union → union or profile-defined equivalent - variant → enum - opaque → opaque Rust type or private struct - function → fn - error contract → Result or profile-defined equivalent Ownership, borrowing, visibility, lifetimes, asynchronous execution, trait implementation, module organization, and other Rust-specific language features are realization decisions defined by the selected realization profile. The Rust Projector may generate additional implementation artifacts provided that the portable semantics of the Canonical System Model remain unchanged. requirement: id: T2S-RUST-001 statement: The Rust Projector shall preserve the portable semantics of every projected element. requirement: id: T2S-RUST-002 statement: Every generated Rust type shall correspond to a compatible portable T2S type. requirement: id: T2S-RUST-003 statement: The Rust Projector shall reject unsupported portable constructs rather than silently changing their meaning. requirement: id: T2S-RUST-004 statement: Rust-specific language features shall be selected according to the active realization profile. 35. Zig Projector (Informative) The Zig Projector transforms the Canonical System Model into Zig source code according to a selected Zig realization profile. The Zig Projector shall preserve the portable semantics of the Canonical System Model. Typical mappings include: - record → struct - enum → enum - sequence → []T or ArrayList(T) - array → [N]T - option → ?T - union → union - variant → tagged union - opaque → opaque or struct - function → fn - error contract → error union or profile-defined equivalent Memory management, allocators, error propagation, visibility, async execution, and other Zig-specific language features are realization decisions defined by the selected realization profile. The Zig Projector may generate additional implementation artifacts provided that the portable semantics of the Canonical System Model remain unchanged. requirement: id: T2S-ZIG-001 statement: The Zig Projector shall preserve the portable semantics of every projected element. requirement: id: T2S-ZIG-002 statement: Every generated Zig declaration shall correspond to a compatible portable semantic element. requirement: id: T2S-ZIG-003 statement: Unsupported portable constructs shall be rejected rather than silently approximated. requirement: id: T2S-ZIG-004 statement: Zig-specific language features shall be selected according to the active realization profile. 36. Python Projector (Informative) The Python Projector transforms the Canonical System Model into Python source code according to a selected Python realization profile. The Python Projector shall preserve the portable semantics of the Canonical System Model. Typical mappings include: - record → dataclass or class - enum → Enum - sequence → list - array → list or profile-defined equivalent - option → Optional[T] or None - union → Union - variant → profile-defined class hierarchy - opaque → implementation-defined object - function → def - error contract → exception or profile-defined result object Dynamic typing, object representation, runtime reflection, and interpreter-specific behavior are realization decisions defined by the selected realization profile. The Python Projector may generate additional implementation artifacts provided that the portable semantics of the Canonical System Model remain unchanged. requirement: id: T2S-PYTHON-001 statement: The Python Projector shall preserve the portable semantics of every projected element. requirement: id: T2S-PYTHON-002 statement: Every generated Python declaration shall correspond to a compatible portable semantic element. requirement: id: T2S-PYTHON-003 statement: Unsupported portable constructs shall be rejected rather than silently approximated. requirement: id: T2S-PYTHON-004 statement: Python-specific language features shall be selected according to the active realization profile. 37. C ABI Projector (Informative) The C ABI Projector transforms the Canonical System Model into a stable C Application Binary Interface according to a selected realization profile. The C ABI Projector shall preserve the portable semantics of the Canonical System Model while producing a deterministic binary interface. Typical mappings include: - record → struct - enum → integer enum representation - sequence → pointer and length - array → fixed-size array - option → profile-defined presence representation - union → union - variant → tagged union - opaque → incomplete struct pointer - function → C function - error contract → status code or profile-defined convention Memory ownership, calling convention, symbol visibility, binary layout, and other ABI-specific properties are realization decisions defined by the selected realization profile. The C ABI Projector may generate headers, interface libraries, and supporting artifacts provided that the portable semantics remain unchanged. requirement: id: T2S-CABI-001 statement: The C ABI Projector shall preserve the portable semantics of every projected element. requirement: id: T2S-CABI-002 statement: Every exported declaration shall have a deterministic binary representation according to the selected realization profile. requirement: id: T2S-CABI-003 statement: Unsupported portable constructs shall be rejected rather than silently approximated. requirement: id: T2S-CABI-004 statement: ABI-specific realization rules shall be selected according to the active realization profile. 38. Documentation Projector (Informative) A Documentation Projector constructs a Documentation Model by combining the Narrative AST with the validated Canonical System Model. The Documentation Model is an intermediate representation that combines narrative content, semantic information, traceability, cross-references, generated indexes, and other documentation metadata. The Documentation Projector transforms the Documentation Model into one or more human-readable documentation artifacts. Typical outputs include: - language specifications - reference manuals - API documentation - architecture documentation - requirements documentation - traceability reports The organization, layout, typography, styling, hyperlinks, indexing, and output formats are realization decisions defined by the selected realization profile. The Documentation Projector shall preserve the semantic meaning of every projected semantic element. requirement: id: T2S-DOC-001 statement: A Documentation Projector shall construct the Documentation Model from the Narrative AST and the validated Canonical System Model. requirement: id: T2S-DOC-002 statement: The Documentation Projector shall preserve the semantic meaning of every projected semantic element. requirement: id: T2S-DOC-003 statement: Documentation generation shall not modify the Canonical System Model. requirement: id: T2S-DOC-004 statement: Every projected semantic element shall remain traceable to its source declaration. 39. Diagram Projector (Informative) The Diagram Projector transforms the Canonical System Model into graphical representations suitable for engineering analysis and communication. The Diagram Projector shall preserve the semantic relationships represented by the Canonical System Model. Typical outputs include: - system diagrams - module diagrams - interface diagrams - dependency diagrams - deployment diagrams - package diagrams - relationship graphs Diagram layout, routing, styling, notation, and rendering technology are realization decisions defined by the selected realization profile. requirement: id: T2S-DIAGRAM-001 statement: The Diagram Projector shall preserve the semantic relationships of the Canonical System Model. requirement: id: T2S-DIAGRAM-002 statement: Diagram generation shall not modify the Canonical System Model. requirement: id: T2S-DIAGRAM-003 statement: Every graphical element shall remain traceable to its originating semantic element. 40. Validation A conforming T2S processor shall validate the Canonical System Model before projection. Validation may be performed as one or more implementation-defined passes, provided the resulting validation outcome is equivalent. Validation consists of the following categories: - Source validation - Structural validation - Semantic validation - Realization profile validation - Implementation consistency validation - Test validation Source validation verifies the lexical, syntactic, and structural correctness of the T2S source. Structural validation verifies that every language construct conforms to the T2S grammar and structural constraints. Semantic validation verifies the semantic consistency of the Canonical System Model, including: - identifier resolution - scope validation - relationship validation - type validation - function validation - configuration validation - package validation - deployment validation - implementation validation Realization profile validation verifies that the validated Canonical System Model can be projected using the selected realization profile. Implementation consistency validation verifies that implementation artifacts remain consistent with the portable semantic model. Test validation verifies consistency between tests, requirements, and the semantic elements they verify. The method by which validation is performed is implementation-defined. requirement: id: T2S-VALID-001 statement: Every semantic reference shall resolve to exactly one compatible semantic element. requirement: id: T2S-VALID-002 statement: Duplicate stable identifiers shall be rejected. requirement: id: T2S-VALID-003 statement: Every relationship shall reference existing compatible semantic elements. requirement: id: T2S-VALID-004 statement: Cyclic type definitions shall be rejected unless explicitly permitted by the language semantics. requirement: id: T2S-VALID-005 statement: Every function, type, interface, configuration, package, deployment, and implementation shall satisfy the constraints defined by this specification. requirement: id: T2S-VALID-006 statement: When a realization profile is selected, every projected semantic element shall be compatible with that realization profile before projection begins. requirement: id: T2S-VALID-007 statement: Projection shall not begin until semantic validation has completed successfully. requirement: id: T2S-VALID-008 statement: Every reported validation error shall identify the affected semantic element. requirement: id: T2S-VALID-009 statement: Validation shall not modify the Canonical System Model. Semantic processing pipeline: T2S Source ↓ Region Scan ↓ Narrative AST + Source AST ↓ Canonical System Model Construction ↓ Semantic Validation ↓ Validated Canonical System Model ↓ Projector ↓ Projection Model ↓ Renderer ↓ Artifacts 41. Conformance A conforming T2S processor shall: - accept every valid T2S source defined by this specification, - reject every invalid T2S source with deterministic diagnostics, - construct the Canonical System Model, - perform semantic validation, - preserve the portable semantics defined by this specification. A conforming T2S projector shall: - consume a validated Canonical System Model, - preserve portable semantics, - reject unsupported semantic constructs, - produce deterministic projection artifacts. A conforming realization profile shall: - define deterministic realization policies, - preserve portable semantics, - reject unsupported semantic constructs rather than silently approximating them. requirement: id: T2S-CONFORMANCE-001 statement: A conforming T2S processor shall satisfy every normative requirement defined by this specification. requirement: id: T2S-CONFORMANCE-002 statement: A conforming T2S projector shall preserve the portable semantics of the Canonical System Model. requirement: id: T2S-CONFORMANCE-003 statement: A conforming realization profile shall not redefine the portable semantics of any language construct. requirement: id: T2S-CONFORMANCE-004 statement: Every conformance claim shall identify the implemented T2S language version. 42. Reference Processor Implementation (Informative) The recommended implementation sequence for a reference T2S processor is: 1) Region scanning. 2) Source parsing. 3) Narrative AST construction. 4) Source AST construction. 5) Semantic validation. 6) Canonical System Model construction. 7) Projection profile validation. 8) Projector execution. 9) Artifact generation. Alternative implementation strategies are permitted provided that they produce equivalent observable behavior. The reference processor implementation does not define the semantics of the T2S language. The T2S Language Specification is the sole normative definition of the language. 43. Design Principles (Informative) The design of T2S is guided by the following principles. - Text first. - Human-readable by default. - Machine-readable by design. - One canonical semantic model. - Language-neutral semantics. - Separation of system definition and implementation. - Portable type system. - Explicit interfaces. - Explicit function contracts. - Explicit relationships. - Explicit requirements and traceability. - Deterministic parsing. - Deterministic semantic validation. - Deterministic projection. - Projection profiles preserve portable semantics. - Unsupported projections shall be rejected rather than approximated. - Algorithms remain in implementation languages. - Documentation and semantics may coexist in a single source. - Embedded and standalone semantic source are semantically equivalent. - The language specification defines semantics; projectors define realization. 44. Summary (Informative) T2S 1.0 defines a portable, text-defined language for describing software and embedded systems. The language separates narrative documentation, portable system semantics, realization policies, and implementation artifacts. The Canonical System Model is the single normative semantic representation defined by the language. The portable semantics of the Canonical System Model are independent of programming languages, execution environments, and realization technologies. Implementations, realization profiles, and projectors transform the Canonical System Model into concrete engineering artifacts while preserving its portable semantics. T2S does not describe implementation algorithms. Algorithms remain in ordinary programming languages and are validated through testing. A conforming T2S processor constructs and validates the Canonical System Model. A conforming projector consumes the validated Canonical System Model and produces deterministic realization artifacts. The T2S Language Specification defines the semantics of the language. Realization profiles, projectors, validators, and other tooling are specified independently and do not redefine the language. The result is a language that enables human-readable system definition, deterministic machine processing, and portable realization across multiple implementation technologies. 45. APPENDIX A : Glossary This appendix defines the terminology used throughout this specification. Unless explicitly stated otherwise, glossary entries are informative. 45.1 Abstract Syntax Tree (AST) The structured representation produced by parsing a T2S source. Two abstract syntax trees are defined by this specification: - Source AST - Narrative AST The internal representation of an AST is implementation-defined. 45.2 Canonical System Model The implementation-independent semantic representation produced by the Semantic Builder. The Canonical System Model is the normative semantic representation consumed by projectors. 45.3 Compilation Unit A single T2S source document processed as one logical unit. A compilation unit shall define exactly one logical root schematic. 45.4 Declaration A semantic definition represented using the T2S semantic language. Examples include: - system - subsystem - module - interface - function - type - constant - configuration - relationship - requirement - constraint - implementation - test - package - deployment - realization_profile 45.5 Documentation Projector A projector producing documentation artifacts. Typical outputs include: - HTML - PDF - Markdown - DOCX 45.6 Embedded Semantic Source Semantic declarations embedded within narrative text using the semantic envelope. 45.7 Function A callable semantic operation belonging to an interface or module. 45.8 Interface A technology-independent callable contract. 45.9 Module A reusable implementation unit. 45.10 Narrative The human-readable documentation processed by the T2D parser. 45.11 Projector A processor transforming the Canonical System Model into one target representation. Projectors shall not modify the Canonical System Model. 45.12 Realization A platform-specific implementation of one or more semantic declarations. 45.13 Relationship A semantic connection between semantic elements. 45.14 Semantic Builder The processor transforming the Source AST into the Canonical System Model. 45.15 Semantic Envelope Exactly two leading SPACE characters introducing embedded semantic source. The semantic envelope is removed before semantic parsing. 45.16 Source AST The parser output preserving source order and source locations. 45.17 Standalone Semantic Source Semantic declarations represented without narrative text. 45.18 Target Model The intermediate representation produced by a projector before rendering. 45.19 T2D Text2Doc language. 45.20 T2S Text2System language. 46. APPENDIX B : Reserved Words This appendix defines the reserved declaration keywords of the T2S language. Reserved words shall only be used as semantic declaration kinds. The following reserved words are defined by T2S 1.0: - system - subsystem - module - interface - function - type - constant - configuration - relationship - requirement - constraint - implementation - test - package - deployment - realization_profile - t2s Future versions of the language may define additional reserved words. requirement: id: T2S-RESERVED-001 statement: A conforming processor shall recognize every reserved declaration keyword defined by this specification. requirement: id: T2S-RESERVED-002 statement: Reserved declaration keywords shall not be assigned different language semantics by a conforming implementation. requirement: id: T2S-RESERVED-003 statement: Future language revisions may introduce additional reserved declaration keywords while preserving the semantics of previously defined reserved declaration keywords. 47. APPENDIX C : Standard Diagnostics This appendix defines the recommended diagnostic identifiers for conforming T2S processors. Diagnostic identifiers are intended to provide implementation-independent error reporting. Processors may present diagnostics differently, but should preserve the diagnostic identifier. 47.1 General Diagnostics constant: id: T2S-G001 value: "Compilation aborted." constant: id: T2S-G002 value: "Internal processor error." constant: id: T2S-G003 value: "Unsupported language version." 47.2 Narrative Diagnostics constant: id: T2S-N001 value: "Invalid document structure." constant: id: T2S-N002 value: "Invalid cover metadata." constant: id: T2S-N003 value: "Invalid section hierarchy." 47.3 Semantic Diagnostics constant: id: T2S-E001 value: "Duplicate semantic identifier." constant: id: T2S-E002 value: "Missing semantic identifier." constant: id: T2S-E003 value: "Unknown semantic declaration kind." constant: id: T2S-E004 value: "Invalid identifier." constant: id: T2S-E005 value: "Invalid semantic indentation." constant: id: T2S-E006 value: "Duplicate mapping key." constant: id: T2S-E007 value: "Unsupported YAML construct." constant: id: T2S-E008 value: "Invalid semantic region." constant: id: T2S-E009 value: "Unknown semantic reference." constant: id: T2S-E010 value: "Invalid semantic relationship." 47.4 Projector Diagnostics constant: id: T2S-P001 value: "Unknown projector." constant: id: T2S-P002 value: "Unsupported semantic construct." constant: id: T2S-P003 value: "Projection failed." constant: id: T2S-P004 value: "Renderer failed." 47.5 Recommendations Diagnostic identifiers should remain stable across language revisions. Diagnostic messages may be localized. A conforming processor should include: - diagnostic identifier, - source location, - severity, - human-readable message. requirement: id: T2S-DIAG-001 statement: A processor shall preserve the diagnostic identifier independently of the presentation language. requirement: id: T2S-DIAG-002 statement: A processor shall report the source location whenever it can be determined. requirement: id: T2S-DIAG-003 statement: Diagnostic identifiers shall remain stable within a major language version. 48. APPENDIX D : Implementation Notes This appendix is informative. It does not define language semantics. 48.1 Processing Pipeline A conforming implementation typically processes a T2S source using the following stages: Source ↓ Narrative Parser ↓ Source AST ↓ Semantic Builder ↓ Canonical System Model ↓ Projector ↓ Projection Model ↓ Renderer ↓ Target Artifact The internal representation of each stage is implementation-defined. 48.2 Narrative Processing Narrative text is processed according to the T2D Language Specification. Narrative processing and semantic processing are independent. A processor shall preserve the relative source locations of narrative and semantic content. 48.3 Semantic Processing The Semantic Builder transforms the Source AST into the Canonical System Model. The Canonical System Model is independent of: - programming language, - operating system, - processor architecture, - deployment environment, - rendering technology. 48.4 Validation Validation should be performed using the Canonical System Model. Typical validation includes: - identifier validation, - reference validation, - relationship validation, - type validation, - configuration validation, - requirement validation. 48.5 Projectors Projectors transform the Canonical System Model into one target representation. Typical projectors include: - Documentation - Rust - Zig - Python - C ABI - Mermaid - PlantUML Additional projectors may be developed independently without modifying the T2S language specification. 48.6 Renderers A renderer transforms a Projection Model into one or more target artifacts. Typical outputs include: - HTML - PDF - Markdown - DOCX - Source Code - JSON - SVG 48.7 Determinism A conforming implementation should produce deterministic output for identical inputs. The order of semantic declarations shall be preserved unless a projector explicitly specifies otherwise. 48.8 Implementation Freedom This specification intentionally does not define: - parser implementation, - AST representation, - memory management, - optimization strategy, - validation algorithms, - rendering implementation, - projector implementation. Conforming implementations may freely choose these implementation details provided that the externally observable language semantics defined by this specification are preserved. ==== End of T2S 1.0 Language Specification ====