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

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @opendatalabs/personal-server-ts-stream-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The pure core of whole-file stream sync (design revision 4.1, section 2). Every
+host (full server, Lite, and client libraries) builds against this one tested
+package.
+
+The package does no I/O. It imports no SDK, no Node built-ins, no browser APIs,
+no clock and no randomness. Hosts inject SHA-256, Keccak-256 and the namespace
+HMAC, and do every registry, storage and spool call themselves.
+
+This is version 0.0.1 and marked `private`. It is not wired into the release
+workflows.
+
+## Contract
+
+| Area          | Rule                                                                                                                                                                                                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Names         | Stream scope `pdpp.<c>~<ns>.<s>`, control scope `pdpp.<c>~<ns>`. `ns` is 16 lowercase hex, or empty for identity-less connectors. Head blob `h-<keccak hex>`, part blob `g<gen>-p-<sha256 hex>`. Scopes over 256 UTF-8 bytes are a permanent error.                                      |
+| Master key    | `streamMasterKeyFromSignature(signature)` returns the 65-byte owner signature as r, low s and v = 27/28. Every stream-sync key (`K_ns`, head and part keys) derives from it, so every encoding of one signature gives one `ns` and `keyCheck`. Legacy scope keys keep the raw signature. |
+| Namespace     | `ns = hex(first 8 bytes of HMAC-SHA256(K_ns, canonicalJson([c, accountId])))`, `keyCheck = hex(first 8 bytes of HMAC-SHA256(K_ns, "key-check"))`. The host derives `K_ns` with label `pdpp-stream-sync/namespace/v1` and passes an HMAC port bound to it.                                |
+| Control row   | `ACTIVE_DATA = keccak256("pdpp.stream-sync.connection.active.v1:" + keyCheck)`. A read classifies as `absent`, `active(g)`, `deleted(v)` or `foreign` (another key's row).                                                                                                               |
+| Lines, parts  | `pkHash = sha256(canonicalJson([pk values]))`. A part is NDJSON lines `{"o":<run start ms>,"r":"<runId>","v":<record>}` sorted by `pkHash`. A line over 8 MiB is `record_too_large`. Parts ≤ 16 MiB, heads ≤ 1 MiB.                                                                      |
+| Merge         | Greatest `(o, r)` wins per key; on equal `(o, r)` the later line wins. Feed base lines, then run lines. Seed lines have `o = 0`, `r = "seed"`. The reducer keeps one line per key.                                                                                                       |
+| Planner       | 256 spool shards by first `pkHash` byte. Split a bucket over the target by the next bit, never deeper than 16 bits. Deeper than 8 bits, the host makes one counting pass per shard when asked (`needs_counts`).                                                                          |
+| Head format 1 | Canonical JSON with `complete`, `connector`, `format`, `generation` (decimal string), `keyCheck`, `ns`, `observedAt`, `parts`, `primaryKey`, `profile {key, version}`, `recordCount`, `stream`. Readers check the hash, format, names and `keyCheck`.                                    |
+| Admission     | `decide(S, C)` over the start snapshot `S` and the authoritative read `C`. The target generation depends on `S` only, so one run never publishes at two generations. After a create or reconnect reply the host re-reads and decides with phase `after_write`.                           |
+| Checkpoint    | Save `(ns, T)` only when every stream is committed or no-op at `T`, no stream was published `complete:false`, seed receipts are in, and control re-reads `active(T)`.                                                                                                                    |
+| `needsFull`   | Publishing `complete:false` sets it and clears the checkpoint; a full run that commits `complete:true` clears it; any entry for a connector forces full runs.                                                                                                                            |
+| Eligibility   | One predicate for reads, readiness and totals: a complete live view, else `unavailable` while any connection of the connector is deleted, else a legacy or raw file, else `unavailable`. `isReady` is `eligible(...).kind !== "unavailable"`.                                            |
+
+Open questions and the readings the package takes until they are answered are
+in [DESIGN-QUESTIONS.md](DESIGN-QUESTIONS.md).
+
+## API
+
+| Export                                                                                | Purpose                                                               |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `Sha256`, `Keccak256`, `NamespaceHmac`, `HashPorts`                                   | Port types the host implements.                                       |
+| `canonicalJson`                                                                       | The one serialization behind every byte and hash.                     |
+| `streamScope`, `controlScope`, `parseScope`                                           | Build and parse registry scopes.                                      |
+| `headBlobName`, `partBlobName`, `parseBlobName`                                       | Build and parse blob names.                                           |
+| `deriveNs`, `deriveKeyCheck`, `controlHashes`                                         | Namespace, key check and control-row hashes.                          |
+| `encodeLine`, `decodeLine`, `pkHash`, `shardOf`, `pkHashBits`, `inPrefix`, `lineSize` | Line codec, key hash, shard and prefix helpers, the 8 MiB line limit. |
+| `compareStamp`, `BucketReducer`, `mergeLines`                                         | Merge rule and winner-only reduce.                                    |
+| `encodePart`, `encodeWinners`, `decodePart`                                           | Part codec with fail-closed verification.                             |
+| `planBuckets`, `basePartsFor`                                                         | Bucket planner and base-part routing.                                 |
+| `encodeHead`, `decodeHead`, `digestHead`, `verifyHead`                                | Head format 1.                                                        |
+| `isHeadLive`, `chooseBase`, `writerCompatibility`, `headComplete`, `isNoop`           | Head rules.                                                           |
+| `classifyControl`, `sameControl`                                                      | Control-row states.                                                   |
+| `startState`, `decide`, `targetFor`, `checkpointDecision`                             | Admission, generation and checkpoint rules.                           |
+| `afterCommit`, `runMustBeFull`                                                        | `needsFull` rules.                                                    |
+| `selectConnection`, `eligible`, `isReady`                                             | The eligibility predicate.                                            |
+| `createOutboxEntry`, `streamRunResult`, `OutboxEntry`                                 | Outbox entry type.                                                    |
+| `runVectors`                                                                          | Run `vectors/v1.json` against a host's ports.                         |
+
+## Vectors
+
+`vectors/v1.json` holds byte-exact expected outputs (namespace, scopes, key
+hashes, lines, merge, parts, planner, heads) and the expected result of every
+rule (every `decide` table cell, traces, checkpoint, `needsFull`,
+eligibility). It is plain JSON. A host in another repository can load it and
+call `runVectors(vectors, ports)` with its own crypto ports, or read it with
+its own runner.
+
+`scripts/generate-vectors.mjs` writes the file. It computes bytes with
+`node:crypto` and `@noble/hashes`, independently of the package code, and
+holds the rule expectations as hand-written tables. A test fails if the
+checked-in file differs from the generator output.
+
+## Tests
+
+```sh
+nice -n 10 npx vitest run --maxWorkers=4 packages/stream-sync
+```

package/dist/bytes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Ports and byte helpers. The package imports no crypto, clock, randomness or
+ * I/O: hosts inject every hash and the namespace HMAC.
+ */
+/** SHA-256 of the exact bytes, as the 32-byte digest. */
+export type Sha256 = (data: Uint8Array) => Promise<Uint8Array>;
+/** Keccak-256 (Ethereum, not SHA3-256) of the exact bytes, as the 32-byte digest. */
+export type Keccak256 = (data: Uint8Array) => Promise<Uint8Array>;
+/**
+ * HMAC-SHA256 keyed with `K_ns`, as the 32-byte digest. The host binds the key
+ * inside its own closure, so `K_ns` never enters this package.
+ */
+export type NamespaceHmac = (message: Uint8Array) => Promise<Uint8Array>;
+/** Hash ports used by codec functions. */
+export interface HashPorts {
+    readonly sha256: Sha256;
+    readonly keccak256: Keccak256;
+}
+export declare function utf8(text: string): Uint8Array;
+export declare function utf8Length(text: string): number;
+export declare function toHex(bytes: Uint8Array): string;
+/** Lowercase 64-hex SHA-256 of the bytes, no prefix. */
+export declare function sha256Hex(sha256: Sha256, data: Uint8Array): Promise<string>;
+/** Registry form of a Keccak-256 hash: `0x` + 64 lowercase hex. */
+export declare function keccakHex(keccak256: Keccak256, data: Uint8Array): Promise<`0x${string}`>;
+export declare const HEX64: RegExp;
+export declare const HEX16: RegExp;
+export declare const REGISTRY_HASH: RegExp;
+/** §2.2: a record whose canonical line exceeds this is not published. */
+export declare const RECORD_LINE_LIMIT_BYTES: number;
+/** §2.2: default writer target per part. Hosts with less memory pass a smaller target. */
+export declare const DEFAULT_PART_TARGET_BYTES: number;
+/** §2.2: decoder limit for a clear head. */
+export declare const HEAD_LIMIT_BYTES: number;
+/** §2.2: decoder limit for a clear part; §2.6 bucket winners limit. */
+export declare const PART_LIMIT_BYTES: number;
+/** §2.1: registry scope names longer than this are a permanent error. */
+export declare const NAME_LIMIT_BYTES = 256;
+/** §2.6: the planner never splits deeper than this many bits. */
+export declare const PLANNER_DEPTH_CAP = 16;
+/** §2.6: number of spool shards (first pkHash byte). */
+export declare const SHARD_COUNT = 256;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAE/D,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzE,0CAA0C;AAC1C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAID,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAE7C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAM/C;AAED,wDAAwD;AACxD,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,mEAAmE;AACnE,wBAAsB,SAAS,CAC7B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAExB;AAED,eAAO,MAAM,KAAK,QAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,QAAmB,CAAC;AACtC,eAAO,MAAM,aAAa,QAAqB,CAAC;AAIhD,yEAAyE;AACzE,eAAO,MAAM,uBAAuB,QAAU,CAAC;AAC/C,0FAA0F;AAC1F,eAAO,MAAM,yBAAyB,QAAU,CAAC;AACjD,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,QAAU,CAAC;AACxC,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,iEAAiE;AACjE,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,wDAAwD;AACxD,eAAO,MAAM,WAAW,MAAM,CAAC"}

package/dist/bytes.js

@@ -0,0 +1,45 @@
+/**
+ * Ports and byte helpers. The package imports no crypto, clock, randomness or
+ * I/O: hosts inject every hash and the namespace HMAC.
+ */
+const encoder = new TextEncoder();
+export function utf8(text) {
+    return encoder.encode(text);
+}
+export function utf8Length(text) {
+    return encoder.encode(text).length;
+}
+export function toHex(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 1) {
+        out += bytes[i].toString(16).padStart(2, "0");
+    }
+    return out;
+}
+/** Lowercase 64-hex SHA-256 of the bytes, no prefix. */
+export async function sha256Hex(sha256, data) {
+    return toHex(await sha256(data));
+}
+/** Registry form of a Keccak-256 hash: `0x` + 64 lowercase hex. */
+export async function keccakHex(keccak256, data) {
+    return `0x${toHex(await keccak256(data))}`;
+}
+export const HEX64 = /^[0-9a-f]{64}$/;
+export const HEX16 = /^[0-9a-f]{16}$/;
+export const REGISTRY_HASH = /^0x[0-9a-f]{64}$/;
+const MiB = 1024 * 1024;
+/** §2.2: a record whose canonical line exceeds this is not published. */
+export const RECORD_LINE_LIMIT_BYTES = 8 * MiB;
+/** §2.2: default writer target per part. Hosts with less memory pass a smaller target. */
+export const DEFAULT_PART_TARGET_BYTES = 4 * MiB;
+/** §2.2: decoder limit for a clear head. */
+export const HEAD_LIMIT_BYTES = 1 * MiB;
+/** §2.2: decoder limit for a clear part; §2.6 bucket winners limit. */
+export const PART_LIMIT_BYTES = 16 * MiB;
+/** §2.1: registry scope names longer than this are a permanent error. */
+export const NAME_LIMIT_BYTES = 256;
+/** §2.6: the planner never splits deeper than this many bits. */
+export const PLANNER_DEPTH_CAP = 16;
+/** §2.6: number of spool shards (first pkHash byte). */
+export const SHARD_COUNT = 256;
+//# sourceMappingURL=bytes.js.map

