# Language Semantics and Runtime Behavior Specification

## 1. Scope

This document defines the normative behavior of the query and routine language, including value semantics, type behavior, relational semantics, transaction behavior, routines, authorization, subscriptions, events, changefeeds, concurrency, determinism, and client-facing execution behavior.

The syntax is defined separately.

## 2. Normative Terms

The terms **shall**, **shall not**, **should**, **should not**, and **may** are normative.

- **shall** denotes a mandatory requirement.
- **shall not** denotes a mandatory prohibition.
- **should** denotes recommended behavior.
- **should not** denotes discouraged behavior.
- **may** denotes an allowed implementation choice.

## 3. General Design Rule

The implementation may hide execution machinery but shall not hide semantic meaning.

Implicit behavior is permitted only where it:

1. cannot fail,
2. cannot lose information, and
3. cannot change program meaning.

Where historical SQL behavior conflicts with deterministic and readily understandable behavior, the deterministic behavior takes precedence.

## 4. Identifier Semantics

Identifiers are case-insensitive and case-preserving.

An implementation shall treat differently-cased spellings of the same identifier as equivalent.

An ambiguous identifier reference is an error.

Search paths shall not silently resolve ambiguous names.

## 5. The `unknown` Value

`unknown` represents missing, indeterminate, or unavailable data.

A field permits `unknown` unless constrained by `not unknown`.

Ordinary comparisons involving `unknown` produce `unknown`.

Direct comparison of a value against the literal `unknown` is invalid. Programs shall use `is unknown` or `is not unknown`.

`unknown` is never implicitly substituted by a type-specific zero value.

## 6. Boolean Semantics

Boolean evaluation uses three-valued logic:

```text
true
false
unknown
```

Filtering contexts retain only `true`.

Both `false` and `unknown` reject a row.

### 6.1 not

| input | result |
|---|---|
| `true` | `false` |
| `false` | `true` |
| `unknown` | `unknown` |

### 6.2 and

| left | right | result |
|---|---|---|
| `true` | `true` | `true` |
| `true` | `false` | `false` |
| `true` | `unknown` | `unknown` |
| `false` | any | `false` |
| `unknown` | `true` | `unknown` |
| `unknown` | `false` | `false` |
| `unknown` | `unknown` | `unknown` |

### 6.3 or

| left | right | result |
|---|---|---|
| `true` | any | `true` |
| `false` | `true` | `true` |
| `false` | `false` | `false` |
| `false` | `unknown` | `unknown` |
| `unknown` | `true` | `true` |
| `unknown` | `false` | `unknown` |
| `unknown` | `unknown` | `unknown` |

Numeric and textual values shall not be implicitly interpreted as booleans.

## 7. Numeric Semantics

Integer overflow is an error.

Integer arithmetic shall never silently wrap.

`/` performs mathematical division and may produce a non-integral result.

`div` performs integer division.

`%` computes remainder.

Decimal arithmetic is exact according to declared precision and scale.

Decimal operations shall not silently degrade into binary floating-point arithmetic.

`float32` and `float64` follow IEEE 754 arithmetic semantics.

The database shall define a deterministic total sort order for floating-point values when ordering or indexing requires one.

## 8. Type Conversion

Implicit conversion is permitted only when lossless and infallible.

Examples of valid implicit widening include:

```text
int8 -> int16 -> int32 -> int64
uint8 -> uint16 -> uint32 -> uint64
```

The following are never implicit:

```text
text -> numeric
numeric -> text
numeric -> bool
bool -> numeric
timestamp -> instant
instant -> timestamp
```

`cast` raises `conversion_error` on failure.

`try_cast` returns `unknown` on failure.

## 9. Text Semantics

`text` shall contain valid UTF-8.

Malformed UTF-8 shall not be representable as `text`.

Binary data uses `bytes`.

The default collation is deterministic, case-sensitive, locale-independent Unicode scalar ordering.

Host operating-system locale shall not alter default comparison semantics.

`varchar(n)` limits Unicode scalar count and shall not pad.

The historical fixed-width `char(n)` behavior is not supported.

Length concepts are distinct:

```text
byte_length
scalar_length
grapheme_length
```

## 10. Temporal Semantics

`date` represents a civil calendar date.

`time` represents wall-clock time without date or timezone.

`timestamp` represents civil date and wall-clock time without timezone interpretation.

`instant` represents an absolute UTC timeline position.

`duration` represents elapsed time.

Conversion between `timestamp` and `instant` requires an explicit timezone.

Session timezone may affect formatting but shall not change stored meaning.

## 11. Record Identity

Every persistent record has stable logical identity.

Logical identity is independent of physical storage location.

A record reference remains valid across:

- compaction,
- page movement,
- segment rewriting,
- index rebuilding,
- storage-layout changes.

Physical tuple location shall not be exposed as record identity.

## 12. Record References

A `record<table>` value may reference only records of the declared target table unless the type explicitly permits multiple target types.

Reference traversal behaves as relational lookup.

Reference traversal shall preserve ordinary transaction visibility and authorization semantics.

The implementation may lower traversal into joins, direct lookups, or equivalent index operations.

## 13. Structured Values

Objects and arrays are first-class typed values.

Strict structures reject undeclared fields.

Flexible structures permit undeclared fields.

Known fields inside flexible structures retain their declared type and constraints.

Structured values are not semantically equivalent to opaque JSON text.

Serialization format shall not define database value semantics.

## 14. Relational Query Semantics

The logical clause order is:

1. source construction
2. join evaluation
3. `where`
4. grouping
5. `having`
6. projection
7. ordering
8. limit/offset

The optimizer may reorder physical execution provided observable results are unchanged.

## 15. Projection and Aliases

Every result column shall have a unique output name.

Duplicate output names are an error unless explicitly aliased.

Projection aliases are visible to `order by`.

Projection aliases are not visible to `where`, `group by`, or `having`.

## 16. `select *`

`select *` is valid for ad hoc queries.

It is invalid in persistent schema-bound interfaces such as:

- views,
- materialized views,
- routines,
- functions,
- stored queries,
- generated public query contracts.

Persistent interfaces shall enumerate fields explicitly.

## 17. Ordering

Result order is undefined without `order by`.

Programs shall not depend on:

- insertion order,
- physical row order,
- page order,
- index traversal order,
- planner order,
- worker scheduling,
- parallel scan order.

Unknown values sort last by default for both ascending and descending order.

`unknowns first` and `unknowns last` override the default.

A query using `limit` without `order by` is valid but nondeterministic.

Tooling should warn about this pattern.

## 18. Join Semantics

`join` is equivalent to `inner join`.

`using(column)` merges the corresponding join columns into one output field.

Comma joins are not supported.

`natural join` is not supported.

Schema changes shall not silently alter join predicates.

## 19. Grouping

Every projected non-aggregate expression in a grouped query shall either:

1. occur in the grouping key, or
2. be functionally dependent on that key in a way provable from declared schema constraints.

The engine shall never select arbitrary non-grouped values.

## 20. Aggregate Semantics

`count(*)` counts rows.

`count(expression)` counts non-`unknown` values.

Empty input results:

```text
count(*) = 0
sum(expression) = 0
avg(expression) = unknown
min(expression) = unknown
max(expression) = unknown
```

## 21. Mutation Semantics

`insert`, `update`, and `delete` are explicit persistent mutation operations.

Loading a record into a local variable does not create implicit persistence.

Modifying a local row value modifies only the local value.

Persistent mutation shall remain visible in source as a database mutation statement.

## 22. Conflict Handling

`on conflict` is the standard atomic insert-conflict mechanism.

`merge` is not defined.

More complex state transitions shall use routines.

Conflict targets should be explicit.

## 23. Constraint Semantics

Foreign keys are always enforced.

No session or compatibility mode may silently disable them.

The default referential actions are:

```text
on delete restrict
on update restrict
```

Cascade behavior must be explicitly declared.

Constraints are immediate unless declared `deferred`.

Deferred constraints are validated at commit.

Schema changes shall not silently truncate, wrap, reinterpret, or discard existing values.

## 24. Schema Transaction Semantics

