@opendatalabs/personal-server-ts-stream-sync 0.0.0-stage → 0.0.1-canary.14eb2b2

package/dist/eligible.js

@@ -0,0 +1,60 @@
+/**
+ * §2.10 the one eligibility predicate, used by reads, consent readiness and
+ * memory totals.
+ *
+ * For connector c and a requested name:
+ *   1. If every stream the name needs is live and `complete` in the selected
+ *      connection → serve the stream view. A legacy file is never compared
+ *      with a complete view (one-way).
+ *   2. Else, if any connection of c is deleted and not since reconnected →
+ *      `unavailable` (no legacy or raw fallback).
+ *   3. Else, if a legacy or raw file of that name exists → serve it.
+ *   4. Else `unavailable`.
+ *
+ * Selected connection: live (control `active`, so never `foreign`) with the
+ * most recently registered heads. A physical name selects its own connection.
+ */
+import { InvalidArgumentError } from "./errors.js";
+import { hasOwn } from "./json.js";
+function rank(a, b) {
+    const ra = a.latestHeadRegistration ?? -Infinity;
+    const rb = b.latestHeadRegistration ?? -Infinity;
+    if (ra !== rb)
+        return rb > ra ? 1 : -1;
+    // Tie: lowest ns (DESIGN-QUESTIONS.md Q6).
+    return a.ns < b.ns ? -1 : a.ns > b.ns ? 1 : 0;
+}
+/** The connection a plain (logical) name of the connector reads. */
+export function selectConnection(connections) {
+    const live = connections.filter((c) => c.control.kind === "active");
+    return live.length === 0 ? null : [...live].sort(rank)[0];
+}
+export function eligible(input) {
+    const { connections, target } = input;
+    if (target.streams.length === 0) {
+        throw new InvalidArgumentError("a read target needs at least one stream");
+    }
+    const selected = target.kind === "physical"
+        ? (connections.find((c) => c.ns === target.ns && c.control.kind === "active") ?? null)
+        : selectConnection(connections);
+    if (selected &&
+        target.streams.every((s) => {
+            if (!hasOwn(selected.streams, s))
+                return false;
+            const head = selected.streams[s];
+            return head.live && head.complete;
+        })) {
+        return { kind: "view", ns: selected.ns };
+    }
+    if (connections.some((c) => c.control.kind === "deleted")) {
+        return { kind: "unavailable", reason: "deleted" };
+    }
+    if (input.legacyFile)
+        return { kind: "legacy" };
+    return { kind: "unavailable", reason: "no_data" };
+}
+/** Readiness is exactly "a read would not be `unavailable`". */
+export function isReady(input) {
+    return eligible(input).kind !== "unavailable";
+}
+//# sourceMappingURL=eligible.js.map

package/dist/eligible.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligible.js","sourceRoot":"","sources":["../src/eligible.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Typed failures. Every error carries a stable `code` so callers in another
+ * bundle can switch on it without `instanceof`.
+ *
+ * Errors are for inputs a caller must never pass (a malformed name, a value
+ * outside JSON). Expected outcomes of the protocol (`key_mismatch`,
+ * `record_too_large`, `unsupported_format`, ...) are returned as values.
+ */
+export type StreamSyncErrorCode = "non-canonical-value" | "invalid-name" | "invalid-record" | "missing-key-field" | "invalid-line" | "invalid-part" | "invalid-argument";
+export declare class StreamSyncError extends Error {
+    readonly code: StreamSyncErrorCode;
+    constructor(code: StreamSyncErrorCode, message: string);
+}
+/** A value outside the JSON model (undefined, NaN, Date, cycles, ...). */
+export declare class NonCanonicalValueError extends StreamSyncError {
+    constructor(message: string);
+}
+/** A name cannot be built: a permanent error, never retried. */
+export declare class InvalidNameError extends StreamSyncError {
+    constructor(message: string);
+}
+export declare class InvalidRecordError extends StreamSyncError {
+    constructor(message: string);
+}
+/** A record has no own property for one of the primary-key fields. */
+export declare class MissingKeyFieldError extends StreamSyncError {
+    readonly field: string;
+    constructor(field: string);
+}
+/** A part line is not `{"o":<ms>,"r":"<runId>","v":<record>}` in canonical form. */
+export declare class InvalidLineError extends StreamSyncError {
+    constructor(message: string);
+}
+/** Part bytes do not match their head entry, or break the part grammar. */
+export declare class InvalidPartError extends StreamSyncError {
+    constructor(message: string);
+}
+export declare class InvalidArgumentError extends StreamSyncError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GACnB,cAAc,GACd,cAAc,GACd,kBAAkB,CAAC;AAEvB,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM;CAKvD;AAED,0EAA0E;AAC1E,qBAAa,sBAAuB,SAAQ,eAAe;gBAC7C,OAAO,EAAE,MAAM;CAG5B;AAED,gEAAgE;AAChE,qBAAa,gBAAiB,SAAQ,eAAe;gBACvC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,kBAAmB,SAAQ,eAAe;gBACzC,OAAO,EAAE,MAAM;CAG5B;AAED,sEAAsE;AACtE,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM;CAI1B;AAED,oFAAoF;AACpF,qBAAa,gBAAiB,SAAQ,eAAe;gBACvC,OAAO,EAAE,MAAM;CAG5B;AAED,2EAA2E;AAC3E,qBAAa,gBAAiB,SAAQ,eAAe;gBACvC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,oBAAqB,SAAQ,eAAe;gBAC3C,OAAO,EAAE,MAAM;CAG5B"}

