@tensorix/metahub 0.1.11 → 0.2.1

package/dist/core/blobs-core.d.ts

@@ -0,0 +1,106 @@
+import type { DbDriver } from "./driver.ts";
+export declare const POLICY_ID = "default";
+export type Redundancy = "all" | "any";
+export interface BlobPolicy {
+    fullNodes: string[];
+    redundancy: Redundancy;
+}
+export interface CachedBlob {
+    hash: string;
+    size: number;
+    content_type: string | null;
+    last_access: number | null;
+    /** Node-local pin: 1 = never auto-evicted / cleared (does not sync). */
+    pinned: number;
+    /** 1 = bytes produced here, not yet flushed to a durable anchor — protected. */
+    pending: number;
+    /** Node-local: 1 = the last presence verify confirmed a designated anchor holds
+     *  this blob (per redundancy). Drives isClearable; reset to 0 on policy change. */
+    anchored: number;
+}
+export interface CacheStats {
+    /** Total bytes currently held in the node-local cache. */
+    totalBytes: number;
+    /** Bytes safe to clear (durable on the required full set). */
+    clearableBytes: number;
+    /** Bytes that cannot be cleared (sole copy / no anchor / this is a full node). */
+    retainedBytes: number;
+    count: number;
+    clearableCount: number;
+}
+export declare function readPolicy(db: DbDriver): BlobPolicy;
+/** Designate the full-blob anchors (synced workspace policy). Each entry is
+ *  either a node id (a device that keeps everything) OR a bucket url `s3://…`
+ *  (object storage as a durable full library). Bucket urls never match a node id,
+ *  so isFullBlobNode()/isClearable() are unaffected — they're a visible guardrail. */
+export declare const setFullNodes: (db: DbDriver, nodeIds: string[]) => void;
+export declare const setRedundancy: (db: DbDriver, redundancy: Redundancy) => void;
+/** Is `node` (default: this device) a designated full-blob library? */
+export declare function isFullBlobNode(db: DbDriver, node?: string): boolean;
+/**
+ * Whether this device may safely drop `hash`'s local bytes — a purely LOCAL,
+ * offline decision read from local flags. Clearable requires ALL of:
+ *  1. This node is not itself the full-blob library (a full node keeps everything).
+ *  2. The blob is not a `pending` production (bytes produced here, not yet flushed
+ *     to an anchor) — the only locally-unique copy.
+ *  3. `anchored == 1`: the last presence verify confirmed a designated anchor holds
+ *     this blob, per redundancy(any/all). Until a verify runs (or after a policy
+ *     change resets it), anchored is 0 → nothing is clearable (conservative). This
+ *     replaces the earlier coarse "an anchor is designated" floor with a per-blob,
+ *     freshly-verified fact. See verifyAnchorPresence (blobs.ts) and
+ *     docs/impl-context/22-blob-sync (D4, on-demand presence verify).
+ */
+export declare function isClearable(db: DbDriver, hash: string): boolean;
+/** Record/clear the per-blob "a designated anchor verifiably holds this" flag. */
+export declare function setAnchored(db: DbDriver, hash: string, anchored: boolean): void;
+export declare function isAnchored(db: DbDriver, hash: string): boolean;
+/** Drop every verified verdict (after a policy change) — forces a re-verify before
+ *  anything is clearable again. Also clears the last-verified stamp. */
+export declare function invalidateAnchored(db: DbDriver): void;
+/** Epoch-ms of the last successful presence verify, or null if never / invalidated. */
+export declare function readBlobVerifiedAt(db: DbDriver): number | null;
+export declare function writeBlobVerifiedAt(db: DbDriver, ts: number): void;
+/** Blob hashes referenced by a `/blob/<hash>` URL inside a markdown/text value. */
+export declare function blobRefsIn(text: string | null): string[];
+/**
+ * Every blob hash a live document or site still points at. Union of:
+ *  - site_files rows stored as a blob (content = hash), and
+ *  - `/blob/<hash>` references inside live doc_blocks markdown (doc images).
+ * Drives GC (orphan = not in this set) and a full node's byte acquisition.
+ */
+export declare function referencedHashes(db: DbDriver): Set<string>;
+/** Record/refresh a blob's ledger row after its bytes land in the cache. */
+/** Record/refresh a cached blob. `pending`: 1 for bytes PRODUCED here (must flush
+ *  to an anchor before they're clearable), 0 for an ACQUIRED cache copy (already
+ *  durable at its source). */
+export declare function recordBlob(db: DbDriver, hash: string, size: number, contentType?: string | null, pending?: number): void;
+/** Mark a blob flushed (0) or pending (1). Flush is set after the bytes are
+ *  confirmed at the durable anchor (see blobs.ts blobMaintenance). */
+export declare function setPending(db: DbDriver, hash: string, pending: boolean): void;
+/** Bump last_access on a cache hit (LRU signal for stats/future eviction). */
+export declare function touchBlob(db: DbDriver, hash: string): void;
+export declare function forgetBlob(db: DbDriver, hash: string): void;
+export declare function cachedBlobs(db: DbDriver): CachedBlob[];
+/** Blobs produced here that are not yet flushed to a durable anchor (the upload
+ *  worklist; steady state is empty). */
+export declare function pendingBlobs(db: DbDriver): {
+    hash: string;
+    size: number;
+}[];
+/** Pin/unpin a cached blob (node-local; never synced). Returns true when a row
+ *  was updated (false when the hash isn't in the ledger). */
+export declare function setPinned(db: DbDriver, hash: string, pinned: boolean): boolean;
+/** Is a cached blob pinned? (false when not in the ledger). */
+export declare function isPinned(db: DbDriver, hash: string): boolean;
+/** Recorded content type for a cached blob (null when unknown / not cached). */
+export declare function blobContentType(db: DbDriver, hash: string): string | null;
+export declare function cacheStats(db: DbDriver): CacheStats;
+export interface KnownNode {
+    nodeId: string;
+    label: string | null;
+    self: boolean;
+}
+/** Distinct node ids this device knows about (self + outbound peers + grantees),
+ *  for the "pick a full-blob device" selector in Settings / CLI. */
+export declare function knownNodes(db: DbDriver): KnownNode[];
+//# sourceMappingURL=blobs-core.d.ts.map

package/dist/core/blobs-core.d.ts.map

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

package/dist/core/blobs.d.ts