DDL participates in transactions.

A transaction containing schema changes shall commit or roll back atomically with its other changes.

## 25. Routine Semantics

A normal `routine` is:

- transactional,
- database-local,
- atomic,
- retryable when the engine can safely replay it,
- isolated from externally observable I/O.

A top-level routine invocation establishes a transaction unless already executing in one.

Successful completion commits.

An uncaught error rolls back all mutations in the routine transaction.

Nested routine calls participate in the current transaction.

## 26. External Routines

A routine marked `external` may perform external I/O.

An external routine:

- is not assumed deterministic,
- is not automatically retryable,
- is not automatically replay-safe,
- shall not be treated as an atomic wrapper around external side effects.

Database transactions inside external routines must have explicit and well-defined boundaries.

## 27. Function Semantics

Query-visible functions shall be:

- deterministic,
- free of persistent mutation,
- free of application event emission,
- free of externally observable I/O.

The optimizer may inline or otherwise rewrite such functions if behavior is preserved.

## 28. Procedural Query Cardinality

A query used directly in scalar-row context expects at most one row.

Zero rows produce `unknown`.

More than one row raises `cardinality_error`.

A query used in `for` iteration may produce any number of rows.

No cursor API is required for ordinary iteration.

## 29. Procedural Conditions

Only `true` enters an `if` or continues a `while`.

`false` and `unknown` both do not.

## 30. Error Model

Errors are structured typed values.

Core categories include:

```text
syntax_error
type_error
conversion_error
constraint_violation
unique_violation
foreign_key_violation
check_violation
cardinality_error
serialization_conflict
deadlock
permission_error
not_found
user_error
```

Applications shall not need to parse human-readable error strings.

A caught error is consumed unless the handler raises another error.

## 31. Authentication Context

`auth` is intrinsic connection/session context.

Clients shall not be able to forge `auth` fields through ordinary routine arguments.

Typical fields include:

```text
auth.identity
auth.account
auth.player
auth.roles
auth.session
```

The exact schema may be implementation-configurable while preserving typed access.

## 32. Policy Semantics

Policies are automatically incorporated into query and mutation authorization.

Application code should not need to repeat policy predicates manually.

A policy violation raises `permission_error` or filters inaccessible rows according to the operation's defined policy mode.

Authorization shall apply equally to:

- direct SQL,
- routines,
- reference traversal,
- relation traversal,
- subscriptions,
- generated client bindings.

## 33. Relation Semantics

A relation is a first-class record with at least:

- source identity,
- destination identity,
- relation type,
- optional user fields.

Relations participate in:

- transactions,
- policies,
- changefeeds,
- subscriptions,
- indexing,
- ordinary queries.

Graph traversal is not a separate consistency model.

## 34. Event Semantics

`emit` creates an application-semantic event inside the current transaction.

An emitted event becomes externally visible only after commit.

Rolled-back transactions emit no events.

Events from one transaction preserve source-program order.

Application events are distinct from raw database mutation history.

## 35. Changefeed Semantics

`changes` exposes durable committed mutation history.

Changefeed cursors shall identify a monotonic position in committed database history.

Changefeeds may be used for:

- replication,
- replay,
- audit,
- synchronization,
- analytics.

Retention may be finite.

The engine shall report when a requested cursor predates retained history.

## 36. Subscription Semantics

A subscription represents a maintained query result.

Creation produces:

1. an initial snapshot,
2. ordered committed deltas after that snapshot.

Clients shall observe only committed state.

A rolled-back mutation shall never appear in a subscription.

The implementation may maintain subscriptions using:

- incremental view maintenance,
- dependency tracking,
- partial recomputation,
- full recomputation,
- specialized indexes.

These strategies are not observable.

## 37. Client Local-State Semantics

Generated clients may maintain subscribed results as local typed relations.

The ordinary application model is:

```text
read -> subscribed local state
write -> routine invocation
```

Direct SQL remains available to trusted or conventional clients.

Reactive usage is optional.

A basic relational application shall not be required to use routines, subscriptions, policies, graph relations, or structured fields.

## 38. Routine Retry Semantics

