@factoidal/core 0.2.0 → 0.3.0

package/store-host/node.mjs

@@ -0,0 +1,212 @@
+// Node implementation of the four host primitives the Lean persisted store
+// needs (Harness/PosixRangeIO.lean). See ./index.mjs for the contract and
+// for the places where Node's semantics differ from the C externs.
+//
+// Nothing here parses, verifies or interprets a byte. It opens files,
+// moves bytes, and syncs.
+
+import {
+  closeSync, fstatSync, fsyncSync, openSync, readSync, readdirSync,
+  renameSync, statSync, unlinkSync, writeSync
+} from 'node:fs'
+
+import { StoreHostError } from './errors.mjs'
+import { baseName, dirName, joinPath } from './paths.mjs'
+
+export const runtime = 'node'
+
+function wrap (code, message, path, cause) {
+  return new StoreHostError(code, `${message}: ${String(cause && cause.message ? cause.message : cause)}`, { path, cause })
+}
+
+function isInterrupt (error) {
+  return error && (error.code === 'EINTR' || error.code === 'EAGAIN')
+}
+
+function openRead (path) {
+  try {
+    return openSync(path, 'r')
+  } catch (cause) {
+    throw wrap('OPEN_FAILED', `cannot open ${path} for reading`, path, cause)
+  }
+}
+
+/** Read `length` bytes at `offset` into `out` at `outOffset`. Returns how many. */
+function preadInto (fd, out, outOffset, length, offset, path) {
+  let done = 0
+  while (done < length) {
+    let read
+    try {
+      read = readSync(fd, out, outOffset + done, length - done, offset + done)
+    } catch (cause) {
+      if (isInterrupt(cause)) continue
+      throw wrap('READ_FAILED', `read failed on ${path}`, path, cause)
+    }
+    if (read === 0) break
+    done += read
+  }
+  return done
+}
+
+export function readWhole (path) {
+  const fd = openRead(path)
+  try {
+    const size = fstatSync(fd).size
+    if (!Number.isSafeInteger(size)) {
+      throw new StoreHostError('FILE_TOO_LARGE', `${path} is larger than 2^53 - 1 bytes`, { path })
+    }
+    const out = new Uint8Array(size)
+    const done = preadInto(fd, out, 0, size, 0, path)
+    if (done !== size) {
+      throw new StoreHostError('SHORT_READ', `${path} shrank during the read (${done} of ${size} bytes)`, { path })
+    }
+    return out
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function readRange (path, offset, length) {
+  if (length === 0) return new Uint8Array(0)
+  const fd = openRead(path)
+  try {
+    const out = new Uint8Array(length)
+    const done = preadInto(fd, out, 0, length, offset, path)
+    if (done !== length) {
+      throw new StoreHostError(
+        'SHORT_READ',
+        `${path} returned ${done} of ${length} bytes at offset ${offset}`,
+        { path }
+      )
+    }
+    return out
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function appendSyncAtSize (path, bytes, expectedSize) {
+  let fd
+  try {
+    // 'a' is O_WRONLY | O_CREAT | O_APPEND, matching the C extern's open.
+    fd = openSync(path, 'a')
+  } catch (cause) {
+    throw wrap('OPEN_FAILED', `cannot open ${path} for append`, path, cause)
+  }
+  try {
+    const size = fstatSync(fd).size
+    if (size !== expectedSize) return false
+    let done = 0
+    while (done < bytes.length) {
+      let written
+      try {
+        // position null keeps the O_APPEND placement the C extern relies on.
+        written = writeSync(fd, bytes, done, bytes.length - done, null)
+      } catch (cause) {
+        if (isInterrupt(cause)) continue
+        throw wrap('WRITE_FAILED', `append failed on ${path}`, path, cause)
+      }
+      done += written
+    }
+    try {
+      fsyncSync(fd)
+    } catch (cause) {
+      throw wrap('FSYNC_FAILED', `fsync failed on ${path}`, path, cause)
+    }
+    return true
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function temporaryName (path) {
+  const suffix = Math.floor(Math.random() * 0xffffff).toString(16).padStart(6, '0')
+  return joinPath(dirName(path), baseName(path) + '.tmp.' + suffix)
+}
+
+function fsyncDirectory (directory) {
+  let fd
+  try {
+    fd = openSync(directory, 'r')
+  } catch (cause) {
+    throw wrap('DIR_OPEN_FAILED', `cannot open ${directory} to sync it`, directory, cause)
+  }
+  try {
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function atomicReplace (path, bytes) {
+  const directory = dirName(path)
+  let temporary = null
+  let fd = null
+  try {
+    for (let attempt = 0; attempt < 8 && fd === null; attempt += 1) {
+      temporary = temporaryName(path)
+      try {
+        // 'wx' is O_WRONLY | O_CREAT | O_EXCL, the exclusive create that
+        // makes the name ours the way mkstemp does in the C extern.
+        fd = openSync(temporary, 'wx')
+      } catch (cause) {
+        if (cause && cause.code === 'EEXIST') continue
+        throw wrap('OPEN_FAILED', `cannot create ${temporary}`, temporary, cause)
+      }
+    }
+    if (fd === null) {
+      throw new StoreHostError('TEMP_NAME_EXHAUSTED', `no free temporary name beside ${path}`, { path })
+    }
+    let done = 0
+    while (done < bytes.length) {
+      let written
+      try {
+        written = writeSync(fd, bytes, done, bytes.length - done, null)
+      } catch (cause) {
+        if (isInterrupt(cause)) continue
+        throw wrap('WRITE_FAILED', `write failed on ${temporary}`, temporary, cause)
+      }
+      done += written
+    }
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = null
+    renameSync(temporary, path)
+    temporary = null
+    try {
+      fsyncDirectory(directory)
+    } catch (_error) {
+      // The C extern also returns false here, with the replacement already
+      // done. Reported the same way; see ./index.mjs for what false means.
+      return false
+    }
+    return true
+  } catch (error) {
+    if (fd !== null) closeSync(fd)
+    if (temporary !== null) {
+      try { unlinkSync(temporary) } catch (_ignored) { /* the temporary may not exist */ }
+    }
+    throw error
+  }
+}
+
+export function listGeneration (directory) {
+  let names
+  try {
+    names = readdirSync(directory)
+  } catch (cause) {
+    throw wrap('DIR_READ_FAILED', `cannot list ${directory}`, directory, cause)
+  }
+  const out = []
+  for (const name of names.sort()) {
+    let info
+    try {
+      info = statSync(joinPath(directory, name))
+    } catch (_cause) {
+      continue // a name that vanished between readdir and stat
+    }
+    if (!info.isFile()) continue
+    out.push({ name, size: info.size })
+  }
+  return out
+}

package/store-host/paths.mjs

@@ -0,0 +1,77 @@
+// Path plumbing for the store host. No dependency on `node:path`, so the
+// same file loads under Deno without the Node compatibility layer.
+//
+// These functions join and split path strings. They make no decision about
+// what a Shardborough generation contains.
+
+import { StoreHostError } from './errors.mjs'
+
+const SEPARATORS = ['/', '\\']
+
+function isSeparator (character) {
+  return SEPARATORS.indexOf(character) >= 0
+}
+
+/** Join with '/'. Every runtime this module targets accepts '/'. */
+export function joinPath (base, child) {
+  if (base.length === 0) return child
+  const last = base[base.length - 1]
+  return isSeparator(last) ? base + child : base + '/' + child
+}
+
+/** The directory part of a path, or '.' when the path has no separator. */
+export function dirName (path) {
+  let end = path.length
+  while (end > 1 && isSeparator(path[end - 1])) end -= 1
+  let index = end - 1
+  while (index >= 0 && !isSeparator(path[index])) index -= 1
+  if (index < 0) return '.'
+  if (index === 0) return path[0]
+  return path.slice(0, index)
+}
+
+/** The final component of a path. */
+export function baseName (path) {
+  let end = path.length
+  while (end > 1 && isSeparator(path[end - 1])) end -= 1
+  let index = end - 1
+  while (index >= 0 && !isSeparator(path[index])) index -= 1
+  return path.slice(index + 1, end)
+}
+
+/**
+ * A single child name that may be appended to a directory path.
+ *
+ * `CURRENT` holds a generation name written by the Lean activation path;
+ * this module still refuses a value that would leave the collection root
+ * when joined. That is a filesystem-safety guard on a string the host is
+ * about to turn into a path, not a check of the pointer's format.
+ */
+export function requireChildName (name, label) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new StoreHostError('BAD_CHILD_NAME', `${label} is empty`)
+  }
+  if (name === '.' || name === '..') {
+    throw new StoreHostError('BAD_CHILD_NAME', `${label} is "${name}"`)
+  }
+  for (const character of name) {
+    if (isSeparator(character) || character === '\u0000') {
+      throw new StoreHostError(
+        'BAD_CHILD_NAME',
+        `${label} contains a path separator or NUL byte`
+      )
+    }
+  }
+  return name
+}
+
+/** Convert a `file:` URL string to a filesystem path. */
+export function fileUrlToPath (url) {
+  const text = typeof url === 'string' ? url : String(url)
+  if (!text.startsWith('file://')) return text
+  let path = decodeURIComponent(text.slice('file://'.length))
+  const host = path.indexOf('/')
+  if (host > 0) path = path.slice(host)
+  if (/^\/[A-Za-z]:/.test(path)) path = path.slice(1)
+  return path
+}

package/version.json

@@ -1,20 +1,20 @@
 {
-  "version": "0.2.0",
+  "version": "0.3.0",
   "gitSha": "49f8ca4d70bf57c12fea445611e2b01b067bf6ba",
   "builtAt": "2026-08-26T21:45:40Z",
   "claims": {
     "schema": "1",
-    "statement": "Proved sound with respect to an independent F* formalization of the W3C RDF/RDFS/OWL semantics, under the stated fragment restrictions and the trust surface recorded in docs/theorem-registry.md — never claimed as a complete formally verified implementation of RDF semantics (docs/theorem-registry.md § Calibrated claims).",
+    "statement": "Proved sound with respect to an independent F* formalization of the W3C RDF/RDFS/OWL semantics, under the stated fragment restrictions and the trust surface recorded in docs/theorem-registry.md \u2014 never claimed as a complete formally verified implementation of RDF semantics (docs/theorem-registry.md \u00a7 Calibrated claims).",
     "registry": "docs/theorem-registry.md",
-    "trustSurface": "docs/theorem-registry.md § Trust surface",
-    "notes": "Each item below names the exact theorem/lemma, the F* file that carries it, and the registry section a reader can open to check the claim. This is a summary, not the full registry — read docs/theorem-registry.md for the complete rule-by-rule table, hypothesis provenance, and open findings.",
+    "trustSurface": "docs/theorem-registry.md \u00a7 Trust surface",
+    "notes": "Each item below names the exact theorem/lemma, the F* file that carries it, and the registry section a reader can open to check the claim. This is a summary, not the full registry \u2014 read docs/theorem-registry.md for the complete rule-by-rule table, hypothesis provenance, and open findings.",
     "items": [
       {
         "id": "rho-df-closure-decides",
-        "claim": "The certified six-rule core-RDFS (ρdf) closure (rdfs2/3/5/7/9/11) decides entailment exactly on fragment inputs — its simple-query answers are exactly the entailed consequences.",
+        "claim": "The certified six-rule core-RDFS (\u03c1df) closure (rdfs2/3/5/7/9/11) decides entailment exactly on fragment inputs \u2014 its simple-query answers are exactly the entailed consequences.",
         "theorem": "rho_df_closure_sound, rho_df_closure_decides",
         "file": "formal/fstar/RDF.Entailment.RDFS.RhoDFClosure.fst",
-        "registrySection": "docs/theorem-registry.md § Layer 3 — the composed regime theorem, rho_df_closure soundness/fragment-preservation rows",
+        "registrySection": "docs/theorem-registry.md \u00a7 Layer 3 \u2014 the composed regime theorem, rho_df_closure soundness/fragment-preservation rows",
         "npmSurface": [
           "coreRdfsClosure",
           "rhoDfClosure",
@@ -27,7 +27,7 @@
         "id": "owl-rl-licensing-truth",
         "claim": "Every OWL 2 RL/RDF engine rule classified [row] emits only input triples or a licensed W3C table-row application (licensing), and every row's conclusion is model-theoretically true given its premises (truth).",
         "file": "formal/fstar/OWL.RL.Spec.fst, OWL.RL.Refinement.fst, OWL.Semantics.fst",
-        "registrySection": "docs/theorem-registry.md § 1 (OWL 2 RL/RDF — licensing and truth, per engine rule)",
+        "registrySection": "docs/theorem-registry.md \u00a7 1 (OWL 2 RL/RDF \u2014 licensing and truth, per engine rule)",
         "npmSurface": [
           "owlClosure",
           "rdfsPlusClosure",
@@ -36,21 +36,21 @@
           "owlIsConsistent",
           "owlEntails"
         ],
-        "status": "proved per-rule; see §1 table for per-row status and PARKED clash-row exceptions"
+        "status": "proved per-rule; see \u00a71 table for per-row status and PARKED clash-row exceptions"
       },
       {
         "id": "rdfs-entailment-13-rows",
-        "claim": "11 of 13 RDF 1.1 Semantics §9 RDFS entailment rows have a shipping engine rule with both licensing and truth proved; the remaining 2 (rdfs6, rdfs10) are proved at the spec-predicate level but the shipping engine's reflexivity over-approximation for them is correctly flagged unsound (finding RS-1), not silently shipped as sound.",
+        "claim": "11 of 13 RDF 1.1 Semantics \u00a79 RDFS entailment rows have a shipping engine rule with both licensing and truth proved; the remaining 2 (rdfs6, rdfs10) are proved at the spec-predicate level but the shipping engine's reflexivity over-approximation for them is correctly flagged unsound (finding RS-1), not silently shipped as sound.",
         "file": "formal/fstar/RDF.Entailment.RDFS.Spec.fst, RDF.Entailment.RDFS.Refinement.fst, RDF.Entailment.RDFS.ModelTheory.fst",
-        "registrySection": "docs/theorem-registry.md § 2 (RDFS entailment — 13 rows)",
+        "registrySection": "docs/theorem-registry.md \u00a7 2 (RDFS entailment \u2014 13 rows)",
         "status": "11/13 proved sound+true; 2/13 truth-only, engine unsoundness flagged not hidden"
       },
       {
         "id": "sparql-rdfs-regime-exact-answer",
-        "claim": "The SPARQL evaluator's answer set over the ρdf closure IS the RDFS entailment regime's answer set, on fragment inputs, for ground answers (soundness + completeness, unconditional).",
+        "claim": "The SPARQL evaluator's answer set over the \u03c1df closure IS the RDFS entailment regime's answer set, on fragment inputs, for ground answers (soundness + completeness, unconditional).",
         "theorem": "theorem_rdfs_regime_bgp_exact_answer, theorem_rdfs_regime_ask_query_complete",
         "file": "formal/fstar/SPARQL11.EntailmentRegime.RDFS.fst",
-        "registrySection": "docs/theorem-registry.md § 5 (SPARQL algebra refinement, the query rung) § Layer 3",
+        "registrySection": "docs/theorem-registry.md \u00a7 5 (SPARQL algebra refinement, the query rung) \u00a7 Layer 3",
         "npmSurface": [
           "query (options.entail = 'RDFS')"
         ],
@@ -58,18 +58,18 @@
       },
       {
         "id": "streaming-multichunk",
-        "claim": "N-Quads streaming parse over ANY list of input chunks equals a batch parse of their concatenation (stream_parse chunks == batch_parse (concat_all chunks)) — the machine-checked answer to whether chunked/streamed parsing of arbitrarily large files agrees with parsing the whole file at once.",
+        "claim": "N-Quads streaming parse over ANY list of input chunks equals a batch parse of their concatenation (stream_parse chunks == batch_parse (concat_all chunks)) \u2014 the machine-checked answer to whether chunked/streamed parsing of arbitrarily large files agrees with parsing the whole file at once.",
         "theorem": "theorem_stream_eq_batch",
         "file": "formal/fstar/RDF.NQuads.Streaming.fst",
-        "registrySection": "docs/theorem-registry.md § 7 (G4/M1 parser round-trip theorems) — Task #48/#402 MULTI-CHUNK STREAMING THEOREM, 2026-08-11",
+        "registrySection": "docs/theorem-registry.md \u00a7 7 (G4/M1 parser round-trip theorems) \u2014 Task #48/#402 MULTI-CHUNK STREAMING THEOREM, 2026-08-11",
         "status": "proved"
       },
       {
         "id": "srj-n-row",
-        "claim": "SPARQL Results JSON serialisation (serialise_response_json) equals the fixed SRJ shape (head/vars block, comma-joined row texts) for ANY variable list and ANY row list of ANY length N — not just the 0/1/2-row cases spot-checked before.",
+        "claim": "SPARQL Results JSON serialisation (serialise_response_json) equals the fixed SRJ shape (head/vars block, comma-joined row texts) for ANY variable list and ANY row list of ANY length N \u2014 not just the 0/1/2-row cases spot-checked before.",
         "theorem": "lemma_srj_n_rows",
         "file": "formal/fstar/SPARQL.Protocol.RoundTrip.fst",
-        "registrySection": "docs/theorem-registry.md § 7 (G4/M1 parser round-trip theorems) — G4 M4 N-ROW symbolic SRJ theorem, 2026-08-11",
+        "registrySection": "docs/theorem-registry.md \u00a7 7 (G4/M1 parser round-trip theorems) \u2014 G4 M4 N-ROW symbolic SRJ theorem, 2026-08-11",
         "npmSurface": [
           "query (SELECT, output SPARQL Results JSON)"
         ],
@@ -77,10 +77,10 @@
       },
       {
         "id": "symbolic-iri-roundtrip",
-        "claim": "Parsing the printed N-Triples form of a SYMBOLIC IRI term (any ASCII codepoint list of IRI-safe characters, no escapes, no controls) recovers the original term exactly — proved against the real serializer, not a transcription.",
+        "claim": "Parsing the printed N-Triples form of a SYMBOLIC IRI term (any ASCII codepoint list of IRI-safe characters, no escapes, no controls) recovers the original term exactly \u2014 proved against the real serializer, not a transcription.",
         "theorem": "lemma_term_iri_round_trip_build_string",
         "file": "formal/fstar/RDF.NTriples.RoundTrip.fst",
-        "registrySection": "docs/theorem-registry.md § 7 (G4/M1 parser round-trip theorems) — G4 M1 SYMBOLIC IRI round-trip theorem, 2026-08-11",
+        "registrySection": "docs/theorem-registry.md \u00a7 7 (G4/M1 parser round-trip theorems) \u2014 G4 M1 SYMBOLIC IRI round-trip theorem, 2026-08-11",
         "npmSurface": [
           "parse",
           "serialize"
@@ -92,10 +92,11 @@
         "claim": "The FastString byte-primitive migration (steps 0-6) is complete: zero assume vals in the FastString family except the one documented CharBoundary primitive (unsafe_char_of_d7ff); the equivalence corpus is IDENTICAL between native OCaml and Node (js_of_ocaml) execution.",
         "measurement": "93846 pass, 962 expected-fail, 0 unexpected fail (out of 94808), verified 3 ways (fresh Node run, fresh same-source native compile, prior recorded number)",
         "file": "formal/fstar/Parser.FastString.fst, Parser.FastString.Spec.fst",
-        "registrySection": "docs/theorem-registry.md § 7 (G4/M1 parser round-trip theorems) — FastString migration COMPLETE, steps 0-6, 2026-08-11",
+        "registrySection": "docs/theorem-registry.md \u00a7 7 (G4/M1 parser round-trip theorems) \u2014 FastString migration COMPLETE, steps 0-6, 2026-08-11",
         "status": "complete, measured equivalent native+Node"
       }
     ],
-    "notClaimed": "A complete formally verified implementation of RDF semantics. See docs/theorem-registry.md § Trust surface for the assume-val count (~146, mostly COTTAS/HDT storage I/O per iron rule #11), the extraction-step caveat (fstar.exe --codegen OCaml is not itself re-verified), and the rdf-mt / W3C conformance suites this registry relies on as the independent runtime check. CLAUDE.md's standing qualifier applies: parser and algebra spec verified in F*; the on-disk backend carries unverified OCaml-side optimization layers being migrated back to F*."
-  }
+    "notClaimed": "A complete formally verified implementation of RDF semantics. See docs/theorem-registry.md \u00a7 Trust surface for the assume-val count (~146, mostly COTTAS/HDT storage I/O per iron rule #11), the extraction-step caveat (fstar.exe --codegen OCaml is not itself re-verified), and the rdf-mt / W3C conformance suites this registry relies on as the independent runtime check. CLAUDE.md's standing qualifier applies: parser and algebra spec verified in F*; the on-disk backend carries unverified OCaml-side optimization layers being migrated back to F*."
+  },
+  "note": "The F* engine bundle in this package was built at gitSha 49f8ca4d7 (2026-08-26T21:45:40Z) and is unchanged since; the version member mirrors the package version. The Lean engine's own provenance is in l4-assets/version.json."
 }