@factoidal/core 0.2.0 → 0.4.0

package/sample-store/gen-1/predicate-3.ibk3.merkle

@@ -0,0 +1 @@
+�R�2 ���mcY(]HI��

package/sample-store/gen-1/predicate-3.ibk3.oli2.merkle

@@ -0,0 +1 @@
+��Q�+_�`*YN�	;B��E�<Ls�+d���

package/sample-store/gen-1/predicate-3.ibk3.sri2.merkle

@@ -0,0 +1 @@
+�c����E���EҮ���J�x?ݣ67���

package/sample-store/gen-1/predicate-3.ibk3.tli1.merkle

@@ -0,0 +1 @@
+5�z�@d���Z�����Kg���U,�"�{�l��q֪נ�c�,��@$�zo���Q���

package/sample-store/gen-1/predicate-4.ibk3.oli2.merkle

@@ -0,0 +1 @@
+�$�����B�7�!bUs�2���1��S�f

package/sample-store/gen-1/predicate-4.ibk3.sri2.merkle

@@ -0,0 +1 @@
+5c�X���,'C����8DYӻ[����t�@�/l

package/sample-store/gen-1/predicate-4.ibk3.tli1.merkle

@@ -0,0 +1,2 @@
+X��N�����(`tw8a�sdR���
+H�:���

package/sample-store/gen-1/predicate-5.ibk3.merkle

@@ -0,0 +1 @@
+'�=�U)B:��ӯ�ٳ�{I��4FoֹJKA

package/sample-store/gen-1/predicate-5.ibk3.oli2.merkle

@@ -0,0 +1 @@
+	i���<�%4�0���z."~�v4n�*$ǝ

package/sample-store/gen-1/predicate-5.ibk3.sri2.merkle

@@ -0,0 +1 @@
+��(WUVh�ؠ$w���6�zh��L�Qo���

package/sample-store/gen-1/predicate-5.ibk3.tli1.merkle

@@ -0,0 +1 @@
+�Đ��5�k��EQ2��zE��;��oɗ�

package/sample-store/gen-1/predicate-6.ibk3.merkle

@@ -0,0 +1 @@
+���2N����Y�M~8������3�(z>l�r��

package/sample-store/gen-1/predicate-6.ibk3.oli2.merkle

@@ -0,0 +1 @@
+�6��%v�.+u���}0�v�0��������

package/sample-store/gen-1/predicate-6.ibk3.sri2.merkle

@@ -0,0 +1 @@
+q�/F����AL&��z�1�z�YP�x#

package/sample-store/gen-1/predicate-7.ibk3.oli2.merkle

@@ -0,0 +1,2 @@
+�w�#���H��Ѐ:4����<V�
+Q�n��

package/sample-store/gen-1/predicate-7.ibk3.sri2.merkle

@@ -0,0 +1 @@
+�~��CV�L��3&#�|��D�6��	��

package/sample-store/gen-1/predicate-7.ibk3.tli1.merkle

@@ -0,0 +1 @@
+�8}��P0�oK���5t ����8�f
OR�

package/sample-store/gen-1/predicate-8.ibk3.merkle

@@ -0,0 +1 @@
+_��k��2Ǟ��bk[�r�Փ���>+�8�"

package/sample-store/gen-1/predicate-8.ibk3.oli2.merkle

@@ -0,0 +1 @@
+�

package/sample-store/gen-1/predicate-8.ibk3.sri2.merkle

@@ -0,0 +1 @@
+���]",�b��\�B\�$on�ΰ�gcEb

package/sample-store/gen-1/predicate-8.ibk3.tli1.merkle

