Scope Backlog¶

This file is the canonical V1 scope and open-question backlog for Catalyst's language design docs. It is the place to start when finishing V1: work from the V1 backlog top to bottom, then accept or defer each remaining design decision.

The detailed design rules live in the topic pages linked from each item. This page owns V1 design sequencing, status, and the remaining design work needed to mark V1 accepted. Compiler implementation tasks live in V1 Compiler Implementation Tasks. Non-V1 work lives in Catalyst Enhancement Proposals.

Status Terms¶

Accepted: settled enough to implement without another semantics pass.
Needs acceptance: a working direction exists, but one or more design choices still need to be frozen or moved to a later version.
In progress: V1 source semantics are mostly settled, but diagnostics, reflection, or lint-facing design still need completion.
Open: deliberately unresolved and not safe to implement as a V1 contract.
Deferred: intentionally outside the named version.

V1 Design Definition of Done¶

V1 design is done when the active reference pages define a coherent language surface without requiring later implementation work to invent source semantics.

That means:

every V1 source form has syntax, static semantics, diagnostics categories, and deferred boundaries recorded;
every V1 type, contract, reflection value, prelude name, and attribute has an accepted public shape or an explicit implementation-private boundary;
every hard error and warning needed to define the language contract is classified;
deferred V2/Far Future features are rejected, deferred, or cataloged as optional lint/tooling guidance with deterministic design intent when their syntax overlaps V1;
source examples use accepted V1 forms or are explicitly marked invalid/deferred.

V1 explicitly excludes the package manager, LSP, LLVM backend, advanced optimizer, async/concurrency/effects, closures/captures, general pattern matching, overload sets, named arguments, full std, and broad C FFI.

V1 Scope Summary¶

V1 is a coherent native language/reference target with a small inspectable compiler pipeline:

source syntax, comments/docs, declarations, literals, operators, blocks, if, optional binding, loops, functions, methods, defaults, function pointers, errors, modules, imports, attributes, structs, enums, optionals, arrays, slices, ranges, pointers, mutability, ownership, move, and Box;
explicit comptime parameters, forced comptime evaluation, compile-time-only functions, Type, structural constraints, semantic contracts, explicit impl, static dispatch, opaque static returns, borrowed dyn, owned Box(dyn C), and reflection facts needed by those features;
compiler-provided prelude, explicit std namespace skeleton, scalar C ABI interop, deterministic diagnostics, structured non-SSA IR, C backend, and shared IR interpreter as design constraints for later implementation.

V1 Backlog Order¶

Order	Status	Workstream
0	Accepted	V1 Scope Freeze and Acceptance Pass
1	Accepted	Core Compiler Pipeline
2	Accepted	Syntax and Source Forms
3	Accepted	Functions and Calls
4	Accepted	Comptime and Compile-Time Evaluation
5	Accepted	Errors
6	Accepted	Modules, Namespaces, Imports, and Package Boundaries
7	Accepted	Prelude
8	Accepted	Type System and Reflection
9	Accepted	Structs, Methods, References, Mutability, and Ownership
10	Accepted	Semantic Contracts and Dispatch
11	Accepted	Prelude Contract Families
12	Accepted	Arrays, Slices, Ranges, and Indexing
13	Accepted	Loops and Iteration
14	Accepted	Attributes
15	Accepted	C ABI Interop
16	Accepted	Realtime and Allocation Visibility
17	Accepted	Compiler Diagnostics and Lint Boundary
18	Accepted	Standard Library Skeleton

V1 Backlog¶

V1 Scope Freeze and Acceptance Pass¶

Status: Accepted.

Purpose: turn the current working design wiki into a language-reference target. This is the pass that prevents later compiler work from becoming accidental language design.

Scope:

align page status blocks with actual readiness;
promote settled V1 source semantics from Working direction or In progress to Accepted;
move non-blocking polish and future ideas to the proposal backlog;
make every V1/deferred boundary obvious on the owning page.

Done when:

Every active V1 topic page has a status block whose wording matches this backlog.
Every Open, Still open, exact API is open, and deferred marker is either a V1 task here or a CEP.
All V1 examples use only V1 source forms, or are explicitly marked invalid/deferred.
Cross-links from V1 pages point to canonical homes instead of repeating general semantics.

Source docs:

Core Compiler Pipeline¶

Status: Accepted. Pipeline, phase boundaries, target/safety vocabulary, deterministic snapshots, verifier requirements, and the shared interpreter/comptime execution model are accepted as compiler design constraints. Per-feature implementation coverage is tracked by V1 Compiler Implementation Tasks.

