@cavelang/core 0.1.0

package/src/claim.ts

@@ -0,0 +1,148 @@
+/**
+ * Claims — the CAVE model (spec §2.1).
+ *
+ * Every CAVE line denotes a claim c = ⟨s, v, o, n, m⟩: subject, verb,
+ * object-or-attribute/value, negated, metadata (confidence, contexts, tags,
+ * value uncertainty, importance, comment, transaction identity). Claims are
+ * immutable — belief changes by appending (spec §9).
+ *
+ * This module defines the *canonical* claim shape: subject/verb/object are in
+ * primary direction (inverse forms are normalized before keying, spec §5.5),
+ * with the author's original text preserved in `raw`.
+ */
+
+import * as Value from './value.ts'
+import * as Tag from './tag.ts'
+import * as Context from './context.ts'
+import * as Confidence from './confidence.ts'
+
+/** Subject or object term (spec §16: atom, literal or code literal). */
+export type TermKind = 'entity' | 'text' | 'code'
+
+export type Term = {
+  readonly kind: TermKind
+  readonly text: string
+}
+
+/** @returns entity term. */
+export const entity = (text: string): Term =>
+  ({ kind: 'entity', text })
+
+/** @returns double-quoted natural-language literal term. */
+export const text = (value: string): Term =>
+  ({ kind: 'text', text: value })
+
+/** @returns backticked code literal term. */
+export const code = (value: string): Term =>
+  ({ kind: 'code', text: value })
+
+/** @returns canonical text of a term with its delimiters. */
+export const formatTerm = (term: Term): string => {
+  switch (term.kind) {
+    case 'text':
+      return `"${term.text}"`
+    case 'code':
+      return `\`${term.text}\``
+    default:
+      return term.text
+  }
+}
+
+/**
+ * Claim payload — the canonical line shapes (spec §3.1) plus the object-less
+ * form used by bare existence assertions (spec §5.2 `EXISTS`):
+ *
+ * - `relation`:  `subject VERB object`
+ * - `attribute`: `subject HAS attribute: value`
+ * - `metric`:    `metric IS value`
+ * - `none`:      `memory-leak EXISTS @production`
+ */
+export type Payload =
+  | { readonly kind: 'relation', readonly object: Term }
+  | { readonly kind: 'attribute', readonly attribute: string, readonly value: Value.t }
+  | { readonly kind: 'metric', readonly value: Value.t }
+  | { readonly kind: 'none' }
+
+/** Canonical (primary-direction) claim. */
+export type Claim = {
+  readonly subject: Term
+  /** Canonical primary verb, uppercase (spec §13.4 steps 1–2). */
+  readonly verb: string
+  /** `VERB NOT` logical negation (spec §5.6). */
+  readonly negated: boolean
+  readonly payload: Payload
+  /** Contexts in author order, deduplicated. */
+  readonly contexts: readonly Context.t[]
+  readonly tags: readonly Tag.t[]
+  /** Epistemic confidence in [0, 1]; 1 when omitted (spec §6.3). */
+  readonly conf: Confidence.t
+  /** `!` marker (spec §6). */
+  readonly importance: boolean
+  /** `+/-` value uncertainty (spec §7.2). */
+  readonly delta?: Value.t
+  /** `(Nσ)` σ-level override; semantic default is 2 (spec §7.2). */
+  readonly sigmaLevel?: number
+  /** `;` persisted prose (spec §6.4). */
+  readonly comment?: string
+  /** The line exactly as written, including inverse form (spec §5.5). */
+  readonly raw: string
+}
+
+export type t = Claim
+
+export type Init = {
+  subject: Term
+  verb: string
+  payload: Payload
+  negated?: boolean
+  contexts?: readonly Context.t[]
+  tags?: readonly Tag.t[]
+  conf?: Confidence.t
+  importance?: boolean
+  delta?: Value.t
+  sigmaLevel?: number
+  comment?: string
+  raw?: string
+}
+
+/** @returns claim with defaults applied (spec §6: all suffixes optional). */
+export const of = (init: Init): Claim => ({
+  subject: init.subject,
+  verb: init.verb,
+  negated: init.negated ?? false,
+  payload: init.payload,
+  contexts: Context.dedupe(init.contexts ?? []),
+  tags: init.tags ?? [],
+  conf: init.conf ?? Confidence.defaultConfidence,
+  importance: init.importance ?? false,
+  ...init.delta !== undefined ? { delta: init.delta } : {},
+  ...init.sigmaLevel !== undefined ? { sigmaLevel: init.sigmaLevel } : {},
+  ...init.comment !== undefined ? { comment: init.comment } : {},
+  raw: init.raw ?? ''
+})
+
+/** @returns relational claim payload. */
+export const relation = (object: Term): Payload =>
+  ({ kind: 'relation', object })
+
+/** @returns attribute/value claim payload. */
+export const attribute = (attribute: string, value: Value.t): Payload =>
+  ({ kind: 'attribute', attribute, value })
+
+/** @returns metric claim payload. */
+export const metric = (value: Value.t): Payload =>
+  ({ kind: 'metric', value })
+
+/** Object-less payload — bare existence assertion (spec §5.2 `EXISTS`). */
+export const none: Payload =
+  { kind: 'none' }
+
+/**
+ * σ derived from the claim's `+/- Δ (kσ)` metadata: σ = Δ / k with k
+ * defaulting to 2 (spec §7.2). `undefined` when the claim carries no numeric
+ * uncertainty.
+ */
+export const sigmaOf = (claim: Claim): undefined | number =>
+  claim.delta?.num === undefined ?
+    undefined :
+    claim.delta.num / (claim.sigmaLevel ?? 2)