package/dist/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Typed failures. Every error carries a stable `code` so callers in another
+ * bundle can switch on it without `instanceof`.
+ *
+ * Errors are for inputs a caller must never pass (a malformed name, a value
+ * outside JSON). Expected outcomes of the protocol (`key_mismatch`,
+ * `record_too_large`, `unsupported_format`, ...) are returned as values.
+ */
+export class StreamSyncError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+/** A value outside the JSON model (undefined, NaN, Date, cycles, ...). */
+export class NonCanonicalValueError extends StreamSyncError {
+    constructor(message) {
+        super("non-canonical-value", message);
+    }
+}
+/** A name cannot be built: a permanent error, never retried. */
+export class InvalidNameError extends StreamSyncError {
+    constructor(message) {
+        super("invalid-name", message);
+    }
+}
+export class InvalidRecordError extends StreamSyncError {
+    constructor(message) {
+        super("invalid-record", message);
+    }
+}
+/** A record has no own property for one of the primary-key fields. */
+export class MissingKeyFieldError extends StreamSyncError {
+    field;
+    constructor(field) {
+        super("missing-key-field", `record has no value for key field "${field}"`);
+        this.field = field;
+    }
+}
+/** A part line is not `{"o":<ms>,"r":"<runId>","v":<record>}` in canonical form. */
+export class InvalidLineError extends StreamSyncError {
+    constructor(message) {
+        super("invalid-line", message);
+    }
+}
+/** Part bytes do not match their head entry, or break the part grammar. */
+export class InvalidPartError extends StreamSyncError {
+    constructor(message) {
+        super("invalid-part", message);
+    }
+}
+export class InvalidArgumentError extends StreamSyncError {
+    constructor(message) {
+        super("invalid-argument", message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAsB;IAEnC,YAAY,IAAyB,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACzD,YAAY,OAAe;QACzB,KAAK,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,eAAe;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IAC9C,KAAK,CAAS;IAEvB,YAAY,KAAa;QACvB,KAAK,CAAC,mBAAmB,EAAE,sCAAsC,KAAK,GAAG,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,oFAAoF;AACpF,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IACvD,YAAY,OAAe;QACzB,KAAK,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/head.d.ts

@@ -0,0 +1,160 @@
+/**
+ * §2.5 head format 1, and the head rules of §2.4, §2.5, §2.6 and §2.7:
+ * liveness, base choice, the compatible-writer rule, `complete` and no-op.
+ *
+ * Clear head bytes are canonical JSON:
+ *
+ *   {"complete":bool,"connector":c,"format":1,"generation":"<dec>",
+ *    "keyCheck":"<16 hex>","ns":ns,"observedAt":<ms>,
+ *    "parts":[{"bytes":n,"count":n,"hash":"<sha256>","prefix":"<bits>"}],
+ *    "primaryKey":[...],"profile":{"key":<string|null>,"version":"<v>"},
+ *    "recordCount":n,"stream":s}
+ *
+ * The registry `dataHash` of a head is Keccak-256 of these bytes; its blob
+ * name is `h-<that hash in hex>`.
+ */
+import { type Keccak256 } from "./bytes.js";
+import type { HeadPart } from "./parts.js";
+import type { ControlState } from "./control.js";
+export declare const HEAD_FORMAT = 1;
+export interface HeadProfile {
+    /** The legacy projector's profile key, or `null`. */
+    readonly key: string | null;
+    /** The connector version that wrote the head. */
+    readonly version: string;
+}
+export interface Head {
+    readonly complete: boolean;
+    readonly connector: string;
+    readonly format: 1;
+    /** Positive integer; written as a decimal string. */
+    readonly generation: number;
+    readonly keyCheck: string;
+    readonly ns: string;
+    readonly observedAt: number;
+    readonly parts: readonly HeadPart[];
+    readonly primaryKey: readonly string[];
+    readonly profile: HeadProfile;
+    readonly recordCount: number;
+    readonly stream: string;
+}
+/** Canonical clear head bytes. Throws on a head this package would reject. */
+export declare function encodeHead(head: Head): Uint8Array;
+export interface HeadDigest {
+    /** Registry form: `0x` + 64 lowercase hex. */
+    readonly dataHash: `0x${string}`;
+    /** `h-<hex>`. */
+    readonly blobName: string;
+}
+export declare function digestHead(keccak256: Keccak256, bytes: Uint8Array): Promise<HeadDigest>;
+export type DecodedHead = {
+    readonly kind: "ok";
+    readonly head: Head;
+} | {
+    readonly kind: "unsupported_format";
+    readonly format: unknown;
+} | {
+    readonly kind: "malformed";
+    readonly reason: string;
+};
+/**
+ * Parse clear head bytes. Any `format` other than 1 is `unsupported_format`.
+ * A format-1 head must be canonical, so every host derives the same hash.
+ */
+export declare function decodeHead(bytes: Uint8Array): DecodedHead;
+export type VerifiedHead = {
+    readonly kind: "ok";
+    readonly head: Head;
+} | {
+    readonly kind: "hash_mismatch";
+} | {
+    readonly kind: "unsupported_format";
+    readonly format: unknown;
+} | {
+    readonly kind: "malformed";
+    readonly reason: string;
+} | {
+    readonly kind: "name_mismatch";
+} | {
+    readonly kind: "key_mismatch";
+};
+/**
+ * §2.5 reader checks on decrypted head bytes: `keccak = dataHash`, format,
+ * shape, name fields against the scope, and `keyCheck`. Part SHA-256 is
+ * checked per part by `decodePart`.
+ */
+export declare function verifyHead(keccak256: Keccak256, bytes: Uint8Array, expected: {
+    readonly dataHash: string;
+    readonly connector: string;
+    readonly ns: string;
+    readonly stream: string;
+    readonly keyCheck: string;
+}): Promise<VerifiedHead>;
+/** The stream row as read from the registry. */
+export type StreamRow = "absent" | "tombstoned" | "present";
+/**
+ * §2.4: a stream head is live iff the control is `active(g)`, the stream row
+ * is not tombstoned, and the head's generation is g.
+ */
+export declare function isHeadLive(control: ControlState, streamRow: StreamRow, headGeneration: number | null): boolean;
+export type BaseChoice = 
+/** The stream row's head is of the target generation: merge onto it. */
+{
+    readonly kind: "base";
+    readonly head: Head;
+}
+/** Row absent or tombstoned, or its head is older: fresh generation. */
+ | {
+    readonly kind: "empty";
+}
+/**
+ * The row's head is of a NEWER generation than the target: the run's start
+ * snapshot is older than the registry. Do not publish; re-read control and
+ * decide with phase `stale_base` (P0-RULINGS F1).
+ */
+ | {
+    readonly kind: "stale_generation";
+};
+/**
+ * §2.7 with ruling F1: three outcomes, never two.
+ *
+ * - row absent or tombstoned, or `head.generation < target` → `empty`
+ * - `head.generation == target` → `base`
+ * - `head.generation > target` → `stale_generation`
+ *
+ * A present row needs its verified head: a host that cannot read the head of
+ * a present row must not call this (it would take an empty base over data).
+ */
+export declare function chooseBase(streamRow: StreamRow, head: Head | null, target: number): BaseChoice;
+export type VersionOrder = "higher" | "equal" | "lower";
+export type WriterCompatibility = 
+/** Same primary key: merge onto the base. */
+{
+    readonly kind: "use_base";
+}
+/** Newer connector changed the primary key: empty base, base complete false. */
+ | {
+    readonly kind: "empty_base";
+}
+/** Older (or same-version) connector meets a changed key: do not publish. */
+ | {
+    readonly kind: "connector_update_required";
+};
+/**
+ * §2.5 compatible-writer rule. `writerVersusBase` is the host's comparison
+ * of the writer's connector version with `base.profile.version`.
+ */
+export declare function writerCompatibility(base: Head | null, writerPrimaryKey: readonly string[], writerVersusBase: VersionOrder): WriterCompatibility;
+/**
+ * §2.5: `complete` = run `full` OR base `complete` OR seed merged (a host merged its retained history).
+ * An empty base (none, tombstoned, other generation, or replaced by
+ * `empty_base`) counts as not complete.
+ */
+export declare function headComplete(input: {
+    readonly full: boolean;
+    readonly baseComplete: boolean;
+    readonly seedMerged: boolean;
+}): boolean;
+/** §2.6: every part and `complete` unchanged against the base → skip upload and POST. */
+export declare function isNoop(base: Head | null, parts: readonly HeadPart[], complete: boolean): boolean;
+//# sourceMappingURL=head.d.ts.map

package/dist/head.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"head.d.ts","sourceRoot":"","sources":["../src/head.ts"],"names":[],"mappings":"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"}

package/dist/head.js

@@ -0,0 +1,315 @@
+/**
+ * §2.5 head format 1, and the head rules of §2.4, §2.5, §2.6 and §2.7:
+ * liveness, base choice, the compatible-writer rule, `complete` and no-op.
+ *
+ * Clear head bytes are canonical JSON:
+ *
+ *   {"complete":bool,"connector":c,"format":1,"generation":"<dec>",
+ *    "keyCheck":"<16 hex>","ns":ns,"observedAt":<ms>,
+ *    "parts":[{"bytes":n,"count":n,"hash":"<sha256>","prefix":"<bits>"}],
+ *    "primaryKey":[...],"profile":{"key":<string|null>,"version":"<v>"},
+ *    "recordCount":n,"stream":s}
+ *
+ * The registry `dataHash` of a head is Keccak-256 of these bytes; its blob
+ * name is `h-<that hash in hex>`.
+ */
+import { HEAD_LIMIT_BYTES, HEX16, HEX64, PART_LIMIT_BYTES, PLANNER_DEPTH_CAP, keccakHex, utf8, } from "./bytes.js";
+import { InvalidArgumentError } from "./errors.js";
+import { canonicalJson, hasOwn, isPlainObject } from "./json.js";
+import { headBlobName } from "./names.js";
+export const HEAD_FORMAT = 1;
+const HEAD_FIELDS = [
+    "complete",
+    "connector",
+    "format",
+    "generation",
+    "keyCheck",
+    "ns",
+    "observedAt",
+    "parts",
+    "primaryKey",
+    "profile",
+    "recordCount",
+    "stream",
+];
+const PART_FIELDS = ["bytes", "count", "hash", "prefix"];
+const PROFILE_FIELDS = ["key", "version"];
+const GENERATION = /^[1-9][0-9]*$/;
+function exactKeys(value, expected) {
+    const keys = Object.keys(value).sort();
+    return (keys.length === expected.length && keys.every((k, i) => k === expected[i]));
+}
+function isCount(value, min) {
+    return (typeof value === "number" && Number.isSafeInteger(value) && value >= min);
+}
+/** Why a head is malformed, or `null` when it is a valid format-1 head. */
+function headProblem(value) {
+    if (!exactKeys(value, HEAD_FIELDS)) {
+        return `fields must be exactly: ${HEAD_FIELDS.join(", ")}`;
+    }
+    const v = value;
+    if (typeof v["complete"] !== "boolean")
+        return "complete must be a boolean";
+    const connector = v["connector"];
+    if (typeof connector !== "string" ||
+        connector === "" ||
+        connector.includes("~")) {
+        return "connector must be non-empty with no ~";
+    }
+    const generation = v["generation"];
+    if (typeof generation !== "string" ||
+        !GENERATION.test(generation) ||
+        !Number.isSafeInteger(Number(generation))) {
+        return "generation must be a positive decimal string";
+    }
+    if (typeof v["keyCheck"] !== "string" || !HEX16.test(v["keyCheck"])) {
+        return "keyCheck must be 16 lowercase hex";
+    }
+    const ns = v["ns"];
+    if (typeof ns !== "string" || (ns !== "" && !HEX16.test(ns))) {
+        return "ns must be empty or 16 lowercase hex";
+    }
+    if (!isCount(v["observedAt"], 0))
+        return "observedAt must be a non-negative integer";
+    if (typeof v["stream"] !== "string" || v["stream"] === "") {
+        return "stream must be a non-empty string";
+    }
+    const primaryKey = v["primaryKey"];
+    if (!Array.isArray(primaryKey) ||
+        primaryKey.length === 0 ||
+        primaryKey.some((f) => typeof f !== "string" || f === "") ||
+        new Set(primaryKey).size !== primaryKey.length) {
+        return "primaryKey must be a non-empty list of distinct non-empty strings";
+    }
+    const profile = v["profile"];
+    if (!isPlainObject(profile) ||
+        !exactKeys(profile, PROFILE_FIELDS) ||
+        (profile["key"] !== null && typeof profile["key"] !== "string") ||
+        typeof profile["version"] !== "string" ||
+        profile["version"] === "") {
+        return "profile must be {key: string|null, version: non-empty string}";
+    }
+    if (!isCount(v["recordCount"], 0))
+        return "recordCount must be a non-negative integer";
+    const parts = v["parts"];
+    if (!Array.isArray(parts))
+        return "parts must be an array";
+    let total = 0;
+    let previous = null;
+    for (let i = 0; i < parts.length; i += 1) {
+        const part = parts[i];
+        if (!isPlainObject(part) || !exactKeys(part, PART_FIELDS)) {
+            return `part ${i} must have exactly ${PART_FIELDS.join(", ")}`;
+        }
+        const { bytes, count, hash, prefix } = part;
+        if (!isCount(count, 1))
+            return `part ${i} count must be a positive integer`;
+        if (!isCount(bytes, 1) || bytes > PART_LIMIT_BYTES) {
+            return `part ${i} bytes must be in [1, ${PART_LIMIT_BYTES}]`;
+        }
+        if (typeof hash !== "string" || !HEX64.test(hash)) {
+            return `part ${i} hash must be 64 lowercase hex`;
+        }
+        if (typeof prefix !== "string" ||
+            !/^[01]*$/.test(prefix) ||
+            prefix.length > PLANNER_DEPTH_CAP) {
+            return `part ${i} prefix must be at most 16 bits of 0 and 1`;
+        }
+        if (previous !== null) {
+            if (prefix <= previous)
+                return "parts must be sorted by prefix";
+            if (prefix.startsWith(previous))
+                return "part prefixes must be prefix-free";
+        }
+        previous = prefix;
+        total += count;
+    }
+    if (total !== v["recordCount"])
+        return "recordCount must equal the sum of part counts";
+    return null;
+}
+function toWire(head) {
+    return {
+        complete: head.complete,
+        connector: head.connector,
+        format: head.format,
+        generation: String(head.generation),
+        keyCheck: head.keyCheck,
+        ns: head.ns,
+        observedAt: head.observedAt,
+        parts: head.parts.map((p) => ({
+            bytes: p.bytes,
+            count: p.count,
+            hash: p.hash,
+            prefix: p.prefix,
+        })),
+        primaryKey: [...head.primaryKey],
+        profile: { key: head.profile.key, version: head.profile.version },
+        recordCount: head.recordCount,
+        stream: head.stream,
+    };
+}
+/** Canonical clear head bytes. Throws on a head this package would reject. */
+export function encodeHead(head) {
+    if (head.format !== HEAD_FORMAT) {
+        throw new InvalidArgumentError("only format 1 heads can be written");
+    }
+    if (!Number.isSafeInteger(head.generation) || head.generation < 1) {
+        throw new InvalidArgumentError("generation must be a positive safe integer");
+    }
+    const wire = toWire(head);
+    const problem = headProblem(wire);
+    if (problem)
+        throw new InvalidArgumentError(`invalid head: ${problem}`);
+    const bytes = utf8(canonicalJson(wire));
+    if (bytes.length > HEAD_LIMIT_BYTES) {
+        throw new InvalidArgumentError("head exceeds the 1 MiB head limit");
+    }
+    return bytes;
+}
+export async function digestHead(keccak256, bytes) {
+    const dataHash = await keccakHex(keccak256, bytes);
+    return { dataHash, blobName: headBlobName(dataHash) };
+}
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+ * Parse clear head bytes. Any `format` other than 1 is `unsupported_format`.
+ * A format-1 head must be canonical, so every host derives the same hash.
+ */
+export function decodeHead(bytes) {
+    if (bytes.length > HEAD_LIMIT_BYTES) {
+        return {
+            kind: "malformed",
+            reason: "head exceeds the 1 MiB decoder limit",
+        };
+    }
+    let text;
+    let parsed;
+    try {
+        text = decoder.decode(bytes);
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { kind: "malformed", reason: "head is not UTF-8 JSON" };
+    }
+    if (!isPlainObject(parsed))
+        return { kind: "malformed", reason: "head is not an object" };
+    const format = hasOwn(parsed, "format") ? parsed["format"] : undefined;
+    if (format !== HEAD_FORMAT)
+        return { kind: "unsupported_format", format };
+    const problem = headProblem(parsed);
+    if (problem)
+        return { kind: "malformed", reason: problem };
+    if (canonicalJson(parsed) !== text) {
+        return { kind: "malformed", reason: "head is not canonical JSON" };
+    }
+    const p = parsed;
+    return {
+        kind: "ok",
+        head: {
+            complete: p["complete"],
+            connector: p["connector"],
+            format: HEAD_FORMAT,
+            generation: Number(p["generation"]),
+            keyCheck: p["keyCheck"],
+            ns: p["ns"],
+            observedAt: p["observedAt"],
+            parts: p.parts,
+            primaryKey: p["primaryKey"],
+            profile: p.profile,
+            recordCount: p["recordCount"],
+            stream: p["stream"],
+        },
+    };
+}
+/**
+ * §2.5 reader checks on decrypted head bytes: `keccak = dataHash`, format,
+ * shape, name fields against the scope, and `keyCheck`. Part SHA-256 is
+ * checked per part by `decodePart`.
+ */
+export async function verifyHead(keccak256, bytes, expected) {
+    const dataHash = await keccakHex(keccak256, bytes);
+    if (dataHash !== expected.dataHash.toLowerCase())
+        return { kind: "hash_mismatch" };
+    const decoded = decodeHead(bytes);
+    if (decoded.kind !== "ok")
+        return decoded;
+    const { head } = decoded;
+    if (head.connector !== expected.connector ||
+        head.ns !== expected.ns ||
+        head.stream !== expected.stream) {
+        return { kind: "name_mismatch" };
+    }
+    if (head.keyCheck !== expected.keyCheck)
+        return { kind: "key_mismatch" };
+    return decoded;
+}
+/**
+ * §2.4: a stream head is live iff the control is `active(g)`, the stream row
+ * is not tombstoned, and the head's generation is g.
+ */
+export function isHeadLive(control, streamRow, headGeneration) {
+    return (control.kind === "active" &&
+        streamRow === "present" &&
+        headGeneration === control.generation);
+}
+/**
+ * §2.7 with ruling F1: three outcomes, never two.
+ *
+ * - row absent or tombstoned, or `head.generation < target` → `empty`
+ * - `head.generation == target` → `base`
+ * - `head.generation > target` → `stale_generation`
+ *
+ * A present row needs its verified head: a host that cannot read the head of
+ * a present row must not call this (it would take an empty base over data).
+ */
+export function chooseBase(streamRow, head, target) {
+    if (streamRow !== "present")
+        return { kind: "empty" };
+    if (head === null) {
+        throw new InvalidArgumentError("a present stream row needs its verified head");
+    }
+    if (head.generation < target)
+        return { kind: "empty" };
+    if (head.generation === target)
+        return { kind: "base", head };
+    return { kind: "stale_generation" };
+}
+/**
+ * §2.5 compatible-writer rule. `writerVersusBase` is the host's comparison
+ * of the writer's connector version with `base.profile.version`.
+ */
+export function writerCompatibility(base, writerPrimaryKey, writerVersusBase) {
+    if (base === null)
+        return { kind: "use_base" };
+    const same = base.primaryKey.length === writerPrimaryKey.length &&
+        base.primaryKey.every((field, i) => field === writerPrimaryKey[i]);
+    if (same)
+        return { kind: "use_base" };
+    return writerVersusBase === "higher"
+        ? { kind: "empty_base" }
+        : { kind: "connector_update_required" };
+}
+/**
+ * §2.5: `complete` = run `full` OR base `complete` OR seed merged (a host merged its retained history).
+ * An empty base (none, tombstoned, other generation, or replaced by
+ * `empty_base`) counts as not complete.
+ */
+export function headComplete(input) {
+    return input.full || input.baseComplete || input.seedMerged;
+}
+/** §2.6: every part and `complete` unchanged against the base → skip upload and POST. */
+export function isNoop(base, parts, complete) {
+    if (base === null || base.complete !== complete)
+        return false;
+    if (base.parts.length !== parts.length)
+        return false;
+    return base.parts.every((p, i) => {
+        const q = parts[i];
+        return (p.prefix === q.prefix &&
+            p.hash === q.hash &&
+            p.bytes === q.bytes &&
+            p.count === q.count);
+    });
+}
+//# sourceMappingURL=head.js.map