ICNS
Related · ICNS

ICNS — declare the numeral before you use it

Interpretation-Complete Numeral Specification

Everyone has seen a version sorter decide 0.10 < 0.9. ICNS treats that not as a bug in one tool but as a missing declaration: a numeral only has decidable meaning once its carrier, grammar, radix, position map, bounds, ordering, equality, normalization, resolution, carry and successor rules are all declared and retrievable. Its scope is deliberately narrow, and it is engineered to 1.0.

Spec version
1.0.0
Frozen
2026-07-29
Status
STABLE
Profiles
4
Stable features
21
Built-in schemas
8
Transport
icns-transport v1
API paths
78
Tests
227
License
undecided
The problem

Four strings, three legitimate orderings

Take the same four tokens and read them under three different declarations. Every ordering below is correct — under its own schema. Nothing about the characters themselves tells you which one applies, which is why a reader, a package manager and a language model can each pick a different answer and all feel confident.

tokens:   0.9    0.10    0.89    0.91

decimal-real          0.10 = 0.1  <  0.89  <  0.9   <  0.91
version-2-lex          (0,9)      <  (0,10) < (0,89) < (0,91)
version-packed-111     0.91  ->  (0, 9, 1)     not  (0, 91)

so:  succ(0.90) = 0.91        under decimal-10-p2   (resolution 1/100)
     succ(0.9)  = 1.0         under decimal-10-p1   (resolution 1/10)
     succ(x)    = undefined   under decimal-real    (no quantization)

and:  "V0.91"  ->  UNRESOLVED + W_PREFIX_ONLY
      a prefix is a hint, not a declaration

The last line is ICNS’s first proposition: string concatenation cannot make a numeral unambiguous. `V0.91` still admits (0,91), (0,9,1) and 0.91 — unless `V` resolves to a complete, retrievable schema, it carries context, not semantics.

Core object

Surface, declaration, judgment, envelope

ICNS splits a numeral into a surface token plus the environment that gives it meaning. The declaration domain says what it is; the judgment domain says how it may be compared, normalized and advanced; the operation envelope makes the whole thing identifiable, versioned and exchangeable.

N^  =  < s ; Δ , Π ; Ω >

Δ  =  < D, G, R, P, M, K >     declaration
      carrier, grammar, radix, position map, bounds, length

Π  =  < O, E, N, Q, C, S >     judgment
      order, equality, normalization, resolution, carry, successor

Ω  =  < ρ, ν, h, λ, μ >        envelope
      schema id, version, content hash, scope, provenance

meaning(s)          is not well-formed
meaning(s | Γ)      is                      Γ = (Δ, Π)

The envelope may never change what Δ and Π mean mathematically — it exists for resolution, verification, caching, tracing and cross-system exchange. And the same (ρ, ν) pair must never point at two different content hashes: that is E_SCHEMA_HASH_MISMATCH, refused rather than resolved.

Propositions

Three results that make the rest necessary

01

Prefixes are insufficient

For any prefix p and bare numeral s, concatenating them cannot guarantee a unique interpretation. `V0.91` has at least three compatible readings. A prefix only becomes a declaration when it resolves to a complete, unique, retrievable schema.

02

“Next” depends on the domain

The successor of a numeral is not a property of its surface value. In ℝ no successor exists; on a quantization grid it is x + Q; in a version vector it is a chosen field plus one. Without D, Q and S declared, “the next one” has no unique answer.

03

Equal display ≠ equal meaning

Under real semantics 0.9 = 0.90. Under measurement semantics the values match but the resolutions do not. Under field semantics (0,9) ≠ (0,90). Value equality, representation equality, precision equality and structural equality have to be declared separately.

A fourth distinction runs through the paper: the largest single digit, the digit-count limit, the largest representable value at that limit (1 − b⁻ⁿ), and the supremum or limit under unbounded expansion are four different things and must not share one word.

Representations

Seven surfaces, one intermediate representation

ICNS does not require every environment to look the same — it requires every environment to compile down to the same declaration and judgment conditions. Two representations are semantically equivalent exactly when CompileRep gives them the same canonical object.

FormName
ALinear scope declaration
BOver/under attachment
CFour-corner attachment
DSchema anchoring
EExplicit container
FSelf-describing exchange
GSidecar schema

Resolution priority is fixed and silent overwrite is forbidden: inline ▷ anchor ▷ block ▷ sidecar ▷ document ▷ application ▷ registry. Two conflicting declarations at the same priority return E_SCHEMA_CONFLICT rather than letting the implementation pick.