package/src/confidence.ts

@@ -0,0 +1,42 @@
+/**
+ * Claim confidence — `@ N%` (spec §6.3).
+ *
+ * Epistemic belief in the assertion, stored as a decimal in [0, 1].
+ * Omitted confidence means `@ 100%` — directly observed, certain for
+ * practical purposes. `@ 0%` means evidentially false or fully rejected
+ * (retraction, spec §9.3).
+ */
+
+export type Confidence = number
+
+export type t = Confidence
+
+/** Confidence of a claim with no explicit `@ N%` (spec §6.3). */
+export const defaultConfidence = 1
+
+/**
+ * Parses a percentage token (`90%`) to a decimal clamped to [0, 1]
+ * (spec §13.4 step 6: `@ 90%` → `0.9`). The `%` is required — the grammar
+ * (spec §16) defines confidence as a percentage ending in `%`, and demanding
+ * it keeps a mistyped context like `@ 2026` from silently becoming
+ * certainty.
+ * @returns `undefined` when the token is not a percentage.
+ */
+export const parse = (token: string): undefined | Confidence => {
+  const match = /^(\d+(?:\.\d+)?)%$/.exec(token.trim())
+  if (!match || match[1] === undefined) {
+    return undefined
+  }
+  return clamp(Number(match[1]) / 100)
+}
+
+/** @returns confidence clamped to [0, 1]. */
+export const clamp = (conf: number): Confidence =>
+  Math.min(1, Math.max(0, conf))
+
+/** @returns canonical `N%` text: `0.9` → `90%`. */
+export const format = (conf: Confidence): string => {
+  const percent = conf * 100
+  const rounded = Math.round(percent * 100) / 100
+  return `${rounded}%`
+}

package/src/context.ts

@@ -0,0 +1,43 @@
+/**
+ * Contexts — `@ctx` (spec §6.1).
+ *
+ * A context scopes a claim by time, place, source or logical scope:
+ * `@production`, `@2026-Q1`, `@auth.ts:42`, `@src:filing`. No space after
+ * `@` (with a space it is confidence, spec §6.3). Multiple contexts per
+ * claim are allowed and are part of the claim key (spec §9.2).
+ */
+
+export type Context = string
+
+export type t = Context
+
+/** Recommended context prefixes (spec §6.1). */
+export const prefixes = ['src', 'time', 'loc', 'scope'] as const
+
+export type Prefix = (typeof prefixes)[number]
+
+const prefixSet = new Set<string>(prefixes)
+
+/**
+ * @returns the recommended prefix of a context, when it has one:
+ * `src:filing` → `src`, `production` → `undefined`.
+ */
+export const prefix = (context: Context): undefined | Prefix => {
+  const colonAt = context.indexOf(':')
+  if (colonAt === -1) {
+    return undefined
+  }
+  const head = context.slice(0, colonAt)
+  return prefixSet.has(head) ? head as Prefix : undefined
+}
+
+/** @returns canonical `@ctx` text. */
+export const format = (context: Context): string =>
+  `@${context}`
+
+/**
+ * @returns deduplicated contexts in original order. Claim keys use the
+ * sorted form (see `Key`); emission preserves author order.
+ */
+export const dedupe = (contexts: readonly Context[]): Context[] =>
+  [...new Set(contexts)]

