@factoidal/core 0.3.0 → 0.5.0

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

@@ -79,6 +79,69 @@ export function readRange (path, offset, length) {
   }
 }
 
+/**
+ * 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 {

package/store-host/index.mjs

@@ -105,6 +105,45 @@ export function readRange (path, offset, length) {
   return impl.readRange(path, offset, length)
 }
 
+/**
+ * Read at most `length` bytes starting at `offset`. A short read is not an
+ * error: fewer bytes than asked for means the file ended there, and zero
+ * bytes means the offset is at or past the end. This is the shape a
+ * streaming reader needs; `readRange` is the exact-length shape the store
+ * uses when the manifest already committed a length.
+ * @param {string} path
+ * @param {number} offset
+ * @param {number} length
+ * @returns {Uint8Array} between 0 and `length` bytes
+ */
+export function readChunk (path, offset, length) {
+  requirePath(path, 'path')
+  requireCount(offset, 'offset')
+  requireCount(length, 'length')
+  return impl.readChunk(path, offset, length)
+}
+
+/**
+ * Create `path`, write `bytes` and fsync. Refuses an existing file with
+ * code FILE_EXISTS: a generation directory is immutable once written, so
+ * a silent overwrite would hide a name collision rather than report it.
+ * @param {string} path
+ * @param {Uint8Array} bytes
+ */
+export function writeNew (path, bytes) {
+  requirePath(path, 'path')
+  impl.writeNew(path, bytes)
+}
+
+/**
+ * Create a directory and every missing parent.
+ * @param {string} path
+ */
+export function makeDirectory (path) {
+  requirePath(path, 'path')
+  impl.makeDirectory(path)
+}
+
 /**
  * Append `bytes` only if the file currently has exactly `expectedSize`
  * bytes, then fsync it. The counterpart of

package/store-host/node.mjs

@@ -6,7 +6,7 @@
 // moves bytes, and syncs.
 
 import {
-  closeSync, fstatSync, fsyncSync, openSync, readSync, readdirSync,
+  closeSync, fstatSync, fsyncSync, mkdirSync, openSync, readSync, readdirSync,
   renameSync, statSync, unlinkSync, writeSync
 } from 'node:fs'
 
@@ -85,6 +85,67 @@ export function readRange (path, offset, length) {
   }
 }
 
+/**
+ * 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 fd = openRead(path)
+  try {
+    const out = new Uint8Array(length)
+    const done = preadInto(fd, out, 0, length, offset, path)
+    return done === length ? out : out.subarray(0, done)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * 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 fd
+  try {
+    // 'wx' is O_WRONLY | O_CREAT | O_EXCL.
+    fd = openSync(path, 'wx')
+  } catch (cause) {
+    if (cause && cause.code === 'EEXIST') {
+      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 = writeSync(fd, bytes, done, bytes.length - done, null)
+      } catch (cause) {
+        if (isInterrupt(cause)) continue
+        throw wrap('WRITE_FAILED', `write failed on ${path}`, path, cause)
+      }
+      done += written
+    }
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Create a directory and every missing parent. */
+export function makeDirectory (path) {
+  try {
+    mkdirSync(path, { recursive: true })
+  } catch (cause) {
+    throw wrap('MKDIR_FAILED', `cannot create ${path}`, path, cause)
+  }
+}
+
 export function appendSyncAtSize (path, bytes, expectedSize) {
   let fd
   try {

package/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.0",
+  "version": "0.5.0",
   "gitSha": "49f8ca4d70bf57c12fea445611e2b01b067bf6ba",
   "builtAt": "2026-08-26T21:45:40Z",
   "claims": {