@nacre.work/core 0.0.0 → 0.2.0

package/dist/metadata.js

@@ -0,0 +1,127 @@
+/**
+ * Document metadata: what a caller may write, and what they may narrow a search
+ * by.
+ *
+ * One module for both ends on purpose. Ingest and search accept the same shape
+ * from the same untrusted place, and two validators would drift — the ingest
+ * side would grow a type the search side could not express, or the search side
+ * would accept a key ingest had refused, and a caller would be filtering on a
+ * field that can never exist.
+ *
+ * Everything here is a bound. Metadata is written into the vector payload of
+ * *every chunk of a document*, so a key is stored once per point and a
+ * thousand-chunk document multiplies whatever arrives here by a thousand. The
+ * limits are deliberately small; a knowledge index wants `source`, `team`,
+ * `updated_at`, not a document's worth of JSON a second time.
+ */
+/** Keys per document. */
+export const MAX_METADATA_KEYS = 32;
+export const MAX_METADATA_KEY_LENGTH = 64;
+/** A string value, and every string inside a list value. */
+export const MAX_METADATA_VALUE_LENGTH = 256;
+/** Values in one list. */
+export const MAX_METADATA_LIST = 32;
+/**
+ * Keys are `[a-z0-9_]`, lower case, and cannot start with a digit.
+ *
+ * Narrow because the key becomes a Qdrant payload field name, and Qdrant reads
+ * `.` as nested access and `[]` as array indexing — a key containing either
+ * would filter on something other than what the caller wrote. Refusing the
+ * characters is one line; discovering that `a.b` and `a` `{b}` are the same
+ * field is a support ticket.
+ */
+const KEY = /^[a-z_][a-z0-9_]*$/;
+export class MetadataError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MetadataError';
+    }
+}
+function checkScalar(key, value) {
+    if (typeof value === 'string') {
+        if (value.length > MAX_METADATA_VALUE_LENGTH) {
+            throw new MetadataError(`metadata value for '${key}' is over ${MAX_METADATA_VALUE_LENGTH} characters`);
+        }
+        return value;
+    }
+    if (typeof value === 'number') {
+        // NaN and the infinities have no JSON representation, so they arrive here
+        // only from a caller building the body in code — and they would be written
+        // as `null`, which is a value nothing can filter for.
+        if (!Number.isFinite(value)) {
+            throw new MetadataError(`metadata value for '${key}' is not a finite number`);
+        }
+        return value;
+    }
+    if (typeof value === 'boolean')
+        return value;
+    throw new MetadataError(`metadata value for '${key}' must be a string, number, boolean, or a list of those. ` +
+        'Nested objects are not accepted: the filter surface would have to grow a path ' +
+        'syntax, and a path is a way to reach a field the caller did not name.');
+}
+/**
+ * Validate and normalise metadata arriving from a request.
+ *
+ * Raises rather than dropping what it does not like. A silently discarded key
+ * is a document a caller believes is tagged and a filter that will never match
+ * it — the same class of failure as a search parameter read by nothing, and the
+ * reason `filters` answered 400 rather than being ignored.
+ */
+export function parseMetadata(raw, what = 'metadata') {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new MetadataError(`'${what}' must be an object`);
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > MAX_METADATA_KEYS) {
+        throw new MetadataError(`'${what}' has more than ${MAX_METADATA_KEYS} keys`);
+    }
+    const out = {};
+    for (const [key, value] of entries) {
+        if (key.length > MAX_METADATA_KEY_LENGTH) {
+            throw new MetadataError(`metadata key '${key.slice(0, 20)}…' is over ${MAX_METADATA_KEY_LENGTH} characters`);
+        }
+        if (!KEY.test(key)) {
+            throw new MetadataError(`metadata key '${key}' must match ${String(KEY)} — lower case letters, digits and ` +
+                'underscores, not starting with a digit');
+        }
+        // `undefined` survives an object literal in TypeScript but not JSON, so it
+        // reaches here only from a caller assembling the body in code. Dropping it
+        // is the one omission that is not a surprise: the key is absent either way.
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length > MAX_METADATA_LIST) {
+                throw new MetadataError(`metadata value for '${key}' has more than ${MAX_METADATA_LIST} entries`);
+            }
+            out[key] = value.map((v) => checkScalar(key, v));
+        }
+        else {
+            out[key] = checkScalar(key, value);
+        }
+    }
+    return out;
+}
+/**
+ * The same bounds, plus the one rule that belongs only to filtering.
+ *
+ * An empty list is a legitimate *value* — a document may be tagged with no
+ * teams — and an impossible *restriction*: "team is one of nothing" matches
+ * nothing at all. `buildFilter` refuses to encode it, deliberately, so that
+ * what an impossible restriction means stays the caller's decision rather than
+ * the query builder's. This is where that decision is made for a request: a 400
+ * naming the key, because a client that built a list and put nothing in it has
+ * a bug, and answering with an empty result would hide it.
+ */
+export function parseFilters(raw) {
+    const parsed = parseMetadata(raw, 'filters');
+    for (const [key, value] of Object.entries(parsed)) {
+        if (Array.isArray(value) && value.length === 0) {
+            throw new MetadataError(`filter on '${key}' has no values, so it can match nothing. Drop the key to ` +
+                'search without that restriction.');
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

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

package/dist/metrics.d.ts

@@ -52,7 +52,22 @@ export declare class Registry {
      * counters — document counts, the propagation lag, pending tombstones.
      */
     collect(fn: () => Promise<void>): void;
-    render(): Promise<string>;
+    /**
+     * How long a collected value is reused.
+     *
+     * `/metrics` is unauthenticated by default and the collectors are database
+     * queries — one per organization. Without this, anyone who can reach the port
+     * decides how often the API queries every tenant's `documents` table, on the
+     * same pool the request path uses. A scrape loop is a denial of service that
+     * looks like monitoring.
+     *
+     * Ten seconds is shorter than any sensible scrape interval, so a real
+     * Prometheus never sees a cached value and the numbers are as live as they
+     * were. It only collapses the excess: a second scraper, a human with `watch
+     * curl`, or a flood.
+     */
+    static readonly COLLECT_TTL_MS = 10000;
+    render(now?: number): Promise<string>;
 }
 /**
  * The metrics docs/config.md requires.
@@ -67,10 +82,13 @@ export declare function createMetrics(registry: Registry): {
     searchDuration: Histogram;
     searchResults: Counter;
     aclDenials: Counter;
+    authFailures: Counter;
     aclPropagationLag: Gauge;
     ingestDuration: Histogram;
     documents: Gauge;
+    reindexProgress: Gauge;
     tombstonesPending: Gauge;
+    collectionsRetired: Gauge;
 };
 export type Metrics = ReturnType<typeof createMetrics>;
 export {};

package/dist/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAgBrD,UAAU,MAAM;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,WAAW,CAAA;IAChD,MAAM,IAAI,MAAM,EAAE,CAAA;CACnB;AAED,qBAAa,OAAQ,YAAW,MAAM;;IAKlC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IALvB,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAS;gBAIvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;IAKvB,GAAG,CAAC,MAAM,GAAE,MAAW,EAAE,EAAE,SAAI,GAAG,IAAI;IAOtC,MAAM,IAAI,MAAM,EAAE;CAOnB;AAED,qBAAa,KAAM,YAAW,MAAM;;IAKhC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IALvB,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;gBAIrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;IAKvB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI7C,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,MAAM,EAAE;CAInB;AAID,qBAAa,SAAU,YAAW,MAAM;;IAKpC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;IANrC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAS;gBAIzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,SAAS,MAAM,EAAoB;IAKvD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAgBnD,2EAA2E;IACrE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS/D,MAAM,IAAI,MAAM,EAAE;CAmBnB;AAED,qBAAa,QAAQ;;IAInB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC;IAQxC;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAIhC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAahC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ;;;;;;;;EA8B/C;AAED,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAgBrD,UAAU,MAAM;IACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,WAAW,CAAA;IAChD,MAAM,IAAI,MAAM,EAAE,CAAA;CACnB;AAED,qBAAa,OAAQ,YAAW,MAAM;;IAKlC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IALvB,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAS;gBAIvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;IAKvB,GAAG,CAAC,MAAM,GAAE,MAAW,EAAE,EAAE,SAAI,GAAG,IAAI;IAOtC,MAAM,IAAI,MAAM,EAAE;CAOnB;AAED,qBAAa,KAAM,YAAW,MAAM;;IAKhC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IALvB,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;gBAIrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM;IAKvB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI7C,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,MAAM,EAAE;CAInB;AAID,qBAAa,SAAU,YAAW,MAAM;;IAKpC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;IANrC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAS;gBAIzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,SAAS,MAAM,EAAoB;IAKvD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAgBnD,2EAA2E;IACrE,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAS/D,MAAM,IAAI,MAAM,EAAE;CAmBnB;AAED,qBAAa,QAAQ;;IAInB,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC;IAQxC;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAItC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,SAAS;IAwCjC,MAAM,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAWxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ;;;;;;;;;;;EA4E/C;AAED,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAA"}

package/dist/metrics.js

@@ -6,6 +6,7 @@
  * to keep patched. If the needs here outgrow histograms and gauges, replace it
  * with prom-client rather than growing this file.
  */
+var _a;
 const NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
 function escapeLabel(value) {
     return value.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/"/g, '\\"');
@@ -141,10 +142,59 @@ export class Registry {
     collect(fn) {
         this.#collectors.push(fn);
     }
-    async render() {
+    /**
+     * How long a collected value is reused.
+     *
+     * `/metrics` is unauthenticated by default and the collectors are database
+     * queries — one per organization. Without this, anyone who can reach the port
+     * decides how often the API queries every tenant's `documents` table, on the
+     * same pool the request path uses. A scrape loop is a denial of service that
+     * looks like monitoring.
+     *
+     * Ten seconds is shorter than any sensible scrape interval, so a real
+     * Prometheus never sees a cached value and the numbers are as live as they
+     * were. It only collapses the excess: a second scraper, a human with `watch
+     * curl`, or a flood.
+     */
+    static COLLECT_TTL_MS = 10_000;
+    /**
+     * When the collectors last finished, on the same clock `render` was given.
+     *
+     * `undefined` and not 0, because "never collected" and "collected at time
+     * zero" have to be different: a caller injecting a clock — a test, or
+     * anything replaying — would otherwise find a fresh registry believing it had
+     * just collected, and the first scrape would return empty gauges.
+     */
+    #collectedAt;
+    #collecting;
+    /**
+     * Run the collectors, at most one run at a time and at most one per window.
+     *
+     * The single-flight part matters as much as the cache: two scrapes arriving
+     * together used to start two full sweeps, so concurrency multiplied the cost
+     * that the cache alone would bound only in sequence.
+     */
+    async #collectOnce(now) {
+        if (this.#collecting !== undefined)
+            return this.#collecting;
+        if (this.#collectedAt !== undefined && now - this.#collectedAt < _a.COLLECT_TTL_MS)
+            return;
         // A collector that fails must not blank the whole exposition: the metrics
         // that still work are how you find out which one broke.
-        await Promise.allSettled(this.#collectors.map((fn) => fn()));
+        this.#collecting = Promise.allSettled(this.#collectors.map((fn) => fn())).then(() => {
+            // Stamped with the clock this call was given, never with Date.now().
+            // Mixing the two means an injected clock is compared against a real one,
+            // and the window is then either always open or never.
+            //
+            // On completion rather than on entry, so a sweep slower than the window
+            // does not have the next one queued behind it the instant it finishes.
+            this.#collectedAt = now;
+            this.#collecting = undefined;
+        });
+        return this.#collecting;
+    }
+    async render(now = Date.now()) {
+        await this.#collectOnce(now);
         const lines = [];
         for (const metric of this.#metrics) {
             lines.push(`# HELP ${metric.name} ${metric.help}`);
@@ -154,6 +204,7 @@ export class Registry {
         return `${lines.join('\n')}\n`;
     }
 }
+_a = Registry;
 /**
  * The metrics docs/config.md requires.
  *
@@ -170,10 +221,41 @@ export function createMetrics(registry) {
         ])),
         searchResults: registry.register(new Counter('nacre_search_results_total', 'Results returned, by layer')),
         aclDenials: registry.register(new Counter('nacre_acl_denials_total', 'Access denials, by reason')),
+        // Labelled by what was presented, never by why it failed. The 401 itself
+        // carries one message for every reason so a caller cannot tell an expired
+        // token from a forged one; a `reason` label would hand that distinction
+        // back through an endpoint that is unauthenticated by default.
+        //
+        // `kind="jwt"` is the series a key rotation moves, and it is why this
+        // exists: there is no dual-key window, so every outstanding access token
+        // fails at once and an operator has to watch that drain. `kind="service_key"`
+        // staying flat through the same window is the check that the rotation hit
+        // only what it was meant to.
+        authFailures: registry.register(new Counter('nacre_auth_failures_total', 'Rejected credentials, by the kind presented: missing, jwt, service_key. Never by reason — the 401 is deliberately one answer')),
         aclPropagationLag: registry.register(new Gauge('nacre_acl_propagation_lag_seconds', 'Age in seconds of the oldest document, per organization, whose ACL tags predate the current groups_version. Alert on max() over this. The only external evidence that invariant I4 holds')),
         ingestDuration: registry.register(new Histogram('nacre_ingest_duration_seconds', 'Indexing latency, by stage')),
         documents: registry.register(new Gauge('nacre_documents_total', 'Documents, by organization and status')),
+        // Specified in docs/config.md and registered by nothing until there was a
+        // reindex to measure.
+        //
+        // One series per layer that has ever been reindexed, and no series for the
+        // rest — a layer nobody has migrated has no progress to report, and
+        // inventing a zero for it would mean every layer in the installation
+        // permanently reads "reindex started, gone nowhere".
+        //
+        // With no reindexes at all the registry still emits a bare
+        // `nacre_reindex_progress_ratio 0`, because an unlabelled gauge with no
+        // values renders that way here. That is the "nothing to report" marker
+        // rather than a layer at zero: a real layer always carries a `layer` label.
+        reindexProgress: registry.register(new Gauge('nacre_reindex_progress_ratio', 'How far a layer is through a reindex, 0 to 1. Absent when no reindex has run; 0 means one started and has moved nothing')),
         tombstonesPending: registry.register(new Gauge('nacre_tombstones_pending_total', 'Deleted documents whose vectors are not yet purged. Climbing means garbage collection is losing')),
+        // A gauge and not a counter, because the question an operator has is "how
+        // much disk is a finished migration still holding", not "how many have I
+        // reclaimed since this process started". Each one retained is a full copy
+        // of an organization's vectors, so a number that stays high is the signal —
+        // and a number that never falls means the sweep is not running at all,
+        // which is the state this whole table replaced.
+        collectionsRetired: registry.register(new Gauge('nacre_collections_retired_total', 'Superseded collections still held for the reindex rollback window, by organization. Each is a full copy of that organization vectors')),
     };
 }
 //# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;;AAIH,MAAM,IAAI,GAAG,4BAA4B,CAAA;AAEzC,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AAChF,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;SAC3B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAC9C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;AAClE,CAAC;AASD,MAAM,OAAO,OAAO;IAKP;IACA;IALF,IAAI,GAAG,SAAkB,CAAA;IACzB,OAAO,GAAG,IAAI,GAAG,EAA6C,CAAA;IAEvE,YACW,IAAY,EACZ,IAAY;QADZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QAErB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAA;IAC3E,CAAC;IAED,GAAG,CAAC,SAAiB,EAAE,EAAE,EAAE,GAAG,CAAC;QAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;QAC3D,KAAK,CAAC,KAAK,IAAI,EAAE,CAAA;QACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,MAAM;QACJ,uEAAuE;QACvE,sEAAsE;QACtE,mEAAmE;QACnE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAA;QACtD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;IACjE,CAAC;CACF;AAED,MAAM,OAAO,KAAK;IAKL;IACA;IALF,IAAI,GAAG,OAAgB,CAAA;IACvB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE5C,YACW,IAAY,EACZ,IAAY;QADZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QAErB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAA;IAC3E,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,SAAiB,EAAE;QACpC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,CAAA;IACpD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAA;QACtD,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;IAC3D,CAAC;CACF;AAED,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AAEjF,MAAM,OAAO,SAAS;IAKT;IACA;IACA;IANF,IAAI,GAAG,WAAoB,CAAA;IAC3B,OAAO,GAAG,IAAI,GAAG,EAA4E,CAAA;IAEtG,YACW,IAAY,EACZ,IAAY,EACZ,UAA6B,eAAe;QAF5C,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAqC;QAErD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAA;IAC3E,CAAC;IAED,OAAO,CAAC,OAAe,EAAE,SAAiB,EAAE;QAC1C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI;YACrC,MAAM;YACN,MAAM,EAAE,IAAI,KAAK,CAAS,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACtD,GAAG,EAAE,CAAC;YACN,KAAK,EAAE,CAAC;SACT,CAAA;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,IAAI,OAAO,IAAK,IAAI,CAAC,OAAO,CAAC,CAAC,CAAY;gBAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAY,GAAG,CAAC,CAAA;QAC/F,CAAC;QACD,KAAK,CAAC,GAAG,IAAI,OAAO,CAAA;QACpB,KAAK,CAAC,KAAK,IAAI,CAAC,CAAA;QAChB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,IAAI,CAAI,MAAc,EAAE,EAAoB;QAChD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;QACjC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAA;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,MAAM;QACJ,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,sEAAsE;YACtE,uEAAuE;YACvE,sEAAsE;YACtE,wEAAwE;YACxE,wBAAwB;YACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7C,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAW,EAAE,CAClH,CAAA;YACH,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,SAAS,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;YAC9F,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;YACtE,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;QAC5E,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;CACF;AAED,MAAM,OAAO,QAAQ;IACV,QAAQ,GAAa,EAAE,CAAA;IACvB,WAAW,GAA4B,EAAE,CAAA;IAElD,QAAQ,CAAmB,MAAS;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;QAC9D,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC1B,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,EAAuB;QAC7B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC3B,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAU,cAAc,GAAG,MAAM,CAAA;IAEvC;;;;;;;OAOG;IACH,YAAY,CAAoB;IAChC,WAAW,CAA2B;IAEtC;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,GAAW;QAC5B,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,WAAW,CAAA;QAC3D,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,GAAG,GAAG,IAAI,CAAC,YAAY,GAAG,EAAQ,CAAC,cAAc;YAAE,OAAM;QAEhG,0EAA0E;QAC1E,wDAAwD;QACxD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YAClF,qEAAqE;YACrE,yEAAyE;YACzE,sDAAsD;YACtD,EAAE;YACF,wEAAwE;YACxE,uEAAuE;YACvE,IAAI,CAAC,YAAY,GAAG,GAAG,CAAA;YACvB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAA;QAC9B,CAAC,CAAC,CAAA;QAEF,OAAO,IAAI,CAAC,WAAW,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,IAAI,CAAC,GAAG,EAAE;QACnC,MAAM,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAA;QAE5B,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;YAClD,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;YAClD,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;QAChC,CAAC;QACD,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;IAChC,CAAC;;;AAGH;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,OAAO;QACL,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAC/B,IAAI,SAAS,CAAC,+BAA+B,EAAE,4BAA4B,EAAE;YAC3E,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;SAC1C,CAAC,CACH;QACD,aAAa,EAAE,QAAQ,CAAC,QAAQ,CAC9B,IAAI,OAAO,CAAC,4BAA4B,EAAE,4BAA4B,CAAC,CACxE;QACD,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAC3B,IAAI,OAAO,CAAC,yBAAyB,EAAE,2BAA2B,CAAC,CACpE;QACD,yEAAyE;QACzE,0EAA0E;QAC1E,wEAAwE;QACxE,+DAA+D;QAC/D,EAAE;QACF,sEAAsE;QACtE,yEAAyE;QACzE,8EAA8E;QAC9E,0EAA0E;QAC1E,6BAA6B;QAC7B,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAC7B,IAAI,OAAO,CACT,2BAA2B,EAC3B,8HAA8H,CAC/H,CACF;QACD,iBAAiB,EAAE,QAAQ,CAAC,QAAQ,CAClC,IAAI,KAAK,CACP,mCAAmC,EACnC,0LAA0L,CAC3L,CACF;QACD,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAC/B,IAAI,SAAS,CAAC,+BAA+B,EAAE,4BAA4B,CAAC,CAC7E;QACD,SAAS,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,uBAAuB,EAAE,uCAAuC,CAAC,CAAC;QACzG,0EAA0E;QAC1E,sBAAsB;QACtB,EAAE;QACF,2EAA2E;QAC3E,oEAAoE;QACpE,qEAAqE;QACrE,qDAAqD;QACrD,EAAE;QACF,2DAA2D;QAC3D,wEAAwE;QACxE,uEAAuE;QACvE,4EAA4E;QAC5E,eAAe,EAAE,QAAQ,CAAC,QAAQ,CAChC,IAAI,KAAK,CACP,8BAA8B,EAC9B,yHAAyH,CAC1H,CACF;QACD,iBAAiB,EAAE,QAAQ,CAAC,QAAQ,CAClC,IAAI,KAAK,CACP,gCAAgC,EAChC,iGAAiG,CAClG,CACF;QACD,0EAA0E;QAC1E,yEAAyE;QACzE,0EAA0E;QAC1E,4EAA4E;QAC5E,uEAAuE;QACvE,gDAAgD;QAChD,kBAAkB,EAAE,QAAQ,CAAC,QAAQ,CACnC,IAAI,KAAK,CACP,iCAAiC,EACjC,sIAAsI,CACvI,CACF;KACF,CAAA;AACH,CAAC"}

package/dist/migrations/0008_authenticating_lookup.sql

@@ -0,0 +1,124 @@
+-- Resolving a credential cannot be scoped to an organization, because the
+-- credential is what says which organization it is.
+--
+-- `PostgresServiceKeys.resolve` reads `service_accounts` by key prefix across
+-- every tenant for exactly that reason. It has never worked anywhere the
+-- documentation says to deploy it: `org_isolation` calls
+-- `current_setting('app.current_org')` in its one-argument form, which raises
+-- `unrecognized configuration parameter` rather than returning null, so the
+-- query fails outright on any connection that is subject to row-level
+-- security. It works in development only because development connects as a
+-- superuser — the one configuration `docs/config.md` explicitly forbids:
+--
+--     $ psql "postgres://nacre_app@…" -c "SELECT id, org_id FROM service_accounts
+--                                          WHERE key_prefix = '…'"
+--     ERROR:  unrecognized configuration parameter "app.current_org"
+--
+-- So every service account key stops working the moment an operator follows
+-- the rule about not connecting as a superuser. Nothing failed in CI, because
+-- CI connects as `postgres` too.
+--
+-- ─── the fix, and why it is a policy rather than a bypass ───
+--
+-- The obvious repair is a SECURITY DEFINER function, and it does not work
+-- here: these tables carry FORCE ROW LEVEL SECURITY, which applies to the
+-- owner as well, so a function running as the owner is still filtered. The
+-- alternative — a role with BYPASSRLS — buys a permanent hole in the isolation
+-- model to solve a problem that lasts one query.
+--
+-- Row-level security is the mechanism, so this uses it. A second policy admits
+-- the lookup, and only while `app.authenticating` is set on the connection.
+-- Policies for the same command are OR'd, so the org-scoped policy is
+-- unchanged for every other caller.
+--
+-- The guard on `org_isolation` is what makes that safe. Without it Postgres
+-- may evaluate the org-scoped expression anyway and raise before the second
+-- policy is ever consulted; `CASE` short-circuits, so the raising call is not
+-- reached while authenticating. It is deliberately left raising in every other
+-- case: a query that forgets `withOrg` should fail loudly rather than quietly
+-- return nothing, and "quietly returns nothing" is indistinguishable from a
+-- permission working correctly, which is the hardest kind of bug to see.
+
+ALTER POLICY org_isolation ON service_accounts
+    USING (
+        CASE
+            WHEN current_setting('app.authenticating', true) = 'on' THEN false
+            ELSE org_id = current_setting('app.current_org')::uuid
+        END
+    );
+
+-- SELECT only. Authentication reads a credential; it never writes one, and a
+-- policy that admitted INSERT or UPDATE here would let the one path that runs
+-- without an organization create rows in any of them.
+CREATE POLICY authenticating ON service_accounts
+    FOR SELECT
+    USING (current_setting('app.authenticating', true) = 'on');
+
+-- `users` gets neither, and that is a decision rather than an omission. Login
+-- resolves the organization from `organizations` — which has no row-level
+-- security, because an organization is not inside one — and then reads the
+-- user through `withOrg` like everything else. There is no cross-tenant read
+-- on the login path, so there is nothing here to open.
+
+-- ─────────────────────── the worker role that was only ever a comment ───────────────────────
+--
+-- `0001_init.sql` says: "Background worker jobs run under a separate role with
+-- BYPASSRLS." No migration ever created it. The worker claims documents across
+-- every tenant — that is what a queue is — and those queries run on a raw
+-- connection with no organization set, so they raise the same
+-- `unrecognized configuration parameter` as the credential lookup did:
+--
+--     $ psql "postgres://nacre_app@…" -c "SELECT d.id, d.org_id FROM documents d
+--                                          JOIN organizations o ON o.id = d.org_id"
+--     ERROR:  unrecognized configuration parameter "app.current_org"
+--
+-- So indexing stops entirely on a deployment that connects as anything but a
+-- superuser. The Compose stack has never shown it, because POSTGRES_USER makes
+-- the connecting role a superuser — the configuration docs/config.md tells
+-- operators not to use.
+--
+-- BYPASSRLS rather than another policy flag, and the difference from the
+-- lookup above is worth being explicit about: authentication reads one column
+-- set from one table and never writes, so a narrow SELECT policy fits it. The
+-- worker reads and writes documents, chunks and layers across every tenant, so
+-- a flag admitting all of that is BYPASSRLS with a worse name and a longer
+-- audit trail. The honest thing is to say so in the role.
+--
+-- Which is also why the worker names org_id explicitly in every query it makes
+-- afterwards: with the second line of defence off, the first one is all there
+-- is.
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'nacre_worker') THEN
+        CREATE ROLE nacre_worker NOLOGIN BYPASSRLS;
+    ELSIF NOT (SELECT rolbypassrls FROM pg_roles WHERE rolname = 'nacre_worker') THEN
+        ALTER ROLE nacre_worker BYPASSRLS;
+    END IF;
+EXCEPTION WHEN insufficient_privilege THEN
+    -- Creating a BYPASSRLS role needs a superuser, and the role running
+    -- migrations may not be one. Failing here with the statement to run is the
+    -- whole point: the alternative is a worker that starts, claims nothing,
+    -- and reports itself healthy.
+    RAISE EXCEPTION USING
+        MESSAGE = 'nacre_worker could not be created: creating a BYPASSRLS role requires a superuser.',
+        HINT    = 'Run this once as a superuser, then re-run migrations: '
+                  'CREATE ROLE nacre_worker NOLOGIN BYPASSRLS; '
+                  'GRANT nacre_worker TO <the role in NACRE_PG_URL>;';
+END
+$$;
+
+GRANT USAGE ON SCHEMA public TO nacre_worker;
+GRANT SELECT, INSERT, UPDATE, DELETE ON
+    organizations, users, groups, group_members, service_accounts,
+    embedding_providers, workspaces, layers, documents, chunks, grants
+    TO nacre_worker;
+GRANT SELECT, INSERT ON audit_events TO nacre_worker;
+REVOKE UPDATE, DELETE ON audit_events FROM nacre_worker;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO nacre_worker;
+
+-- The application role has to be a member to `SET LOCAL ROLE` to it. Granted
+-- rather than assumed: a deployment that manages roles externally will already
+-- have done this, and one that does not would otherwise get a worker that
+-- connects successfully and cannot claim anything.
+GRANT nacre_worker TO nacre_app;

package/dist/migrations/0009_refresh_tokens.sql

@@ -0,0 +1,73 @@
+-- Refresh tokens, for the login flow.
+--
+-- ─── stored hashed, like every other credential here ───
+--
+-- The column holds a SHA-256 of the token and never the token. A refresh token
+-- outlives an access token by a month, so a database dump that contained them
+-- would be a month of sessions rather than a list of identifiers.
+--
+-- ─── rotation, and what reuse means ───
+--
+-- Every refresh issues a new token and marks the old one used. A used token
+-- presented again is not a client bug worth tolerating: the legitimate holder
+-- has already exchanged it, so a second presentation means two parties hold the
+-- same token, and one of them stole it. There is no way to tell which, so the
+-- whole family is revoked and both are made to sign in again. Annoying once
+-- beats a silent, indefinite session for whoever took it.
+--
+-- `family_id` is what makes that possible: it is the same value for every token
+-- descended from one login, so revoking a family ends that session and no other.
+
+CREATE TABLE refresh_tokens (
+    id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    org_id      uuid NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    user_id     uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    -- Not unique across the table by accident: it is unique because the token
+    -- is 32 bytes from the CSPRNG, and the constraint says so rather than
+    -- leaving a collision to become two users sharing a session.
+    token_hash  text NOT NULL UNIQUE,
+    family_id   uuid NOT NULL,
+    issued_at   timestamptz NOT NULL DEFAULT now(),
+    expires_at  timestamptz NOT NULL,
+    used_at     timestamptz,
+    revoked_at  timestamptz
+);
+
+-- The lookup on every refresh: by hash, which is also the uniqueness above.
+-- The family index is for revocation, which touches every row of one family.
+CREATE INDEX refresh_tokens_family ON refresh_tokens (family_id) WHERE revoked_at IS NULL;
+-- Expired rows are deleted by a sweep rather than kept forever; ordering by
+-- expiry is what makes that sweep cheap.
+CREATE INDEX refresh_tokens_expiry ON refresh_tokens (expires_at);
+
+ALTER TABLE refresh_tokens ENABLE ROW LEVEL SECURITY;
+ALTER TABLE refresh_tokens FORCE ROW LEVEL SECURITY;
+
+-- Scoped like everything else. A refresh token names the organization it was
+-- issued for, and the endpoint that redeems one has already resolved that
+-- organization from the token's own row — through the authenticating policy
+-- below, which is the same mechanism service account keys use and for the same
+-- reason: the credential is what says which tenant it belongs to.
+CREATE POLICY org_isolation ON refresh_tokens
+    USING (
+        CASE
+            WHEN current_setting('app.authenticating', true) = 'on' THEN false
+            ELSE org_id = current_setting('app.current_org')::uuid
+        END
+    );
+
+CREATE POLICY authenticating ON refresh_tokens
+    FOR SELECT
+    USING (current_setting('app.authenticating', true) = 'on');
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON refresh_tokens TO nacre_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON refresh_tokens TO nacre_worker;
+
+-- ─── the password column gets a check it never had ───
+--
+-- `users.password_hash` has existed since 0001 and nothing has ever written to
+-- it. Now that something does, an empty string must not be storable: it is
+-- falsy in application code and truthy in SQL, which is exactly the shape of
+-- difference that becomes an account anyone can sign into.
+ALTER TABLE users ADD CONSTRAINT users_password_hash_not_blank
+    CHECK (password_hash IS NULL OR length(password_hash) >= 16);

package/dist/migrations/0010_definer_search_path.sql

@@ -0,0 +1,22 @@
+-- Pin the search_path on the one SECURITY DEFINER function.
+--
+-- `0003` made `bump_groups_version()` SECURITY DEFINER and did not pin its
+-- search_path. The body's unqualified `organizations` therefore resolves
+-- through the *caller's* search_path, and any role may create objects in
+-- `pg_temp`. A caller who shadows the table stops `groups_version` advancing —
+-- so revocations never propagate, while `nacre_acl_propagation_lag_seconds`
+-- reports a healthy zero because nothing is behind a version that never moved.
+-- A silent failure of invariant 4, with its own evidence metric confirming
+-- health.
+--
+-- It runs as the migration owner, which `docs/config.md` allows to be a
+-- superuser, so the ceiling is high. Reaching it needs database access as
+-- `nacre_app` — defence in depth rather than a remote hole — which is exactly
+-- what the second line of defence is for in a product whose first line is a
+-- permission model.
+--
+-- A separate migration rather than an edit to 0003: migrations are
+-- forward-only and their checksums are re-verified on every run, so editing an
+-- applied file makes the next `migrate` fail on every existing database.
+
+ALTER FUNCTION bump_groups_version() SET search_path = pg_catalog, public;

package/dist/migrations/0011_sweep_lease.sql

@@ -0,0 +1,36 @@
+-- A lease on the two background sweeps, so more workers do more work.
+--
+-- `claimStale` (retag) and `claimPurgeable` (garbage collection) both selected
+-- the oldest N rows with no lock and no claim marker. Every replica therefore
+-- selected the **same** N rows and did the same work: throughput stayed at one
+-- worker's rate however many were running, while the load on Qdrant multiplied
+-- by the replica count.
+--
+-- That matters beyond efficiency. The documented response to a climbing
+-- `nacre_acl_propagation_lag_seconds` is to look at the worker — and scaling it
+-- out, the obvious move, did nothing at all.
+--
+-- `FOR UPDATE SKIP LOCKED` alone does not fix it. The lock lives until the
+-- transaction commits, and these transactions end the moment the SELECT
+-- returns — the actual work (a Qdrant round trip) happens afterwards, outside
+-- any transaction. So two replicas polling a second apart still collide.
+--
+-- ─── one column, because the two states are mutually exclusive ───
+--
+-- A document is either live and behind its organization's version (retag), or
+-- deleted and not yet purged (garbage collection). `deleted_at IS NULL` decides
+-- which, and nothing is ever both, so one claim column serves both sweeps.
+--
+-- Leased rather than owned, exactly like `documents.claimed_at`: a worker that
+-- dies mid-sweep must not park a row forever. `NACRE_INDEX_LEASE` bounds it,
+-- and the claim is only ever an optimisation — both sweeps are idempotent, and
+-- `markTagged`'s version guard and `markPurged`'s `vectors_purged_at IS NULL`
+-- guard remain the things that make a double pass harmless.
+
+ALTER TABLE documents ADD COLUMN sweep_claimed_at timestamptz;
+
+-- Partial, and on the claim rather than on the whole table: the sweeps read
+-- "unclaimed, or claimed long enough ago to be abandoned", which is a small
+-- slice of a large table.
+CREATE INDEX documents_sweep_claim ON documents (sweep_claimed_at)
+    WHERE sweep_claimed_at IS NOT NULL;