package/src/entity.ts

@@ -0,0 +1,49 @@
+/**
+ * Entity names (spec §4.1).
+ *
+ * Entities are compact names: `auth/middleware`, `react/hooks/use-memo`,
+ * `PostgreSQL`, `Sarah`. `/` separates scope segments (at most 3:
+ * `domain/entity/aspect`), segments are kebab-case, proper nouns keep their
+ * casing.
+ */
+
+export type Entity = string
+
+export type t = Entity
+
+/**
+ * Normalizes an entity name (spec §13.4 step 4): trims and collapses runs of
+ * internal whitespace to `-`. Casing is preserved — proper nouns keep theirs.
+ *
+ * `token expiry` → `token-expiry`, `PostgreSQL` → `PostgreSQL`.
+ */
+export const normalize = (name: string): Entity =>
+  name.trim().replace(/\s+/g, '-')
+
+/** @returns scope segments of an entity name: `a/b/c` → `['a', 'b', 'c']`. */
+export const segments = (entity: Entity): string[] =>
+  entity.split('/')
+
+/**
+ * Advisory well-formedness check (spec §4.1). Returns a list of human-readable
+ * problems; an empty list means the name follows every convention. Problems
+ * are advisories, not parse errors — CAVE tolerates messy extraction input.
+ */
+export const check = (entity: Entity): string[] => {
+  const problems: string[] = []
+  if (entity.length === 0) {
+    problems.push('empty entity name')
+    return problems
+  }
+  const parts = segments(entity)
+  if (parts.length > 3) {
+    problems.push(`more than 3 scope segments (${parts.length}): domain/entity/aspect is the maximum`)
+  }
+  if (parts.some(part => part.length === 0)) {
+    problems.push('empty scope segment')
+  }
+  if (/\s/.test(entity)) {
+    problems.push('whitespace in entity name (normalize to -)')
+  }
+  return problems
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@cavelang/core` — the CAVE domain model (spec §2, §6, §7, §9).
+ *
+ * Dependency-free foundation of the CAVE monorepo: canonical claim shapes,
+ * values/units/multipliers, uncertainty and confidence semantics, claim keys
+ * and UUIDv7 transaction identifiers. Higher packages (parser, canonical,
+ * store, query, fusion, loop, cli) build on these types.
+ *
+ * Modules follow the `@prelude` convention: `import * as Claim from ...`,
+ * with each module exporting its principal type as `t`.
+ */
+
+export * as Claim from './claim.ts'
+export * as Confidence from './confidence.ts'
+export * as Context from './context.ts'
+export * as Entity from './entity.ts'
+export * as Key from './key.ts'
+export * as Multiplier from './multiplier.ts'
+export * as Tag from './tag.ts'
+export * as Uncertainty from './uncertainty.ts'
+export * as Uuidv7 from './uuidv7.ts'
+export * as Value from './value.ts'
+export * as Verb from './verb.ts'

package/src/key.ts

@@ -0,0 +1,55 @@
+/**
+ * Claim keys (spec §9.2).
+ *
+ * The claim key identifies the *fact* whose belief evolves over time: the
+ * latest transaction with the same key is the current belief (spec §9.1).
+ * Keys are computed on the canonical (primary-direction) form, so a forward
+ * claim and its inverse reading share one key — one fact, two names
+ * (spec §5.5).
+ *
+ * Key components:
+ *
+ * - relational claim:      subject, verb, object, negated, context set
+ * - attribute/value claim: subject, verb, attribute, negated, context set
+ * - metric claim:          subject, verb, negated, context set
+ *
+ * The value is *excluded* — it may change over time while the key stays
+ * about the same property. Confidence, tags, uncertainty, importance and
+ * comments are metadata and never key components. Contexts participate as a
+ * sorted, deduplicated set, which is what lets competing hypotheses
+ * differentiate by `@hyp:` context (spec §10.3).
+ *
+ * The key format is a JSON array — deterministic, collision-free and
+ * readable in the database.
+ */
+
+import type * as Claim from './claim.ts'
+
+// Every term kind gets its own prefix so the three encodings occupy
+// disjoint namespaces — an entity literally named `code:<=` must not
+// collide with the backticked code literal `<=`.
+const termPart = (term: Claim.Term): string =>
+  term.kind === 'entity' ? `e:${term.text}` : `${term.kind}:${term.text}`
+
+const payloadPart = (payload: Claim.Payload): string => {
+  switch (payload.kind) {
+    case 'relation':
+      return `r:${termPart(payload.object)}`
+    case 'attribute':
+      return `a:${payload.attribute}`
+    case 'metric':
+      return 'm'
+    case 'none':
+      return 'n'
+  }
+}
+
+/** @returns stable claim key of a canonical claim. */
+export const of = (claim: Claim.t): string =>
+  JSON.stringify([
+    termPart(claim.subject),
+    claim.verb,
+    claim.negated ? 1 : 0,
+    payloadPart(claim.payload),
+    [...new Set(claim.contexts)].sort()
+  ])

package/src/multiplier.ts

@@ -0,0 +1,28 @@
+/**
+ * Numeric multipliers (spec §7.1).
+ *
+ * A multiplier is a single uppercase letter glued to a number: `20B`, `900M`,
+ * `1.5T`, `10K`. It scales the numeric value during canonicalization
+ * (spec §13.4 step 8: `20B` → `20000000000`); the raw text is preserved.
+ */
+
+/** Multiplier letter. */
+export type Multiplier = 'T' | 'B' | 'M' | 'K'
+
+export type t = Multiplier
+
+/** Scale factor per multiplier letter. */
+export const factors: Readonly<Record<Multiplier, number>> = {
+  T: 1e12,
+  B: 1e9,
+  M: 1e6,
+  K: 1e3
+}
+
+/** @returns `true` if `s` is exactly one multiplier letter. */
+export const is = (s: string): s is Multiplier =>
+  s === 'T' || s === 'B' || s === 'M' || s === 'K'
+
+/** @returns scale factor of multiplier. */
+export const factor = (m: Multiplier): number =>
+  factors[m]

package/src/tag.ts

@@ -0,0 +1,42 @@
+/**
+ * Tags — flat `#tag` and scoped `#key:value` (spec §6.2).
+ *
+ * A flat `#security` is `key=security, value=undefined`; a scoped
+ * `#topic:auth-security` splits on the first `:`. Scoped tags subsume flat
+ * tags — a flat `#tag` is simply a tag with null value.
+ *
+ * Tags classify the claim, not the entity, and carry no independent belief
+ * history (the two-lane rule, spec §11.1).
+ */
+
+export type Tag = {
+  readonly key: string
+  /** `undefined` for flat tags; spec stores NULL (spec §13.2). */
+  readonly value?: string
+}
+
+export type t = Tag
+
+/** @returns tag from key and optional scoped value. */
+export const of = (key: string, value?: string): Tag =>
+  value === undefined ? { key } : { key, value }
+
+/**
+ * Splits a tag body (without the leading `#`) on the first `:`
+ * (spec §6.2 disambiguation): `topic:auth-security` → scoped,
+ * `security` → flat.
+ */
+export const parse = (body: string): Tag => {
+  const colonAt = body.indexOf(':')
+  return colonAt === -1 ?
+    { key: body } :
+    { key: body.slice(0, colonAt), value: body.slice(colonAt + 1) }
+}
+
+/** @returns canonical `#key[:value]` text. */
+export const format = (tag: Tag): string =>
+  tag.value === undefined ? `#${tag.key}` : `#${tag.key}:${tag.value}`
+
+/** @returns `true` when both tags have the same key and value. */
+export const equals = (a: Tag, b: Tag): boolean =>
+  a.key === b.key && a.value === b.value

package/src/uncertainty.ts

@@ -0,0 +1,29 @@
+/**
+ * Value uncertainty — `+/- delta [(Nσ)]` (spec §7.2).
+ *
+ * `+/-` defines a symmetric interval around the value; the default
+ * interpretation is 2σ (≈95% interval). If the interval is Δ at kσ then
+ * σ = Δ / k:
+ *
+ * - `20B +/- 2B`      → σ = 1B  (default 2σ)
+ * - `20B +/- 2B (1σ)` → σ = 2B  (wider)
+ * - `20B +/- 2B (3σ)` → σ ≈ 0.67B (tighter)
+ *
+ * Value uncertainty is aleatory (the quantity itself is imprecise) and is
+ * independent of epistemic claim confidence `@ N%` (spec §7.3).
+ */
+
+/** Default σ level when `(Nσ)` is omitted (spec §7.2). */
+export const defaultSigmaLevel = 2
+
+/** @returns σ from an interval `delta` given at `level`σ: σ = Δ / k. */
+export const sigma = (delta: number, level: number = defaultSigmaLevel): number => {
+  if (!(level > 0)) {
+    throw new Error(`Expected positive sigma level, got ${level}.`)
+  }
+  return delta / level
+}
+
+/** @returns symmetric `[low, high]` interval around `mean`. */
+export const interval = (mean: number, delta: number): [number, number] =>
+  [mean - delta, mean + delta]

package/src/uuidv7.ts

@@ -0,0 +1,76 @@
+/**
+ * UUIDv7 transaction identifiers (spec §9.1).
+ *
+ * CAVE storage is append-only; each appended claim carries a transaction id.
+ * UUIDv7 is recommended because it encodes timestamp and ordering — ids sort
+ * lexicographically by creation time, so `MAX(tx)` resolves current belief.
+ *
+ * {@link next} is strictly monotonic within a process: same-millisecond calls
+ * increment a 12-bit sequence in the `rand_a` field, and a backwards system
+ * clock never produces a smaller id.
+ */
+
+import { randomFillSync } from 'node:crypto'
+
+const hex = (n: number, digits: number): string =>
+  n.toString(16).padStart(digits, '0')
+
+/**
+ * Formats a UUIDv7 from parts — pure, for tests and deterministic imports.
+ *
+ * @param ms unix timestamp in milliseconds (48 bits)
+ * @param seq 12-bit sequence placed in `rand_a`
+ * @param rand 62 bits of randomness for `rand_b` as 8 bytes (top 2 bits are
+ * overwritten by the variant)
+ */
+export const at = (ms: number, seq: number, rand: Uint8Array): string => {
+  if (!Number.isInteger(ms) || ms < 0 || ms > 0xffff_ffff_ffff) {
+    throw new Error(`Expected 48-bit millisecond timestamp, got ${ms}.`)
+  }
+  if (!Number.isInteger(seq) || seq < 0 || seq > 0xfff) {
+    throw new Error(`Expected 12-bit sequence, got ${seq}.`)
+  }
+  if (rand.length < 8) {
+    throw new Error(`Expected 8 random bytes, got ${rand.length}.`)
+  }
+  const time = hex(ms, 12)
+  const variantByte = (rand[0]! & 0x3f) | 0x80
+  return [
+    time.slice(0, 8),
+    time.slice(8, 12),
+    `7${hex(seq, 3)}`,
+    hex(variantByte, 2) + hex(rand[1]!, 2),
+    [...rand.slice(2, 8)].map(byte => hex(byte, 2)).join('')
+  ].join('-')
+}
+
+let lastMs = -1
+let lastSeq = 0
+
+/**
+ * @returns next monotonic UUIDv7. Strictly increasing (lexicographically)
+ * within the process even across same-millisecond calls and clock skew.
+ */
+export const next = (now: () => number = Date.now): string => {
+  let ms = now()
+  if (ms <= lastMs) {
+    ms = lastMs
+    lastSeq += 1
+    if (lastSeq > 0xfff) {
+      ms += 1
+      lastSeq = 0
+    }
+  } else {
+    lastSeq = 0
+  }
+  lastMs = ms
+  const rand = new Uint8Array(8)
+  randomFillSync(rand)
+  return at(ms, lastSeq, rand)
+}
+
+const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+/** @returns `true` if `s` is a well-formed UUIDv7 string. */
+export const is = (s: string): boolean =>
+  uuidRe.test(s)

package/src/value.ts

@@ -0,0 +1,138 @@
+/**
+ * Values, units and multipliers (spec §7.1).
+ *
+ * A value is the payload of an attribute claim (`HAS attr: value`), a metric
+ * claim (`metric IS value`), or a `+/-` uncertainty delta. Parsing keeps the
+ * raw text verbatim and additionally extracts a normalized numeric value and
+ * unit when possible (spec §13.4 steps 7–9):
+ *
+ * - `30ms`           → num 30, unit `ms`
+ * - `20B USD/yr`     → num 20000000000, unit `USD/yr`
+ * - `~20B USD/yr`    → the same, `approx` set
+ * - `94.5%`          → num 94.5, unit `%`
+ * - `20 conn`        → num 20, unit `conn`
+ * - `2026-H2`        → date-like, kept textual
+ * - `token-expiry`   → atom, kept textual
+ *
+ * Quoted (`"..."`) and backticked (`` `...` ``) values arrive from the parser
+ * with their kind already known; use {@link ofText} / {@link ofCode}.
+ */
+
+import * as Multiplier from './multiplier.ts'
+
+/** How the value text was classified. */
+export type Kind =
+  | 'number' // numeric, possibly with multiplier and unit
+  | 'date'   // date-like: 2026-H2, 2026-Q1, 2026-04-10
+  | 'atom'   // bare word(s): token-expiry, critical
+  | 'text'   // double-quoted natural-language literal
+  | 'code'   // backticked exact literal
+
+export type Value = {
+  /** Exactly as written, including `~` and multiplier letter. */
+  readonly raw: string
+  readonly kind: Kind
+  /** `~` prefix (spec §7.1): the value is approximate. */
+  readonly approx: boolean
+  /** Normalized numeric value with multiplier expanded, when parseable. */
+  readonly num?: number
+  /** Normalized unit expression (`USD/yr`, `ms`, `%`), when present. */
+  readonly unit?: string
+}
+
+export type t = Value
+
+const numberRe = /^(-?\d+(?:\.\d+)?)([A-Za-z%]*)$/
+const unitRe = /^[A-Za-z%$][A-Za-z0-9%$]*(?:\/[A-Za-z0-9%$]+)*$/
+const dateRe = /^\d{4}-(?:H[1-2]|Q[1-4]|W\d{1,2}|\d{2})(?:-\d{2})?$/
+
+/** @returns `true` if `s` is a valid unit expression (`USD/yr`, `ms`, `%`). */
+export const isUnit = (s: string): boolean =>
+  unitRe.test(s)
+
+/**
+ * @returns `true` if `s` is date-like (spec §16 `date_like`): `2026-H2`,
+ * `2026-Q1`, `2026-04`, `2026-04-10`. A bare year parses as a number instead.
+ */
+export const isDateLike = (s: string): boolean =>
+  dateRe.test(s)
+
+type Numeric = { num: number, unit?: string }
+
+/**
+ * Parses `body` as number [multiplier] [unit] where the unit is either glued
+ * (`30ms`, `94.5%`) or space-separated (`20B USD/yr`, `20 conn`).
+ * @returns `undefined` when `body` is not numeric.
+ */
+const parseNumeric = (body: string): undefined | Numeric => {
+  const spaceAt = body.indexOf(' ')
+  const head = spaceAt === -1 ? body : body.slice(0, spaceAt)
+  const tail = spaceAt === -1 ? undefined : body.slice(spaceAt + 1).trim()
+  const match = numberRe.exec(head)
+  if (!match) {
+    return undefined
+  }
+  const [, digits, glued] = match
+  let num = Number(digits)
+  let unit: undefined | string
+  if (glued !== undefined && glued !== '') {
+    if (Multiplier.is(glued)) {
+      num *= Multiplier.factor(glued)
+    } else if (isUnit(glued)) {
+      unit = glued
+    } else {
+      return undefined
+    }
+  }
+  if (tail !== undefined) {
+    if (unit !== undefined || !isUnit(tail)) {
+      return undefined
+    }
+    unit = tail
+  }
+  return unit === undefined ? { num } : { num, unit }
+}
+
+/**
+ * Parses an unquoted value string (spec §16 `value`), classifying it as
+ * number, date or atom. The raw text (including `~` and multiplier letters)
+ * is preserved verbatim.
+ */
+export const parse = (raw: string): Value => {
+  const approx = raw.startsWith('~')
+  const body = approx ? raw.slice(1) : raw
+  const numeric = parseNumeric(body)
+  if (numeric !== undefined) {
+    return numeric.unit === undefined ?
+      { raw, kind: 'number', approx, num: numeric.num } :
+      { raw, kind: 'number', approx, num: numeric.num, unit: numeric.unit }
+  }
+  if (isDateLike(body)) {
+    return { raw, kind: 'date', approx }
+  }
+  return { raw, kind: 'atom', approx }
+}
+
+/** @returns value for a double-quoted natural-language literal (spec §4.2). */
+export const ofText = (text: string): Value =>
+  ({ raw: text, kind: 'text', approx: false })
+
+/** @returns value for a backticked exact code literal (spec §4.2). */
+export const ofCode = (code: string): Value =>
+  ({ raw: code, kind: 'code', approx: false })
+
+/**
+ * @returns canonical text of the value for emission. Raw text is already
+ * canonical (spec normalizes multipliers only in storage, never in text);
+ * quoted kinds are re-wrapped in their delimiters.
+ */
+export const format = (value: Value): string => {
+  switch (value.kind) {
+    case 'text':
+      return `"${value.raw}"`
+    case 'code':
+      return `\`${value.raw}\``
+    default:
+      return value.raw
+  }
+}