Engine

The processing pipeline

Pure-function-first, so f(x, Γ) is reproducible for the same input and schema. Parsing requires exactly one legal reading: zero matches is E_PARSE_NO_MATCH, more than one is E_PARSE_AMBIGUOUS. Neither is quietly resolved.

resolve
parse
validate
evaluate
normalize
operate
serialize

Cross-schema comparison negotiates a common schema Γ* first and converts losslessly into it. If no common schema exists, or a conversion would lose scale or structure, the answer is INCOMPARABLE or a W_CONVERSION_LOSSY warning — not a number.

Grading

Six levels of completeness

Not every use needs the same strength, so ICNS grades it instead of demanding everything everywhere. The reference implementation targets at least L3, raises to L4 when successor or carry is used, and L5 when publishing across systems.

LevelName
L0Bare symbol
L1Type hint
L2Parseable
L3Decidable
L4Operable
L5Exchangeable & traceable

Six of the eight schemas frozen in 1.0 reach L4 — decimal-10-p1, decimal-10-p2, time-hms, version-2-lex, version-3-lex, version-packed-111 — while decimal-real and identifier-exact stop at L3, because a real number has no successor and an opaque identifier has no order.

What 1.0 freezes

Four profiles, one contract hash

ICNS 1.0 does not just tag a version — it emits a machine-readable stability contract (spec/icns-1.0-freeze.json) pinning profiles, feature stability, built-in schema hashes, transport operations and the OpenAPI hash, then verifies itself against it for drift.

Core 1.0 — 8 features

  • parse, compare, equal, normalize, successor, serialize
  • declarative schema validation
  • the built-in schema set and its frozen semantics
  • 8 schemas, each pinned by content hash: decimal-real, decimal-10-p1, decimal-10-p2, version-2-lex, version-3-lex, version-packed-111, time-hms, identifier-exact

Interop 1.0 — 5 features

  • Transport v1: 17 hashable request/response operations, idempotent replay, collision refusal
  • sorted-json-utf8-v1 canonicalization — Python and JavaScript produce the same SHA-256
  • Signed schema packages with SHA-256 integrity and a four-state trust model
  • Append-only registry: one content hash per (package, version), forever
  • Transparency log with Merkle inclusion proofs; federation snapshots, deltas, fork evidence, offline bundles, witnesses

Tooling 1.0 — 4 features

  • Python SDK (local + HTTP client) and JavaScript SDK (browser + Node)
  • Language Server: diagnostics, hover, completion, formatting, quick fixes, document symbols
  • VS Code extension, project check with SARIF output, GitHub Actions and pre-commit hooks
  • Deterministic codegen to Python, TypeScript and JSON Schema, with a verifiable codegen manifest

Deployment 1.0 — 4 features

  • Liveness, readiness and full runtime status endpoints; Prometheus text metrics
  • Structured forward-hash-chain audit log with verification
  • Verifiable backup, safe restore refusing path traversal, recovery drill
  • Reproducible release manifest; Docker, Compose, Kubernetes and systemd assets running non-root on a read-only root filesystem

Verified by 227 regression tests plus a normative conformance suite (icns-1.0-core, 18 cases, PASS). Within 1.x: no stable feature removed, no built-in schema semantics changed, no transport operation removed, no stable API path dropped without a replacement, and no new required field added to an existing stable request. Deprecation takes at least 2 minor releases and at least 180 days, whichever is later.

Boundaries

What ICNS refuses to be

ICNS’s own post-1.0 plan opens with five principles, and most of them are restraints rather than features.

Not a consensus system

The federation layer is not a blockchain and not Byzantine consensus. It will never automatically rule which side of a fork is the real history — it produces verifiable evidence and leaves adjudication to explicit governance policy.

Verifiable is not true

Content hashes, signatures, transparency logs and witnesses prove whether content was modified, whether a publisher signed, and whether a node witnessed. They cannot prove a schema is correct about the real world.

Experimental must not pose as stable

Anything without enough tests, cases and formal analysis is marked EXPERIMENTAL, may iterate fast, and promises no 1.x compatibility. Network exploration and arbitrary executable schema rules were deliberately left outside the stable core.

No untrusted code execution

External schemas may not run arbitrary code. Custom parsers and comparators are declarative, sandboxed, resource-limited, reproducible and network-denied by default. Token length, field count, recursion depth and candidate-parse count are all capped against parser DoS.

Not owned by a product