@@ -0,0 +1,110 @@
+import type { DbDriver } from "./driver.ts";
+export * from "./blobs-core.ts";
+export interface KnownBucket {
+    url: string;
+    label: string | null;
+    bucket: string | null;
+}
+/** Attached object-storage buckets (s3 peers), for the "pick a full-blob anchor"
+ *  selector in Settings. A bucket is a durable full-blob library but is NOT a node
+ *  (1:N store-and-forward, no single node id), so it lives alongside knownNodes()
+ *  rather than inside it — designated by its synthetic url, not a node_id. */
+export declare function knownBuckets(db: DbDriver): KnownBucket[];
+/**
+ * Resolve a blob's bytes by content hash: local cache → each enabled HTTP peer's
+ * `GET /blob/<hash>?local=1` (local=1 keeps the peer from re-resolving, so there
+ * are no fetch loops) → each attached bucket's `blobs/<hash>`. Content-addressed,
+ * so every source is verified by re-hashing and any source is interchangeable.
+ * The first verified hit is cached locally and returned; null when unreachable.
+ */
+export declare function resolveBlob(db: DbDriver, hash: string): Promise<Uint8Array | null>;
+export interface VerifyResult {
+    /** Blobs confirmed durable on the anchor set (per redundancy) → clearable. */
+    anchoredCount: number;
+    anchoredBytes: number;
+    /** Designated anchors (bucket urls / device node ids) we could not reach to
+     *  check. Under `all`, any unreachable anchor makes everything un-clearable. */
+    unreachable: string[];
+    /** Epoch-ms this verify ran. */
+    at: number;
+}
+/**
+ * Verify, right now, which locally-cached blobs a designated anchor durably holds,
+ * and record the per-blob `anchored` flag that `isClearable` reads. Buckets are
+ * checked with one paginated LIST (listBucketBlobHashes); device anchors with a
+ * `POST /api/blobs/has`. An anchor we can't reach (offline / no stored url+token /
+ * bad creds) goes into `unreachable` and is treated as NOT holding anything —
+ * conservative, so a transient outage defers clearing rather than risking loss.
+ *
+ * Redundancy: `any` → present on ≥1 reachable anchor; `all` → every designated
+ * anchor reachable AND holding it. Run on demand only (panel open / refresh /
+ * pre-eviction when over quota), never in the steady-state maintenance loop.
+ */
+export declare function verifyAnchorPresence(db: DbDriver): Promise<VerifyResult>;
+export interface BlobMaintenanceResult {
+    /** Referenced blobs a full library pulled in this round. */
+    acquired: number;
+    /** Pending productions confirmed flushed to the bucket(s) this round. */
+    flushed: number;
+    /** Blobs auto-evicted to stay under the configured cache quota. */
+    evicted: number;
+}
+/**
+ * Background blob upkeep, run from the sync tick (throttled). Cheap in steady
+ * state — it only touches work that actually exists:
+ *  1. A full blob library pulls every referenced blob it is still MISSING
+ *     (resolveBlob); self-limiting, a no-op once caught up.
+ *  2. This node flushes its own PENDING productions to each attached bucket, then
+ *     marks them flushed (→ clearable). It iterates ONLY pending blobs (empty in
+ *     steady state), so — unlike the old design — it does NOT re-read/encrypt/HEAD
+ *     every already-uploaded blob each round.
+ *  3. Evicts to stay under the cache quota.
+ */
+export declare function blobMaintenance(db: DbDriver): Promise<BlobMaintenanceResult>;
+export interface EvictResult {
+    evicted: number;
+    freedBytes: number;
+}
+/**
+ * Auto-evict clearable, unpinned blobs by least-recently-accessed order until the
+ * local cache total is at/under the low-water mark. No-op when quotaBytes <= 0
+ * (disabled) or the cache is already under quota. Only touches blobs `isClearable`
+ * marks safe (durable on the full set) and never a pinned blob — bytes stay
+ * re-fetchable, so this is loss-free.
+ */
+export declare function evictToQuota(db: DbDriver, quotaBytes: number): Promise<EvictResult>;
+export interface ClearResult {
+    /** Blobs whose bytes were dropped. */
+    cleared: number;
+    /** Actual bytes freed on disk. */
+    freedBytes: number;
+    /** Blobs left in place (sole copy / no anchor / this is a full node). */
+    skipped: number;
+}
+export interface GcResult {
+    removed: number;
+    freedBytes: number;
+}
+/**
+ * Fold on-disk cache files into the blob_cache ledger so stats/clear/gc also see
+ * blobs written before the ledger existed. content_type is unknown for these
+ * (left null — serve falls back to the URL suffix).
+ */
+export declare function reconcileCache(db: DbDriver): void;
+/** Drop the bytes of every locally-cached blob that is safe to clear (durable on
+ *  the designated full set). Reference + hash stay in the oplog, re-fetchable. */
+export declare function clearCache(db: DbDriver): Promise<ClearResult>;
+/** Drop bytes for blobs no live site_files / doc image still references (true
+ *  garbage, distinct from clearable cache). */
+export declare function gcOrphans(db: DbDriver): Promise<GcResult>;
+/** Clear a CHOSEN subset of cached blobs — the per-blob counterpart of
+ *  clearCache, for the Settings blob manager. Same safety floor: only a blob that
+ *  is unpinned AND isClearable (durable on the designated full set) has its bytes
+ *  dropped; everything else is left in place and counted as skipped. */
+export declare function clearBlobs(db: DbDriver, hashes: string[]): Promise<ClearResult>;
+/** Delete a CHOSEN subset of ORPHAN blobs — the per-blob counterpart of gcOrphans.
+ *  A hash is removed only when no live site_files / doc image still references it;
+ *  any still-referenced (or unknown) hash is skipped, so a blob a document points
+ *  at can never be deleted out from under it. */
+export declare function deleteOrphanBlobs(db: DbDriver, hashes: string[]): Promise<GcResult>;
+//# sourceMappingURL=blobs.d.ts.map

package/dist/core/blobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../../src/core/blobs.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAsB5C,cAAc,iBAAiB,CAAC;AAEhC,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;8EAG8E;AAC9E,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,WAAW,EAAE,CAYxD;AAWD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgCxF;AAID,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB;oFACgF;IAChF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;CACZ;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAoD9E;AAED,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsClF;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA4BzF;AAED,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAiBjD;AAED;kFACkF;AAClF,wBAAsB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBnE;AAED;+CAC+C;AAC/C,wBAAsB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAY/D;AAED;;;wEAGwE;AACxE,wBAAsB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBrF;AAED;;;iDAGiD;AACjD,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAazF"}

