@4fu/arbor-journal-sqlite 0.0.0-stage → 2026.1106.0

package/stored.js

@@ -0,0 +1,57 @@
+/**
+ * Reading refs back out of storage.
+ *
+ * The journal stores refs as text. A ref that does not match the vocabulary in
+ * docs/journal.md#refs means the database was written by something else, so
+ * reading it fails in the core's error shape instead of handing a caller a
+ * string that is not a ref.
+ */
+import { arborError } from "@4fu/arbor-errors";
+const PATTERNS = [
+    /^r\d+$/, // an event
+    /^c\d+$/, // a window
+    /^n\d+(@\d+)?$/, // a note, or one of its revisions
+    /^t\d+$/, // a task
+    /^m\d+$/, // a message between windows
+    /^ws\d+$/, // a workspace
+    /^e\d+$/, // an environment revision
+    /^(sk|mcp|svc):[^\s@]+@\d+$/, // a skill, an MCP server or a service
+    /^b\d+$/, // media stored beside the journal
+    /^[^\s:]+:[^\s]+$/, // an outside message, by its native id
+];
+function malformed(kind, value) {
+    throw arborError({
+        code: "internal",
+        rule: "journal.storage.ref",
+        message: `journal: stored ${kind} ${value} is not a ref`,
+        nextAction: "the journal database was written by another build; rebuild it",
+        details: { kind, value },
+    });
+}
+/** Any ref. */
+export function storedRef(value) {
+    for (const pattern of PATTERNS) {
+        if (pattern.test(value))
+            return value;
+    }
+    return malformed("ref", value);
+}
+export function storedWindowRef(value) {
+    if (value === null)
+        return null;
+    if (!/^c\d+$/.test(value))
+        return malformed("window ref", value);
+    return value;
+}
+export function storedBlobRef(value) {
+    if (!/^b\d+$/.test(value))
+        return malformed("blob ref", value);
+    return value;
+}
+export function storedExternalRef(value) {
+    if (value === null)
+        return null;
+    if (!/^[^\s:]+:[^\s]+$/.test(value))
+        return malformed("external ref", value);
+    return value;
+}