A normal routine may be automatically retried after serialization conflict if:

- arguments are preserved,
- no external effects occurred,
- transaction-visible inputs can be reconstructed,
- runtime semantics remain unchanged.

The application should not need manual retry loops for ordinary retryable routines.

## 39. Transaction-Stable Values

Values such as `now()` shall be transaction-stable inside retryable routines.

Repeated evaluation within one transaction returns the same logical value.

Randomness offered inside retryable routines should likewise be transaction-stable or otherwise replay-safe.

## 40. Concurrency Semantics

The default transaction isolation level shall prevent lost updates.

The implementation may use:

- locking,
- optimistic validation,
- MVCC,
- hybrid strategies.

The physical mechanism is not observable.

`for update` requests update protection but does not prescribe the internal lock implementation.

Serialization conflicts are structured errors.

## 41. Commit Ordering

Committed transactions shall receive a monotonic logical commit position.

This position may back:

- MVCC visibility,
- subscriptions,
- changefeeds,
- replication,
- historical reads.

The exact representation is implementation-defined.

## 42. Generated Bindings

Generated client bindings shall derive from schema metadata.

Bindings may expose:

- record types,
- routine calls,
- subscription relations,
- events,
- structured errors.

The database schema acts as the protocol definition.

Applications should not need duplicate ORM, DTO, RPC, or subscription schemas.

## 43. Scheduling Semantics

Scheduled work invokes ordinary routines.

Periodic and record-driven schedules are durable database metadata.

A scheduled invocation follows normal routine transaction semantics.

At-most-once, at-least-once, or exactly-once execution guarantees shall be explicitly defined by the implementation.

The preferred application-visible behavior is logically once-per-scheduled occurrence, with retry handled internally for retryable routines.

## 44. Lifecycle Routine Semantics

Lifecycle routines are invoked by engine events such as connection, disconnection, startup, and shutdown.

Lifecycle routines follow ordinary routine semantics unless explicitly marked `external`.

Implementations shall document whether connection lifecycle hooks are guaranteed under abrupt process or network failure.

## 45. Search, Vector, Spatial, and Time-Series Semantics

Specialized capabilities extend ordinary types and indexes.

They do not create independent transaction domains.

All such queries observe the same committed database state.

Specialized indexes may be eventually built or rebuilt internally, but visible query behavior shall preserve transaction correctness.

## 46. Determinism

Nondeterministic physical behavior shall not become a language contract.

This includes:

- row storage order,
- page placement,
- index traversal,
- compaction order,
- worker scheduling,
- execution-plan shape.

Where deterministic output is required, the query shall express it.

## 47. Progressive Complexity Requirement

A simple table-based application shall be able to use the database as a conventional relational engine.

Unused advanced capabilities shall impose no mandatory source-level architecture.

The following shall remain optional:

- routines,
- subscriptions,
- graph relations,
- nested structures,
- policies,
- generated bindings,
- client local mirrors,
- changefeeds,
- application events.

## 48. Implementation Freedom

A conforming implementation may:

- interpret or compile queries,
- compile routines,
- reorder joins,
- vectorize scans,
- inline functions,
- fuse statements,
- transform procedural loops into set operations,
- eliminate redundant reads,
- combine compatible mutations,
- maintain derived indexes or projections,
- compact storage.

Such transformations are valid only when they preserve observable semantics.

## 49. Prohibited Implicit Behavior

The implementation shall not silently:

- convert text to numeric values,
- convert numeric values to text,
- interpret integers as booleans,
- reinterpret timestamps as instants,
- disable constraints,
- truncate values on schema change,
- wrap integer overflow,
- choose arbitrary grouped values,
- introduce semantic row order,
- alter collation according to host locale,
- persist local row mutation,
- expose rolled-back events,
- expose rolled-back subscription deltas,
- reinterpret quoted identifiers as strings,
- reinterpret strings as identifiers.

## 50. Guiding Principle

The preferred default shall be the safest useful behavior.

Explicit syntax should be required only where intent cannot be inferred without changing meaning.

The engine should perform mechanical work automatically while keeping semantic choices visible.