@cynodia/axiom 0.17.0-alpha.1 → 1.0.0

package/README.md

@@ -32,8 +32,10 @@ documentation above was missed.
 Shorter forms of the same routing: [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llms.txt), both
 at this package's root.
 
-**Status: experimental / alpha.** The API may change between alpha releases. The
-documentation in `docs/` describes this exact version, `0.17.0-alpha.1`.
+**Status: stable — 1.0.0.** The portable semantic contract is frozen (Axiom 0.17) and the
+public API follows the `1.x` compatibility policy in
+[`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md). The documentation in `docs/` describes
+this exact version, `1.0.0`.
 
 ## Installation
 
@@ -43,11 +45,10 @@ npm install @cynodia/axiom-ui         # semantic UI authoring patterns (build ti
 npm install @cynodia/axiom-server     # only if the application has an authority
 ```
 
-Every release of this project is a pre-release and npm's `latest` tag points at it, so the
-plain command above installs the current version. **There is no `alpha` dist-tag** — the tag
-was removed once it stopped tracking releases, and `npm install @cynodia/axiom@alpha` now
-fails with a 404. Pin the exact version instead when one is needed:
-`npm install @cynodia/axiom@0.17.0-alpha.1`.
+npm's `latest` tag points at the current release, so the plain command above installs it.
+**There is no `alpha` dist-tag** — the tag was removed once it stopped tracking releases,
+and `npm install @cynodia/axiom@alpha` now fails with a 404. Pin the exact version instead
+when one is needed: `npm install @cynodia/axiom@1.0.0`.
 
 These are ES modules compiled to ES2022; import them with `import`, not `require`.
 `@cynodia/axiom-cli` (`npm install -g @cynodia/axiom-cli`) publishes the `axiom` executable
@@ -173,6 +174,7 @@ focused document when the reference is not specific enough for the question at h
 | --- | --- |
 | **Compressed contract for authoring or modifying an app — start here** | [`docs/AGENT_REFERENCE.md`](docs/AGENT_REFERENCE.md) |
 | Exact runtime guarantees, stated formally | [`docs/SEMANTIC_CONTRACT.md`](docs/SEMANTIC_CONTRACT.md) |
+| What 1.0 guarantees, the SemVer policy, upgrading from 0.17 | [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) |
 | Mistakes that compile but are wrong | [`docs/ANTI_PATTERNS.md`](docs/ANTI_PATTERNS.md) |
 | Graph, node kinds, ids, types, entity value representation | [`docs/GRAPH_MODEL.md`](docs/GRAPH_MODEL.md) |
 | Every expression kind, builtin, scope, presence and null rule | [`docs/EXPRESSIONS.md`](docs/EXPRESSIONS.md) |

package/docs/ACTIONS_TRANSACTIONS.md

@@ -1,6 +1,6 @@
 # Actions and transactions
 
-Axiom 0.17.0-alpha.1. An action is behavior expressed as data, executed as a transaction.
+Axiom 1.0.0. An action is behavior expressed as data, executed as a transaction.
 
 ```ts
 {
@@ -190,6 +190,15 @@ The controlled boundary for behavior the operation vocabulary cannot express.
 **Use it only where no semantic primitive exists.** A native operation is opaque to every
 analysis Axiom offers.
 
+**`NativeOperation` is not portable semantics.** It is a host-language extension point, not
+part of the portable semantic profile. A conforming runtime that has no compatible
+registered implementation for an encountered `NativeOperation` MUST report it as
+**unsupported / opaque** and refuse — it MUST NOT ignore the operation, skip it, substitute
+a no-op, or invent host behavior. A graph that *requires* a `NativeOperation` is outside the
+portable profile unless an explicitly declared runtime-specific extension defines it. That
+the reference full-stack host *can* run registered native operations does not make the
+construct portable, and does not change this requirement for any other runtime.
+
 ### `integration-query`
 
 ```ts

package/docs/AGENT_API.md

@@ -1,6 +1,6 @@
 # Agent API
 
-Axiom 0.17.0-alpha.1. The machine-facing interface. Agents query semantics and apply
+Axiom 1.0.0. The machine-facing interface. Agents query semantics and apply
 structural transformations; they never edit generated code.
 
 ```ts

package/docs/AGENT_REFERENCE.md

@@ -1,6 +1,6 @@
 # Agent reference
 
-Axiom 0.17.0-alpha.1. Compressed operational contract. Read this plus the `.d.ts`
+Axiom 1.0.0. Compressed operational contract. Read this plus the `.d.ts`
 declarations before authoring or modifying an Axiom application.
 
 Formal guarantees: [`SEMANTIC_CONTRACT.md`](SEMANTIC_CONTRACT.md). Mistakes that compile:

package/docs/ANTI_PATTERNS.md

@@ -1,6 +1,6 @@
 # Anti-patterns
 
-Axiom 0.17.0-alpha.1. Each of these compiles. Each is wrong. Each is followed by the correct
+Axiom 1.0.0. Each of these compiles. Each is wrong. Each is followed by the correct
 alternative.
 
 ## 1. Field names as entity runtime keys

package/docs/AUTHORITY.md

@@ -1,6 +1,6 @@
 # Authority
 
-Axiom 0.17.0-alpha.1. How an application crosses the trust boundary.
+Axiom 1.0.0. How an application crosses the trust boundary.
 
 Until 0.5.x an Axiom application executed locally. 0.6 adds an **authority**: a generic
 runtime that owns state, decides mutations and persists them. The same semantic graph
@@ -695,7 +695,7 @@ do not conflate them under one "contract" name):
 | --- | --- |
 | `manifest.conformance` | The **fixture-format** version (`axiom.conformance.v1`/`v2`) — the shape of the JSON documents themselves: what top-level keys a fixture may have (`invocations` vs `steps`/`externalAdapters`, and so on). |
 | `manifest.baseContract` | The **oldest** Server IR contract any fixture in this manifest may use — `axiom.server.v1`, always, since new fixtures are added without ever raising this floor. It does **not** describe what the newest fixture needs. |
-| `manifest.fixtures[].contract` | The Server IR contract **that specific fixture** requires — this is what is authoritative for what running it needs. The suite ships fixtures spanning `v1` through `v4` simultaneously, each correctly labelled. |
+| `manifest.fixtures[].contract` | The Server IR contract **that specific fixture** requires — this is what is authoritative for what running it needs. The root suite ships fixtures spanning `v1` through `v5` simultaneously (and the sub-tiers reach `v9`), each correctly labelled. |
 | `manifest.release` | The `@cynodia/axiom` package version this snapshot of the suite shipped with — unrelated to either version above. |
 
 Before 8.2 the manifest's top-level field was named `contract` and fixed at
@@ -734,10 +734,15 @@ are tested against the same expectation.
 ## Machine-readable contracts
 
 ```
-@cynodia/axiom-server/schema/server-ir.v1.schema.json
+@cynodia/axiom-server/schema/server-ir.v1.schema.json   ← frozen, byte-stable
 @cynodia/axiom-server/schema/server-ir.v2.schema.json
 @cynodia/axiom-server/schema/server-ir.v3.schema.json
 @cynodia/axiom-server/schema/server-ir.v4.schema.json
+@cynodia/axiom-server/schema/server-ir.v5.schema.json
+@cynodia/axiom-server/schema/server-ir.v6.schema.json
+@cynodia/axiom-server/schema/server-ir.v7.schema.json
+@cynodia/axiom-server/schema/server-ir.v8.schema.json
+@cynodia/axiom-server/schema/server-ir.v9.schema.json   ← current
 @cynodia/axiom-server/schema/protocol.v1.schema.json
 ```
 

package/docs/AUTHORIZATION.md

@@ -1,6 +1,6 @@
 # Authorization
 
-Axiom 0.17.0-alpha.1. The operational contract for **authorization completeness** — the 0.15
+Axiom 1.0.0. The operational contract for **authorization completeness** — the 0.15
 milestone (spec15). Whether a principal may perform a semantic operation is part of the
 graph's executable meaning — not a runtime concern, not UI visibility, not something that
 varies by transport, provider, process, retry path or authority topology. `axiom.server.v9`

package/docs/COMPATIBILITY.md

@@ -0,0 +1,166 @@
+# Compatibility and the 1.0 contract
+
+Axiom 1.0.0. **Normative.** This document states what Axiom 1.0 guarantees across the
+`1.x` line and how those guarantees are allowed to change.
+
+## Axiom 1.0 portable semantics ARE the frozen 0.17 semantic contract
+
+Axiom 1.0 is not a new semantic milestone. It is the stable publication of the semantic
+contract that was frozen at Axiom 0.17:
+
+```
+AXIOM 0.17 SEMANTIC CONTRACT: FROZEN
+```
+
+For every graph inside the portable semantic profile:
+
+```
+portableMeaning(Axiom 1.0) == portableMeaning(Axiom 0.17 frozen contract)
+```
+
+The 0.17 validation history (Track A — an independent Python runtime executes the portable
+contract equivalently; Track B — a fresh evaluator reconstructed the model from public
+artifacts alone; the pre-freeze correction pass) is retained as **architecture and
+conformance evidence** in `reports/` (a maintainer directory, never shipped in a tarball).
+**You do not need to read it to use Axiom 1.0.** What Axiom *means* lives in the documents
+below; how that meaning was *proven* lives in `reports/`.
+
+## Where authoritative information lives
+
+| Layer | Role | Class |
+| --- | --- | --- |
+| `specs/spec*.md` | The design record for each milestone. History; not rewritten. | INFORMATIVE (except where a rule is stated nowhere else) |
+| `docs/SEMANTIC_CONTRACT.md` | The consolidated formal statement of portable runtime behavior, incl. [Normative precedence](SEMANTIC_CONTRACT.md#normative-precedence). | **NORMATIVE** |
+| `docs/AUTHORITY.md` | Server IR, the trust boundary, the protocol, Server IR admission, conformance. | **NORMATIVE** |
+| `docs/EXPRESSIONS.md`, `LOCATIONS.md`, `STATE.md`, `ACTIONS_TRANSACTIONS.md`, `CONSTRAINTS.md`, `QUERIES.md`, `AUTHORIZATION.md`, `WORKFLOWS.md`, `EFFECTS.md`, `EVENTS.md`, `SUBSCRIPTIONS.md`, `LIVE_QUERIES.md`, `MIGRATIONS.md`, `DISTRIBUTED_AUTHORITY.md`, `STORAGE.md`, `VALIDATION.md` | The full contract for each semantic area. | **NORMATIVE** |
+| `docs/AGENT_REFERENCE.md` | The compressed reference, including truth tables. | NORMATIVE (compressed; the topic doc wins on any conflict) |
+| `@cynodia/axiom-server/schema/*.json` | Structural validity and discriminators for Server IR and the protocol. | NORMATIVE for **structure only** — never overrides prose meaning |
+| `*.d.ts` | The local contract of each public type. | NORMATIVE for **structure only** |
+| `@cynodia/axiom-server/conformance/**` | Runtime-neutral fixtures. | NORMATIVE **evidence** — tests specified semantics, does not invent them |
+| `docs/RUNTIME.md`, `docs/INTEGRATIONS.md` adapter sections, package READMEs | Reference-implementation and operational guidance. | OPERATIONAL / INFORMATIVE |
+| `README.md` examples, `packages/demo` | Illustrations. | EXAMPLE — illustrate normative rules, never define them |
+
+**The reference TypeScript runtime is one conforming implementation of this contract, not
+its definition.** Where the reference runtime disagrees with the normative documents above,
+the reference runtime is defective (see
+[Normative precedence](SEMANTIC_CONTRACT.md#normative-precedence)).
+
+## The portable semantic profile
+
+Everything defined by the normative documents is portable **except** where a document marks
+it otherwise. The two explicit non-portable boundaries in 1.0:
+
+- **`NativeOperation`** — a host-language extension point. A runtime with no compatible
+  registered implementation MUST report it unsupported/opaque and refuse; a graph that
+  requires one is outside the portable profile unless an explicit runtime-specific extension
+  defines it. See [`ACTIONS_TRANSACTIONS.md`](ACTIONS_TRANSACTIONS.md#native).
+- **Structured value → text coercion** — a graph MUST NOT depend on the text form of a
+  record or collection. See [`EXPRESSIONS.md`](EXPRESSIONS.md#text-form).
+
+Non-semantic differences a conforming runtime MAY exhibit: human-readable diagnostic wording;
+the exact diagnostic **code** where the contract says it is implementation-defined (e.g. an
+unknown `EventRequest` `eventId`); physical retry/attempt counts where the contract calls
+them non-semantic; storage layout, thread/process model, private logging, performance.
+
+## Conformance baseline
+
+`@cynodia/axiom-server` ships the runtime-neutral fixture corpus and its manifests. The
+Axiom 1.0 semantic baseline is the corpus as published with `1.0.0`:
+
+```
+axiom.conformance.1.0   ← the named, permanent reference to the 1.0 fixture corpus
+```
+
+The corpus is organised as a root tier plus per-area sub-tiers, each with its own
+fixture-format version (`manifest.conformance`) and reference runner; see
+[`AUTHORITY.md`](AUTHORITY.md#conformance). Those internal generation numbers
+(`axiom.conformance.v1` … `v11`) are **not renamed** for 1.0 — `axiom.conformance.1.0` is a
+permanent *pointer* to the whole corpus at the 1.0 release, so a runtime can cite exactly
+which baseline it passed.
+
+## `1.x` compatibility policy (SemVer)
+
+### Patch (`1.0.x`)
+
+MAY include: bug fixes, performance fixes, security fixes, diagnostic improvements
+compatible with the stability class of the diagnostic (below), documentation corrections,
+and **new conformance fixtures that test already-defined behavior** (including
+bug-regression fixtures). MUST NOT intentionally change portable semantic meaning. MUST NOT
+add a fixture that imposes a *new* semantic requirement.
+
+### Minor (`1.x.0`)
+
+MAY add backward-compatible public API and capability surface (new exports, new provider
+capabilities behind explicit declaration, new tooling). Any semantic **expansion** MUST be
+explicitly versioned (a new Server IR contract, a new capability a graph opts into) and MUST
+NOT reinterpret an existing graph. A graph valid under `1.0` stays valid and keeps its
+meaning under every `1.x`.
+
+### Major (`2.0.0`)
+
+Required for any intentionally incompatible change to an established `1.x` contract.
+
+### Semantic bugs found after 1.0
+
+- **Reference runtime violates the normative contract** → fix the runtime to the contract;
+  keep the reproducer permanently. Not a contract change.
+- **The normative contract itself contains a genuine contradiction or an unsafe defect** →
+  explicit compatibility / security adjudication, documented: what changes, why, blast
+  radius, whether it is patch/minor/major, and whether prior conformance evidence is
+  affected. Never a silent reinterpretation.
+
+"All existing reference-runtime behavior is frozen forever" is **not** the rule. The
+*contract* is frozen; the implementation is corrected toward it.
+
+## Semantic identity and mixed-version deployment
+
+`semanticFingerprint(graph)` moves only for an **execution-affecting** change (an
+`ActionDef` semantic change, an `AuthorizationPolicyDef` edit, a `WorkflowDef` control-flow
+or step change, a `QueryDef` clause change, a `ReadPolicyDef` predicate change, …). A
+presentation-only or metadata-only edit does not move it. Two authorities with the same
+`semanticFingerprint` and compatible `AuthorityCompatibilityKey` (Server IR contract +
+`schemaFingerprint` + `semanticFingerprint` + authorization runtime marker) may run the same
+durable work; an incompatible pair fails closed (`INCOMPATIBLE_AUTHORITY`). See
+[`DISTRIBUTED_AUTHORITY.md`](DISTRIBUTED_AUTHORITY.md).
+
+Current markers at 1.0: Server IR `axiom.server.v9`, authorization runtime `axiom.authz.v3`.
+1.0 adds **no** new Server IR vocabulary and does not move `SEMANTIC_FINGERPRINT_VERSION`.
+
+## Diagnostic stability classes
+
+| Class | Meaning |
+| --- | --- |
+| STABLE_MACHINE_CODE | The exact `code` string is contractual (e.g. `AUTHORIZATION_DENIED`, `CONCURRENCY_CONFLICT`, `SERVER_IR_NOT_NORMALIZED`, the `VALIDATION_CODES` set). |
+| STABLE_CATEGORY | The semantic category is contractual; the exact code is not (e.g. "a refusal, not a mutation"). |
+| IMPLEMENTATION_DEFINED | Neither code nor wording is contractual — only the observable effect (e.g. the code for an unknown `eventId`). |
+| DEBUG_ONLY | Present for humans; never part of a machine contract. Free-form `message`, stack traces. |
+
+`VALIDATION_CODES` and `RUNTIME_DIAGNOSTIC_CODES` members, and the `SERVER_IR_*` /
+`AUTHORIZATION_DENIED` / `CONCURRENCY_CONFLICT` / migration / coordination codes, are
+STABLE_MACHINE_CODE. A native host-language exception is **never** the machine contract at a
+boundary that accepts untrusted serialized input — such input yields a structured Axiom
+diagnostic.
+
+## Upgrading from 0.17
+
+Moving from the final 0.17 package set to 1.0 is a **publication**, not a semantic migration:
+
+- Every graph that admitted under 0.17 admits under 1.0 unchanged.
+- `semanticFingerprint`, `schemaFingerprint`, Server IR contract labels and
+  `AuthorityCompatibilityKey` are unchanged for every graph.
+- Persisted state, durable workflow records, migration metadata and live-query cursors
+  minted under 0.17 remain valid.
+- No graph edit is required because the version number became `1.0`.
+
+## Known 1.0 limitations
+
+- `NativeOperation` is non-portable (above).
+- Physical exactly-once **effect delivery** is only as strong as the adapter's own
+  idempotency; Axiom guarantees exactly-once *logical* effect creation and documented
+  physical retry. See [`EFFECTS.md`](EFFECTS.md).
+- Provider-internal behavior (locking, DDL, storage layout, cleanup scheduling) is
+  operational, not portable semantics.
+- Retention/cleanup of workflow history, effect records, event-dedup records, subscription
+  cursors, blob intents and coordination leases is a host/provider responsibility, not a
+  portable guarantee. See each area's document.
+- Unsupported capabilities on a partial-conformance runtime are refused, never approximated.

package/docs/CONSTRAINTS.md

@@ -1,6 +1,6 @@
 # Constraints
 
-Axiom 0.17.0-alpha.1. Two constructs, answering different questions. They are not
+Axiom 1.0.0. Two constructs, answering different questions. They are not
 interchangeable.
 
 | | Question | Sees |

package/docs/DISTRIBUTED_AUTHORITY.md

@@ -1,6 +1,6 @@
 # Distributed authority
 
-*This document describes Axiom `0.17.0-alpha.1`.*
+*This document describes Axiom `1.0.0`.*
 
 The authoritative runtime (`docs/AUTHORITY.md`) may run as **more than one process at the
 same time**, over one shared persistence provider, without any change to the
@@ -201,6 +201,22 @@ A stable id is **never synthesised** from a receive timestamp, an authority inst
 random UUID. The window per source is bounded; an id that has fallen out of the window is
 treated as new (bounded, not exactly-once).
 
+**Ownership and scope.** External-event deduplication is owned by the **ingestion boundary** —
+it runs before any `Event` is constructed and therefore before any trigger, action or
+workflow. Neither the trigger dispatcher nor the action runtime deduplicates: by the time a
+delivery reaches a trigger it is already a single accepted occurrence. The **identity** is
+always an external one the provider supplies (`source + externalEventId`); Axiom never
+invents it. The **scope** is whatever backs the check:
+
+| Mechanism | Layer | Identity | Durable? | Scope |
+| --- | --- | --- | --- | --- |
+| Webhook `deliveryId` window (`docs/EVENTS.md`) | HTTP webhook decode | `decode`'s `deliveryId` | no (bounded in-memory, per route) | one process |
+| `ExternalEventDedupStore` | event ingestion | `source + externalEventId` + payload fingerprint | yes | cluster-wide when the store is shared; per-authority otherwise |
+| `SubscriptionDef.delivery.deduplicateBy` (`docs/SUBSCRIPTIONS.md`) | subscription delivery | a named payload field | restart-durable when the adapter implements `hasDelivery` | per subscription |
+
+A runtime that does not implement a durable store gets the bounded, in-process window and
+MUST say so — it MUST NOT claim exactly-once.
+
 ## 12. Subscriptions
 
 A `SubscriptionDef` separates three things: the semantic subscription (durable), the

package/docs/EFFECTS.md

@@ -1,6 +1,6 @@
 # Effects
 
-Axiom 0.17.0-alpha.1. External effects are not rollback-capable state mutations. This file
+Axiom 1.0.0. External effects are not rollback-capable state mutations. This file
 is the delivery model; [`AUTHORITY.md`](AUTHORITY.md#external-effects) is the load-bearing
 statement of why, and [`INTEGRATIONS.md`](INTEGRATIONS.md) is the operation vocabulary this
 builds on.

package/docs/EVENTS.md

@@ -1,6 +1,6 @@
 # Events
 
-Axiom 0.17.0-alpha.1. An event is a typed fact — something that happened — never work
+Axiom 1.0.0. An event is a typed fact — something that happened — never work
 itself. [`AUTHORITY.md`](AUTHORITY.md#external-events) is the load-bearing statement;
 this file is the vocabulary and the webhook delivery mechanism. A **subscription** is the
 other way an external fact becomes an `EventDef` payload — see
@@ -44,12 +44,28 @@ An event reaches the semantic layer three ways, and all three funnel through the
 3. **The semantic protocol directly** — `EventRequest{ kind: 'event', eventId, payload }`,
    for a host that already trusts its own caller (an internal service, a test).
 
+## Unknown event id
+
+An `EventRequest` (or a webhook `decode` result, or a subscription delivery) whose `eventId`
+is **not an `EventDef` in the admitted application graph** MUST be **refused**. No `Event` is
+constructed, no trigger is dispatched, no `ActionDef` is invoked, no `WorkflowDef` is
+started, no application-state or provider mutation occurs, and no logical effect is created.
+The request is answered `ok: false`.
+
+The **exact diagnostic code** for an unknown `eventId` is **implementation-defined** unless
+a more specific public diagnostic contract applies: portable conformance compares the
+refusal and its zero side effects, not the code string. The reference runtime reuses
+`EVENT_PAYLOAD_INVALID` (an unknown event cannot have a conforming payload); another
+conforming runtime MAY report a distinct code such as `UNKNOWN_EVENT`. That difference is a
+non-semantic diagnostic-representation difference, not a behavioral disagreement.
+
 ## Payload validation
 
 Every event's payload is checked against its declared `EventDef.payloadType` — the same
 `validateValueAgainstType` walk that checks action arguments and seed data — **before any
 trigger's action runs**. A malformed payload never reaches trusted code:
-`EVENT_PAYLOAD_INVALID`, and no action is invoked.
+`EVENT_PAYLOAD_INVALID`, and no action is invoked, no state or provider mutates, and no
+effect is created.
 
 ## Webhooks
 

package/docs/EXPRESSIONS.md

@@ -1,6 +1,6 @@
 # Expressions
 
-Axiom 0.17.0-alpha.1. An expression describes **what value is computed**. It is a tree of
+Axiom 1.0.0. An expression describes **what value is computed**. It is a tree of
 plain data, never source text and never a callback. Evaluation is pure: an expression MUST
 NOT change state.
 
@@ -14,9 +14,24 @@ To describe *where* a value is written, see [`LOCATIONS.md`](LOCATIONS.md).
 
 ## Conversions
 
-Three coercions decide most edge cases. They are shared by every kind.
+Four coercions decide most edge cases. They are shared by every kind, and are defined here
+in **language-neutral** terms: a conforming runtime MUST implement these rules directly, not
+by delegating to a host language's `Number()`, `String()` or JSON serializer. Two runtimes
+in different languages must produce the same result for every input below.
 
-**Truthiness** (`and`, `or`, `not`, `conditional`, predicates, `visibleWhen`):
+### Number model
+
+Every Axiom number is an IEEE-754 64-bit binary floating-point value (binary64). `NaN` and
+the two infinities are numbers to the arithmetic below, but they are **not domain values**:
+a stored field, an `initialValue` or a query row that is non-finite is a schema-conformance
+failure (`INITIAL_VALUE_TYPE_MISMATCH` at authoring time; a mutation that would store one is
+rejected). `divide` by zero is `null`, never an infinity. An ordered comparison (`gt`,
+`gte`, `lt`, `lte`) in which either side is a non-finite number is **`false`**. Negative
+zero is not observably distinct from zero.
+
+### Truthiness
+
+`and`, `or`, `not`, `conditional`, predicates, `visibleWhen`.
 
 | Value | Truthy |
 | --- | --- |
@@ -24,24 +39,108 @@ Three coercions decide most edge cases. They are shared by every kind.
 | `[x]` | `true` |
 | `''` | `false` |
 | `'x'` | `true` |
-| `0` | `false` |
-| `null` / `undefined` | `false` |
-| `{}` | `true` |
+| `0` / negative zero | `false` |
+| `NaN` | `false` |
+| `null` / absent | `false` |
+| any other number | `true` |
+| `{}` (a record) | `true` |
 
 A collection is truthy only when non-empty. This is the one coercion most likely to
 surprise: use `count(...) > 0` when you mean "has members" and want it to read that way.
 
-**Text** (`concat`, `to-string`, `lowercase`, `trim`, `substring-before`, `substring-after`, comparison of non-numbers, rendering):
-`null`/`undefined` → `''`; string → itself; number/boolean → `String(v)`; anything else →
-`JSON.stringify(v)`.
+### Text form
 
-**Number** (`add`, `subtract`, `multiply`, `divide`, `negate`): `Number(value ?? 0)`. A
-non-numeric string therefore yields `NaN` rather than an error, and comparisons against
-`NaN` are false — a guard fails closed rather than passing on a value it could not compute.
+`concat`, `to-string`, `lowercase`, `trim`, `substring-before`, `substring-after`, `length`
+of a non-collection, the text side of a mixed-type `gt`/`lt` comparison, `contains` on
+text, and rendering.
 
-**Equality** (`eq`, `neq`, `contains`, `one-of`, identity selectors, transition-constraint
-change detection) is structural and key-order independent. `null` and `undefined` are
-equal to each other and to nothing else.
+| Value | Text form |
+| --- | --- |
+| `null` / absent | `""` |
+| a string | itself, unchanged |
+| `true` / `false` | `"true"` / `"false"` |
+| a number | its **canonical decimal string** (below) |
+| a record or collection | a JSON rendering — **outside the portable conversion grammar** (below) |
+
+**Canonical decimal string of a number** — the ECMAScript `Number::toString` radix-10
+algorithm, restated so any language reproduces it:
+
+- `0` and negative zero → `"0"`.
+- A negative finite number → `"-"` then the text form of its magnitude.
+- Choose the **shortest** decimal digit sequence that round-trips to the same binary64
+  value.
+- Use **fixed** notation when `1e-6 ≤ |value| < 1e21` (and for `0`): the integer digits,
+  then — only if a fractional part remains — `.` (U+002E) and the fraction digits. No
+  trailing zeros, no leading `+`, no exponent.
+- Otherwise use **exponential** notation: one mantissa digit, then (if more significant
+  digits remain) `.` and those digits with no trailing zeros, then `e`, then the exponent
+  sign (`+` or `-`), then the exponent digits with no leading zero. `1e21` → `"1e+21"`;
+  `1e-7` → `"1e-7"`; `1.5e300` → `"1.5e+300"`.
+- `NaN` → `"NaN"`; positive infinity → `"Infinity"`; negative infinity → `"-Infinity"`.
+
+**Structured value → text is not portable.** A record or collection has a text form only as
+a last resort (`to-string` of an object, comparing two records with `lt`). The reference
+runtime renders JSON with object members in **definition order** and no whitespace; a
+conforming runtime MAY differ, and a graph that depends on it is outside the portable
+profile. Where structural text genuinely matters — identity selectors, `group` keys,
+structural equality, `semanticFingerprint` — the runtime uses **canonical JSON** instead
+(object keys sorted by Unicode code point, recursively; no whitespace; `null` kept; absent
+members omitted; numbers in canonical decimal form), which every conforming runtime MUST
+reproduce byte-for-byte.
+
+### Numeric form
+
+`add`, `subtract`, `multiply`, `divide`, `negate`. (`sum` does **not** coerce — a
+non-numeric member fails the evaluation.)
+
+| Operand | Numeric form |
+| --- | --- |
+| `null` / absent | `0` |
+| a number | itself |
+| `true` / `false` | `1` / `0` |
+| `[]` | `0` |
+| `[x]` | the numeric form of `x` |
+| a collection of two or more | `NaN` |
+| a record | `NaN` |
+| a string | **portable numeric text** (below), else `NaN` |
+
+A `NaN` operand propagates: the result is `NaN`, which then fails every ordered comparison
+and cannot be stored — a guard fails closed rather than passing on a value it could not
+compute.
+
+**Portable numeric text.** The string is first stripped of leading and trailing whitespace
+(U+0009, U+000A, U+000B, U+000C, U+000D, U+0020, and the Unicode space separators), then:
+
+| Trimmed string | Result |
+| --- | --- |
+| empty (originally empty or all whitespace) | `0` |
+| `Infinity` or `+Infinity` | positive infinity |
+| `-Infinity` | negative infinity |
+| a **canonical decimal literal** (below) | that value |
+| a radix-prefixed integer — `0x`/`0X`, `0o`/`0O`, `0b`/`0B` then digits of that radix | that integer |
+| anything else — `"NaN"`, `"1_000"`, `"1,5"`, `"abc"`, `"1abc"`, a lone `.`, `"1e"`, `"5%"` | `NaN` |
+
+A **canonical decimal literal** is an optional sign (`+` / `-`), then digits with an
+optional single `.` (at least one digit on one side — `.5` and `1.` are both accepted),
+then an optional exponent: `e` / `E`, an optional sign, one or more digits.
+
+> **The radix-prefixed and `Infinity` forms are accepted for host-behaviour compatibility
+> but are discouraged.** A portable graph should coerce only **canonical decimal** text. A
+> future contract version MAY narrow the accepted grammar to canonical decimal; it will not
+> silently widen it. Coercion never yields "implementation-defined" — every string maps to a
+> number, `NaN`, or an infinity by the table above.
+
+### Equality and ordering
+
+**Equality** (`eq`, `neq`, `contains` on a collection, `one-of`, identity selectors,
+transition-constraint change detection) is **structural** and key-order independent. `null`
+and absent are equal to each other and to nothing else. Two numbers are equal when they are
+the same binary64 value (so `-0` equals `0`; `NaN` equals nothing, including itself).
+
+**Ordering** (`gt`, `gte`, `lt`, `lte`, `sort`): **numeric** when both sides are numbers,
+otherwise by the **Unicode code point** sequence of the two text forms (not the host
+language's string comparison, not locale collation). A comparison with a non-finite number
+on either side is `false`.
 
 ## Expression kinds
 
@@ -93,15 +192,15 @@ object([
 | Operator | Semantics |
 | --- | --- |
 | `eq` / `neq` | Structural equality, key-order independent. |
-| `gt` `gte` `lt` `lte` | Numeric when **both** sides are numbers; otherwise lexicographic on their text form. |
+| `gt` `gte` `lt` `lte` | Numeric when **both** sides are numbers; otherwise by Unicode code point of their [text form](#text-form). A non-finite number on either side → `false`. |
 | `and` / `or` | Truthiness, short-circuiting. Output is a boolean. |
-| `add` `subtract` `multiply` | `Number(x ?? 0)` arithmetic. |
-| `divide` | Division by zero yields **`null`**, not an error and not `Infinity`. |
+| `add` `subtract` `multiply` | Binary64 arithmetic on the [numeric form](#numeric-form) of each side (absent → `0`). |
+| `divide` | As above; division by zero yields **`null`**, not an error and not `Infinity`. |
 
 ### `unary(operator, operand)`
 
-- `not` → `!truthy(operand)`.
-- `negate` → `-Number(operand ?? 0)`.
+- `not` → the boolean negation of the operand's [truthiness](#truthiness).
+- `negate` → the arithmetic negation of the operand's [numeric form](#numeric-form) (absent → `0`).
 
 > **An expression evaluated as an authorization decision evaluates differently for a
 > missing security field.** Both `AuthorizationPolicyDef.allow` **and** the legacy

package/docs/GRAPH_MODEL.md

@@ -1,6 +1,6 @@
 # Graph model
 
-Axiom 0.17.0-alpha.1. The `ApplicationGraph` is the authoritative representation of an
+Axiom 1.0.0. The `ApplicationGraph` is the authoritative representation of an
 application. Everything else — the IR, the page, the DOM — is derived from it and is never
 edited.
 

package/docs/INTEGRATIONS.md

@@ -1,6 +1,6 @@
 # Integrations
 
-Axiom 0.17.0-alpha.1. How an application declares and calls an external system, without
+Axiom 1.0.0. How an application declares and calls an external system, without
 embedding a transport, an SDK or a secret in the graph. The authority boundary this
 depends on is [`AUTHORITY.md`](AUTHORITY.md#external-systems); this file is the vocabulary.
 

package/docs/LIVE_QUERIES.md

@@ -1,6 +1,6 @@
 # Realtime — live canonical queries
 
-Axiom 0.17.0-alpha.1. The operational contract for **observing a `QueryDef` result over
+Axiom 1.0.0. The operational contract for **observing a `QueryDef` result over
 time**: subscribe once, receive an initial coherent result, then receive canonical changes
 as authoritative committed state moves — through any compatible authority, across
 reconnects. 0.13 adds no Server IR vocabulary of its own — current is `axiom.server.v9`.

package/docs/LOCATIONS.md

@@ -1,6 +1,6 @@
 # Locations
 
-Axiom 0.17.0-alpha.1.
+Axiom 1.0.0.
 
 ```text
 Expression = a value

package/docs/MIGRATIONS.md

@@ -1,6 +1,6 @@
 # Schema evolution & semantic migrations
 
-Axiom 0.17.0-alpha.1. The operational contract for evolving a deployed application's
+Axiom 1.0.0. The operational contract for evolving a deployed application's
 semantic model and its persisted canonical data over time — adding a required field,
 splitting one field into two, removing an obsolete one, migrating millions of
 provider-backed rows — **without** an application-authored SQL migration, an ORM migration,

package/docs/PRESENTATION.md

@@ -1,6 +1,6 @@
 # Presentation
 
-Axiom 0.17.0-alpha.1. Presentation is **semantic UX intent**, expressed as data on a UI
+Axiom 1.0.0. Presentation is **semantic UX intent**, expressed as data on a UI
 node. It names roles, tokens and device classes. It never names a colour, a length, a media
 query or a CSS property.
 

package/docs/QUERIES.md

@@ -1,6 +1,6 @@
 # Semantic data access & the query layer
 
-Axiom 0.17.0-alpha.1. The operational contract for demand-driven reads over authoritative
+Axiom 1.0.0. The operational contract for demand-driven reads over authoritative
 data that is too large to materialize as a `StateDef` — 500,000 orders, 5,000,000 order
 lines, years of audit rows. `axiom.server.v6`.
 

package/docs/RUNTIME.md

@@ -1,6 +1,6 @@
 # Runtime
 
-Axiom 0.17.0-alpha.1. The runtime executes an `ApplicationIR`. It is domain-independent: it
+Axiom 1.0.0. The runtime executes an `ApplicationIR`. It is domain-independent: it
 contains no knowledge of any application.
 
 ## Constructing

package/docs/SEMANTIC_CONTRACT.md

@@ -1,11 +1,41 @@
 # Semantic contract
 
-Axiom 0.17.0-alpha.1. Runtime guarantees, stated formally. This file defines behavior; it
-does not teach. Where this file and any specification in `../specs/` disagree, this file
-describes the implementation and is authoritative.
+Axiom 1.0.0. Runtime guarantees, stated formally. This file defines behavior; it
+does not teach.
 
 `MUST` / `MUST NOT` describe guaranteed behavior. `MAY` describes a documented option.
 
+## Normative precedence
+
+For a **portable semantic rule** — one whose result can change what an application means to
+an observer — the order of authority is:
+
+1. The formal specification (`specs/spec*.md`) for a rule it states explicitly.
+2. This semantic contract and the topic documents under `docs/` — the consolidated
+   normative statement of portable runtime behavior.
+3. The public JSON Schemas (`@cynodia/axiom-server/schema/*`) — structural validity and
+   discriminators only.
+4. The public type declarations (`*.d.ts`) — structural shape only; they never override
+   prose meaning.
+5. The runtime-neutral conformance fixtures — normative **evidence** of the rules above.
+   They test specified semantics; they do not invent them. A fixture that exercises a
+   behavior no normative artifact describes is a **specification gap**, not a new rule.
+
+**Reference-runtime behavior is evidence, not authority.** Where the reference runtime
+disagrees with 1–5, the reference runtime is **defective** and is corrected to the
+contract — never the contract to the runtime. Where two of 1–5 disagree, that is a
+specification defect resolved explicitly, not silently by convention or by observing a
+runtime. Where the contract is **silent** on a portable behavior, it is filled by an
+explicit contract change.
+
+This inverts the pre-0.17 "the implementation is authoritative" rule, which held only while
+the portable contract was still incomplete. That rule survives **only** for
+**non-portable implementation detail** — rendering internals, storage layout,
+process/thread model, private diagnostics, performance, physical retry counts — none of
+which is portable semantics and none of which cross-runtime conformance compares. For those,
+`docs/` describes the reference implementation and the reference implementation is
+authoritative.
+
 ## State
 
 ### Stored state
@@ -177,9 +207,10 @@ location.
 - Nothing returns a plausible value alongside a failure diagnostic.
 - Collection operators are strict about their source: `null` fails, `[]` behaves normally.
 - `sum` fails if any member is not a finite number.
-- Values are cloned with `structuredClone`, never a JSON round trip, so `NaN` is not disguised as `null`.
+- Values are cloned structurally, never via a JSON round trip, so `NaN` is not disguised as `null`.
+- Truthiness, text form, numeric form, equality and ordering are defined **language-neutrally** and MUST NOT be delegated to a host language's conversion functions. Axiom numbers are IEEE-754 binary64; `divide` by zero is `null`; an ordered comparison with a non-finite operand is `false`; `NaN` and the infinities are not storable domain values. Number → text is the canonical decimal string (ECMAScript `Number::toString` radix 10, restated); text → number accepts trimmed canonical decimal literals (empty → `0`, unparseable → `NaN`), with radix-prefixed and `Infinity` forms accepted for compatibility but discouraged. Text coercion of a **structured** value is outside the portable grammar; structural identity/keys/fingerprints use canonical (code-point-sorted) JSON.
 
-Full per-kind semantics: [`EXPRESSIONS.md`](EXPRESSIONS.md).
+Full per-kind semantics and the full conversion tables: [`EXPRESSIONS.md`](EXPRESSIONS.md#conversions).
 
 ## Authority
 

package/docs/STATE.md

@@ -1,6 +1,6 @@
 # State
 
-Axiom 0.17.0-alpha.1. A `StateDef` is a named application value: stored, or computed from
+Axiom 1.0.0. A `StateDef` is a named application value: stored, or computed from
 other state.
 
 ```ts

package/docs/STORAGE.md

@@ -1,6 +1,6 @@
 # Storage and blobs
 
-Axiom 0.17.0-alpha.1. How an application stores, references, serves and deletes binary data —
+Axiom 1.0.0. How an application stores, references, serves and deletes binary data —
 an attachment, a document, a photograph, a diagnostic log — with no filesystem path, no
 upload route and no download route anywhere in it.
 

package/docs/SUBSCRIPTIONS.md

@@ -1,6 +1,6 @@
 # Subscriptions
 
-Axiom 0.17.0-alpha.1. How an application receives a stream of external events — an MQTT
+Axiom 1.0.0. How an application receives a stream of external events — an MQTT
 topic, a WebSocket feed, a queue consumer, a filesystem watcher, a serial port — without a
 client, a socket or a callback anywhere in the graph.
 

package/docs/TRIGGERS.md

@@ -1,6 +1,6 @@
 # Triggers
 
-Axiom 0.17.0-alpha.1. A `TriggerDef` says **when** an action should be invoked, without
+Axiom 1.0.0. A `TriggerDef` says **when** an action should be invoked, without
 embedding callback code. `docs/AUTHORITY.md`
 [§ Triggers](AUTHORITY.md#triggers) is the load-bearing statement of the execution model;
 this file is the vocabulary.

package/docs/UI.md

@@ -1,6 +1,6 @@
 # UI
 
-Axiom 0.17.0-alpha.1. Eleven semantic UI node kinds describe **what exists and what it does**.
+Axiom 1.0.0. Eleven semantic UI node kinds describe **what exists and what it does**.
 How it looks is [presentation](PRESENTATION.md).
 
 All eleven share `UIBase`:

package/docs/VALIDATION.md

@@ -1,6 +1,6 @@
 # Validation
 
-Axiom 0.17.0-alpha.1. Validation is authoring-time structural checking. It is not the same
+Axiom 1.0.0. Validation is authoring-time structural checking. It is not the same
 as runtime constraint evaluation — see [`CONSTRAINTS.md`](CONSTRAINTS.md) for the four
 layers of correctness.
 

package/docs/WORKFLOWS.md

@@ -1,6 +1,6 @@
 # Durable workflows
 
-Axiom 0.17.0-alpha.1. The operational contract for **long-running semantic computations with
+Axiom 1.0.0. The operational contract for **long-running semantic computations with
 a durable control position** — orchestration that survives process death, authority
 failover, retries, timer delivery, event delivery and ordinary distributed contention
 without application-owned infrastructure. `axiom.server.v8`.
@@ -255,7 +255,7 @@ step's argument expressions / `retry` policy, a `wait-event` step's `where` / `b
   or binding migration, and none is inferred ("closest step" recovery never happens).
 - A graph with **no** `WorkflowDef` compiles to the byte-identical `axiom.server.v1`–`v7`
   document it always did, and its `semanticFingerprint` / `schemaFingerprint` are unchanged.
-- Pre-`0.17.0-alpha.1` instances carry a compatibility key computed before `WorkflowDef`
+- Pre-`1.0.0` instances carry a compatibility key computed before `WorkflowDef`
   participated; a corrected authority treats them as incompatible and fails closed (these
   are pre-freeze alpha releases — silent reinterpretation is the only unacceptable
   outcome).

package/llms.txt

@@ -1,6 +1,6 @@
 # Axiom
 
-> AI-native semantic application framework, version 0.17.0-alpha.1. An Axiom application is a
+> AI-native semantic application framework, version 1.0.0. An Axiom application is a
 > typed semantic graph — state, behavior, constraints, UI structure, presentation and
 > authority as structured data — executed by generic runtimes. The JavaScript, HTML and CSS
 > that reach a browser are compiler output and are never authored or edited. The primary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cynodia/axiom",
-  "version": "0.17.0-alpha.1",
+  "version": "1.0.0",
   "description": "AI-native semantic web application framework.",
   "license": "MIT",
   "author": "AskTech AS",
@@ -34,12 +34,15 @@
     }
   },
   "dependencies": {
-    "@cynodia/axiom-core": "0.17.0-alpha.1",
-    "@cynodia/axiom-runtime": "0.17.0-alpha.1",
-    "@cynodia/axiom-compiler": "0.17.0-alpha.1",
-    "@cynodia/axiom-agent-api": "0.17.0-alpha.1"
+    "@cynodia/axiom-core": "1.0.0",
+    "@cynodia/axiom-runtime": "1.0.0",
+    "@cynodia/axiom-compiler": "1.0.0",
+    "@cynodia/axiom-agent-api": "1.0.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
   }
 }