Scope:

source -> tokens -> AST -> SIR -> IR -> backend;
structured non-SSA IR;
deterministic phase snapshots;
C backend first;
shared IR interpreter for execution tests and demand-driven comptime.

Done when:

Phase ownership categories are accepted: syntax in AST, semantic facts and demand-driven comptime evaluation in SIR/sema, backend facts in IR.
Snapshot outputs are deterministic and treated as public contracts for every touched phase.
The compiler phase boundary remains parser -> sema -> IR -> backend, without later phases reaching into earlier phase data.
Required IR verifier checks are listed before C and interpreter backends consume IR.
The compilation target and build/safety mode vocabulary used by V1 docs is defined, with Debug, ReleaseSafe, and ReleaseFast kept as build-profile presets over semantic SafetyMode.
The shared IR interpreter scope is accepted for V1 validation and demand-driven comptime evaluation.
Interpreter traps and runtime-error reporting are settled: checked safety failures are deterministic traps outside ordinary error returns.
Backend-neutral V1 metadata, SIR/IR schema obligations, and representative lowering recipes are identified, and V2 metadata is explicitly excluded.

Source docs:

Syntax and Source Forms¶

Status: Accepted. V1 source-form syntax is frozen.

Scope:

UTF-8 .ct source files and byte-based spans;
comments and documentation comments;
declarations, const, var, shadowing, statement separation;
keywords, naming conventions, literals, operators, expected-type shorthand;
destructuring binding forms;
move expression spelling;
conditional declarations.

Done when:

Source docs:

Functions and Calls¶

Status: Accepted. Error-set details are tracked by Errors.

Scope:

function declarations and methods as receiver-first functions;
comptime fn declarations as compile-time-only helpers;
expression-bodied arrow functions as a general function body form with ordinary final-expression completion and normal signature inference;
destructured parameters as binding syntax;
ordinary parameters for capabilities and context records;
anonymous static impl pointer parameters in function declaration parameter position;
default parameter values with trailing-suffix omission;
function item values in comptime positions;
runtime function pointers for concrete signatures;
explicit @callconv spelling for non-default calling conventions;
main entry-point rules and return-type inference boundaries.

Source docs:

Comptime and Compile-Time Evaluation¶

Status: Accepted. V1 has a minimal deterministic compile-time evaluation model with forced comptime expressions/blocks, compile-time-only function declarations, semantic-instance evaluation, visible dependencies, and explicit V2 boundaries for advanced metaprogramming.

Scope:

explicit comptime parameters, compile-time-known constants, and lazy top-level const initializer evaluation;
forced comptime expressions and blocks;
comptime fn declarations callable only during comptime evaluation;
type factories, contract factories, structural constraints, and predicate-producing reflection;
contract operation guards and conditional declarations;
attribute provider evaluation;
module(...) and include(...) resolution at declaration scope;
Scope.caller() and Scope.current() where needed by reflection APIs;
comptime diagnostics through Compiler.note, Compiler.warn, and Compiler.err;
deterministic, sandboxed, cacheable, resource-limited evaluation.

Accepted decisions:

Source docs:

Errors¶

Status: Accepted.

Scope:

error-set declarations and values;
closed error sets and closed error-set unions;
top error-set type value Error;
inferred error sets;
T!E, T!, and T!Error;
try;
catch fallback handling and catch as binding for a single error value;
error returns distinct from compiler diagnostics;
top Error and AllocError placement in prelude.

Done when:

Error-set declaration, duplicate-case, union, value, and compatibility rules are accepted.
Inferred error-set behavior is accepted for ordinary functions and rejected where bodyless forms cannot infer.
catch fallback, catch as binding, parser disambiguation, and result-type rules are accepted.
The exact reflection API for closed error-set cases is explicitly deferred without blocking diagnostics.
C ABI rejection of error-return types is linked back to the scalar C ABI item.

Source docs:

Modules, Namespaces, Imports, and Package Boundaries¶

Status: Accepted. V1 root module resolution, module.toml, source loading, namespace identity, import/re-export behavior, prelude/std boundaries, and loose-file module synthesis are accepted. Full package-manager fetching, registries, version solving, conditional dependencies, provider metadata, and publishing workflow are V2.

Scope:

Namespace as a comptime-only value;
module("...") for root module names;
include("...ct") for source loading;
.ct Catalyst source extension;
minimal module.toml with name, version, main, optional [dependencies], and non-semantic metadata fields;
declaration-scope imports;
namespace destructuring for selective binding;
module API as public declarations of the manifest main namespace;
public/private declaration and impl visibility;
prelude as compiler-owned namespace, not a module;
std as toolchain-provided normal module available for resolution but not implicitly imported;
loose file compile/run through a synthesized main module context.

