@superbee/core 0.1.0

package/dist/version-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-transport.js","sourceRoot":"","sources":["../src/version-transport.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAIhG,oEAAoE;AACpE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACtB,IAAI,GAAG,iBAAiB,CAAC;IAClC,EAAE,CAAS;IACX,QAAQ,CAAiB;IACzB,MAAM,CAAiB;IAEhC,YAAY,EAAU,EAAE,QAAwB,EAAE,MAAsB;QACtE,KAAK,CACH,wBAAwB,EAAE,eAAe,QAAQ,IAAI,QAAQ,WAAW,MAAM,IAAI,MAAM,GAAG;YACzF,8DAA8D,CACjE,CAAC;QACF,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/versioning.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Versioning + attribution primitives shared by every {@link StorageBackend}.
+ *
+ * These make the seam's "hardest case" (content-addressed versions, compare-and-swap
+ * writes, actor attribution) implementable uniformly across adapters:
+ *   - {@link contentVersion} defines the opaque {@link Version} token as a SHA-256 over
+ *     the canonically serialized document, so identical content yields the same token
+ *     REGARDLESS of backend. The filesystem adapter hashes the on-disk bytes; the
+ *     in-memory adapter hashes the same serialization — an engine-written document
+ *     therefore carries the same version token in either store.
+ *   - {@link blobVersion} is the SAME idea for opaque blob bytes, but hashes the raw
+ *     `Uint8Array` directly with no string/UTF-8 step — a doc-shaped hash would corrupt
+ *     binary content, so blobs get their own primitive rather than reusing `contentVersion`
+ *     or `versionOfBytes`.
+ *   - {@link defaultActor} supplies a local identity when a write is unattributed.
+ *   - {@link VersionConflict} is the typed error a compare-and-swap write throws when
+ *     the caller's `expectedVersion` no longer matches the backend's current version.
+ *
+ * Nothing here touches the filesystem — hashing and attribution are backend-neutral,
+ * which is precisely why the memory adapter can reuse them.
+ */
+import type { OkfDocument, Version } from "./types.js";
+export { VersionConflict, stripETagWrapper } from "./version-transport.js";
+/** Lowercase hex SHA-256 of a UTF-8 string. The version tokens' underlying digest. */
+export declare function sha256Hex(input: string): string;
+/**
+ * The content-addressed {@link Version} of a concept document: the SHA-256 of its
+ * OKF-serialized bytes (`sha256:<hex>`). Deterministic and backend-independent — two
+ * backends holding byte-identical serializations report the same version.
+ */
+export declare function contentVersion(doc: OkfDocument): Version;
+/** The version of already-serialized document bytes (the filesystem adapter's on-disk form). */
+export declare function versionOfBytes(raw: string): Version;
+/**
+ * The content-addressed {@link Version} of raw blob bytes: the SHA-256 of `bytes`
+ * directly, with NO string/UTF-8 encoding step. This is deliberately a SEPARATE
+ * primitive from {@link contentVersion} (doc-shaped, serializes frontmatter+body first)
+ * and {@link versionOfBytes} (hashes a STRING as UTF-8) — routing binary blob content
+ * through either would corrupt any byte sequence that is not valid UTF-8 (e.g. a lone
+ * continuation byte decodes to U+FFFD before hashing), silently breaking the
+ * byte-identical round-trip a blob promises. Every {@link StorageBackend}'s blob
+ * methods must hash bytes through THIS function so the token is identical regardless
+ * of adapter, exactly as {@link contentVersion} is for documents.
+ */
+export declare function blobVersion(bytes: Uint8Array): Version;
+/** A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`. */
+export declare function defaultActor(): string;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAEtD;AAED,gGAAgG;AAChG,wBAAgB,YAAY,IAAI,MAAM,CAOrC"}

package/dist/versioning.js