@@ -0,0 +1 @@
+`��y�

package/sample-store/gen-1/predicate-9.ibk3.merkle

@@ -0,0 +1 @@
+Zvt&��Sv�V�u¹t��ڼ{7�MP��j*

package/sample-store/gen-1/predicate-9.ibk3.oli2.merkle

@@ -0,0 +1 @@
+!'M�Uw����,GD��������A�|���a�

package/sample-store/gen-1/predicate-9.ibk3.sri2.merkle

@@ -0,0 +1,3 @@
+��9\X��
+�
+�cGC�%Mο�c���*��G?

package/sample-store/gen-1/predicate-9.ibk3.tli1.merkle

@@ -0,0 +1,2 @@
+�
+>��fa���?��i�+-N���>R��

package/sample-store.d.ts

@@ -0,0 +1,16 @@
+/** The collection root of the sample Shardborough store bundled with this
+ * package: the directory that holds CURRENT. */
+export declare function sampleStorePath (): string
+
+export declare const sampleStoreFacts: Readonly<{
+  triples: number
+  blocks: number
+  layout: string
+  wireVersion: number
+  source: string
+  licence: string
+  licenceUrl: string
+  publisher: string
+}>
+
+export default sampleStorePath

package/sample-store.mjs

@@ -0,0 +1,37 @@
+// The sample Shardborough store this package carries, so a fresh install
+// answers a SPARQL query with no other download and no native binary.
+//
+// The store was packed by `l4block-shard-pack … ibk3` and activated by
+// `l4block-shard-activate`. Nothing here decodes it; this module only
+// resolves its path inside the installed package.
+//
+// CONTENT AND LICENCE. Five IPTC NewsCodes vocabularies, published by the
+// IPTC under CC BY 4.0 and taken from danbri/skosdex third_party/skos:
+// spamfstat, videoqualifier, subjectqualifier, videocodec and spct.
+// 4,434 triples in 13 predicate blocks. See NOTICE.
+
+import { fileUrlToPath, joinPath } from './store-host/paths.mjs'
+
+/** The collection root of the bundled sample store: the directory holding
+ * CURRENT. Pass it to `factoidal inspect` / `factoidal query`, or to
+ * `openStore` from `@factoidal/core/store-host`. */
+export function sampleStorePath () {
+  const packageRoot = fileUrlToPath(new URL('.', import.meta.url).href)
+  return joinPath(packageRoot, 'sample-store')
+}
+
+/** What the sample store holds, as recorded when it was packed. The engine
+ * is the authority on every one of these numbers at run time; they are here
+ * so a caller can print something before it opens the store. */
+export const sampleStoreFacts = Object.freeze({
+  triples: 4434,
+  blocks: 13,
+  layout: 'predicate-ibk3-ptd1-sri2-tli1-oli2-merkle-v0',
+  wireVersion: 6,
+  source: 'IPTC NewsCodes (spamfstat, videoqualifier, subjectqualifier, videocodec, spct)',
+  licence: 'CC BY 4.0',
+  licenceUrl: 'https://creativecommons.org/licenses/by/4.0/',
+  publisher: 'https://iptc.org/'
+})
+
+export default sampleStorePath

package/store-host/deno.mjs

@@ -0,0 +1,262 @@
+// Deno implementation of the same four host primitives. Uses only Deno
+// globals, so it never loads Deno's Node compatibility layer.
+//
+// Deno 2 removed the resource-id fsync entry points (`Deno.fsyncSync`);
+// the file-handle method `FsFile.syncSync()` is the one that exists.
+
+import { StoreHostError } from './errors.mjs'
+import { baseName, dirName, joinPath } from './paths.mjs'
+
+export const runtime = 'deno'
+
+function wrap (code, message, path, cause) {
+  return new StoreHostError(code, `${message}: ${String(cause && cause.message ? cause.message : cause)}`, { path, cause })
+}
+
+function openRead (path) {
+  try {
+    return Deno.openSync(path, { read: true })
+  } catch (cause) {
+    throw wrap('OPEN_FAILED', `cannot open ${path} for reading`, path, cause)
+  }
+}
+
+/**
+ * Deno has no positional read. Each call here opens its own handle, so the
+ * seek belongs to that handle alone and no other reader can move it. That
+ * is what `pread` buys the C extern; it is not the same instruction.
+ */
+function readInto (file, out, length, offset, path) {
+  if (offset > 0) file.seekSync(offset, Deno.SeekMode.Start)
+  let done = 0
+  while (done < length) {
+    let read
+    try {
+      read = file.readSync(out.subarray(done, length))
+    } catch (cause) {
+      throw wrap('READ_FAILED', `read failed on ${path}`, path, cause)
+    }
+    if (read === null || read === 0) break
+    done += read
+  }
+  return done
+}
+
+export function readWhole (path) {
+  const file = openRead(path)
+  try {
+    const size = file.statSync().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 = readInto(file, out, size, 0, path)
+    if (done !== size) {
+      throw new StoreHostError('SHORT_READ', `${path} shrank during the read (${done} of ${size} bytes)`, { path })
+    }
+    return out
+  } finally {
+    file.close()
+  }
+}
+
+export function readRange (path, offset, length) {
+  if (length === 0) return new Uint8Array(0)
+  const file = openRead(path)
+  try {
+    const out = new Uint8Array(length)
+    const done = readInto(file, out, length, offset, path)
+    if (done !== length) {
+      throw new StoreHostError(
+        'SHORT_READ',
+        `${path} returned ${done} of ${length} bytes at offset ${offset}`,
+        { path }
+      )
+    }
+    return out
+  } finally {
+    file.close()
+  }
+}
+
+/**
+ * Read at most `length` bytes at `offset`. Unlike `readRange` a short read
+ * is NOT an error: it is how the reader learns it reached the end of the
+ * file. The packer streams a file it did not stat first, so it needs this
+ * shape rather than the exact-length one.
+ */
+export function readChunk (path, offset, length) {
+  if (length === 0) return new Uint8Array(0)
+  const file = openRead(path)
+  try {
+    const out = new Uint8Array(length)
+    const done = readInto(file, out, length, offset, path)
+    return done === length ? out : out.subarray(0, done)
+  } finally {
+    file.close()
+  }
+}
+
+/**
+ * Create `path` and write `bytes`. Refuses to replace an existing file:
+ * a generation directory is immutable once written, and a packer that
+ * silently overwrote an artifact would hide a name collision.
+ */
+export function writeNew (path, bytes) {
+  let file
+  try {
+    file = Deno.openSync(path, { write: true, createNew: true })
+  } catch (cause) {
+    if (cause instanceof Deno.errors.AlreadyExists) {
+      throw new StoreHostError('FILE_EXISTS', `${path} already exists`, { path })
+    }
+    throw wrap('OPEN_FAILED', `cannot create ${path}`, path, cause)
+  }
+  try {
+    let done = 0
+    while (done < bytes.length) {
+      let written
+      try {
+        written = file.writeSync(bytes.subarray(done))
+      } catch (cause) {
+        throw wrap('WRITE_FAILED', `write failed on ${path}`, path, cause)
+      }
+      done += written
+    }
+    try {
+      file.syncSync()
+    } catch (cause) {
+      throw wrap('FSYNC_FAILED', `fsync failed on ${path}`, path, cause)
+    }
+  } finally {
+    file.close()
+  }
+}
+
+/** Create a directory and every missing parent. */
+export function makeDirectory (path) {
+  try {
+    Deno.mkdirSync(path, { recursive: true })
+  } catch (cause) {
+    throw wrap('MKDIR_FAILED', `cannot create ${path}`, path, cause)
+  }
+}
+
+export function appendSyncAtSize (path, bytes, expectedSize) {
+  let file
+  try {
+    file = Deno.openSync(path, { write: true, create: true, append: true })
+  } catch (cause) {
+    throw wrap('OPEN_FAILED', `cannot open ${path} for append`, path, cause)
+  }
+  try {
+    const size = file.statSync().size
+    if (size !== expectedSize) return false
+    let done = 0
+    while (done < bytes.length) {
+      let written
+      try {
+        written = file.writeSync(bytes.subarray(done))
+      } catch (cause) {
+        throw wrap('WRITE_FAILED', `append failed on ${path}`, path, cause)
+      }
+      done += written
+    }
+    try {
+      file.syncSync()
+    } catch (cause) {
+      throw wrap('FSYNC_FAILED', `fsync failed on ${path}`, path, cause)
+    }
+    return true
+  } finally {
+    file.close()
+  }
+}
+
+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 handle
+  try {
+    handle = Deno.openSync(directory, { read: true })
+  } catch (cause) {
+    throw wrap('DIR_OPEN_FAILED', `cannot open ${directory} to sync it`, directory, cause)
+  }
+  try {
+    handle.syncSync()
+  } finally {
+    handle.close()
+  }
+}
+
+export function atomicReplace (path, bytes) {
+  const directory = dirName(path)
+  let temporary = null
+  let file = null
+  try {
+    for (let attempt = 0; attempt < 8 && file === null; attempt += 1) {
+      temporary = temporaryName(path)
+      try {
+        file = Deno.openSync(temporary, { write: true, createNew: true })
+      } catch (cause) {
+        if (cause instanceof Deno.errors.AlreadyExists) continue
+        throw wrap('OPEN_FAILED', `cannot create ${temporary}`, temporary, cause)
+      }
+    }
+    if (file === 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 = file.writeSync(bytes.subarray(done))
+      } catch (cause) {
+        throw wrap('WRITE_FAILED', `write failed on ${temporary}`, temporary, cause)
+      }
+      done += written
+    }
+    file.syncSync()
+    file.close()
+    file = null
+    Deno.renameSync(temporary, path)
+    temporary = null
+    try {
+      fsyncDirectory(directory)
+    } catch (_error) {
+      return false
+    }
+    return true
+  } catch (error) {
+    if (file !== null) file.close()
+    if (temporary !== null) {
+      try { Deno.removeSync(temporary) } catch (_ignored) { /* the temporary may not exist */ }
+    }
+    throw error
+  }
+}
+
+export function listGeneration (directory) {
+  const out = []
+  let entries
+  try {
+    entries = [...Deno.readDirSync(directory)]
+  } catch (cause) {
+    throw wrap('DIR_READ_FAILED', `cannot list ${directory}`, directory, cause)
+  }
+  entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+  for (const entry of entries) {
+    if (!entry.isFile) continue
+    let info
+    try {
+      info = Deno.statSync(joinPath(directory, entry.name))
+    } catch (_cause) {
+      continue
+    }
+    out.push({ name: entry.name, size: info.size })
+  }
+  return out
+}

package/store-host/errors.mjs

@@ -0,0 +1,55 @@
+// Error type shared by the Node and Deno host-I/O implementations.
+//
+// The store host moves bytes. It never reports a FORMAT decision, so no
+// error code here names a manifest, a digest, a block or a generation
+// layout: those decisions belong to the Lean source
+// (https://github.com/danbri/factoidal/issues/641, iron rule 7).
+
+export class StoreHostError extends Error {
+  /**
+   * @param {string} code   stable machine-readable code
+   * @param {string} message
+   * @param {{cause?: unknown, path?: string}} [detail]
+   */
+  constructor (code, message, detail = {}) {
+    super(message, detail.cause === undefined ? undefined : { cause: detail.cause })
+    this.name = 'StoreHostError'
+    this.code = code
+    if (detail.path !== undefined) this.path = detail.path
+  }
+}
+
+/** Reject an argument that is not a usable filesystem path. */
+export function requirePath (value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new StoreHostError('BAD_ARGUMENT', `${label} must be a non-empty string`)
+  }
+  if (value.indexOf('\u0000') >= 0) {
+    throw new StoreHostError('BAD_ARGUMENT', `${label} must not contain a NUL byte`)
+  }
+  return value
+}
+
+/**
+ * Reject an offset or length that a 64-bit host accepts and JavaScript
+ * cannot represent exactly. The C extern refuses `offset > INT64_MAX`;
+ * a JavaScript number stops being exact at 2^53 - 1, so that is the
+ * limit this module enforces.
+ */
+export function requireCount (value, label) {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+    throw new StoreHostError(
+      'BAD_ARGUMENT',
+      `${label} must be a non-negative integer below 2^53`
+    )
+  }
+  return value
+}
+
+/** Reject a payload that is not raw bytes. */
+export function requireBytes (value, label) {
+  if (!(value instanceof Uint8Array)) {
+    throw new StoreHostError('BAD_ARGUMENT', `${label} must be a Uint8Array`)
+  }
+  return value
+}