Reference Governance

Last Updated: 2026-05-09

Purpose

This document defines the roles and authority levels of files in the Culsma reference set. Its purpose is to prevent chapters, appendices, decision notes, tests, and implementation documents from becoming competing sources of truth.

Authority Model

The active public reading path in index.md identifies the current reference chapters and synchronized matrices. Drafts, working decisions, legacy snapshots, and maintenance notes keep explicit status labels so they cannot be mistaken for current reference text.

Artifact class or status label	Meaning	Authority
Current public chapter	Defines current public language, semantic, diagnostic, or conformance behavior.	Binding for the current reference baseline.
Current reference matrix	Compact matrix form of current source/API surface.	Binding when listed in the active reading path; must stay aligned with current chapters.
current reference extension contract	Defines a stable extension boundary shared by replaceable modules.	Binding for extension compatibility and kernel/provider authority.
current built-in provider specification	Defines one official provider behind a stable extension contract.	Binding for that provider only; does not constrain other conforming providers to the same internal rules.
compatibility note	Documents legacy acceptance, aliasing, or migration behavior.	Binding only for compatibility behavior described.
working decision	Records accepted direction and unresolved review points.	Not binding until promoted into current chapters/matrices.
draft	Exploratory design or review aid.	Non-normative.
implementation note	Explains implementation structure or internal behavior.	Non-normative for public language semantics.
planned	Future direction.	Non-normative until accepted and promoted.

Document Roles

1. index.md is the entry point and declares the active public reading path.
2. Core chapters define current public semantics and diagnostics.
3. Appendix A is the current compact source/API matrix. It is not merely archival when marked current; it must stay synchronized with the core chapters.
4. Conformance mapping defines which requirements need test evidence before a conformance claim can be made.
5. Decision cards record rationale, compatibility strategy, and unresolved review questions. They do not override current reference text until promoted.
6. PM issues coordinate work and review state. They are not normative reference artifacts.
7. Implementation and architecture notes explain how the current implementation is organized. They do not define public language semantics by themselves.
8. Extension contracts define stable capability and validation boundaries. Provider specifications may evolve independently without editing core chapters unless they change those boundaries or kernel invariants.

Chapter Responsibility Table

This table defines where a rule is allowed to become authoritative. Chapters may cross-reference other chapters, but they should not duplicate or silently override another chapter's responsibility.

Artifact	Defines	Does not define
index.md	Active reading path, baseline status, and links to current reference artifacts.	Language rules, diagnostics, operator contracts, or vocabulary definitions.
reference_governance.md	Authority levels, artifact roles, conflict resolution, and promotion rules.	Domain vocabulary contents or runtime behavior.
01_notation.md	Notation conventions used by the reference.	Culsma source grammar, diagnostics, or execution semantics.
02_lexical_structure.md	Lexical tokens, comments, identifiers, literals, and spelling-level constraints.	Statement forms, domain operator contracts, or material vocabulary policy.
03_programs_and_source_files.md	Program/file structure, source units, declarations, and cross-file organization.	Operator parameter contracts or runtime material effects.
04_surface_grammar_and_statement_forms.md	Source-level grammar, statement forms, authoring sugar, and public source-surface constraints.	Full operator call contracts, runtime effects, or conformance evidence.
05_names_and_bindings.md	Name binding, scope, references, and resolution behavior.	Domain vocabulary tables or operation-specific runtime semantics.
05_operation_vocabulary_and_call_contracts.md	Public operator names, argument contracts, return contracts, and call-level vocabulary.	Source grammar, execution scheduling, or test evidence requirements.
06_operational_semantics.md	Deterministic runtime effects, material-state transitions, and public operational behavior.	Source spelling, parser grammar, or diagnostic stage placement.
06_validation_and_diagnostics.md	Validation stages, diagnostic placement, diagnostic codes, and earliest-decidable error placement.	New language semantics that are not specified by grammar, binding, call contracts, or runtime chapters.
07_execution_model.md	Execution pipeline, scheduling model, run/report projections, and execution artifacts.	Source-language return contracts or domain material taxonomy.
08_configuration_and_modes.md	Configuration fields, modes, and mode-dependent behavior.	Core grammar, domain operator vocabulary, or diagnostics not caused by configuration/mode selection.
09_type_and_units.md	Type lattice, unit/dimension behavior, and value-level typing constraints.	Material taxonomy token sets except where referenced as typed values.
10_conformance_and_test_mapping.md	Requirement-to-test mapping and evidence required for conformance claims.	New semantics without corresponding rules in the relevant source chapter.
11_stdlib_portals.md	Standard-library portal boundary and public portal contracts.	Core language semantics outside the portal boundary.
extensions/scientific_model/README.md	Capability, provider, binding, validation, provenance, and commit-authority contracts.	Provider-internal scientific rules or implementation layout.
Scientific-model provider specifications	Behavior of one named/versioned provider.	Core syntax, extension contract, other provider behavior, or commit authority.
appendix_a_unified_statement_matrix.md	Compact synchronized matrix of current source/API forms.	Rationale, future design, or rules that have not been promoted into current chapters.
Decision cards	Accepted direction, rationale, compatibility strategy, and unresolved review questions.	Binding current behavior until promoted into the relevant chapter or matrix.
PM issues	Work coordination, review requests, and triage state.	Current language/reference behavior.

Conflict Resolution

When reference artifacts conflict:

1. Prefer the artifact with the highest authority level.
2. If two current reference artifacts conflict, stop and reconcile them in the reference before treating either as settled.
3. Use implementation behavior and tests as conformance evidence, not as a silent replacement for the reference.
4. If implementation behavior is intentionally ahead of the reference, mark the relevant decision or implementation note as non-normative until the reference is updated.
5. If implementation behavior is behind accepted reference semantics, track it as implementation debt with conformance hooks.

Promotion Rule

A working decision becomes current reference text only after:

1. the accepted rule is written into the appropriate current chapter or matrix;
2. compatibility behavior is documented when existing public inputs are affected;
3. conformance hooks are listed;
4. implementation tests are added or updated; and
5. contradictory examples or stale statements are removed.

Current Content Taxonomy Note

The content taxonomy cleanup has been promoted into the current Chapter 6 contract and Appendix A quick lookup. The non-normative decision record is maintained outside this DOI-facing reference set in the PM repository. Implementation is complete only after legacy alias normalization and conformance tests are synchronized with those promoted contracts.