package/dist/core/cache.d.ts

@@ -4,7 +4,29 @@ export interface BlobInfo {
     size: number;
 }
 export declare function blobPath(hash: string): string;
-/** Store bytes content-addressed (sha256) under cache/. Returns its hash + path. */
+/** Content key length: sha256 truncated to 128 bits (32 hex). Shorter keys keep
+ *  doc markdown (`![](/blob/<hash>.png)`) readable; collision is negligible.
+ *  Addressing stays length-agnostic, so legacy full 64-hex refs still resolve. */
+export declare const BLOB_HASH_HEX = 32;
+/** Full sha256 hex of the bytes. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Canonical content hash for new blobs: sha256 of the bytes, truncated. */
+export declare function blobHash(bytes: Uint8Array): string;
+/** Verify fetched bytes match a content reference of either length (canonical
+ *  32-hex or legacy 64-hex) — the ref is always a prefix of the full sha256. */
+export declare function verifyBlobBytes(bytes: Uint8Array, hash: string): boolean;
+/** Store bytes content-addressed under cache/. Returns its hash + path. */
 export declare function putBlob(data: ArrayBuffer | Uint8Array | string): Promise<BlobInfo>;
 export declare function getBlob(hash: string): Promise<Uint8Array | null>;
+/** Whether this node currently holds a blob's bytes on disk — a cheap existence
+ *  check (no read). Use over the ledger when correctness depends on the bytes
+ *  actually being present (e.g. answering a peer's "do you hold X" before it
+ *  drops its own copy), since the ledger can lag a vanished file. */
+export declare function blobExists(hash: string): Promise<boolean>;
+/** Store bytes under a GIVEN content hash (not recomputed) — for caching a blob
+ *  fetched from a peer/bucket by its reference, which may be a legacy 64-hex hash
+ *  that putBlob's truncation would not reproduce. Returns the byte length. */
+export declare function putBlobAt(hash: string, bytes: Uint8Array): Promise<number>;
+/** Remove a blob's bytes from the cache. Returns its size, or 0 if absent. */
+export declare function deleteBlob(hash: string): Promise<number>;
 //# sourceMappingURL=cache.d.ts.map

package/dist/core/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,oFAAoF;AACpF,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAaxF;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAItE"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;kFAEkF;AAClF,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,oCAAoC;AACpC,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAInD;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAElD;AAED;gFACgF;AAChF,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,2EAA2E;AAC3E,wBAAsB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAWxF;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAItE;AAED;;;qEAGqE;AACrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzD;AAED;;8EAE8E;AAC9E,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAIhF;AAED,8EAA8E;AAC9E,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D"}

package/dist/core/compact.d.ts