package/dist/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,KAAiB;IACrC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAc,EACd,IAAgB;IAEhB,OAAO,KAAK,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAAoB,EACpB,IAAgB;IAEhB,OAAO,KAAK,KAAK,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,gBAAgB,CAAC;AACtC,MAAM,CAAC,MAAM,KAAK,GAAG,gBAAgB,CAAC;AACtC,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEhD,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAExB,yEAAyE;AACzE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,GAAG,CAAC;AAC/C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,GAAG,GAAG,CAAC;AACjD,4CAA4C;AAC5C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,GAAG,CAAC;AACxC,uEAAuE;AACvE,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,GAAG,GAAG,CAAC;AACzC,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,iEAAiE;AACjE,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,wDAAwD;AACxD,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC"}

package/dist/control.d.ts

@@ -0,0 +1,38 @@
+/**
+ * §2.3 control-row states.
+ *
+ * The authoritative control read is `GET /v1/data/:id?includeDeleted=true`.
+ * A device classifies the row against its own `ACTIVE_DATA`:
+ *
+ *   absent       no row
+ *   deleted(v)   the row at version v is a tombstone
+ *   active(g)    live row whose dataHash is this device's ACTIVE_DATA; g = version
+ *   foreign      live row with any other dataHash (another key → key_mismatch)
+ */
+import type { ControlHashes } from "./namespace.js";
+export type ControlState = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "active";
+    readonly generation: number;
+} | {
+    readonly kind: "deleted";
+    readonly version: number;
+} | {
+    readonly kind: "foreign";
+    readonly version: number;
+};
+/** What the registry returned for the control scope. */
+export type ControlRead = {
+    readonly found: false;
+} | {
+    readonly found: true;
+    readonly version: number;
+    readonly dataHash: string;
+    readonly metadataHash: string;
+    /** The row's `deleted_at` is set. */
+    readonly deleted: boolean;
+};
+export declare function classifyControl(read: ControlRead, hashes: Pick<ControlHashes, "activeData" | "tombstoneData" | "tombstoneMetadata">): ControlState;
+export declare function sameControl(a: ControlState, b: ControlState): boolean;
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,wDAAwD;AACxD,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACzB;IACE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,CAAC;AAUN,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,IAAI,CACV,aAAa,EACb,YAAY,GAAG,eAAe,GAAG,mBAAmB,CACrD,GACA,YAAY,CAcd;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAUrE"}