The core stays an independently usable specification. A product may use ICNS; it may not reverse-decide ICNS’s semantics. Its value depends on cross-implementation agreement, which a closed core would destroy.

Not an internet standard, and not yet licensed

The `application/icns+json` media type is experimental; standardization is meant to follow real interoperability demand, not theoretical completeness. And 1.0 freezes technical contracts only — MIT, Apache-2.0 or dual licensing all remain an explicit, unmade publisher decision.

What comes next

Four separate lines, and a stop condition

ICNS 1.0 is capped, and its own plan argues against extending 1.1, 1.2, 1.3 merely because more features are possible. The four development lines are deliberately separated so a research experiment can never leak into the stable contract.

LineScopeStatus
1.xStable maintenancepartial
2.0Experimental researchplanned
ecoEcosystem & adoptionplanned
linkTheory & product bridgesplanned

Otherwise the state is STABLE / MAINTENANCE. Restart conditions are explicit: a confirmed defect, a real use case, an external report, a publication need, a dependent product, formalization work that requires spec wording changes, or new theory strong enough to justify 2.0.

Relation to EML

Why this sits next to a transpiler

The link is not thematic — it is in the release. ICNS 1.0 ships EveMissLab version schemas as worked examples: `eml-version-2-bounded`, `eml-version-3-bounded` (major 0–9, minor 0–99, patch 0–99 with a default, lexicographic order, pad-right-zero normalization, no carry, successor increments patch) and `eml-release-train` (year 2026–2099 × train 0–99). They exist because a spec that cannot state its own version numbering has not finished.

The deeper overlap is a shared refusal. EML’s core rule is that no LLM sits in the transpilation chain and round-trip faithfulness is an invariant, not a feature. ICNS’s core rule is that a declaration always beats a guess, and an insufficient declaration returns UNRESOLVED or AMBIGUOUS instead of a plausible number. Both are betting that determinism is what makes a layer safe to put under an AI, and both would rather fail loudly than be quietly wrong.

They also fail in the same direction. EML’s reverse compression is a deterministic inverse only on its supported subset and errors out on inexpressible constructs. ICNS refuses cross-schema comparison when no lossless common schema exists. Neither treats “produce something” as better than “say it cannot be done”.

The one-line principle ICNS wants to outlive itself: before any symbol is executed, compared, sorted, exchanged, or handed to an artificial intelligence, it should first declare which semantic system it belongs to.

Source documents

Paper, whitepaper, frozen spec

ICNS went from proposition to capped specification in one cycle: bare numeral → interpretation-complete semantics → schema → document → package → governance → federation → SDK → toolchain → deployment → stable spec.

解譯完備數符:從裸數字到可判定語義的表示框架

public paper · v0.1 · 2026-07-29

The theory: bare-numeral ambiguity, the declaration and judgment domains, the three propositions, the fourfold distinction of decimal limits, and the four public representation methods.

解譯完備數符統合技術白皮書

whitepaper · v0.1 · 2026-07-29

The implementable spec: field-by-field declaration and judgment vocabulary, the seven representations, scope priority, the minimal EBNF, schema registration and fingerprints, the pipeline, algorithms, error and warning codes, completeness levels, and the acceptance test vectors.

spec/icns-1.0-freeze.json

sha256:151b432d…

The machine-readable stability contract: 4 profiles, 21 features with stability labels, 8 built-in schema hashes, the transport operation list, the OpenAPI lock (78 paths), 12 normative artifacts with their own hashes, and the compatibility policy.

spec/ICNS-1.0-Core / Schema-and-Semantics / Transport / Profiles / Versioning / Conformance

6 normative documents

The 1.0 normative document set, each pinned by hash inside the freeze contract and re-verified by `spec-verify` for drift.

conformance/icns-1.0-core.suite.json

18 cases · PASS

The normative conformance suite, runnable via `conformance-run`, with JSON and JUnit reports so another implementation can be measured against the same cases.

ICNS 1.0 後續發展與未來計畫

non-normative · v0.1 · 2026-07-29

The four development lines, five principles, priority order, and the stop / restart conditions summarised in the table above. Explicitly does not modify the 1.0 freeze.

Like CAIR, ICNS is currently a research and engineering archive, so nothing here is a download link. Its release states the licensing position outright: 1.0 freezes technical contracts only, the bundled implementation keeps its research-artifact notice, and choosing MIT, Apache-2.0 or dual licensing remains a separate publisher decision. The compatibility promise above is a technical policy — not a commercial SLA, warranty, uptime or response-time commitment.