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
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 declarationThe 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.
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.
Three results that make the rest necessary
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.
“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.
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.
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.
| Form | Name |
|---|---|
| A | Linear scope declaration |
| B | Over/under attachment |
| C | Four-corner attachment |
| D | Schema anchoring |
| E | Explicit container |
| F | Self-describing exchange |
| G | Sidecar 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.
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.
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.
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.
| Level | Name |
|---|---|
| L0 | Bare symbol |
| L1 | Type hint |
| L2 | Parseable |
| L3 | Decidable |
| L4 | Operable |
| L5 | Exchangeable & 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.
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.
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.
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.
| Line | Scope | Status |
|---|---|---|
| 1.x | Stable maintenance | partial |
| 2.0 | Experimental research | planned |
| eco | Ecosystem & adoption | planned |
| link | Theory & product bridges | planned |
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.
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.
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.
Canonical Authoritative Intermediate Representation
A program does not have to be owned by one text surface. Text, graph, grid, natural language, AI candidates, tensors and governance are projections of one authoritative computational ontology.
Multi-layer Numerical Visualization Protocol
A number being correctly represented is not the same as a number being correctly understood. Every display is a projection — MNVP makes that projection declare what it kept, what it dropped, and whether it is still faithful.