package/dist/control.js

@@ -0,0 +1,45 @@
+/**
+ * §2.3 control-row states.
+ *
+ * The authoritative control read is `GET /v1/data/:id?includeDeleted=true`.
+ * A device classifies the row against its own `ACTIVE_DATA`:
+ *
+ *   absent       no row
+ *   deleted(v)   the row at version v is a tombstone
+ *   active(g)    live row whose dataHash is this device's ACTIVE_DATA; g = version
+ *   foreign      live row with any other dataHash (another key → key_mismatch)
+ */
+import { InvalidArgumentError } from "./errors.js";
+function checkVersion(version) {
+    if (!Number.isSafeInteger(version) || version < 1) {
+        throw new InvalidArgumentError("registry version must be a positive safe integer");
+    }
+}
+export function classifyControl(read, hashes) {
+    if (!read.found)
+        return { kind: "absent" };
+    checkVersion(read.version);
+    const dataHash = read.dataHash.toLowerCase();
+    const metadataHash = read.metadataHash.toLowerCase();
+    const tombstone = dataHash === hashes.tombstoneData &&
+        metadataHash === hashes.tombstoneMetadata;
+    if (read.deleted || tombstone)
+        return { kind: "deleted", version: read.version };
+    if (dataHash === hashes.activeData) {
+        return { kind: "active", generation: read.version };
+    }
+    return { kind: "foreign", version: read.version };
+}
+export function sameControl(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    switch (a.kind) {
+        case "absent":
+            return true;
+        case "active":
+            return a.generation === b.generation;
+        default:
+            return a.version === b.version;
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAqBnD,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,oBAAoB,CAC5B,kDAAkD,CACnD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,IAAiB,EACjB,MAGC;IAED,IAAI,CAAC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC3C,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IACrD,MAAM,SAAS,GACb,QAAQ,KAAK,MAAM,CAAC,aAAa;QACjC,YAAY,KAAK,MAAM,CAAC,iBAAiB,CAAC;IAC5C,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS;QAC3B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACpD,IAAI,QAAQ,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC;QACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAe,EAAE,CAAe;IAC1D,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACpC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,CAAC,CAAC,UAAU,KAAM,CAAc,CAAC,UAAU,CAAC;QACrD;YACE,OAAO,CAAC,CAAC,OAAO,KAAM,CAAc,CAAC,OAAO,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/decide.d.ts

@@ -0,0 +1,108 @@
+/**
+ * §2.4 admission and generation rule.
+ *
+ * At run start the host stores `start`: a copy of the connector's control
+ * states from the last registry listing completed in this app session, keyed
+ * by ns, or `null` when no listing has completed. At publish,
+ *
+ *   S = start == null ? unknown : start[ns] ?? absent
+ *   C = the authoritative control read
+ *
+ * and `decide(S, C)` gives the action. The target generation T depends on S
+ * alone (absent → 1, active(g0) → g0, deleted(v0) → v0 + 1), so every stream
+ * of one run publishes under the same T, or the run is discarded. A spool is
+ * never re-bound to another generation.
+ *
+ * After a create or reconnect reply (2xx or `replayed`) the host re-reads
+ * the control row and calls `decide` again with phase `after_write`; only
+ * `publish` may follow, anything else discards. A replay proves only that the
+ * row was written once.
+ */
+import type { ControlState } from "./control.js";
+export type StartSnapshot = Readonly<Record<string, ControlState>> | null;
+export type StartState = {
+    readonly kind: "unknown";
+} | ControlState;
+export declare function startState(start: StartSnapshot, ns: string): StartState;
+/**
+ * `first`: first decision for this stream in this attempt.
+ * `reread`: the host re-read control once after a `reread` decision.
+ * `after_write`: the host re-read control after its create/reconnect reply.
+ * `stale_base`: the host re-read control after `chooseBase` returned
+ *   `stale_generation` (a stream head of a newer generation than T).
+ */
+export type DecidePhase = "first" | "reread" | "after_write" | "stale_base";
+export interface DecideInput {
+    readonly start: StartState;
+    readonly current: ControlState;
+    /** True only when an explicit connect action started this run. */
+    readonly userConnect: boolean;
+    /** The run used no checkpoint. */
+    readonly full: boolean;
+    readonly phase: DecidePhase;
+}
+export type Decision = {
+    readonly kind: "publish";
+    readonly target: number;
+}
+/** POST control v1 ACTIVE (exclusive), then re-read and decide `after_write`. */
+ | {
+    readonly kind: "create";
+    readonly target: 1;
+}
+/** POST control v0+1 ACTIVE (exclusive), then re-read and decide `after_write`. */
+ | {
+    readonly kind: "reconnect";
+    readonly target: number;
+}
+/** Re-read control once and decide with phase `reread`. */
+ | {
+    readonly kind: "reread";
+} | {
+    readonly kind: "keep_pending";
+    readonly reason: "registry_inconsistent" | "key_mismatch";
+} | {
+    readonly kind: "discard";
+    /** Start snapshot was unknown: collect again. */
+    readonly recollect: boolean;
+    /** Clear checkpoints for (c, ns). */
+    readonly clearCheckpoints: boolean;
+    /** A userConnect run discarded only for not being full: start a full run now. */
+    readonly restartFull: boolean;
+};
+export declare function decide(input: DecideInput): Decision;
+/** The target generation a start state admits, or `null` (unknown, foreign). */
+export declare function targetFor(start: StartState): number | null;
+/** Per-stream result of one run, as kept in the outbox. */
+export type StreamRunResult = {
+    readonly state: "committed" | "noop";
+    readonly generation: number;
+    /** `complete` of the committed (or unchanged) head. */
+    readonly complete: boolean;
+} | {
+    /** Not committed: still pending (including a visible failure) or discarded. */
+    readonly state: "pending" | "discarded";
+};
+export type CheckpointDecision = {
+    readonly kind: "save";
+    readonly generation: number;
+} | {
+    readonly kind: "skip";
+    readonly reason: "stream_not_committed" | "published_incomplete" | "seed_receipts_pending" | "control_changed";
+};
+/**
+ * §2.4 checkpoint save: after every stream of the run is committed or no-op
+ * at T, re-read control. Save tagged (ns, T) only if it is `active(T)` and
+ * no stream was published `complete:false` or left a `complete:false` head
+ * unchanged (no-op, ruling Q9). A `record_too_large` exclusion
+ * does not block; a `bucket_too_large` stream is not committed and does. §2.9:
+ * the checkpoint also waits for every seed receipt of the run (a host merging its retained history).
+ */
+export declare function checkpointDecision(input: {
+    readonly target: number;
+    readonly streams: Readonly<Record<string, StreamRunResult>>;
+    /** Control re-read after the last commit. */
+    readonly control: ControlState;
+    readonly seedReceiptsPending: boolean;
+}): CheckpointDecision;
+//# sourceMappingURL=decide.d.ts.map

package/dist/decide.d.ts.map

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

package/dist/decide.js

@@ -0,0 +1,144 @@
+/**
+ * §2.4 admission and generation rule.
+ *
+ * At run start the host stores `start`: a copy of the connector's control
+ * states from the last registry listing completed in this app session, keyed
+ * by ns, or `null` when no listing has completed. At publish,
+ *
+ *   S = start == null ? unknown : start[ns] ?? absent
+ *   C = the authoritative control read
+ *
+ * and `decide(S, C)` gives the action. The target generation T depends on S
+ * alone (absent → 1, active(g0) → g0, deleted(v0) → v0 + 1), so every stream
+ * of one run publishes under the same T, or the run is discarded. A spool is
+ * never re-bound to another generation.
+ *
+ * After a create or reconnect reply (2xx or `replayed`) the host re-reads
+ * the control row and calls `decide` again with phase `after_write`; only
+ * `publish` may follow, anything else discards. A replay proves only that the
+ * row was written once.
+ */
+import { hasOwn } from "./json.js";
+export function startState(start, ns) {
+    if (start === null)
+        return { kind: "unknown" };
+    return hasOwn(start, ns) ? start[ns] : { kind: "absent" };
+}
+const DISCARD = {
+    kind: "discard",
+    recollect: false,
+    clearCheckpoints: false,
+    restartFull: false,
+};
+function table(input) {
+    const { start: s, current: c, userConnect, full, phase } = input;
+    // `any | foreign` overrides the `other` cells (see DESIGN-QUESTIONS.md Q1).
+    if (c.kind === "foreign")
+        return { kind: "keep_pending", reason: "key_mismatch" };
+    switch (s.kind) {
+        case "unknown":
+            return { ...DISCARD, recollect: true };
+        case "absent":
+            if (c.kind === "absent")
+                return { kind: "create", target: 1 };
+            if (c.kind === "active" && c.generation === 1) {
+                return { kind: "publish", target: 1 };
+            }
+            return DISCARD;
+        case "active": {
+            const g0 = s.generation;
+            if (c.kind === "active" && c.generation === g0) {
+                return { kind: "publish", target: g0 };
+            }
+            if (c.kind === "absent" || (c.kind === "active" && c.generation < g0)) {
+                return phase === "reread"
+                    ? { kind: "keep_pending", reason: "registry_inconsistent" }
+                    : { kind: "reread" };
+            }
+            return { ...DISCARD, clearCheckpoints: true };
+        }
+        case "deleted": {
+            const v0 = s.version;
+            const sameDelete = c.kind === "deleted" && c.version === v0;
+            const reconnected = c.kind === "active" && c.generation === v0 + 1;
+            if (userConnect && full) {
+                if (sameDelete)
+                    return { kind: "reconnect", target: v0 + 1 };
+                if (reconnected)
+                    return { kind: "publish", target: v0 + 1 };
+            }
+            return {
+                ...DISCARD,
+                restartFull: userConnect && !full && (sameDelete || reconnected),
+            };
+        }
+        case "foreign":
+            // No table row starts from foreign (DESIGN-QUESTIONS.md Q2).
+            return DISCARD;
+    }
+}
+export function decide(input) {
+    const decision = table(input);
+    if (input.phase === "after_write" && decision.kind !== "publish") {
+        // §2.4: after create/reconnect, C must re-read as active(T), else discard.
+        return DISCARD;
+    }
+    if (input.phase === "stale_base") {
+        // P0-RULINGS F1: a stream head of a newer generation than T exists, so
+        // the start snapshot is older than the registry. The table normally
+        // discards (with its §2.4 checkpoint rule). If control still admits T,
+        // the registry contradicts itself: keep pending, never publish or write.
+        if (decision.kind === "discard" || decision.kind === "keep_pending") {
+            return decision;
+        }
+        return { kind: "keep_pending", reason: "registry_inconsistent" };
+    }
+    return decision;
+}
+/** The target generation a start state admits, or `null` (unknown, foreign). */
+export function targetFor(start) {
+    switch (start.kind) {
+        case "absent":
+            return 1;
+        case "active":
+            return start.generation;
+        case "deleted":
+            return start.version + 1;
+        default:
+            return null;
+    }
+}
+/**
+ * §2.4 checkpoint save: after every stream of the run is committed or no-op
+ * at T, re-read control. Save tagged (ns, T) only if it is `active(T)` and
+ * no stream was published `complete:false` or left a `complete:false` head
+ * unchanged (no-op, ruling Q9). A `record_too_large` exclusion
+ * does not block; a `bucket_too_large` stream is not committed and does. §2.9:
+ * the checkpoint also waits for every seed receipt of the run (a host merging its retained history).
+ */
+export function checkpointDecision(input) {
+    const results = Object.values(input.streams);
+    for (const result of results) {
+        if (result.state !== "committed" && result.state !== "noop") {
+            return { kind: "skip", reason: "stream_not_committed" };
+        }
+        if (result.generation !== input.target) {
+            return { kind: "skip", reason: "stream_not_committed" };
+        }
+    }
+    for (const result of results) {
+        // Q9 ruling: a no-op onto a `complete:false` base blocks the checkpoint
+        // the same as publishing `complete:false` (liveness L3).
+        if ("complete" in result && !result.complete) {
+            return { kind: "skip", reason: "published_incomplete" };
+        }
+    }
+    if (input.seedReceiptsPending)
+        return { kind: "skip", reason: "seed_receipts_pending" };
+    if (input.control.kind !== "active" ||
+        input.control.generation !== input.target) {
+        return { kind: "skip", reason: "control_changed" };
+    }
+    return { kind: "save", generation: input.target };
+}
+//# sourceMappingURL=decide.js.map

package/dist/decide.js.map

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

package/dist/eligible.d.ts

@@ -0,0 +1,67 @@
+/**
+ * §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 type { ControlState } from "./control.js";
+export interface StreamHeadView {
+    /** §2.4 liveness (`isHeadLive`). */
+    readonly live: boolean;
+    readonly complete: boolean;
+}
+export interface ConnectionView {
+    readonly ns: string;
+    /** This server's last synced control state for the connection. */
+    readonly control: ControlState;
+    /**
+     * Registration order of the connection's most recently registered live
+     * head (larger is more recent), or `null` when it has none.
+     */
+    readonly latestHeadRegistration: number | null;
+    readonly streams: Readonly<Record<string, StreamHeadView>>;
+}
+export type ReadTarget = 
+/** `pdpp.<c>.<s>` or a legacy binding: the streams it needs. */
+{
+    readonly kind: "logical";
+    readonly streams: readonly string[];
+}
+/** `pdpp.<c>~<ns>.<s>`: its own connection. */
+ | {
+    readonly kind: "physical";
+    readonly ns: string;
+    readonly streams: readonly string[];
+};
+export interface EligibilityInput {
+    /** Every connection of the connector known to this server. */
+    readonly connections: readonly ConnectionView[];
+    readonly target: ReadTarget;
+    /** A legacy or raw file of the requested name exists. */
+    readonly legacyFile: boolean;
+}
+export type Eligibility = {
+    readonly kind: "view";
+    readonly ns: string;
+} | {
+    readonly kind: "legacy";
+} | {
+    readonly kind: "unavailable";
+    readonly reason: "deleted" | "no_data";
+};
+/** The connection a plain (logical) name of the connector reads. */
+export declare function selectConnection(connections: readonly ConnectionView[]): ConnectionView | null;
+export declare function eligible(input: EligibilityInput): Eligibility;
+/** Readiness is exactly "a read would not be `unavailable`". */
+export declare function isReady(input: EligibilityInput): boolean;
+//# sourceMappingURL=eligible.d.ts.map

package/dist/eligible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligible.d.ts","sourceRoot":"","sources":["../src/eligible.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;CAC5D;AAED,MAAM,MAAM,UAAU;AACpB,gEAAgE;AAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AACnE,+CAA+C;GAC7C;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEN,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAAC;AAU7E,oEAAoE;AACpE,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,SAAS,cAAc,EAAE,GACrC,cAAc,GAAG,IAAI,CAGvB;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CA0B7D;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAExD"}