@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/via/geo/geohash.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The geospatial primitives (#1355) — geohash encoding, great-circle
+ * distance, and the bounding-box → prefix-set cover that lets a `near()`
+ * query take the existing sorted index.
+ *
+ * ⭐ WHY A GEOHASH PREFIX AND NOT A COORDINATE. The store holds ciphertext
+ * and never runs a query, but a secondary index key is a value the hub
+ * itself keeps in a structure a persisted sidecar can carry (#1359). A raw
+ * `lat`/`lng` in that key space is a coordinate at full precision; a
+ * geohash PREFIX is a cell — deliberately lossy, and the coarser the query
+ * the less it says. That is the whole reason this module exists rather
+ * than a pair of numeric range indexes on `lat` and `lng`.
+ *
+ * ⛔ THE SUPERSET LAW. {@link coverPrefixes} must return a cover whose
+ * union CONTAINS every point of the box, and {@link boundingBox} a box
+ * that contains every point within the radius. A candidate set that is
+ * too big costs a haversine call per extra row; one that is too small is
+ * a WRONG ANSWER, and no post-filter can put a dropped record back.
+ * `__tests__/geo-superset.test.ts` is the property that pins it.
+ *
+ * Pure, portable, dependency-free — no Node built-ins, no npm math lib.
+ */
+/** A WGS-84 point. Latitude in [-90, 90], longitude in [-180, 180]. */
+export interface GeoPoint {
+    readonly lat: number;
+    readonly lng: number;
+}
+/** A latitude/longitude rectangle. Never wraps: {@link boundingBox} splits at the antimeridian instead. */
+export interface GeoBox {
+    readonly minLat: number;
+    readonly maxLat: number;
+    readonly minLng: number;
+    readonly maxLng: number;
+}
+/** Mean Earth radius (IUGG), km — the same constant every reference haversine uses. */
+export declare const EARTH_RADIUS_KM = 6371.0088;
+/** Widest geohash precision this module encodes. 12 chars ≈ 3.7cm — past any GPS fix. */
+export declare const MAX_PRECISION = 12;
+/** True when `p` is a usable point. Rejects NaN, infinities and out-of-range values. */
+export declare function isGeoPoint(p: unknown): p is GeoPoint;
+/**
+ * Great-circle distance in kilometres.
+ *
+ * Haversine rather than the law of cosines: the two agree to metres at
+ * continental scale, but `acos` loses all its significant digits for
+ * nearby points (`cos d → 1`), which is exactly the regime a `near()`
+ * query lives in.
+ */
+export declare function haversineKm(a: GeoPoint, b: GeoPoint): number;
+/**
+ * Encode a point as a geohash of `precision` characters.
+ *
+ * Bits interleave longitude-first, which is what makes a shared prefix
+ * mean "the same cell" and therefore what makes the sorted index's
+ * `startsWith` slice a spatial answer.
+ */
+export declare function encodeGeohash(point: GeoPoint, precision: number): string;
+/** The cell a geohash names. Throws on a character outside the alphabet. */
+export declare function decodeGeohashBox(hash: string): GeoBox;
+/** How many latitude / longitude bits a `precision`-character hash spends. */
+export declare function gridBits(precision: number): {
+    latBits: number;
+    lngBits: number;
+};
+/**
+ * The boxes enclosing every point within `radiusKm` of `center`.
+ *
+ * Returns TWO boxes when the circle crosses the antimeridian, and one
+ * spanning the full longitude range when it reaches a pole — a rectangle
+ * in lat/lng cannot express either case, and quietly clipping would
+ * violate the superset law at exactly the coordinates nobody tests by
+ * hand.
+ */
+export declare function boundingBox(center: GeoPoint, radiusKm: number): GeoBox[];
+/** Number of `precision`-cells the boxes touch — computed from grid indices, never by enumerating. */
+export declare function coverSize(boxes: readonly GeoBox[], precision: number): number;
+/**
+ * The geohash prefixes whose cells cover `boxes` at `precision`.
+ *
+ * Every returned prefix is exactly `precision` characters, so the set can
+ * be handed to the sorted index one `startsWith` at a time and unioned.
+ */
+export declare function coverPrefixes(boxes: readonly GeoBox[], precision: number): string[];
+/**
+ * The finest cover of `center`/`radiusKm` that stays within `maxCells`
+ * prefixes, capped at `maxPrecision`.
+ *
+ * Finer is better: the prefixes ARE the candidate set, so a coarser cover
+ * hands more rows to the haversine post-filter. The search always
+ * terminates — precision 1 is a 4×8 grid, so 32 cells cover the planet.
+ */
+export declare function prefixesForRadius(center: GeoPoint, radiusKm: number, maxPrecision: number, maxCells: number): {
+    prefixes: string[];
+    precision: number;
+};

package/dist/via/geo/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@noy-db/hub` geospatial field descriptor (#1355) — `geo()` plus the
+ * pure primitives a consumer may want directly (`haversineKm` for a
+ * distance column, `encodeGeohash` for a cell label).
+ *
+ * @see ./descriptor for the public `geo()` factory.
+ * @see ./geohash for the superset law the prefix cover obeys.
+ */
+export { geo, isGeoDescriptor, GeoPointError } from './descriptor.js';
+export type { GeoDescriptor, GeoOptions } from './descriptor.js';
+export { haversineKm, encodeGeohash, decodeGeohashBox, boundingBox, coverPrefixes, coverSize, prefixesForRadius, isGeoPoint, gridBits, EARTH_RADIUS_KM, MAX_PRECISION, } from './geohash.js';
+export type { GeoPoint, GeoBox } from './geohash.js';
+export type { NearOperand, GeoWhereOperand, GeoNearOperand, GeoPassthroughOperand } from './where.js';

package/dist/via/geo/where.d.ts

@@ -0,0 +1,50 @@
+import { type Operator } from '../../kernel/query/predicate.js';
+import type { ViaPrefixProbe } from '../../kernel/via/index.js';
+import type { GeoDescriptor } from './descriptor.js';
+import { type GeoPoint } from './geohash.js';
+/** The `near` operand: a centre and a radius in kilometres. */
+export interface NearOperand extends GeoPoint {
+    readonly radiusKm: number;
+}
+/** A `near` clause: the centre, the radius, and the cover the index probes. */
+export interface GeoNearOperand {
+    readonly kind: 'near';
+    readonly center: GeoPoint;
+    readonly radiusKm: number;
+    readonly prefixes: readonly string[];
+    /** Cover precision actually chosen — reported by `describeFragment()`, not used to match. */
+    readonly precision: number;
+}
+/** Any other operator over a geo field: claimed, un-probed, generically compared. */
+export interface GeoPassthroughOperand {
+    readonly kind: 'passthrough';
+    readonly value: unknown;
+}
+/** The opaque payload `buildClause` produces and `evaluateClause` consumes. */
+export type GeoWhereOperand = GeoNearOperand | GeoPassthroughOperand;
+/**
+ * Build the payload for a clause over a geo field. A `near` operand is
+ * validated and covered here; every other operator is captured verbatim.
+ *
+ * A malformed `near` operand throws at the `where()` CALL SITE (money's
+ * precedent) — a silently-empty result set is the worst possible answer to
+ * a typo'd coordinate.
+ */
+export declare function geoFieldClause(field: string, op: Operator, value: unknown, desc: GeoDescriptor): GeoWhereOperand;
+/**
+ * Exact membership: the stored point is within `radiusKm` of the centre.
+ *
+ * A value that is not a point — absent, nullish, or written before the
+ * field was declared `geo()` — matches nothing. That is the same posture
+ * every other operator takes on a type mismatch, and it is what keeps the
+ * index sound: such a record has no geohash key either, so it is absent
+ * from the candidate set AND from the answer.
+ */
+export declare function evaluateGeoClause(actual: unknown, op: string, payload: GeoWhereOperand): boolean;
+/**
+ * The index operand: a prefix cover the sorted index can slice.
+ *
+ * `undefined` for any other operator, which sends the clause to the scan
+ * — the geo binding claims no fast path it cannot make sound.
+ */
+export declare function geoIndexProbe(op: string, payload: GeoWhereOperand): ViaPrefixProbe | undefined;

package/dist/via/i18n/core.d.ts

@@ -246,7 +246,7 @@ export { getAtPath } from '../../kernel/paths.js';
 export declare function applyI18nLocale(record: Record<string, unknown>, i18nFields: Record<string, I18nTextDescriptor>, locale: string, fallback?: string | readonly string[], layer?: Layer): Record<string, unknown>;
 /**
  * Sync i18n-text-only present-for-join dressing — the exact `join`-layer
- * partial application `kernel/query/join.ts` used to import and call
+ * partial application `kernel/query/relate/join.ts` used to import and call
  * directly before #626's retirement (#650 Task 6): fixes `fallback`
  * `undefined` and `layer` `'join'`. `via/lookup/snapshot.ts`'s
  * `buildPresentForJoin` composes this with the lookup-label half to build

package/dist/via/lookup/registry.d.ts

@@ -9,7 +9,7 @@
  * by `vault.collection()` and read by the backup path) and calls these
  * helpers through the `port/with/lookup-strategy.ts` seam.
  */
-import type { JoinableSource } from '../../kernel/query/index.js';
+import type { JoinableSource } from '../../kernel/query/relate/join.js';
 import type { ViaGraph } from '../../kernel/via/graph.js';
 import type { StaticDictDescriptor } from '../../port/with/i18n-strategy.js';
 import { type LookupHandle } from './handle.js';

package/dist/via/lookup/snapshot.d.ts

@@ -1,7 +1,7 @@
 /**
  * The sync lookup snapshot + join/locale seam (#650 Task 6, spec §5 — "the
  * snapshot+locale seam"). Retires the #626 kernel→via grandfather:
- * `kernel/query/join.ts` no longer imports `via/i18n/core.js` directly
+ * `kernel/query/relate/join.ts` no longer imports `via/i18n/core.js` directly
  * — it calls the `presentForJoin` hook this file's `buildPresentForJoin`
  * builds instead (seam map Part 2 item 4, the #626 reviewer-spec'd shape:
  * a sync `presentI18nForJoin`-class hook on `JoinableSource`).
@@ -16,7 +16,7 @@
  * Serves (reserved AND matrix tier since #650 Task 7 — `registry.ts`'s
  * `buildLookupSnapshotRows` routes both; static tier is read straight off
  * `descriptor.table` by every consumer below, never through this cache):
- *   - join dressing (`presentForJoin`, consumed by `kernel/query/join.ts`
+ *   - join dressing (`presentForJoin`, consumed by `kernel/query/relate/join.ts`
  *     via `JoinableSource.presentForJoin`)
  *   - dimension sort (`compareForOrder`, consumed by
  *     `via/lookup/binding.ts`'s `NoydbVia.compareForOrder` closure)
@@ -59,7 +59,7 @@ export declare function buildLookupSnapshot(dimension: string, rows: ReadonlyMap
  * `Collection` attaches to the `JoinableSource` it exposes
  * (`querySourceForJoin()`) — the i18n-text half (`presentI18nForJoin`, the
  * exact `applyI18nLocale(..., 'join')` partial application
- * `kernel/query/join.ts` used to call directly, #626) composed with the
+ * `kernel/query/relate/join.ts` used to call directly, #626) composed with the
  * lookup-label half above. `undefined` when the collection declares
  * neither — `JoinableSource.presentForJoin` then stays unset, matching
  * today's `i18nFields`-absent behavior exactly (#626 parity lock).

package/dist/walk-HJ42EISE.js

@@ -0,0 +1,21 @@
+import {
+  dumpVaultSchema
+} from "./chunk-BP6DARYA.js";
+import "./chunk-RXLYKVTF.js";
+import "./chunk-VYYM3MEN.js";
+import "./chunk-PSIV7CJV.js";
+import "./chunk-Y2NBBT6K.js";
+import "./chunk-3H5KLDZN.js";
+import "./chunk-KJFW62P4.js";
+import "./chunk-SEE332EV.js";
+import "./chunk-6QSQQLSE.js";
+import "./chunk-DE4DH2RZ.js";
+import "./chunk-LQ4ZHOKP.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-UYB234ZR.js";
+import "./chunk-ODVPTDPK.js";
+import "./chunk-244VXYPG.js";
+export {
+  dumpVaultSchema
+};
+//# sourceMappingURL=walk-HJ42EISE.js.map

package/dist/walk-HJ42EISE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/with-audit/coverage/accounting.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Coverage accounting (#1363) — per `(principal, vault, collection)`.
+ *
+ * ⛔⛔ **TELEMETRY, NOT A CONTROL.** Against an insider holding the device and
+ * local keys this prevents nothing; it makes bulk extraction visible early,
+ * attributable and loud. Key custody (tiers, per-collection DEKs) is the
+ * remediation. Nothing in this module refuses a read, and nothing in it may
+ * ever grow the ability to (#1251 §3: a refusal is a threshold the reader can
+ * binary-search; a signal is not).
+ *
+ * What is accounted, and why each one:
+ *
+ *  - **distinct ids ever decrypted** (HyperLogLog) — coverage is the protected
+ *    quantity, not rate: patience lowers an extractor's rate and never their
+ *    coverage. Monotonic, and the horizon is the life of the state, never a
+ *    30-day window that resets faster than the attack completes.
+ *  - **novelty per window** (Bloom, cleared per window) — the discriminator
+ *    that is orthogonal to speed. A legitimate operator re-reads a working
+ *    subset (high volume, low novelty); an extractor reads new records.
+ *  - **served** — decrypts, all time and per window.
+ *  - **burstiness** — this window's served count over the running mean of the
+ *    previous windows'. 1 while there is no history to compare against.
+ *
+ * @module
+ */
+import type { CoverageEmitter, CoverageFieldMeta, CoverageObserver, CoverageStrategy } from '../../port/with/coverage-strategy.js';
+/** Per-collection policy. Absent `corpusSize` ⇒ no coverage estimate, so no alert. */
+export interface CoverageCollectionPolicy {
+    /**
+     * How many records the corpus holds. Coverage is `distinct / corpusSize`.
+     * Deliberately DECLARED rather than counted: counting means a store read on
+     * a sensor that must not touch the store, and a corpus size that moves with
+     * every write makes an alert threshold un-reproducible.
+     */
+    readonly corpusSize?: number;
+    /** Coverage fractions to alert at. Default `[0.6, 0.9]`. Each fires at most once. */
+    readonly alertAt?: readonly number[];
+}
+export interface WithCoverageOptions {
+    /**
+     * HyperLogLog precision — the register file is `2^precision` bytes per
+     * `(principal, vault, collection)`. Default 14 (16 KiB), chosen by
+     * measurement; the table is in `sketch.ts`.
+     */
+    readonly precision?: number;
+    /** Bloom width in bits, per key, per window. Default 16 384 (2 KiB). */
+    readonly bloomBits?: number;
+    /** Bloom hash count. Default 7. */
+    readonly bloomHashes?: number;
+    /** Novelty window length. Default one hour. NOT the coverage horizon — that never resets. */
+    readonly windowMs?: number;
+    /** Per-collection corpus size and alert thresholds. */
+    readonly collections?: Readonly<Record<string, CoverageCollectionPolicy>>;
+    /** Clock seam, for tests. */
+    readonly now?: () => number;
+}
+export interface CoverageStats {
+    readonly principal: string;
+    readonly vault: string;
+    readonly collection: string;
+    /** HLL estimate of distinct ids ever decrypted. */
+    readonly distinct: number;
+    readonly served: number;
+    readonly novelInWindow: number;
+    readonly servedInWindow: number;
+    readonly burstiness: number;
+    /** Absent when the collection declares no `corpusSize`. */
+    readonly coverage?: number;
+    readonly window: string;
+}
+/**
+ * Serializable coverage state.
+ *
+ * ⛔ SKETCHES ONLY — the invariant this module exists to hold. A structure
+ * that could name the records a principal has read would be a second copy of
+ * the sensitive set: the sensor built to notice bulk extraction would become
+ * the single best artefact to extract. Pinned by
+ * `__tests__/coverage/no-record-ids.test.ts`.
+ */
+export interface CoverageSnapshot {
+    readonly _noydb_coverage: 1;
+    readonly entries: ReadonlyArray<{
+        readonly principal: string;
+        readonly vault: string;
+        readonly collection: string;
+        readonly hll: {
+            readonly p: number;
+            readonly r: string;
+        };
+        readonly served: number;
+        readonly windowStart: number;
+    }>;
+}
+export declare class CoverageRegistry implements CoverageStrategy {
+    #private;
+    constructor(opts?: WithCoverageOptions);
+    observer(vault: string, collection: string, principal: string, fieldMeta: () => CoverageFieldMeta | undefined, emitter: CoverageEmitter, eager: boolean): CoverageObserver | undefined;
+    /** Current accounting, for an operator surface. Estimates, never exact. */
+    stats(): readonly CoverageStats[];
+    /**
+     * Serializable state, for a deployment that wants coverage to survive a
+     * restart — the horizon must exceed tenure, and a process does not.
+     * ⛔ Sketches only. Never a record id: see {@link CoverageSnapshot}.
+     */
+    snapshot(): CoverageSnapshot;
+    /**
+     * Restore a snapshot. The novelty filter is deliberately NOT restored:
+     * novelty is a within-window notion and the window did not survive.
+     * Distinct-ever did, which is the quantity that must not reset.
+     */
+    restore(snapshot: CoverageSnapshot): void;
+}

package/dist/with-audit/coverage/active.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `withCoverage()` — the opt-in read-coverage sensor (#1363).
+ *
+ * ⛔⛔ **Against an insider holding the device and local keys, this prevents
+ * nothing. It makes bulk extraction visible early, attributable and loud. It
+ * is telemetry.** The real remediation is key custody — tiers and
+ * per-collection DEKs — and this factory is not a substitute for one. Read the
+ * sentence again before wiring it into anything that describes itself as a
+ * control.
+ *
+ * @module
+ */
+import { CoverageRegistry } from './accounting.js';
+import type { WithCoverageOptions } from './accounting.js';
+/**
+ * Enable coverage accounting for every collection that declares a
+ * `bulk: 'sensitive'` field (or that is named in `opts.collections`).
+ *
+ * ```ts
+ * const coverage = withCoverage({ collections: { clients: { corpusSize: 1200, alertAt: [0.6, 0.9] } } })
+ * const db = await createNoydb({ user: 'alice', secret, coverageStrategy: coverage })
+ * db.on('coverage:threshold', (e) => notifyOwner(e))   // a SIGNAL, never a refusal
+ * ```
+ *
+ * The returned registry is the strategy AND the read surface: `stats()` for a
+ * live view, `snapshot()`/`restore()` to carry the coverage horizon across a
+ * restart. Nothing it returns can name a record that was read.
+ */
+export declare function withCoverage(opts?: WithCoverageOptions): CoverageRegistry;

package/dist/with-audit/coverage/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `@noy-db/hub/coverage` — read-coverage sensor (#1363, from the #1251 design).
+ *
+ * ⛔⛔ **Against an insider holding the device and local keys, this prevents
+ * nothing. It makes bulk extraction visible early, attributable and loud. It
+ * is telemetry.** The real remediation is key custody (tiers, per-collection
+ * DEKs); a coverage alert is a complement to a key boundary and a poor
+ * substitute for one.
+ *
+ * The reframe it implements: the protected quantity for "safe individually,
+ * sensitive in bulk" data is **coverage** — the fraction of a corpus a
+ * principal has *ever* decrypted — not rate. Rate limiting fails structurally
+ * against low-and-slow; patience lowers an extractor's rate and never their
+ * coverage. So this service accounts distinct-ever (HyperLogLog), novelty per
+ * window (Bloom), served count and burstiness per
+ * `(principal, vault, collection)`, and emits `'coverage:threshold'` when
+ * declared coverage thresholds are crossed.
+ *
+ * ⛔ It never refuses a read, and no option to do so may be added: a refusal
+ * at a boundary is a threshold the reader can binary-search.
+ * ⛔ It never persists a record id. Sketches are the only state.
+ * ⚠️ It accounts only LAZY collections (`prefetch: false`). An eager
+ * collection decrypts its whole corpus at hydration, which a decrypt-point
+ * sensor cannot tell from a read — see `accounting.ts#resolveAccounted`.
+ *
+ * ## Honeytoken recipe (prose — the cheapest high-signal sensor in the design)
+ *
+ * Coverage alerting tells you how much of a corpus a principal has seen.
+ * A honeytoken tells you, on the FIRST read, that someone is enumerating —
+ * and it is immune to rate shaping, because there is no legitimate rate at
+ * which a record nobody should open gets opened.
+ *
+ * 1. Seed a handful of records in the bulk-declared collection that no
+ *    business process ever addresses: plausible-looking rows with ids no
+ *    workflow can reach, never referenced by a ref, never in a report.
+ * 2. Keep the list of their ids OUTSIDE the vault — in the code or the
+ *    operator's config. It must never become a queryable "honeytokens"
+ *    collection: that is a lookup table telling an insider which rows to
+ *    avoid, i.e. the same second-copy mistake the sketches exist to avoid.
+ * 3. Wrap the read path the app already owns and compare the id it is about
+ *    to serve against that list. Any hit is a high-confidence signal — page
+ *    the owner, and (with `withHistory()`) append a ledger entry so the
+ *    detection itself is tamper-evident.
+ * 4. Do not refuse the read. Serving it keeps the reader unaware they tripped
+ *    a sensor, which is the entire value; refusing turns the honeytoken into
+ *    an oracle for finding the other honeytokens.
+ * 5. Rotate them when staff change. A honeytoken whose location has leaked is
+ *    a honeytoken that reports nothing.
+ *
+ * ⚠️ Honeytokens detect ENUMERATION, not exfiltration of a known subset. They
+ * complement coverage alerting; neither prevents anything.
+ *
+ * @category capability
+ * @module
+ */
+export { withCoverage } from './active.js';
+export { CoverageRegistry } from './accounting.js';
+export type { CoverageCollectionPolicy, CoverageSnapshot, CoverageStats, WithCoverageOptions, } from './accounting.js';
+export { BloomFilter, HyperLogLog } from './sketch.js';
+export type { CoverageEmitter, CoverageEvent, CoverageFieldMeta, CoverageObserver, CoverageStrategy, } from '../../port/with/coverage-strategy.js';
+export { NO_COVERAGE } from '../../port/with/coverage-strategy.js';

package/dist/with-audit/coverage/sketch.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Bounded-size sketches for the coverage sensor (#1363).
+ *
+ * ⚠️ THE WHOLE POINT OF A SKETCH HERE IS WHAT IT CANNOT DO. Coverage state
+ * answers *"how much of this corpus has this principal seen"*, and the exact
+ * answer — the id set — is a SECOND COPY OF THE SENSITIVE SET. A sensor built
+ * to notice bulk extraction would then be the best single artefact to extract.
+ * So no structure in this module retains a record id, and none can be
+ * enumerated back into one: HyperLogLog keeps per-register leading-zero ranks,
+ * Bloom keeps bits. Both are lossy on purpose, and the accuracy that costs is
+ * the price of the property (`no-record-ids.test.ts` pins it).
+ *
+ * @module
+ */
+/**
+ * HyperLogLog over `2^precision` one-byte registers.
+ *
+ * ⭐ SIZING IS THE OPEN QUESTION THIS FEATURE SHIPS WITH, not a settled
+ * default. At the scale the design anticipates (~1k records, ~30 principals)
+ * the estimator runs entirely in its LINEAR-COUNTING range, where accuracy is
+ * a function of load factor rather than of HLL's asymptotic 1.04/√m. So the
+ * default is chosen by MEASUREMENT, not theory — `__tests__/coverage/sketch.test.ts`
+ * pins the error band this implementation actually produces:
+ *
+ * | distinct ids | p=10 (1 KiB) | p=12 (4 KiB) | **p=14 (16 KiB, default)** |
+ * |---:|---:|---:|---:|
+ * | 100    | 3.00% | 1.00% | **0.00%** |
+ * | 1 000  | 2.90% | 0.50% | **0.40%** |
+ * | 10 000 | 2.34% | 5.62% | **0.96%** |
+ * | 50 000 | 2.31% | 1.70% | **1.52%** |
+ *
+ * (p=12's 5.62% at 10 000 is the linear-counting/raw-estimator crossover, and
+ * is exactly why the default is not chosen from the memory column.)
+ * 16 KiB is per `(principal, vault, collection)` — a ~30-principal deployment
+ * with a handful of bulk-declared collections stays in the low megabytes.
+ * `precision` is configurable for a deployment whose corpus is a different
+ * order of magnitude.
+ *
+ * ⛔ An exact per-collection bitmap would be smaller AND exact at that scale.
+ * It is not shipped because it leaks ids: bit *i* set means "record *i* was
+ * read", which is the second copy this module exists to avoid. Revisit only
+ * against a real dataset, and only with that trade stated.
+ */
+export declare class HyperLogLog {
+    readonly precision: number;
+    private readonly registers;
+    constructor(precision?: number);
+    add(id: string): void;
+    /** Estimated distinct count. */
+    count(): number;
+    /** Serializable state — registers only. No id, no id-derived key. */
+    toJSON(): {
+        readonly p: number;
+        readonly r: string;
+    };
+    static fromJSON(state: {
+        readonly p: number;
+        readonly r: string;
+    }): HyperLogLog;
+}
+/**
+ * Bloom filter for *novelty per window* — "have I seen this id in this
+ * window?". False positives under-report novelty (a novel read is scored as a
+ * repeat), which is the safe direction for a sensor that must not cry wolf;
+ * false negatives are impossible.
+ */
+export declare class BloomFilter {
+    readonly bits: number;
+    readonly hashes: number;
+    private readonly words;
+    constructor(bits?: number, hashes?: number);
+    /** Set the id's bits; returns true when the id was NOT already present. */
+    addIfAbsent(id: string): boolean;
+    clear(): void;
+}

package/dist/with-audit/periods/periods.d.ts

@@ -146,6 +146,7 @@
  */
 import type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js';
 import type { LedgerStore } from '../../with-commit/history/ledger/index.js';
+import { ValidationError } from '../../kernel/errors.js';
 export { PERIODS_COLLECTION, PERIOD_FREEZES_COLLECTION, PERIOD_ARCHIVES_COLLECTION, PERIOD_TARGET_PURGES_COLLECTION, PERIOD_REOPENS_COLLECTION, periodExclusiveUpperBound, } from './window.js';
 /**
  * Companion record recording that a closed period was frozen (its delete
@@ -398,9 +399,25 @@ export interface ClosePeriodOptions {
     /** Human-readable name. Must not collide with an existing period. */
     readonly name: string;
     /**
-     * Inclusive upper cutoff. A record is sealed when its
-     * `record[dateField]` (or, if absent, the envelope `_ts`) is at or
-     * before this ISO timestamp.
+     * Inclusive upper cutoff. With a `dateField`, a record is sealed when its
+     * `record[dateField]` is at or before this ISO timestamp; a record with
+     * NO value there (absent / `null`) carries no business date and belongs
+     * to no period, and a value that is neither an ISO string nor a `Date`
+     * is refused (#1455). Without a `dateField`, the envelope `_ts` of the
+     * stored record is compared instead.
+     *
+     * ⚠️ String comparison is lexicographic: keep `endDate` and the field in
+     * one ISO-8601 shape (`YYYY-MM-DD` against `YYYY-MM-DD`, or full
+     * timestamps against full timestamps).
+     *
+     * ⛔ **Zero-padding is now ENFORCED on both sides (#1459), because that
+     * warning was not enough.** `'2026-6-30'` names a real day and is refused
+     * anyway: as text it sorts BELOW every June date, so the close would seal
+     * nothing and report success — and symmetrically a record dated
+     * `'2026-6-15'` sorted ABOVE `'2026-06-30'` and was written into a sealed
+     * June. Both are `ValidationError` now, at the close and at the write,
+     * rather than a silent pass or a `PeriodClosedError` that fired for a reason
+     * unrelated to dates.
      */
     readonly endDate: string;
     /**
@@ -502,6 +519,17 @@ export interface ReadOnlyCollection<T> {
  * cache. Not part of the public API surface.
  */
 export declare function loadPeriods(adapter: NoydbStore, vault: string, decrypt: (id: string, envelope: EncryptedEnvelope) => Promise<PeriodRecord>): Promise<PeriodRecord[]>;
+/** sha256(canonicalJson(record)) over the STORED shape of a period record. @internal */
+export declare function hashStoredPeriod(period: PeriodRecord): Promise<string>;
+/**
+ * #1454 — every record's `priorPeriodName` / `priorPeriodHash` must resolve to
+ * a stored predecessor in ITS timeline whose hash matches. Followed by name,
+ * not by sort position: two closes within one millisecond sort arbitrarily,
+ * and a deleted predecessor must read as a break, not as a new root.
+ *
+ * @internal
+ */
+export declare function verifyPeriodChain(records: readonly PeriodRecord[]): Promise<void>;
 /**
  * Given the current ordered period list, pick the last entry that
  * belongs to the hash chain — used as the `priorPeriodHash` anchor
@@ -513,22 +541,42 @@ export declare function chainAnchor(records: readonly PeriodRecord[], partition?
     priorPeriodName?: string;
     priorPeriodHash: string;
 }>;
+/**
+ * @internal #1459 — is `value` a business date that can be compared against an
+ * `endDate` and give the calendar's answer?
+ */
+export declare function isOrderableBusinessDate(value: string): boolean;
+/**
+ * @internal #1459 — the refusal, phrased once so the guard and `closePeriod()`
+ * cannot drift on what "malformed" means or on how they say it.
+ */
+export declare function malformedBusinessDate(where: string, value: string): ValidationError;
 /**
  * Throw `PeriodClosedError` if the record being touched falls within
  * any closed period.
  *
- * Three signals, evaluated per period:
+ * Per period, per side (existing record / incoming record):
  *
  *  1. If the period declares a `dateField`, the guard reads
  *     `record[dateField]` on BOTH the existing (prior) record AND the
- *     incoming (new) record. Either comparing `<= endDate` triggers
- *     the error — callers cannot slide a record into a closed period
- *     by editing its date field.
+ *     incoming (new) record, each under its OWN partition. Either comparing
+ *     `<= endDate` triggers the error — callers cannot slide a record into a
+ *     closed period by editing its date field.
+ *     #1455 — value shapes: a string is compared as-is (ISO-8601 assumed —
+ *     the comparison is lexicographic); a `Date` is compared as the ISO string
+ *     it will be stored as; `undefined` / `null` means the record carries no
+ *     business date and belongs to NO period; anything else is REFUSED with
+ *     `ValidationError` — a date the gate cannot evaluate is not a permission.
  *  2. If the period has no `dateField`, the guard falls back to the
  *     envelope `_ts` of the existing record. Fresh inserts (no
  *     existing envelope) pass.
  *  3. For a delete, only the existing side is checked.
  *
+ * #1456 — a value is OWNED by the closed period in its timeline with the
+ * smallest `endDate` at or after it. When that owner is effectively reopened,
+ * no later close vetoes the value: reopening January frees January-dated
+ * rows even with February and March closed, and February's rows stay sealed.
+ *
  * @internal
  */
 export declare function assertTsWritable(existing: {

package/dist/with-audit/periods/reserved-collections.d.ts

@@ -0,0 +1,3 @@
+export declare const PERIODS_RESERVED_COLLECTIONS: ReadonlySet<string>;
+/** True when `name` belongs to the periods family (#1454). */
+export declare function isPeriodsReservedCollection(name: string): boolean;

package/dist/with-audit/periods/vault-facade.d.ts

@@ -166,6 +166,23 @@ export declare class VaultPeriods {
     private mergeReopenState;
     /** Resolve one period within the timeline named by `options` (vault-wide when absent). */
     private findPeriod;
+    /**
+     * #1439 — could a closed period govern this record? Synchronous, and
+     * deliberately a SUPERSET of what {@link assertTsWritable} would refuse.
+     *
+     * Exists so a caller can tell "the period gate is registered" from "the
+     * period gate can fire for this row". Those were conflated, and the cost was
+     * that installing `withPeriods()` disabled an unrelated optimisation for
+     * every collection in the vault — with no period closed and no collection
+     * registered as a subject (#1439, measured: 0 → 250 redundant MV writes per
+     * source write).
+     *
+     * ⛔ Answers `true` whenever it cannot rule the gate out: the cache is not
+     * loaded yet, a closed period has no `dateField` to test against, or no row
+     * was supplied. A predicate that exists to permit an optimisation must fail
+     * towards "the gate applies", never away from it.
+     */
+    couldGovern(record?: Record<string, unknown>): boolean;
     /** Called by the gate bus before put/delete. `collection` selects the subject mapping (#1005). */
     assertTsWritable(existing: {
         ts: string | null;