Culsma Reference

Base Reference Snapshot: 2026.0824 Reference Track: Public Baseline — Culsma 1.0.6 alignment Last Updated: 2026-09-07

This working reference includes accepted updates after the base snapshot. The snapshot version in CITATION.cff identifies the base archive; these working updates are not a newly published reference snapshot. A curated snapshot must update citation and package metadata together before release.

This reference is the normative presentation layer for Culsma language rules. Within the public baseline, the reference set is the source of truth for language, semantic, diagnostic, and conformance claims.

Implementations and conformance tests must be aligned to this reference. They are evidence of conformance, not independent replacements for reference semantics.

When conflicts appear, apply Reference Governance: reconcile current reference artifacts first, then align implementation and tests to the accepted reference state.

Current public baseline notes:

1. For public source-level authoring, Chapter 4 is the public source-surface baseline.
2. Core reference chapters 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 are the active public reading path.
3. Archived design notes may remain in the repository, but they are not part of the current public baseline.
4. Internal freeze material may exist in the repository, but it is not part of the public presentation path.
5. User-facing run/report payloads are documented as derived execution projections in Chapter 9 rather than as source-language return contracts.
6. Implementation-facing architecture notes are outside this public reference; this reference remains language/user-facing.
7. Stdlib portal contracts are current only within the portal boundary declared by Stdlib Portals.

Chapters

0. Reference Governance - document roles, authority levels, and chapter responsibilities
1. Notation - current public baseline
2. Lexical Structure - current public baseline
3. Programs and Source Files - current public baseline
4. Surface Grammar and Statement Forms - current public surface baseline
5. Names and Bindings - current public baseline
6. Core Atomic Operators and Call Contracts - current public baseline
7. Operational Semantics (Core Atomic Runtime Effects) - current public baseline
8. Validation and Diagnostics - current public baseline
9. Execution Model - current public baseline
10. Configuration and Modes - current public baseline
11. Type and Units - current public baseline
12. Conformance and Test Mapping - current public baseline

Scientific Model Extensions

Scientific calculation and inference are defined behind a stable extension boundary rather than as fixed core-language behavior:

1. Scientific Model Extension Contract - stable capability, provider, typed-decision, validation, provenance, and commit-authority boundary shared by replaceable scientific-model implementations
2. Built-in Material Rulebook - current specification of the official built-in provider; binding for that provider only and not for other conforming providers

Core chapters define the source syntax, operation contracts, typed decision boundary, kernel invariants, and diagnostics. Provider specifications define how one scientific-model implementation resolves decisions behind that boundary.

Supporting Current Artifacts

1. Appendix A. Unified Statement Matrix - current compact source/API matrix
2. Stdlib Portals - current portal-boundary contracts

Reading suggestion:

1. For current source-level authoring, read Chapter 4 first.
2. Then use Chapters 5/6/7/8/9/10/11/12 for call contracts, semantics, diagnostics, execution, configuration, type rules, and conformance mapping.

Scope

This reference focuses on language-level conformance:

1. Surface tokens and lexical rules
2. Grammar and parser-facing constraints
3. Static and dynamic semantic constraints
4. Diagnostics and conformance requirements
5. Placement rule: source forms are maintained in Chapter 4, and operator parameter contracts are maintained in Chapter 6.

Non-normative narratives (motivation, roadmap, positioning) remain in separate whitepaper/project documents.

Change Notes

1. Protocol parameterization is implemented in parser/IR/plan lowering.
2. Cross-file protocol calls support named arguments with explicit call-frame binding.
3. Domain built-in chapter now includes full per-operation input type and return type contracts.
4. Surface sugar and domain built-in boundary for container/content is defined in Chapters 4 and 5.
5. Content taxonomy concerns are split by responsibility: Chapter 6 defines constructor vocabulary and call contracts, Chapter 8 defines staged diagnostic mapping, Chapter 10 defines mode switches, Chapter 11 defines type-level consequences, and Chapter 12 defines conformance evidence.