@@ -0,0 +1,62 @@
+/**
+ * Versioning + attribution primitives shared by every {@link StorageBackend}.
+ *
+ * These make the seam's "hardest case" (content-addressed versions, compare-and-swap
+ * writes, actor attribution) implementable uniformly across adapters:
+ *   - {@link contentVersion} defines the opaque {@link Version} token as a SHA-256 over
+ *     the canonically serialized document, so identical content yields the same token
+ *     REGARDLESS of backend. The filesystem adapter hashes the on-disk bytes; the
+ *     in-memory adapter hashes the same serialization — an engine-written document
+ *     therefore carries the same version token in either store.
+ *   - {@link blobVersion} is the SAME idea for opaque blob bytes, but hashes the raw
+ *     `Uint8Array` directly with no string/UTF-8 step — a doc-shaped hash would corrupt
+ *     binary content, so blobs get their own primitive rather than reusing `contentVersion`
+ *     or `versionOfBytes`.
+ *   - {@link defaultActor} supplies a local identity when a write is unattributed.
+ *   - {@link VersionConflict} is the typed error a compare-and-swap write throws when
+ *     the caller's `expectedVersion` no longer matches the backend's current version.
+ *
+ * Nothing here touches the filesystem — hashing and attribution are backend-neutral,
+ * which is precisely why the memory adapter can reuse them.
+ */
+import { createHash } from "node:crypto";
+import { stringifyDoc } from "./frontmatter.js";
+export { VersionConflict, stripETagWrapper } from "./version-transport.js";
+/** Lowercase hex SHA-256 of a UTF-8 string. The version tokens' underlying digest. */
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/**
+ * The content-addressed {@link Version} of a concept document: the SHA-256 of its
+ * OKF-serialized bytes (`sha256:<hex>`). Deterministic and backend-independent — two
+ * backends holding byte-identical serializations report the same version.
+ */
+export function contentVersion(doc) {
+    return `sha256:${sha256Hex(stringifyDoc(doc.frontmatter, doc.body ?? ""))}`;
+}
+/** The version of already-serialized document bytes (the filesystem adapter's on-disk form). */
+export function versionOfBytes(raw) {
+    return `sha256:${sha256Hex(raw)}`;
+}
+/**
+ * The content-addressed {@link Version} of raw blob bytes: the SHA-256 of `bytes`
+ * directly, with NO string/UTF-8 encoding step. This is deliberately a SEPARATE
+ * primitive from {@link contentVersion} (doc-shaped, serializes frontmatter+body first)
+ * and {@link versionOfBytes} (hashes a STRING as UTF-8) — routing binary blob content
+ * through either would corrupt any byte sequence that is not valid UTF-8 (e.g. a lone
+ * continuation byte decodes to U+FFFD before hashing), silently breaking the
+ * byte-identical round-trip a blob promises. Every {@link StorageBackend}'s blob
+ * methods must hash bytes through THIS function so the token is identical regardless
+ * of adapter, exactly as {@link contentVersion} is for documents.
+ */
+export function blobVersion(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/** A local identity for unattributed writes: `$USER`/`$USERNAME`/`$LOGNAME`, else `"local"`. */
+export function defaultActor() {
+    return (process.env.USER?.trim() ||
+        process.env.USERNAME?.trim() ||
+        process.env.LOGNAME?.trim() ||
+        "local");
+}
+//# sourceMappingURL=versioning.js.map

package/dist/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3E,sFAAsF;AACtF,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,OAAO,UAAU,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,UAAU,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,YAAY;IAC1B,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE;QACxB,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE;QAC5B,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE;QAC3B,OAAO,CACR,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@superbee/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OKF store engine — bundle I/O, cross-links, derived backlinks, freshness, and versioned writes.",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine.d.ts",
+      "default": "./dist/engine.js"
+    },
+    "./kinds": {
+      "types": "./dist/kinds.d.ts",
+      "default": "./dist/kinds.js"
+    },
+    "./links": {
+      "types": "./dist/links.d.ts",
+      "default": "./dist/links.js"
+    },
+    "./meaningful-change-time": {
+      "types": "./dist/meaningful-change-time.d.ts",
+      "default": "./dist/meaningful-change-time.js"
+    },
+    "./mutation-attribution": {
+      "types": "./dist/mutation-attribution.d.ts",
+      "default": "./dist/mutation-attribution.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "default": "./dist/page.js"
+    },
+    "./publication-filesystem": {
+      "types": "./dist/publication-filesystem.d.ts",
+      "default": "./dist/publication-filesystem.js"
+    },
+    "./query-filter": {
+      "types": "./dist/query-filter.d.ts",
+      "default": "./dist/query-filter.js"
+    },
+    "./query-selection": {
+      "types": "./dist/query-selection.d.ts",
+      "default": "./dist/query-selection.js"
+    },
+    "./remote": {
+      "types": "./dist/remote.d.ts",
+      "default": "./dist/remote.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "default": "./dist/storage.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import ./test/ts-loader.mjs ./test/*.test.ts",
+    "mutation": "stryker run",
+    "prepublishOnly": "node -e \"console.error('@superbee/core is released by .github/workflows/release-libraries.yml; do not run npm publish here'); process.exit(1)\""
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^3.15.2"
+  },
+  "devDependencies": {
+    "@superbee/server": "*",
+    "@types/js-yaml": "3.12.10",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  }
+}