Done when:

Module-name grammar, include path schemes, normalization, and module-root escape checks are accepted.
Namespace/include/import cycles and manifest dependency cycles have deterministic diagnostic categories.
Module resolver cache and build-graph identity rules are precise enough to define the language contract.
Function-local, block-local, guard-local, and helper-hidden module(...) and include(...) dependency creation is a hard error.
Public/private namespace access, re-export, import conflict, and impl visibility rules are accepted.
Minimal V1 module manifest/resolver behavior is separated from the deferred V2 package manager.

Source docs:

Prelude¶

Status: Accepted. The V1 prelude surface, compiler boundary, and error/allocation placement are accepted.

Scope:

compiler-provided prelude root namespace;
implicit public prelude import into every module;
stable fully qualified prelude.* access;
Namespace, module, include;
core contracts used by syntax;
Box, Allocator, Error, AllocError;
Ordering;
range value types;
V1 prelude attributes.

Done when:

The V1 prelude surface is frozen and marked accepted.
The Allocator contract shape and AllocError semantics needed by Box, box_dyn, iter_dyn, and iter_dyn_mut are accepted, while concrete allocator policies remain in std.
Compiler/prelude boundary assumptions are explicit so sema does not need to bake in broad library behavior.
Every prelude name is either ordinary Catalyst source, compiler primitive, or reflection hook with an explicit boundary.
std placement is cross-linked and no standard-library policy is duplicated in prelude docs.

Source docs:

Type System and Reflection¶

Status: Accepted. V1 primitive types, type categories, opaque pointer recovery, allocator storage primitives, numeric coercions and conversions, optional/enum reflection, classifier predicates, and public reflection API names are accepted.

Scope:

primitive built-in types and built-in type forms;
Type values;
concrete, constraint, sized, and unsized type categories;
comptime_int and comptime_float;
numeric widening coercions and explicit numeric conversions;
optionals, tag-only enums, enum unions, and error-set unions;
intersections for constraints;
structural constraints such as satisfies(...) and mutable_fields(...);
predicate, satisfaction, conformance, dyn-safety, dynamic metadata, function, attribute, layout, and source reflection needed by V1.

Done when:

Source docs:

Structs, Methods, References, Mutability, and Ownership¶

Status: Accepted. V1 source semantics, generated cleanup boundaries, metadata APIs, and optional lintable cleanup patterns are settled enough to implement.

Scope:

structs, fields, field defaults, field mutability, and aggregate construction;
inherent methods, Self, receiver sugar, method calls;
pointer and slice mutability;
address-of and dereference;
move for whole local bindings and by-value parameters;
@resource, copyability metadata, Disposable, and cleanup conventions;
Box(T), box, box_dyn, into_dyn, upcast, ptr, and ptr_const;
compiler-generated cleanup for hidden owners and temporaries;
cataloged lintable cleanup patterns for ordinary user bindings.

Done when:

Struct aggregate construction, default fields, public/private fields, and contract requirements are accepted.
Pointer auto-deref, one-layer method auto-addressing, field mutation, and receiver mutability rules are accepted.
Resource cleanup lint candidates are cataloged without making lint findings part of V1 source validity.
@resource, copyability metadata, and Disposable reflection/provider APIs are documented consistently across attributes and ownership docs.
Cleanup-state examples are documented for defer, early exits, live overwrite, double cleanup, hidden temporaries, loop-created iterators, and move with active defer.
Box helper signatures are final enough for generic-function syntax, including allocation and failure-cleanup semantics.
Box(dyn C) public layout remains explicitly private while descriptor, disposal, and upcast semantics are specified.

Source docs:

Semantic Contracts and Dispatch¶

Status: Accepted.

Scope:

contract(...) { ... };
impl Type as Contract { ... };
semantic contracts distinct from structural constraints;
explicit semantic conformance;
contract dependencies and intersections;
operation guards and ContractSurface.current();
static contract parameters;
opaque static returns;
borrowed *dyn C / *const dyn C;
owned Box(dyn C);
dyn-safety rules;
contract operation method lookup through visible impls;
qualified contract calls.

Done when:

Source docs:

Prelude Contract Families¶

Status: Accepted.

Scope:

Indexable(T);
MutableIndexable(T);
Sequence(T);
MutableSequence(T);
Iterator(Item);
Iterable(Item);
MutableIterable(Item);
PartialEq(Other);
Eq(T);
PartialOrd(Other);
Ord(Other);
Add(Rhs, Out);
Sub(Rhs, Out);
Mul(Rhs, Out);
Div(Rhs, Out);
Rem(Rhs, Out);
Neg(Out);
Disposable;
prelude-declared primitive numeric equality/order/arithmetic conformances over SignedInteger(bits), UnsignedInteger(bits), and Float(bits), including existing-operand integer arithmetic result selection, with primitive type factories calling public compiler primitive-type-construction intrinsics and primitive operations backed by compiler comparison/arithmetic intrinsics;
compiler-provided conformances for array and slice type forms;
prelude conformances for range and selected dynamic/box types.

Done when:

Equality, ordering, indexing, sequence, and iterator laws are documented tightly enough for diagnostics and library implementers.
Arithmetic operator contracts, result selection, primitive numeric conformances, and deferred arithmetic boundaries are documented tightly enough for diagnostics and library implementers.
Final names for equality (PartialEq and Eq) and ordering contracts are synchronized across naming, operators, and contract docs.
Built-in conformances are accepted, including float exclusion from Eq/Ord and no default equality/order for optionals, arrays, slices, or function values.
IndexIterator and MutableIndexIterator names and placement are settled as ordinary prelude helper names.
Iterable.iter_dyn and MutableIterable.iter_dyn_mut are synchronized with the allocator contract decision: dynamic operations take alloc: *dyn Allocator, while static iter / iter_mut remain allocation-free opaque static returns.
Boxed iterator forwarding remains a closed V1 convenience surface and does not imply general Box(dyn C) implements C.

Source docs:

Arrays, Slices, Ranges, and Indexing¶

Status: Accepted. V1 array, slice, range, indexing, slicing, diagnostics, contract dependency, and reflection exposure design is settled; implementation snapshots remain tracked separately.

Scope:

[N]T;
[]T and []const T;
transparent slice descriptors with .ptr and .len;
array literals;
array-to-slice coercion from addressable array places;
indexing and slicing;
Checked safety-mode bounds behavior;
first-class finite integer Range(T) and RangeInclusive(T) values, including fallback endpoint inference for unresolved comptime_int endpoints;
omitted-bound ranges only in slicing contexts;
contract-shaped indexing and iteration.

Done when:

Final Range / RangeInclusive helper names and placement are reflected consistently in prelude docs.
Array, slice, indexing, slicing, and range diagnostics are specified.
Bounds-check trap behavior is specified.
Slice descriptor field reflection is synchronized with type reflection docs.
Array/slice built-in contract conformances are synchronized with prelude contract-family docs.

Source docs:

Loops and Iteration¶

Status: Accepted. V1 loop source forms, iterator source selection, dynamic iteration boundaries, boxed iterator forwarding, hidden cleanup, and loop diagnostics are settled; reassignable loop bindings are deferred to CEP-0057: Reassignable Loop Bindings.

Scope:

for item in items;
for var item in items;
existing-iterator for;
while and while const optional-binding loop forms recorded in control-flow docs;
deferred reassignable while var loop bindings;
iterator source selection;
hidden iterator cleanup for loop-created iterators;
explicit move receiver loops;
dynamic iteration through explicit iter_dyn / iter_dyn_mut;
Box(dyn Iterator(Item)), Box(dyn Iterable(Item)), and Box(dyn MutableIterable(Item)) forwarding.

Done when:

while, while const, deferred while var, break, and continue source forms are documented or explicitly deferred wherever loop cleanup/resource examples rely on them.
Loop source selection is accepted for iterable collections, mutable iterable collections, existing iterators, boxed dynamic iterators, and borrowed dynamic iterator pointers.
for var semantics are accepted as mutable iteration selection, not mutable loop binding.
Loop result type void and deferred break-value/value-producing loop syntax are explicit.
Mutable dynamic iterator borrow lifetimes are diagnosable enough for V1.
Dynamic iterator construction semantics cover Box(dyn Iterator(Item)).create_from_dyn(I, alloc, value), erased allocator authority lifetime lint candidates, allocation failure cleanup, and no hidden allocation in for.
Loop-source diagnostics and hidden cleanup semantics are documented.

Source docs:

Attributes¶

Status: Accepted.

Scope:

@attribute;
@resource;
@callconv;
@export;
@extern;
@link_name;
@repr(.catalyst) only, with future representation modes deferred;
@align;
@deprecated;
attribute providers as ordinary comptime functions;
semantic metadata mutation through explicit setters;
declaration, function-type, type-constructor, field, parameter, implementation, and contract-operation targets documented as V1.

Done when:

The compiler registration API called by the prelude attribute implementation is settled as Compiler.register_attribute_provider(provider, spec).
Attribute names resolve through normal lexical, import, prelude, and namespace-qualified name resolution.
Provider signatures, target kinds, evaluation order, repetition, and conflicts are accepted.
Invalid attribute/provider combinations are classified as hard compiler errors or lints.
Attribute provenance and semantic metadata reflection are synchronized with type reflection docs.
V1 @repr is constrained to .catalyst; .c, .packed, std.c, and compound C layout are deferred to CEP-0063.
Unsupported target sites and unknown attribute names are rejected deterministically; future aliasing and optimization annotations live in CEPs.

Source docs:

C ABI Interop¶

Status: Accepted for V1 scalar source semantics.

Scope:

@callconv(.c) on function declarations and function type expressions;
@export(.c) on free function definitions;
@extern(.c) on external function-pointer const bindings;
@link_name("...") for explicit external symbol names;
scalar C export ABI for void, bool, i32, and f32;
deterministic backend-owned internal symbol naming;
no bodyless C-like imports in V1.

Source docs:

Realtime and Allocation Visibility¶

Status: Accepted. Checked realtime regions, @realtime, @noalloc, @kernel, broad allocation-effect metadata, realtime/kernel restriction metadata, and a separate effect system are not V1.

Future enforcement and restriction metadata are tracked by CEP-0020: Realtime Enforcement Regions.

Scope:

no hidden allocation by default;
allocation visible through explicit APIs, allocator values, ordinary parameters, signatures, resolved calls, and ordinary SIR/IR structure;
ordinary parameters and destructuring for capabilities;
no separate needs / use dependency channel in V1;
no backend source inspection for performance policy; future backend-visible facts must be represented deliberately in SIR or IR.

Done when:

V1 IR allocation facts are explicitly excluded beyond ordinary call, dispatch, ownership-lowering, and allocator API structure already required by accepted V1 semantics.
V1 SIR/IR realtime or restriction facts are explicitly excluded.
Capability examples and realtime policy notes are synchronized across function, performance, and patterns docs.
The compiler role for answering allocation/blocking/IO/hidden-dispatch questions is classified as V2 tooling/lint work over V1-visible structure, not V1 diagnostics or dedicated V1 metadata.

Source docs:

Compiler Diagnostics and Lint Boundary¶

Status: Accepted. The diagnostic payload, comptime diagnostic API, hard-error ownership, warning boundary, and lint/source-validity boundary are accepted; lintable patterns are cataloged as optional tooling guidance, while lint-engine behavior remains deferred.

Scope:

deterministic compiler diagnostics;
phase-owned diagnostic responsibilities;
Compiler.note, Compiler.warn, and Compiler.err;
Compiler.Diagnostic payload;
hard semantic errors vs warnings vs lint findings vs documented conventions;
optional lint catalog entries and their relationship to source validity.

Done when:

Hard compiler errors are defined for all V1 features.
Warnings are defined, including warnings produced by comptime code.
Lint findings are separated from hard semantic errors.
Suggested lint severities are advisory and do not define source validity.
Documented conventions are separated from compiler-enforced findings.
V1 explicitly defers lint configuration and suppression behavior.
Rich first-class lint engine, autofixes, project config, and LSP are parked in V2.

Source docs:

Standard Library Skeleton¶

Status: Accepted. V1 accepts the explicit std namespace skeleton, a minimal declaration surface for accepted examples/tests, and defers full standard-library design to CEPs.

Scope:

namespace plan for std;
std.mem;
std.collections;
std.hash;
std.fmt;
std.debug;
std.io;
std.math;
std.sort;
std.testing;
std.text;
canonical std.Result(T, E);
minimal declarations needed by V1 examples and compiler tests.

Done when:

Minimal std declarations needed to support V1 examples and tests are identified.
std remains explicitly imported/resolved and not part of the implicit prelude.
Allocator/AllocError placement in prelude is synchronized with std.mem, and std.mem.FixedBufferAllocator is accepted as the minimal concrete allocator source for allocation-backed examples and tests.
String literal baseline []const u8 byte-sequence semantics are synchronized with std.text.
Hashing, formatting, debug rendering, IO, collections, math, sort, and testing remain namespace skeletons unless promoted by V1 examples/tests.

Source docs:

Future Work¶

Non-V1 language, compiler, standard-library, and ecosystem ideas are tracked in Catalyst Enhancement Proposals. current-scope.md stays focused on V1 design acceptance.

Implementation Tasks¶

Compiler implementation and verification work is tracked in V1 Compiler Implementation Tasks.