@letta-ai/dreams 0.0.1

package/dist/local/config.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Local configuration stored in the `kv` table.
+ *
+ * Approved roots are the privacy gate for [06]: they are DENY-BY-DEFAULT. No
+ * transcript bytes may enter the upload queue until a work root is explicitly
+ * approved (by an internal tester now, or the source-approval UX later). This
+ * holds even though [06] performs no network calls.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalize = canonicalize;
+exports.isContainedPath = isContainedPath;
+exports.getApprovedRoots = getApprovedRoots;
+exports.approveRoot = approveRoot;
+exports.removeApprovedRoot = removeApprovedRoot;
+exports.isUnderApprovedRoot = isUnderApprovedRoot;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const db_1 = require("./db");
+const APPROVED_ROOTS_KEY = "approved_roots";
+/** Resolve symlinks/aliases to a canonical path; fall back to a lexical resolve. */
+function canonicalize(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/**
+ * Canonical, non-lexical containment. `path.relative` (never a string prefix,
+ * which would treat /work/ab as under /work/a) decides nesting; on
+ * case-insensitive platforms the comparison is case-folded. Callers pass
+ * already-canonicalized paths.
+ */
+function isContainedPath(root, target, platform = process.platform) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    let a = root;
+    let b = target;
+    if (platform === "win32") {
+        a = a.toLowerCase();
+        b = b.toLowerCase();
+    }
+    if (a === b)
+        return true;
+    const rel = p.relative(a, b);
+    return rel !== "" && !rel.startsWith("..") && !p.isAbsolute(rel);
+}
+function getKv(db, key) {
+    const row = db.prepare("SELECT value FROM kv WHERE key = ?").get(key);
+    return row ? row.value : null;
+}
+function setKv(db, key, value) {
+    db.prepare("INSERT INTO kv (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+function getApprovedRoots(db) {
+    const raw = getKv(db, APPROVED_ROOTS_KEY);
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function approveRoot(db, root) {
+    const resolved = canonicalize(root);
+    const roots = getApprovedRoots(db);
+    if (!roots.includes(resolved)) {
+        roots.push(resolved);
+        roots.sort();
+        setKv(db, APPROVED_ROOTS_KEY, JSON.stringify(roots));
+        setKv(db, `${APPROVED_ROOTS_KEY}_updated_at`, (0, db_1.nowIso)());
+    }
+    return roots;
+}
+function removeApprovedRoot(db, root) {
+    const resolved = canonicalize(root);
+    const roots = getApprovedRoots(db).filter((r) => r !== resolved);
+    setKv(db, APPROVED_ROOTS_KEY, JSON.stringify(roots));
+    return roots;
+}
+/** Canonical approved root that contains `target`, or null. Both sides are canonicalized. */
+function isUnderApprovedRoot(roots, target) {
+    const canonicalTarget = canonicalize(target);
+    for (const root of roots) {
+        if (isContainedPath(canonicalize(root), canonicalTarget))
+            return root;
+    }
+    return null;
+}

package/dist/local/db.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * Crash-safe local SQLite store for the Dreams CLI source subsystem.
+ *
+ * Uses the built-in `node:sqlite` (Node >= 22.13, no experimental flag). WAL +
+ * a busy timeout let concurrent CLI invocations touch the DB without clobbering
+ * each other; foreign keys keep source_files / cursors / queue rows consistent.
+ * Schema changes are applied as ordered, transactional migrations recorded in
+ * `kv.schema_version`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+exports.dbFilePath = dbFilePath;
+exports.tx = tx;
+exports.openDb = openDb;
+exports.closeDb = closeDb;
+exports.nowIso = nowIso;
+const node_sqlite_1 = require("node:sqlite");
+const path = __importStar(require("node:path"));
+const store_1 = require("../store");
+const version_1 = require("../version");
+function dbFilePath() {
+    return path.join((0, store_1.dreamsDir)(), "dreams.db");
+}
+/**
+ * Each migration is a list of statements applied inside one transaction. Never
+ * edit an existing migration once shipped; append a new one instead.
+ */
+const MIGRATIONS = [
+    [
+        // `kv` is created by the bootstrap below (it anchors the version counter),
+        // so migration 0 does not recreate it.
+        `CREATE TABLE installation (
+       installation_id TEXT PRIMARY KEY,
+       created_at      TEXT NOT NULL,
+       cli_version     TEXT NOT NULL
+     )`,
+        `CREATE TABLE workspace_bindings (
+       id              INTEGER PRIMARY KEY CHECK (id = 1),
+       api_base_url    TEXT,
+       workspace_id    TEXT,
+       organization_id TEXT,
+       user_id         TEXT,
+       created_at      TEXT NOT NULL,
+       updated_at      TEXT NOT NULL
+     )`,
+        `CREATE TABLE sources (
+       id                  TEXT PRIMARY KEY,
+       source_type         TEXT NOT NULL,
+       source_key          TEXT NOT NULL,
+       display_name        TEXT NOT NULL,
+       root_path           TEXT,
+       adapter_version     TEXT NOT NULL,
+       privacy_config_hash TEXT,
+       backfill_policy     TEXT,
+       status              TEXT NOT NULL,
+       server_source_id    TEXT,
+       created_at          TEXT NOT NULL,
+       updated_at          TEXT NOT NULL,
+       UNIQUE (source_type, source_key)
+     )`,
+        `CREATE TABLE source_files (
+       id             INTEGER PRIMARY KEY AUTOINCREMENT,
+       source_id      TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+       session_id     TEXT NOT NULL,
+       generation     INTEGER NOT NULL,
+       path           TEXT NOT NULL,
+       cwd            TEXT,
+       inode          TEXT,
+       birthtime_ms   INTEGER,
+       size           INTEGER NOT NULL DEFAULT 0,
+       mtime_ms       INTEGER,
+       first_chunk_fp TEXT,
+       prefix_fp      TEXT,
+       is_current     INTEGER NOT NULL DEFAULT 1,
+       created_at     TEXT NOT NULL,
+       updated_at     TEXT NOT NULL,
+       UNIQUE (source_id, session_id, generation)
+     )`,
+        `CREATE INDEX idx_source_files_session ON source_files (source_id, session_id, is_current)`,
+        `CREATE TABLE source_cursors (
+       source_file_id        INTEGER PRIMARY KEY REFERENCES source_files(id) ON DELETE CASCADE,
+       queued_through_offset INTEGER NOT NULL DEFAULT 0,
+       acked_offset          INTEGER NOT NULL DEFAULT 0,
+       updated_at            TEXT NOT NULL
+     )`,
+        `CREATE TABLE upload_queue (
+       id               INTEGER PRIMARY KEY AUTOINCREMENT,
+       upload_id        TEXT NOT NULL UNIQUE,
+       source_id        TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE,
+       source_file_id   INTEGER NOT NULL REFERENCES source_files(id) ON DELETE CASCADE,
+       session_id       TEXT NOT NULL,
+       generation       INTEGER NOT NULL,
+       start_offset     INTEGER NOT NULL,
+       end_offset       INTEGER NOT NULL,
+       byte_length      INTEGER NOT NULL,
+       content_sha256   TEXT NOT NULL,
+       priority         TEXT NOT NULL,
+       state            TEXT NOT NULL,  -- pending | accepted ([07]) | canceled (privacy)
+       server_upload_id TEXT,
+       attempts         INTEGER NOT NULL DEFAULT 0,
+       created_at       TEXT NOT NULL,
+       updated_at       TEXT NOT NULL,
+       UNIQUE (source_file_id, start_offset, end_offset)
+     )`,
+        `CREATE INDEX idx_upload_queue_state ON upload_queue (state, priority)`,
+        `CREATE TABLE excluded_ranges (
+       id             INTEGER PRIMARY KEY AUTOINCREMENT,
+       source_file_id INTEGER NOT NULL REFERENCES source_files(id) ON DELETE CASCADE,
+       start_offset   INTEGER NOT NULL,
+       end_offset     INTEGER NOT NULL,
+       reason         TEXT NOT NULL,
+       created_at     TEXT NOT NULL
+     )`,
+        `CREATE INDEX idx_excluded_ranges_file ON excluded_ranges (source_file_id)`,
+        `CREATE TABLE hook_installations (
+       id                 INTEGER PRIMARY KEY AUTOINCREMENT,
+       target             TEXT NOT NULL UNIQUE,
+       settings_path      TEXT NOT NULL,
+       installed_version  TEXT,
+       config_fingerprint TEXT,
+       created_at         TEXT NOT NULL,
+       updated_at         TEXT NOT NULL
+     )`,
+        `CREATE TABLE operations (
+       operation_id TEXT PRIMARY KEY,
+       kind         TEXT NOT NULL,
+       result_json  TEXT,
+       created_at   TEXT NOT NULL
+     )`,
+        `CREATE TABLE leases (
+       name        TEXT PRIMARY KEY,
+       owner       TEXT NOT NULL,
+       acquired_at INTEGER NOT NULL,
+       expires_at  INTEGER NOT NULL
+     )`,
+    ],
+    [
+        // Policy gate for the future uploader ([07]): the policy fingerprint in force
+        // when a row was enqueued, plus per-file error state so one poisoned session
+        // (e.g. an oversized record) never aborts reconciliation of the others.
+        `ALTER TABLE upload_queue ADD COLUMN policy_fingerprint TEXT`,
+        `ALTER TABLE source_files ADD COLUMN last_error_code TEXT`,
+        `ALTER TABLE source_files ADD COLUMN last_error_message TEXT`,
+        `ALTER TABLE source_files ADD COLUMN last_error_at TEXT`,
+    ],
+    [
+        // Cloud upload lifecycle ([07]): acceptance time, retry backoff schedule, and
+        // per-row error diagnostics. `state` also gains 'accepted' and 'quarantined'
+        // (the column is free-text, so no constraint change is needed).
+        `ALTER TABLE upload_queue ADD COLUMN accepted_at TEXT`,
+        `ALTER TABLE upload_queue ADD COLUMN next_attempt_at TEXT`,
+        `ALTER TABLE upload_queue ADD COLUMN last_error_code TEXT`,
+        `ALTER TABLE upload_queue ADD COLUMN last_error_message TEXT`,
+        // Due-row selection: pending rows for a source, ordered by priority then time.
+        `CREATE INDEX idx_upload_queue_due ON upload_queue (source_id, state, priority, next_attempt_at)`,
+    ],
+];
+exports.SCHEMA_VERSION = MIGRATIONS.length;
+function tx(db, fn) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = fn();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (error) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // A rollback failure must not mask the original error.
+        }
+        throw error;
+    }
+}
+function currentSchemaVersion(db) {
+    const row = db.prepare("SELECT value FROM kv WHERE key = 'schema_version'").get();
+    return row ? parseInt(row.value, 10) || 0 : 0;
+}
+function runMigrations(db) {
+    // The bootstrap table is idempotent. The version decision itself belongs
+    // inside the write lock so concurrent first opens cannot both choose v0.
+    db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
+    tx(db, () => {
+        const applied = currentSchemaVersion(db);
+        if (applied > MIGRATIONS.length) {
+            throw new Error(`Dreams database schema ${applied} is newer than supported schema ${MIGRATIONS.length}`);
+        }
+        for (let version = applied; version < MIGRATIONS.length; version++) {
+            for (const statement of MIGRATIONS[version])
+                db.exec(statement);
+            db.prepare("INSERT INTO kv (key, value) VALUES ('schema_version', ?) " +
+                "ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(version + 1));
+        }
+    });
+}
+/**
+ * Mirror the durable installation identity (canonically ~/.dreams/installation.json,
+ * so it survives DB loss) into the `installation` table for FK/provenance use.
+ */
+function ensureInstallation(db, installationId, createdAt) {
+    db.prepare("INSERT INTO installation (installation_id, created_at, cli_version) VALUES (?, ?, ?) " +
+        "ON CONFLICT(installation_id) DO UPDATE SET cli_version = excluded.cli_version").run(installationId, createdAt, (0, version_1.packageVersion)());
+}
+let cached = null;
+function openDb(options) {
+    if (cached)
+        return cached;
+    // Harden the state directory on every open (not only when minting an
+    // installation), so an upgrade from an older 0755 layout does not create
+    // dreams.db/WAL/SHM with world-readable project paths and session metadata.
+    (0, store_1.secureDreamsDir)();
+    const db = new node_sqlite_1.DatabaseSync(dbFilePath());
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
+    runMigrations(db);
+    ensureInstallation(db, options.installationId, options.installationCreatedAt);
+    cached = db;
+    return db;
+}
+/** Test/most-callers helper: closes and forgets the cached handle. */
+function closeDb() {
+    if (cached) {
+        cached.close();
+        cached = null;
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
+}

package/dist/local/dreamignore.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * `.dreamignore` — the primary local exclusion mechanism, evaluated before a
+ * session's bytes are ever enqueued. A pragmatic gitignore-style subset:
+ * blank lines and `#` comments are skipped, `!` negates, a trailing `/` marks a
+ * directory-only rule, a leading `/` anchors to the root, and `*` / `?` are
+ * glob wildcards (`*` does not cross `/`, `**` does).
+ *
+ * Patterns are matched against a POSIX, root-relative path (e.g. the session's
+ * working directory relative to an approved root).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDreamignore = parseDreamignore;
+exports.isIgnored = isIgnored;
+exports.loadDreamignore = loadDreamignore;
+exports.loadDreamignoreText = loadDreamignoreText;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function globToRegExp(pattern) {
+    const anchored = pattern.startsWith("/");
+    let body = anchored ? pattern.slice(1) : pattern;
+    let re = "";
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === "*") {
+            if (body[i + 1] === "*") {
+                // `**` spans path separators.
+                re += ".*";
+                i++;
+                if (body[i + 1] === "/")
+                    i++;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (c === "?") {
+            re += "[^/]";
+        }
+        else if ("+.()|{}^$\\[]".includes(c)) {
+            re += "\\" + c;
+        }
+        else {
+            re += c;
+        }
+    }
+    // Unanchored patterns match at any path segment boundary.
+    const prefix = anchored ? "^" : "^(?:.*/)?";
+    return new RegExp(`${prefix}${re}(?:/.*)?$`);
+}
+function parseDreamignore(text) {
+    const rules = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        let pattern = line;
+        const negated = pattern.startsWith("!");
+        if (negated)
+            pattern = pattern.slice(1);
+        const dirOnly = pattern.endsWith("/");
+        if (dirOnly)
+            pattern = pattern.slice(0, -1);
+        rules.push({ negated, dirOnly, regex: globToRegExp(pattern) });
+    }
+    return rules;
+}
+/** Last matching rule wins (gitignore semantics), so a later `!rule` can re-include. */
+function isIgnored(rules, relPath, isDir = false) {
+    const normalized = relPath.split(path.sep).join("/").replace(/^\/+/, "");
+    let ignored = false;
+    for (const rule of rules) {
+        if (rule.dirOnly && !isDir)
+            continue;
+        if (rule.regex.test(normalized))
+            ignored = !rule.negated;
+    }
+    return ignored;
+}
+function loadDreamignore(root) {
+    return parseDreamignore(loadDreamignoreText(root));
+}
+/** Raw `.dreamignore` contents (empty string if absent) — used for the policy fingerprint. */
+function loadDreamignoreText(root) {
+    try {
+        return fs.readFileSync(path.join(root, ".dreamignore"), "utf8");
+    }
+    catch {
+        return "";
+    }
+}

package/dist/local/ids.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Deterministic identities for queued upload segments.
+ *
+ * The segment id doubles as the Cloud `client_upload_id` in [07], so it must
+ * satisfy the frozen upload contract (^[A-Za-z0-9_-]{1,128}$). It is derived
+ * ONLY from stable identity coordinates — installation, source, file/session
+ * identity, generation, and the exact byte range — and NEVER from the content
+ * hash. Keeping the hash out of the id is what makes the contract's integrity
+ * check work: the same identity+range with different bytes must collide on the
+ * id (→ 409 conflict) rather than masquerade as two independent uploads. The
+ * content hash is carried and verified as a separate field.
+ *
+ * Replacement/truncation mints a new generation, which is a fresh id namespace.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = sha256Hex;
+exports.segmentId = segmentId;
+const crypto = __importStar(require("node:crypto"));
+function sha256Hex(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Length-delimited, versioned encoding so no field boundary is ambiguous even
+ * if a value contains delimiter-like characters. The `segment-v1` prefix lets
+ * the derivation evolve without silently colliding with old ids.
+ */
+function encodeSegmentTuple(identity) {
+    const fields = [
+        "segment-v1",
+        identity.installation_id,
+        identity.source_key,
+        identity.file_identity,
+        String(identity.generation),
+        String(identity.start_offset),
+        String(identity.end_offset),
+    ];
+    const parts = fields.map((f) => `${Buffer.byteLength(f, "utf8")}:${f}`);
+    return Buffer.from(parts.join(""), "utf8");
+}
+/** `seg_v1_<base64url(sha256(tuple))>` — 50 chars, contract-safe. */
+function segmentId(identity) {
+    const digest = crypto.createHash("sha256").update(encodeSegmentTuple(identity)).digest();
+    return `seg_v1_${digest.toString("base64url")}`;
+}