@@ -22,9 +22,10 @@ export interface CompactOptions {
 }
 export declare function compactOplog(db: Database, opts: CompactOptions): CompactResult;
 /**
- * Delete cache blobs no longer referenced by any remaining oplog value or
- * materialized site file. Conservative: only files named like a sha256 hash
- * are candidates; anything else in the cache dir is left alone.
+ * Delete cache blobs no longer referenced by any remaining oplog value, a
+ * materialized site file, or a `/blob/<hash>` doc image reference. Conservative:
+ * only files named like a content hash (canonical 32-hex or legacy 64-hex) are
+ * candidates; anything else in the cache dir is left alone.
  */
 export declare function gcBlobs(db: Database, opts?: {
     dryRun?: boolean;

package/dist/core/compact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/core/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAsB3C,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAqBD,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAkD9E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA0CpC;AAED;0CAC0C;AAC1C,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,SAAa,GACf;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAa1E"}
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../src/core/compact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA0B3C,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAqBD,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAkD9E;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,QAAQ,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA2DpC;AAED;0CAC0C;AAC1C,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,SAAa,GACf;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAa1E"}

package/dist/core/config.d.ts

@@ -1,10 +1,17 @@
 import type { DbDriver } from "./driver.ts";
+/** Authoritative upper bound for a single POST /api/blob upload (bytes). The
+ *  WebUI applies friendlier per-kind caps (image 25MB / av 100MB / file 100MB)
+ *  client-side; this is the hard server ceiling. Override with METAHUB_MAX_BLOB_UPLOAD. */
+export declare const MAX_BLOB_UPLOAD_BYTES: number;
 export interface ServerConfig {
     host: string;
     port: number;
     /** Auto-sync poll interval in ms; <= 0 disables the timer. */
     syncIntervalMs: number;
     autoSync: boolean;
+    /** Local blob cache quota in bytes. When the cache exceeds it, the sync tick
+     *  auto-evicts clearable, unpinned blobs (LRU). <= 0 disables eviction. */
+    blobCacheQuotaBytes: number;
 }
 export declare const DEFAULT_CONFIG: ServerConfig;
 /** Persisted server config, falling back to DEFAULT_CONFIG per field. */

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQ5C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,cAAc,EAAE,YAK5B,CAAC;AAeF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,YAAY,CAW1D;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAO1F"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;2FAE2F;AAC3F,eAAO,MAAM,qBAAqB,QAAmE,CAAC;AAQtG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB;+EAC2E;IAC3E,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,cAAc,EAAE,YAM5B,CAAC;AAeF,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,GAAG,YAAY,CAc1D;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAS1F"}

package/dist/core/crdt.d.ts

@@ -11,6 +11,13 @@ export interface Change {
 /** Oplog SELECT list, locked to the Change interface (also reused by history). */
 export declare const CHANGE_COLS: readonly ["hlc", "node_id", "dataset", "row_id", "col", "value", "txn"];
 export declare const CHANGE_SELECT: string;
+/**
+ * Run `fn` with every emit stamped with `node` as its node_id (and HLC node
+ * segment) instead of the host node. INVARIANT: relies on core mutators being
+ * synchronous (set/clear around one synchronous call) — do not make the wrapped
+ * mutators async or the slot can leak across requests.
+ */
+export declare function withNodeId<T>(node: string | null, fn: () => T): T;
 /**
  * Run `fn` with all emits stamped with one shared txn id. Nested calls keep the
  * outermost group (a revert that calls updateDocument is ONE revision). `label`
@@ -19,18 +26,33 @@ export declare const CHANGE_SELECT: string;
 export declare function withChangeGroup<T>(label: string | null, fn: () => T): T;
 /** Wrap a mutator so its body runs inside one change group. */
 export declare function grouped<A extends unknown[], R>(fn: (...args: A) => R, label?: string | null): (...args: A) => R;
+/** Outcome of applying one change to the oplog. `inserted` reports whether the
+ *  oplog actually gained a NEW row (false when we already had this exact change —
+ *  the INSERT OR IGNORE was a no-op); it is the honest "did we receive new data"
+ *  signal, distinct from `winner` (whether this change now wins its register and
+ *  was materialized). Re-applying a change we already hold still returns
+ *  `winner:true` if it's the current max-HLC, so callers that want progress (not
+ *  re-materialization) must key off `inserted`. */
+export interface ApplyResult {
+    inserted: boolean;
+    winner: boolean;
+}
 /**
  * Record a change in the oplog (idempotent) and, if it is the latest write for
  * its register, materialize it. Order-independent: convergence holds regardless
  * of the order changes are applied, because the winner is recomputed as the max
  * HLC over the full oplog for that register.
  */
-export declare function applyChange(db: DbDriver, c: Change): boolean;
+export declare function applyChange(db: DbDriver, c: Change): ApplyResult;
 /** Apply a local write: assign a fresh HLC, append to oplog, materialize. */
 export declare function emit(db: DbDriver, dataset: string, rowId: string, col: string, value: unknown): Change;
 /** Apply multiple local field writes to the same row. */
 export declare function emitFields(db: DbDriver, dataset: string, rowId: string, fields: Record<string, unknown>): Change[];
-/** Apply remote changes from a sync peer (advances clock, then merges). */
+/** Apply remote changes from a sync peer (advances clock, then merges). Returns
+ *  the number of changes that were NEW to our oplog (rows actually inserted) —
+ *  the honest "received" count. Re-ingesting data we already hold returns 0, so
+ *  this is a reliable progress signal for the auto-sync backoff (a round that
+ *  only re-reads known data must not count as activity). */
 export declare function ingest(db: DbDriver, changes: Change[]): number;
 /** All oplog changes with HLC strictly greater than `since` (test/debug helper). */
 export declare function changesSince(db: DbDriver, since: string): Change[];
@@ -43,6 +65,14 @@ export interface ChangesAfterOpts {
     limit?: number;
     /** Datasets to omit (partial replicas, e.g. a phone skipping site_files). */
     excludeDatasets?: string[];
+    /**
+     * Return only changes this node produced itself. Storage-sync (see
+     * sync/storage.ts) publishes each node's own ops under its own bucket prefix,
+     * so it must not re-upload ops it merely ingested from peers. The cursor still
+     * advances over the filtered-out rows (high-water on exhaustion), so ingested
+     * ops are skipped once, not rescanned every round.
+     */
+    onlyNode?: string;
 }
 /**
  * Changes inserted after `seq` (a local rowid), in insertion order, plus the

package/dist/core/crdt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/core/crdt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAW5C,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,kFAAkF;AAClF,eAAO,MAAM,WAAW,yEAA0E,CAAC;AAEnG,eAAO,MAAM,aAAa,QAAyB,CAAC;AAMpD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQvE;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC5C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACrB,KAAK,GAAE,MAAM,GAAG,IAAW,GAC1B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAEnB;AA0ID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAc5D;AAED,6EAA6E;AAC7E,wBAAgB,IAAI,CAClB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,MAAM,CAaR;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CACxB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,EAAE,CAMV;AAED,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAW9D;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,gBAAqB,GAC1B,WAAW,CAuBb"}
+{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/core/crdt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAW5C,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,kFAAkF;AAClF,eAAO,MAAM,WAAW,yEAA0E,CAAC;AAEnG,eAAO,MAAM,aAAa,QAAyB,CAAC;AAapD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAQvE;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC5C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACrB,KAAK,GAAE,MAAM,GAAG,IAAW,GAC1B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAEnB;AAkJD;;;;;;mDAMmD;AACnD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAiBhE;AAED,6EAA6E;AAC7E,wBAAgB,IAAI,CAClB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACb,MAAM,CAaR;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CACxB,EAAE,EAAE,QAAQ,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,EAAE,CAMV;AAED;;;;4DAI4D;AAC5D,wBAAgB,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAW9D;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,gBAAqB,GAC1B,WAAW,CAkCb"}

package/dist/core/schema-init.d.ts

@@ -9,9 +9,12 @@ export declare function ftsAvailable(db: DbDriver): boolean;
 export declare function migrateRecords(db: DbDriver): void;
 /**
  * Add the peer-pairing columns to a legacy `peers` table (token/label/node_id/
- * enabled/last_sync_at/last_status/last_error). Idempotent — guarded per column,
- * never drops the table so existing replication cursors survive.
+ * enabled/last_sync_at/last_success_at/last_status/last_error). Idempotent —
+ * guarded per column, never drops the table so existing replication cursors survive.
  */
+/** Add `served_base` to a `shares` table created before the column existed
+ *  (idempotent). The vestigial s3_* columns are left as-is. */
+export declare function migrateShares(db: DbDriver): void;
 export declare function migratePeers(db: DbDriver): void;
 /**
  * Add the `blank_after` column to a legacy `doc_blocks` table. Idempotent —
@@ -19,6 +22,18 @@ export declare function migratePeers(db: DbDriver): void;
  * separators), so the migration never changes an existing document's body.
  */
 export declare function migrateDocBlocks(db: DbDriver): void;
+/**
+ * Bring a legacy `blob_cache` to the current shape and retire the old synced
+ * `blob_presence` table. Idempotent (guarded by hasColumn / IF EXISTS).
+ *  - `pinned`: node-local, never auto-evicted/cleared.
+ *  - `pending`: bytes produced here, not yet flushed to a durable anchor. Existing
+ *    rows can't be classified produced-vs-acquired, so default to 1 (protected);
+ *    the next online flush sets already-in-bucket blobs back to 0, so it self-heals
+ *    and is loss-free. See blobs.ts.
+ *  - `blob_presence` (was synced) is dropped: clearing is now decided locally from
+ *    `pending`. Leftover presence oplog changes are ignored (forward-compat).
+ */
+export declare function migrateBlobCache(db: DbDriver): void;
 /**
  * Add the `order_key` column to a legacy `documents` table and backfill it.
  * Idempotent — guarded by hasColumn; backfill only touches rows with a NULL key,
@@ -32,6 +47,51 @@ export declare function migrateDocuments(db: DbDriver): void;
  * back to time-gap clustering for them).
  */
 export declare function migrateOplog(db: DbDriver): void;
+/**
+ * Rebuild a legacy `crdt_changes` (composite PRIMARY KEY, implicit rowid) into
+ * the current shape with an explicit `seq INTEGER PRIMARY KEY AUTOINCREMENT`.
+ *
+ * Why: replication push/pull cursors are crdt_changes rowids. The legacy table
+ * has no declared INTEGER PRIMARY KEY, so a `VACUUM` (run by `mh` compaction)
+ * renumbers its rowids 1..N; a peer's stored cursor then sits above the new
+ * MAX(rowid) and `changesAfterSeq`'s "never regress" floor pins it there,
+ * silently never pushing/pulling the writes below it. The declared `seq` is
+ * stable across VACUUM and never reused, closing the hole.
+ *
+ * Idempotent — guarded by the `seq` column. Old rowids are copied verbatim into
+ * seq so any *uncorrupted* cursor stays meaningful; then push/pull cursors are
+ * reset to 0 because we cannot tell which were already stranded by a past
+ * VACUUM, and a from-scratch re-sync is safe (INSERT OR IGNORE / ingest dedup)
+ * — a one-time catch-up on first sync after upgrade. storage_cursors are
+ * object-key based, never rowids, so they are left intact.
+ */
+export declare function migrateCrdtChangesSeq(db: DbDriver): void;
+/**
+ * Migrate legacy storage-peer keys `s3://<bucket>/<prefix>` to the
+ * endpoint-qualified `s3://<host>/<bucket>/<prefix>` so two endpoints sharing a
+ * bucket name (R2/MinIO/COS each have their own namespace) no longer collide and
+ * silently overwrite each other's peer row (and stale cursor). Rewrites all three
+ * places the key is referenced — the peers row, its storage_cursors, and any
+ * blob_policy.fullNodes anchor pointing at the bucket.
+ *
+ * Key derivation goes through the shared `storageUrl` (storage-url.ts) so every
+ * producer — CLI/server, the WebUI worker, and this migration — agrees byte for
+ * byte; otherwise a producer still minting the legacy shape turns the rename into
+ * a permanent whack-a-mole.
+ *
+ * Idempotent — a row already at its endpoint-qualified key produces no rename.
+ * Keyed off config.endpoint (authoritative), so re-running is a no-op.
+ *
+ * Cross-version note: rewriting blob_policy.fullNodes is a CRDT write, so it
+ * replicates. A device still on the old code keeps a legacy-format storage peer
+ * and matches anchors by exact string, so it won't recognize the new-format
+ * anchor until it upgrades — during that window a bucket-anchored device pauses
+ * cache eviction (loss-free: bytes stay, nothing is dropped) and self-heals once
+ * the fleet is upgraded. Only affects setups that designate a bucket as a
+ * full-blob anchor. (Accepted over a tolerant-matcher rewrite, which is wider and
+ * still can't fix already-shipped old clients.)
+ */
+export declare function migrateStoragePeerUrls(db: DbDriver): void;
 /** Bring a freshly opened (or legacy) database to the current schema. */
 export declare function initSchema(db: DbDriver): void;
 //# sourceMappingURL=schema-init.d.ts.map

package/dist/core/schema-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-init.d.ts","sourceRoot":"","sources":["../../src/core/schema-init.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAO5C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAKlD;AAeD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAuBjD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAa/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAInD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAG/C;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAO7C"}
+{"version":3,"file":"schema-init.d.ts","sourceRoot":"","sources":["../../src/core/schema-init.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAO5C,wBAAgB,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAO5C;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAKlD;AAeD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAuBjD;AAED;;;;GAIG;AACH;+DAC+D;AAC/D,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAGhD;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAsB/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAGnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAQnD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAInD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAG/C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CA4BxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAuDzD;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAW7C"}

package/dist/core/schema.d.ts

@@ -1,3 +1,3 @@
-export declare const CORE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT\n);\n\n-- CRDT oplog: one row per field assignment. Source of truth for sync.\n-- txn groups the changes of one logical mutation for history rendering\n-- (nullable: legacy rows and changes from pre-txn peers have none).\nCREATE TABLE IF NOT EXISTS crdt_changes (\n  hlc     TEXT NOT NULL,\n  node_id TEXT NOT NULL,\n  dataset TEXT NOT NULL,\n  row_id  TEXT NOT NULL,\n  col     TEXT NOT NULL,\n  value   TEXT,\n  txn     TEXT,\n  PRIMARY KEY (dataset, row_id, col, hlc)\n);\nCREATE INDEX IF NOT EXISTS idx_changes_hlc ON crdt_changes(hlc);\n-- Serves history's \"every block ever attached to this doc\" lookup. Partial so\n-- it never indexes the large values other datasets carry (e.g. site file bodies).\nCREATE INDEX IF NOT EXISTS idx_changes_docref ON crdt_changes(value)\n  WHERE dataset = 'doc_blocks' AND col = 'doc_id';\n\n-- Per-peer replication cursors (SQLite rowids: monotonic in insertion order,\n-- so no change is ever skipped regardless of HLC/clock skew). Outbound side of\n-- a pairing: \"token\" is the credential the *remote* issued to us (sent as a\n-- Bearer header when we sync to them). See migratePeers in db.ts for the columns\n-- added to legacy databases.\nCREATE TABLE IF NOT EXISTS peers (\n  url          TEXT PRIMARY KEY,\n  pull_cursor  INTEGER NOT NULL DEFAULT 0,\n  push_cursor  INTEGER NOT NULL DEFAULT 0,\n  token        TEXT,\n  label        TEXT,\n  node_id      TEXT,\n  enabled      INTEGER NOT NULL DEFAULT 1,\n  last_sync_at INTEGER,\n  last_status  TEXT,\n  last_error   TEXT\n);\n\n-- Inbound side of a pairing: credentials *we* issued to remote devices. A peer\n-- presents one of these on /sync; acceptsSyncToken() checks it alongside the\n-- managed master token. Revoke by deleting the row.\nCREATE TABLE IF NOT EXISTS peer_grants (\n  token      TEXT PRIMARY KEY,\n  peer_url   TEXT,\n  node_id    TEXT,\n  created_at INTEGER\n);\n\n-- One-time pairing codes minted by \"mh config peer code\" / POST /api/pair/new.\n-- Short-lived and single-use: redeemed during the pairing handshake, then the\n-- two devices exchange durable peer_grants. used/exp gate redemption.\nCREATE TABLE IF NOT EXISTS pairing_codes (\n  code       TEXT PRIMARY KEY,\n  exp        INTEGER NOT NULL,\n  used       INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER\n);\n\nCREATE TABLE IF NOT EXISTS databases (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,\n  icon        TEXT,\n  created_hlc TEXT,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE TABLE IF NOT EXISTS properties (\n  id          TEXT PRIMARY KEY,\n  database_id TEXT,\n  name        TEXT,\n  type        TEXT,\n  config      TEXT,\n  position    REAL,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_properties_db ON properties(database_id);\n\n-- One row per record. Field cells live in the data JSON object, keyed by\n-- property id (rename-safe). Each (record,property) is still an independent\n-- CRDT register in the oplog; materialize() folds the winner into data via\n-- json_set/json_remove. Hot fields get expression indexes on data->>'propid'\n-- (see indexing.ts) so filter/sort/limit push down to SQL.\nCREATE TABLE IF NOT EXISTS records (\n  id          TEXT PRIMARY KEY,\n  database_id TEXT,\n  created_hlc TEXT,\n  order_key   TEXT,\n  data        TEXT NOT NULL DEFAULT '{}',\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_records_db_hlc ON records(database_id, created_hlc);\n\nCREATE TABLE IF NOT EXISTS documents (\n  id          TEXT PRIMARY KEY,\n  title       TEXT,\n  body        TEXT,        -- materialized cache: serialized from doc_blocks\n  database_id TEXT,\n  parent_id   TEXT,\n  created_hlc TEXT,\n  order_key   TEXT,        -- fractional index among siblings (same parent_id); ties broken by created_hlc,id\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\n-- Document body as an ordered list of blocks; each (block,field) is an\n-- independent CRDT register so concurrent edits to different blocks merge.\n-- order_key is a fractional index (ties broken by id) giving display order.\nCREATE TABLE IF NOT EXISTS doc_blocks (\n  id          TEXT PRIMARY KEY,\n  doc_id      TEXT,\n  text        TEXT,\n  order_key   TEXT,\n  blank_after INTEGER NOT NULL DEFAULT 0,  -- extra blank lines kept after this block (user spacing)\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_doc_blocks_doc ON doc_blocks(doc_id);\n\n-- A named static site (Supabase-Storage-style bucket). Served at /sites/<name>/.\nCREATE TABLE IF NOT EXISTS sites (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,        -- URL slug; resolved by getSiteByName\n  title       TEXT,\n  created_hlc TEXT,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\n-- One row per file in a site. content holds inline utf8/base64 text, or a blob\n-- hash (see cache.ts) when encoding = 'blob'. (site_id, path) maps to a stable\n-- id so re-uploads merge as a CRDT register instead of duplicating.\nCREATE TABLE IF NOT EXISTS site_files (\n  id           TEXT PRIMARY KEY,\n  site_id      TEXT,\n  path         TEXT,\n  content_type TEXT,\n  encoding     TEXT,       -- 'utf8' | 'base64' | 'blob'\n  content      TEXT,\n  created_hlc  TEXT,\n  __deleted    INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_site_files_site ON site_files(site_id);\n";
+export declare const CORE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS meta (\n  key   TEXT PRIMARY KEY,\n  value TEXT\n);\n\n-- CRDT oplog: one row per field assignment. Source of truth for sync.\n-- txn groups the changes of one logical mutation for history rendering\n-- (nullable: legacy rows and changes from pre-txn peers have none).\n--\n-- seq is an explicit AUTOINCREMENT id used as the replication cursor. It must\n-- be a declared INTEGER PRIMARY KEY (not the implicit rowid): VACUUM renumbers\n-- the rowids of tables that lack one, which would shift them below a peer's\n-- stored push/pull cursor and silently strand every write in the gap.\n-- AUTOINCREMENT additionally guarantees ids are never reused. The\n-- (dataset,row_id,col,hlc) tuple stays UNIQUE so applyChange's INSERT OR IGNORE\n-- dedup is unchanged. Legacy databases are rebuilt into this shape by\n-- migrateCrdtChangesSeq (schema-init.ts).\nCREATE TABLE IF NOT EXISTS crdt_changes (\n  seq     INTEGER PRIMARY KEY AUTOINCREMENT,\n  hlc     TEXT NOT NULL,\n  node_id TEXT NOT NULL,\n  dataset TEXT NOT NULL,\n  row_id  TEXT NOT NULL,\n  col     TEXT NOT NULL,\n  value   TEXT,\n  txn     TEXT,\n  UNIQUE (dataset, row_id, col, hlc)\n);\nCREATE INDEX IF NOT EXISTS idx_changes_hlc ON crdt_changes(hlc);\n-- Serves history's \"every block ever attached to this doc\" lookup. Partial so\n-- it never indexes the large values other datasets carry (e.g. site file bodies).\nCREATE INDEX IF NOT EXISTS idx_changes_docref ON crdt_changes(value)\n  WHERE dataset = 'doc_blocks' AND col = 'doc_id';\n\n-- Per-peer replication cursors (crdt_changes.seq: AUTOINCREMENT, monotonic in\n-- insertion order and stable across VACUUM, so no change is ever skipped\n-- regardless of HLC/clock skew). Outbound side of\n-- a pairing: \"token\" is the credential the *remote* issued to us (sent as a\n-- Bearer header when we sync to them). See migratePeers in db.ts for the columns\n-- added to legacy databases.\n--\n-- kind selects the transport: 'http' (POST /sync to a peer server, the classic\n-- path) or 's3' (an S3-compatible bucket used as dumb store-and-forward \u2014 see\n-- sync/storage.ts). For 's3' peers url is a synthetic key (s3://<bucket>/<prefix>)\n-- and config holds the bucket settings + credentials + master key as JSON.\n-- Like the rest of peers, config is local-only and never enters the CRDT oplog.\nCREATE TABLE IF NOT EXISTS peers (\n  url          TEXT PRIMARY KEY,\n  pull_cursor  INTEGER NOT NULL DEFAULT 0,\n  push_cursor  INTEGER NOT NULL DEFAULT 0,\n  token        TEXT,\n  label        TEXT,\n  node_id      TEXT,\n  enabled      INTEGER NOT NULL DEFAULT 1,\n  last_sync_at INTEGER,\n  last_success_at INTEGER,\n  last_status  TEXT,\n  last_error   TEXT,\n  kind         TEXT NOT NULL DEFAULT 'http',\n  config       TEXT\n);\n\n-- Per-(storage-peer, remote-node) pull progress: the key of the last oplog\n-- segment we consumed from that node's bucket prefix. HTTP peers use the single\n-- pull_cursor above; storage peers need one cursor per remote node because each\n-- node publishes its own segment stream under its own prefix. last_key is a\n-- bucket object key (lexicographically ordered = chronological), so LIST\n-- start-after resumes exactly where we left off.\nCREATE TABLE IF NOT EXISTS storage_cursors (\n  peer_url TEXT NOT NULL,\n  node_id  TEXT NOT NULL,\n  last_key TEXT,\n  PRIMARY KEY (peer_url, node_id)\n);\n\n-- Inbound side of a pairing: credentials *we* issued to remote devices. A peer\n-- presents one of these on /sync; acceptsSyncToken() checks it alongside the\n-- managed master token. Revoke by deleting the row.\nCREATE TABLE IF NOT EXISTS peer_grants (\n  token      TEXT PRIMARY KEY,\n  peer_url   TEXT,\n  node_id    TEXT,\n  created_at INTEGER\n);\n\n-- One-time pairing codes minted by \"mh config peer code\" / POST /api/pair/new.\n-- Short-lived and single-use: redeemed during the pairing handshake, then the\n-- two devices exchange durable peer_grants. used/exp gate redemption.\nCREATE TABLE IF NOT EXISTS pairing_codes (\n  code       TEXT PRIMARY KEY,\n  exp        INTEGER NOT NULL,\n  used       INTEGER NOT NULL DEFAULT 0,\n  created_at INTEGER\n);\n\n-- Public capability links to a doc / database / site. Like peers and blob_cache\n-- this is node-local and deliberately ABSENT from crdt.ts's DOMAIN map, so it\n-- never enters the oplog and never syncs \u2014 a share is a property of the access\n-- point that minted it, not of the workspace. slug is the unguessable capability\n-- in the URL (/share/<slug>). transport selects how it's served: 'server' (the\n-- token-exempt /share endpoint on this node) or 's3' (a presigned static export\n-- under <prefix>/shares/<slug> in a bucket). permission 'edit' is server-only:\n-- a presigned static object can't accept writes. guest_node_id attributes every\n-- edit made through an edit-share to one synthetic node (see crdt.ts withNodeId).\n-- pw_hash/pw_salt: server path stores a PBKDF2 verifier; the s3 path is E2EE so\n-- only pw_salt travels (in the link) and decryption happens in the viewer.\nCREATE TABLE IF NOT EXISTS shares (\n  slug             TEXT PRIMARY KEY,\n  kind             TEXT NOT NULL,   -- 'doc' | 'database' | 'site'\n  target_id        TEXT NOT NULL,   -- documents.id / databases.id / sites.id\n  permission       TEXT NOT NULL,   -- 'view' | 'edit'\n  transport        TEXT NOT NULL,   -- 'server' | 's3'\n  pw_salt          TEXT,            -- base64; null = no password\n  pw_hash          TEXT,            -- base64 PBKDF2 verifier (server path only)\n  expires_at       INTEGER,         -- epoch ms; null = never\n  guest_node_id    TEXT,            -- synthetic node id for edit shares (null for view)\n  served_base      TEXT,            -- reachable base URL chosen at creation (link / source label)\n  s3_peer_url      TEXT,            -- vestigial (s3 shares live in the bucket, not here)\n  s3_object_prefix TEXT,            -- vestigial\n  s3_presign_exp   INTEGER,         -- vestigial\n  s3_key_b64       TEXT,            -- vestigial\n  created_at       INTEGER NOT NULL\n);\nCREATE INDEX IF NOT EXISTS idx_shares_target ON shares(target_id);\n\nCREATE TABLE IF NOT EXISTS databases (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,\n  icon        TEXT,\n  created_hlc TEXT,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\nCREATE TABLE IF NOT EXISTS properties (\n  id          TEXT PRIMARY KEY,\n  database_id TEXT,\n  name        TEXT,\n  type        TEXT,\n  config      TEXT,\n  position    REAL,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_properties_db ON properties(database_id);\n\n-- One row per record. Field cells live in the data JSON object, keyed by\n-- property id (rename-safe). Each (record,property) is still an independent\n-- CRDT register in the oplog; materialize() folds the winner into data via\n-- json_set/json_remove. Hot fields get expression indexes on data->>'propid'\n-- (see indexing.ts) so filter/sort/limit push down to SQL.\nCREATE TABLE IF NOT EXISTS records (\n  id          TEXT PRIMARY KEY,\n  database_id TEXT,\n  created_hlc TEXT,\n  order_key   TEXT,\n  data        TEXT NOT NULL DEFAULT '{}',\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_records_db_hlc ON records(database_id, created_hlc);\n\nCREATE TABLE IF NOT EXISTS documents (\n  id          TEXT PRIMARY KEY,\n  title       TEXT,\n  body        TEXT,        -- materialized cache: serialized from doc_blocks\n  database_id TEXT,\n  parent_id   TEXT,\n  created_hlc TEXT,\n  order_key   TEXT,        -- fractional index among siblings (same parent_id); ties broken by created_hlc,id\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\n-- Document body as an ordered list of blocks; each (block,field) is an\n-- independent CRDT register so concurrent edits to different blocks merge.\n-- order_key is a fractional index (ties broken by id) giving display order.\nCREATE TABLE IF NOT EXISTS doc_blocks (\n  id          TEXT PRIMARY KEY,\n  doc_id      TEXT,\n  text        TEXT,\n  order_key   TEXT,\n  blank_after INTEGER NOT NULL DEFAULT 0,  -- extra blank lines kept after this block (user spacing)\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_doc_blocks_doc ON doc_blocks(doc_id);\n\n-- A named static site (Supabase-Storage-style bucket). Served at /sites/<name>/.\nCREATE TABLE IF NOT EXISTS sites (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,        -- URL slug; resolved by getSiteByName\n  title       TEXT,\n  created_hlc TEXT,\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n\n-- One row per file in a site. content holds inline utf8/base64 text, or a blob\n-- hash (see cache.ts) when encoding = 'blob'. (site_id, path) maps to a stable\n-- id so re-uploads merge as a CRDT register instead of duplicating.\nCREATE TABLE IF NOT EXISTS site_files (\n  id           TEXT PRIMARY KEY,\n  site_id      TEXT,\n  path         TEXT,\n  content_type TEXT,\n  encoding     TEXT,       -- 'utf8' | 'base64' | 'blob'\n  content      TEXT,\n  created_hlc  TEXT,\n  __deleted    INTEGER NOT NULL DEFAULT 0\n);\nCREATE INDEX IF NOT EXISTS idx_site_files_site ON site_files(site_id);\n\n-- Node-local blob cache ledger (NOT synced, like peers/storage_cursors): one row\n-- per blob byte-file held in cache.ts's content-addressed store (~/.metahub/cache).\n-- Gives the bare hash-named files the metadata clearing/stats need. hash is the\n-- canonical content key (sha256 truncated to 32 hex; legacy 64-hex coexist).\n-- pending = bytes produced HERE not yet confirmed flushed to a durable anchor\n-- (bucket) \u2014 the only blobs a device must protect; never auto-evicted/cleared.\n-- pending=0 means a flushed production OR an acquired cache, both safely\n-- clearable (re-fetchable). This local fact replaces the old SYNCED blob_presence\n-- table \u2014 clearing is now purely local/offline. See blobs.ts / 22-blob-sync.\nCREATE TABLE IF NOT EXISTS blob_cache (\n  hash         TEXT PRIMARY KEY,\n  size         INTEGER NOT NULL,\n  content_type TEXT,\n  last_access  INTEGER,\n  pinned       INTEGER NOT NULL DEFAULT 0, -- node-local: never auto-evicted / cleared\n  pending      INTEGER NOT NULL DEFAULT 1, -- produced here, not yet flushed to anchor\n  anchored     INTEGER NOT NULL DEFAULT 0  -- node-local: last verify confirmed a designated anchor holds it (per redundancy). Drives isClearable; reset on policy change\n);\n\n-- Synced workspace policy (single row \"default\"): which nodes are designated\n-- full-blob libraries \u2014 the durable anchor in no-bucket topologies (they pull\n-- everything and never clear). full_nodes is a JSON array of node_id; redundancy\n-- is retained but unused since clearing moved to the local pending model.\nCREATE TABLE IF NOT EXISTS blob_policy (\n  id          TEXT PRIMARY KEY,  -- always \"default\"\n  full_nodes  TEXT,              -- JSON array of node_id\n  redundancy  TEXT,              -- 'all' | 'any'\n  __deleted   INTEGER NOT NULL DEFAULT 0\n);\n";
 export declare const FTS_SCHEMA = "\nCREATE VIRTUAL TABLE IF NOT EXISTS search_fts USING fts5(\n  kind UNINDEXED,\n  id UNINDEXED,\n  database_id UNINDEXED,\n  title,\n  body\n);\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/core/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,kzKAgJvB,CAAC;AAGF,eAAO,MAAM,UAAU,sJAQtB,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,kxVA6OvB,CAAC;AAGF,eAAO,MAAM,UAAU,sJAQtB,CAAC"}

package/dist/core/shares.d.ts

@@ -0,0 +1,60 @@
+import type { DbDriver } from "./driver.ts";
+export type ShareKind = "doc" | "database" | "site";
+export type SharePermission = "view" | "edit";
+export type ShareTransport = "server" | "s3";
+export interface ShareRow {
+    slug: string;
+    kind: ShareKind;
+    target_id: string;
+    permission: SharePermission;
+    transport: ShareTransport;
+    /** base64 salt; null = no password. */
+    pw_salt: string | null;
+    /** base64 PBKDF2 verifier — server path only (s3 password is client-side E2EE). */
+    pw_hash: string | null;
+    /** epoch ms; null = never. */
+    expires_at: number | null;
+    /** synthetic node id every edit through this share is attributed to (edit only). */
+    guest_node_id: string | null;
+    /** Reachable base URL chosen at creation (for the link / source label). */
+    served_base: string | null;
+    s3_peer_url: string | null;
+    s3_object_prefix: string | null;
+    s3_presign_exp: number | null;
+    s3_key_b64: string | null;
+    created_at: number;
+}
+export interface CreateShareInput {
+    kind: ShareKind;
+    target_id: string;
+    permission?: SharePermission;
+    /** base64 salt + verifier (server path); produce with hashSharePassword. */
+    pwSalt?: string | null;
+    pwHash?: string | null;
+    expiresAt?: number | null;
+    /** Reachable base URL recorded for the link / source label. */
+    servedBase?: string | null;
+}
+/**
+ * Mint a server-transport share row. (Object-storage shares are NOT stored here —
+ * they live in the bucket; see sync/share-export.ts.) Validates enums + the
+ * `edit ⇒ server` rule and allocates an unguessable slug (+ guest node for edit).
+ * The caller verifies that `target_id` exists.
+ */
+export declare function createShare(db: DbDriver, input: CreateShareInput): ShareRow;
+export declare function getShare(db: DbDriver, slug: string): ShareRow | null;
+export declare function listShares(db: DbDriver): ShareRow[];
+/** Shares pointing at one target — used to surface existing links in the UI. */
+export declare function listSharesForTarget(db: DbDriver, targetId: string): ShareRow[];
+export declare function deleteShare(db: DbDriver, slug: string): boolean;
+/** True once a share is past its expiry (null expiry = never expires). */
+export declare function shareExpired(row: ShareRow, now?: number): boolean;
+/** Derive a fresh {salt, hash} verifier for the server-path password. */
+export declare function hashSharePassword(password: string): Promise<{
+    salt: string;
+    hash: string;
+}>;
+/** Constant-time check of `password` against a share's stored verifier. A share
+ *  with no password always returns true (nothing to verify). */
+export declare function verifySharePassword(row: ShareRow, password: string): Promise<boolean>;
+//# sourceMappingURL=shares.d.ts.map

package/dist/core/shares.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shares.d.ts","sourceRoot":"","sources":["../../src/core/shares.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC;AACpD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAC9C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,CAAC;AAI7C,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B,uCAAuC;IACvC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oFAAoF;IACpF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAG3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAKD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,GAAG,QAAQ,CA+B3E;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAKpE;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAInD;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAI9E;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,SAAa,GAAG,OAAO,CAErE;AA+BD,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAIjG;AAED;gEACgE;AAChE,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3F"}