latticesql 2.3.0 → 3.1.0

package/dist/index.d.ts

@@ -766,6 +766,31 @@ interface ChangelogOptions {
     /** Keep at most this many entries per row. */
     maxEntriesPerRow?: number;
 }
+/**
+ * Provenance for a change — the per-viewer observation model's audit metadata.
+ * Every field is optional and additive: a plain edit carries none of it and
+ * behaves exactly as before. A *derived* value (e.g. an AI enrichment computed
+ * from source files) carries the `sourceRef` set that informed it, so the
+ * change-log records which authority produced the value rather than discarding
+ * it (the confused-deputy guard). Stage-0 persists this as audit metadata;
+ * later stages read it to fold per-viewer entities and cascade revocation.
+ */
+interface ChangeProvenance {
+    /** Source row/file id(s) that informed this value. Persisted as a JSON array
+     *  in `__lattice_changelog.source_ref`. NOT a foreign key — purely an audit
+     *  trail; a source may be deleted without violating anything. */
+    sourceRef?: string[] | string;
+    /** `ground_truth` — a direct edit; `derived` — computed from sources. */
+    changeKind?: 'ground_truth' | 'derived';
+    /** Reserved per-value audience. Omitted ⇒ the row's audience (no change). */
+    audience?: string;
+    /** Marks the source(s) sensitive (a future crypto-shred candidate). */
+    sourceSensitive?: boolean;
+    /** A prior changelog id this entry supersedes. */
+    supersededBy?: string;
+    /** Free-text reason (mirrors the legacy `reason` field). */
+    reason?: string;
+}
 /**
  * A single entry in the change log returned by `history()` and
  * `recentChanges()`.
@@ -789,6 +814,11 @@ interface ChangeEntry {
     reason: string | null;
     /** ISO timestamp of when the change was recorded. */
     createdAt: string;
+    /** Source-set that informed a derived value (deserialized from `source_ref`).
+     *  Null for plain edits + rows written before 3.0. */
+    sourceRef?: string[] | null;
+    /** `ground_truth` | `derived` provenance tag (null when unrecorded). */
+    changeKind?: 'ground_truth' | 'derived' | null;
 }
 interface SecurityOptions {
     sanitize?: boolean;
@@ -932,6 +962,15 @@ interface TableDefinition {
      * directly in code via `define()`.
      */
     fieldTypes?: Record<string, string>;
+    /**
+     * Column name → audience identifier (Stage-0 per-viewer enrichment
+     * scaffolding). A column absent from this map has `row-audience` — visible to
+     * whoever can see the row, i.e. today's behavior. Populated from YAML field
+     * `audience:` specs (or a future code-level option). Recorded by the schema
+     * manager so a later stage can generate a per-column cell-masking view from
+     * it; unused in Stage-0, so it never changes behavior.
+     */
+    columnAudience?: Record<string, string>;
     /**
      * Optional human description of what this entity represents. Surfaced in the
      * GUI and given to the assistant's ingest classifier so it can decide which
@@ -1275,6 +1314,16 @@ interface CountOptions {
 }
 interface InitOptions {
     migrations?: Migration[];
+    /**
+     * Open an already-provisioned database WITHOUT issuing any DDL — no
+     * `CREATE TABLE`, no migrations, no FTS/changelog/embeddings setup. Used to
+     * connect as a scoped, non-superuser cloud member: every table, migration,
+     * and policy was installed by the cloud owner, and the member's role has no
+     * CREATE/ALTER privilege, so applying the schema would fail. Declared tables
+     * are introspected (best-effort) to populate the column cache; tables the
+     * member can't see are skipped.
+     */
+    introspectOnly?: boolean;
 }
 interface Migration {
     version: number | string;
@@ -1624,6 +1673,147 @@ interface ReconcileResult extends RenderResult {
     reverseSeedRequired: ReverseSeedDetection[];
 }
 
+/**
+ * Cryptographic erasure ("crypto-shred") for sources flagged sensitive.
+ *
+ * Un-sharing or deleting a source already removes its derived values from every
+ * viewer's fold (the fold only includes observations whose sources are visible —
+ * see ./fold.ts). But the bytes can linger in backups and WAL. For a legal /
+ * GDPR "right to be forgotten", a source flagged `source_sensitive` gets a
+ * stronger guarantee: every value derived from it is stored ENCRYPTED under a
+ * key unique to that source. To forget the source you destroy its key — and the
+ * derived values become unrecoverable everywhere the ciphertext exists, backups
+ * included, because the key never lived in the row.
+ *
+ * The key store is pluggable so the keys can live somewhere shred-durable and
+ * separate from the data (a KMS, a key table on a different retention policy).
+ * The default in-memory store is for tests + single-process use.
+ */
+/** Holds the per-source AES keys. Destroying a key is the erasure operation. */
+interface SourceKeyStore {
+    /** The key for a source, or undefined if it was never created / has been shredded. */
+    get(sourceId: string): Buffer | undefined;
+    /** The key for a source, creating a fresh random 256-bit key on first use. */
+    getOrCreate(sourceId: string): Buffer;
+    /** Destroy a source's key — irreversibly. Values sealed under it can no longer
+     *  be opened, anywhere. Idempotent. */
+    destroy(sourceId: string): void;
+}
+/** In-memory {@link SourceKeyStore}. Keys vanish with the process — fine for
+ *  tests; production should persist keys in a shred-durable store. */
+declare class InMemorySourceKeyStore implements SourceKeyStore {
+    private readonly keys;
+    get(sourceId: string): Buffer | undefined;
+    getOrCreate(sourceId: string): Buffer;
+    destroy(sourceId: string): void;
+}
+/** Error thrown when opening a value whose source key has been shredded. */
+declare class SourceShreddedError extends Error {
+    readonly sourceId: string;
+    constructor(sourceId: string);
+}
+/**
+ * Encrypt a derived value under its (sensitive) source's key, creating the key on
+ * first use. The returned ciphertext is opaque without the source key.
+ */
+declare function sealUnderSource(plaintext: string, sourceId: string, store: SourceKeyStore): string;
+/**
+ * Decrypt a value sealed under a source's key. Throws {@link SourceShreddedError}
+ * if the source has been shredded (the key is gone) — the value is unrecoverable,
+ * which is the intended "forgotten" state, not an error to paper over.
+ */
+declare function openUnderSource(ciphertext: string, sourceId: string, store: SourceKeyStore): string;
+/**
+ * Cryptographically shred a source: destroy its key so every value sealed under
+ * it is unrecoverable everywhere the ciphertext exists (live rows, backups, WAL).
+ * Pair with the fold-level revocation (which removes the value from live views) —
+ * this is the durable, backup-proof half for legally-sensitive sources.
+ */
+declare function shredSource(sourceId: string, store: SourceKeyStore): void;
+
+/**
+ * Progress reporting for the render engine.
+ *
+ * A render walks every table and every per-entity context file; for a large
+ * database this can take a while. These types let a caller observe progress
+ * (per-table %, which table is in flight) and cancel a render in progress via
+ * an `AbortSignal`. All of it is optional: a render with no `onProgress` and no
+ * `signal` behaves exactly as it did before — zero overhead, identical output.
+ */
+/** The kind of progress event the render engine emits. */
+type RenderProgressKind = 'table-start' | 'table-progress' | 'table-done' | 'done' | 'error';
+/**
+ * A single progress event. Fields beyond `kind` describe the table currently
+ * being rendered (`table`, `tableIndex`, `tableCount`) and how far along it is
+ * (`entitiesRendered`, `entitiesTotal`, `pct`). `durationMs` is set on the
+ * terminal `done` event; `message` carries human-readable detail (e.g. the
+ * error text on an `error` event).
+ */
+interface RenderProgress {
+    /** Discriminator: what stage of the render this event reports. */
+    kind: RenderProgressKind;
+    /** The table being rendered, or null for non-table events (`done`/`error`). */
+    table: string | null;
+    /** Entities rendered so far within `table` (per-table running count). */
+    entitiesRendered: number;
+    /** Total entities in `table` — the denominator for the per-table %. */
+    entitiesTotal: number;
+    /** Zero-based index of `table` among the entity-context tables. */
+    tableIndex: number;
+    /** Total number of entity-context tables in this render. */
+    tableCount: number;
+    /** Per-table completion percentage, 0–100, exact (`rendered/total`). */
+    pct: number;
+    /** Wall-clock duration of the whole render, set on the `done` event. */
+    durationMs?: number;
+    /** Human-readable detail; the error text on an `error` event. */
+    message?: string;
+}
+/** Sink the render engine pushes {@link RenderProgress} events into. */
+type RenderProgressCallback = (event: RenderProgress) => void;
+/**
+ * Optional knobs for a render. Both are opt-in:
+ * - `onProgress` — observe per-table render progress.
+ * - `signal` — cancel a render in flight; the engine bails between entities and
+ *   returns the partial manifest (which the caller is expected to discard).
+ */
+interface RenderOptions {
+    onProgress?: RenderProgressCallback;
+    signal?: AbortSignal;
+}
+/**
+ * Coalesces high-frequency `table-progress` events down to ≤ ~5/sec per table,
+ * while always passing through the lifecycle events (`table-start`,
+ * `table-done`, `done`, `error`) immediately.
+ *
+ * A render over a 6,760-row table would otherwise emit thousands of
+ * `table-progress` events; this caps it at a few dozen. The throttle lives in
+ * the engine so every consumer benefits and no per-entity object crosses the
+ * progress boundary more than ~5×/sec.
+ *
+ * The 200 ms window is reset on every `table-start` (via {@link force}), so each
+ * table gets its own fresh budget and the first progress tick of a new table is
+ * not suppressed by the previous table's last tick.
+ */
+declare class ProgressThrottle {
+    private readonly cb;
+    private readonly windowMs;
+    private lastEmit;
+    constructor(cb: RenderProgressCallback | undefined, windowMs?: number);
+    /**
+     * Emit a `table-progress` event, but only if the window since the last
+     * passthrough has elapsed. Dropped events are simply not delivered — the next
+     * one that survives carries the latest running count.
+     */
+    tick(event: RenderProgress): void;
+    /**
+     * Emit a lifecycle event immediately and reset the throttle window. Use for
+     * `table-start`, `table-done`, `done`, and `error` — none of which should
+     * ever be dropped. Resetting on `table-start` gives each table a clean budget.
+     */
+    force(event: RenderProgress): void;
+}
+
 /**
  * Initialise Lattice from a YAML config file instead of an explicit path.
  *
@@ -1721,8 +1911,8 @@ declare class Lattice {
      * Idempotent: a second call for an already-registered table is a no-op
      * (the underlying CREATE TABLE IF NOT EXISTS is already idempotent at
      * the DB level; this skip avoids the SchemaManager.define throw on
-     * re-registration). Use this property for clients (e.g. TeamsClient)
-     * that may bootstrap their internal tables on every session start.
+     * re-registration). Useful for callers that may bootstrap their
+     * internal tables on every session start.
      *
      * Throws if called before `init()` (use `define()` instead).
      */
@@ -1793,6 +1983,13 @@ declare class Lattice {
      * SchemaManager default.
      */
     getPrimaryKey(table: string): string[];
+    /**
+     * Per-column audience for a table (per-viewer enrichment) — column name →
+     * audience identifier. A column absent from the map has `row-audience`
+     * (visible to whoever can see the row). Empty until a column declares
+     * `audience:`. Drives the generated cell-masking view.
+     */
+    getColumnAudience(table: string): Record<string, string>;
     /**
      * Return the raw column declarations for a registered table, as
      * passed to `define()` / `defineLate()`. Returns null for tables
@@ -1879,7 +2076,35 @@ declare class Lattice {
      * names containing quotes, semicolons, whitespace, etc.
      */
     private _assertIdent;
-    insert(table: string, row: Row): Promise<string>;
+    insert(table: string, row: Row, provenance?: ChangeProvenance): Promise<string>;
+    /**
+     * Insert a row while atomically forcing its cloud row-visibility, regardless of
+     * the table's `default_row_visibility`. The per-table insert trigger reads a
+     * transaction-local GUC (`lattice.force_row_visibility`); we set it and run the
+     * INSERT inside a single transaction, so the row is stamped at `visibility` the
+     * instant it exists — it is never momentarily visible at the table default, and
+     * the change-feed `NOTIFY` (delivered only at COMMIT) fires when the row already
+     * carries this visibility. This closes the create-then-demote window that a
+     * plain `insert()` + `setRowVisibility()` would leave open.
+     *
+     * Postgres-only: SQLite is single-user (no cross-viewer leak) and has no trigger
+     * to read the GUC, so it degrades to a plain {@link insert}. A `never_share`
+     * table still wins — its rows are forced private even if `visibility` is
+     * `'everyone'` (the trigger enforces that precedence).
+     *
+     * @since 3.1.0
+     */
+    insertForcingVisibility(table: string, row: Row, visibility: 'private' | 'everyone', provenance?: ChangeProvenance): Promise<string>;
+    /**
+     * Build the INSERT statement + canonical pk for a row (sanitize → schema-filter →
+     * auto-pk → encrypt). Shared by {@link insert} and {@link insertForcingVisibility}
+     * so both produce byte-identical writes; the latter only differs in running it
+     * inside a GUC-scoped transaction.
+     */
+    private _prepareInsert;
+    /** Post-insert side effects (changelog, audit, write hooks, embedding sync),
+     *  identical for the plain and force-visibility insert paths. */
+    private _afterInsert;
     /**
      * Insert a row and return the full inserted row (including auto-generated
      * fields and defaults). Equivalent to `insert()` followed by `get()`.
@@ -1889,7 +2114,7 @@ declare class Lattice {
     insertReturning(table: string, row: Row): Promise<Row>;
     upsert(table: string, row: Row): Promise<string>;
     upsertBy(table: string, col: string, val: unknown, row: Row): Promise<string>;
-    update(table: string, id: PkLookup, row: Partial<Row>): Promise<void>;
+    update(table: string, id: PkLookup, row: Partial<Row>, provenance?: ChangeProvenance): Promise<void>;
     /**
      * Update a row and return the full updated row. Equivalent to `update()`
      * followed by `get()`.
@@ -1897,7 +2122,43 @@ declare class Lattice {
      * @since 0.17.0
      */
     updateReturning(table: string, id: PkLookup, row: Partial<Row>): Promise<Row>;
-    delete(table: string, id: PkLookup): Promise<void>;
+    delete(table: string, id: PkLookup, provenance?: ChangeProvenance): Promise<void>;
+    /**
+     * Record a DERIVED observation about a row WITHOUT mutating the canonical row.
+     * The canonical row stays broadly-visible ground truth; the observation carries
+     * its provenance (the source-set it was derived from) and is folded into a
+     * per-viewer entity at read time by {@link foldForViewer} — visible only to a
+     * viewer who can reach every one of its sources. This is how an AI enrichment
+     * lands a per-viewer value without leaking it into the shared row, and without
+     * moving the row's `updated_at` (so a viewer who can't see the source can't even
+     * detect that the enrichment exists). `changes` maps column → derived value.
+     */
+    /** Ensure the observation substrate (`__lattice_changelog`) exists. Cloud setup
+     *  calls this before `enableChangelogRls` so the table is present to secure
+     *  even if nothing has written an observation yet. Idempotent. */
+    ensureObservationSubstrate(): Promise<void>;
+    observe(table: string, id: PkLookup, changes: Record<string, unknown>, provenance?: ChangeProvenance, opts?: {
+        keyStore?: SourceKeyStore;
+    }): Promise<void>;
+    /**
+     * Compile the per-viewer view of a row: the ground-truth canonical row with the
+     * DERIVED observations the viewer is allowed to see folded on top (latest
+     * audience-visible observation per attribute wins). A derived value is visible
+     * only when the viewer can reach every source it came from, so un-sharing a
+     * source reverts the value with no residue. `visibleSources` is the set of
+     * source ids the viewer can see; omit it (or pass `'all'`) for the local
+     * single-user case where you see everything. Returns null if the row is absent.
+     */
+    foldForViewer(table: string, id: PkLookup, opts?: {
+        visibleSources?: Iterable<string> | 'all';
+        keyStore?: SourceKeyStore;
+    }): Promise<Row | null>;
+    /** Open any crypto-sealed values in a derived observation's `changes`. Returns
+     *  the plaintext changes, or `null` if a sealed value can't be opened because
+     *  its source's key was shredded (the value is gone for good). Values that
+     *  aren't sealed pass through; with no key store, sealed values can't be read,
+     *  so the observation is dropped (returns null). */
+    private _openSealedObservation;
     get(table: string, id: PkLookup): Promise<Row | null>;
     /**
      * Upsert a record by natural key. If a non-deleted record with the given
@@ -1969,78 +2230,23 @@ declare class Lattice {
      */
     search(table: string, query: string, opts?: SearchOptions): Promise<SearchResult[]>;
     query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    count(table: string, opts?: CountOptions): Promise<number>;
+    render(outputDir: string, opts?: RenderOptions): Promise<RenderResult>;
     /**
-     * Row-level-security list read for Lattice Teams (2.2). Returns only the
-     * rows of `table` that `userId` may see in team `teamId`, evaluated
-     * entirely in SQL (indexed, bounded — never "load every row then filter
-     * in JS"). A row is visible iff it has a `__lattice_row_acl` entry owned by
-     * the user or marked 'everyone', or a 'custom' entry with a matching
-     * `__lattice_row_grants` row, OR it has no ACL entry at all and the caller
-     * passes `noAclVisible` (the table default is 'everyone', or the user owns
-     * the table — the pre-2.2 / never-narrowed case). Soft-deleted rows are
-     * excluded by default; results reuse the same decrypt path as `query()`.
+     * Render into `outputDir` through the shared single-flight guard, intended to
+     * be called fire-and-forget (e.g. the GUI's instant-open background render).
      *
-     * The ACL predicate joins on the table's primary-key column cast to TEXT
-     * (ACL pks are stored as TEXT), so it is correct regardless of the user
-     * table's pk type and works on both SQLite and Postgres. The teams layer's
-     * `listVisibleRows` (src/teams/row-access.ts) is the intended caller.
-     */
-    queryVisible(table: string, opts: {
-        teamId: string;
-        userId: string;
-        /**
-         * Whether rows with NO `__lattice_row_acl` entry are visible to this
-         * user — true when the table default is 'everyone' OR the user owns the
-         * table (the pre-2.2 / never-narrowed case). Resolved by the teams layer
-         * (`listVisibleRows`); defaults to false, i.e. only rows with an explicit
-         * ACL entry granting access are returned.
-         */
-        noAclVisible?: boolean;
-        /** Soft-delete handling: 'exclude' (default), 'only' (trash), 'any'. */
-        deleted?: 'exclude' | 'only' | 'any';
-        limit?: number;
-        offset?: number;
-        orderBy?: string;
-        orderDir?: 'asc' | 'desc';
-    }): Promise<Row[]>;
-    /**
-     * Visible-row counts for MANY tables in a single round-trip, using the same
-     * ACL predicate as {@link queryVisible} — so dashboard tiles agree with what
-     * the rows view lists and a physical count never reveals the existence or
-     * volume of rows the user can't see. One aggregated
-     * `SELECT (SELECT COUNT(*) …) AS c0, …` statement (no per-table fan-out, so
-     * a session pooler with few slots survives concurrent refreshes), capped at
-     * 50 tables per pass; overflow is logged and skipped (no silent truncation)
-     * and those tables count as absent — the caller renders "—". Soft-deleted
-     * rows are excluded wherever the table carries `deleted_at`, matching the
-     * default rows view.
-     */
-    countVisibleMany(specs: {
-        table: string;
-        noAclVisible: boolean;
-    }[], opts: {
-        teamId: string;
-        userId: string;
-    }): Promise<Map<string, number>>;
-    /**
-     * Hosted-sync change-log pull, filtered per recipient for 2.2 row-level
-     * security (the hosted server's sole enforcement mechanism). Returns
-     * `__lattice_change_log` rows with seq > `since` for team `teamId` that
-     * `userId` is permitted to receive:
-     *   - targeted envelopes (`recipient_user_id = userId`), plus
-     *   - broadcast envelopes (`recipient_user_id IS NULL`) that are either
-     *     table-level (`pk IS NULL` — schema / unshare, delivered to all) or
-     *     whose row is currently visible to the user via `__lattice_row_acl` /
-     *     `__lattice_row_grants` (or has no ACL entry and the table defaults to
-     *     'everyone').
-     * Ordered by seq, capped at `limit`. Raw SQL because the predicate needs
-     * OR / EXISTS that the `query()` API can't express; bounded by the seq
-     * window and indexed ACL point-lookups. Mirrors {@link queryVisible}'s
-     * visibility logic so a member never pulls the bytes of a row they can't see.
-     */
-    listChangesForRecipient(teamId: string, since: number, userId: string, limit: number): Promise<Row[]>;
-    count(table: string, opts?: CountOptions): Promise<number>;
-    render(outputDir: string): Promise<RenderResult>;
+     * The guard ({@link _renderGuarded}) holds {@link _autoRenderInFlight} for the
+     * render's duration, so a data mutation that lands while this render is in
+     * flight is deferred by {@link _runAutoRender} and coalesced — when this
+     * render settles, `finally` clears the flag and re-arms exactly one follow-up
+     * render via {@link _rearmAutoRenderIfPending}. Net invariant: at most one
+     * render to a given dir at a time.
+     *
+     * Errors propagate to the caller (the GUI surfaces them, never silently swallowed); they are
+     * not swallowed here.
+     */
+    renderInBackground(outputDir: string, opts?: RenderOptions): Promise<RenderResult>;
     sync(outputDir: string): Promise<SyncResult>;
     /**
      * Recover rows from rendered files into empty database tables.
@@ -2156,6 +2362,17 @@ declare class Lattice {
     /** Turn off automatic rendering and cancel any pending render. */
     disableAutoRender(): this;
     private _scheduleAutoRender;
+    /**
+     * Shared single-flight render path used by {@link renderInBackground}.
+     *
+     * Holds {@link _autoRenderInFlight} for the render's duration so the
+     * mutation-driven {@link _runAutoRender} defers while this render runs (it
+     * sees the flag and marks itself pending instead of starting a second,
+     * overlapping render). On settle, `finally` clears the flag and re-arms a
+     * single coalesced follow-up render if any mutation arrived mid-flight.
+     * Errors propagate to the caller; the flag is always cleared.
+     */
+    private _renderGuarded;
     private _runAutoRender;
     private _rearmAutoRenderIfPending;
     /**
@@ -2167,10 +2384,31 @@ declare class Lattice {
      * shouldn't block the write completion.
      */
     private _syncEmbedding;
-    /** Create the __lattice_changelog table and index. */
+    /**
+     * Create the __lattice_changelog table and index. This is the single,
+     * canonical change-log substrate (the dead `__lattice_change_log` team-sync
+     * envelope was removed in 3.0). Beyond the field-level delta columns it
+     * carries provenance columns for the per-viewer observation model:
+     * `source_ref` (the source-set that informed a derived value),
+     * `change_kind` (`ground_truth` | `derived`), `superseded_by`, `audience`
+     * (defaults to row audience), and `source_sensitive` (crypto-shred flag).
+     * All are additive + nullable (or defaulted) — Stage-0 metadata, no behavior
+     * change until later stages read them.
+     */
+    /** Whether `__lattice_changelog` physically exists (read-only; no DDL), so a
+     *  scoped member can decide there are no observations without trying to create
+     *  the table. */
+    private _changelogTableExists;
     private _ensureChangelogTable;
-    /** Append a changelog entry if the table has changelog enabled. */
+    /** Append a changelog entry if the table has changelog enabled. The optional
+     *  `prov` carries the per-viewer observation provenance (source-set, kind,
+     *  audience, …); when omitted the entry behaves exactly as a pre-3.0 entry. */
     private _appendChangelog;
+    /** The ungated change-log INSERT. `_appendChangelog` wraps it with the
+     *  changelog-enabled gate; `observe()` calls it directly (an observation is an
+     *  explicit, always-recorded write to the substrate). The change-log table must
+     *  exist already. */
+    private _writeChangelogRow;
     /** Prune changelog entries based on retention policy. */
     private _pruneChangelog;
     /** Parse a raw changelog DB row into a ChangeEntry. */
@@ -2286,6 +2524,15 @@ interface LatticeFieldDef {
      * (e.g. `assignee_id: { ref: user }` → relation name `assignee`).
      */
     ref?: string;
+    /**
+     * Per-column audience (Stage-0 scaffolding for the per-viewer enrichment
+     * model). Names who may see this column's value in a cloud. Omitted ⇒
+     * `row-audience` — the value is visible to exactly whoever can see the row,
+     * which is today's behavior, so leaving it unset changes nothing. Later
+     * stages parse a richer grammar (e.g. `subject+role:hr`) and generate a
+     * cell-masking view from it; Stage-0 only records the metadata.
+     */
+    audience?: string;
 }
 /**
  * Inline render spec inside YAML — a flat object alternative to `TemplateRenderSpec`.
@@ -3062,6 +3309,80 @@ declare function hashFile(srcPath: string): Promise<string>;
  */
 declare function attachBlob(srcPath: string, latticeRoot: string): Promise<BlobMetadata>;
 
+/**
+ * S3 object storage for file blobs (cloud workspaces). Bytes uploaded to a cloud
+ * are written to S3 under a content-addressed key so every member who can see the
+ * `files` row can pull them down — see `docs/cloud.md`. `@aws-sdk/client-s3` is an
+ * OPTIONAL dependency, lazy-imported the same way `sharp` is, so a build without it
+ * still loads: callers catch {@link S3UnavailableError} and fall back to local-only
+ * blobs rather than failing.
+ *
+ * Access control is NOT enforced here — it rides entirely on the `files`-row
+ * Postgres RLS at the serve route (`files-routes.ts`): a member only ever learns a
+ * key for a row they can SELECT, keys are unguessable (sha256), and the bucket
+ * credential is least-privilege (GetObject/PutObject only, no ListBucket). See the
+ * security notes in `docs/cloud.md`.
+ */
+/** A minimal remote blob store — the only surface the upload + serve paths use. */
+interface RemoteBlobStore {
+    /** Idempotent upload under `key` (same content ⇒ same key ⇒ same object). */
+    put(key: string, body: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<void>;
+    /** Stream the object's bytes back (to pipe into an HTTP response). */
+    get(key: string): Promise<NodeJS.ReadableStream>;
+    /** Whether an object exists under `key`. */
+    exists(key: string): Promise<boolean>;
+}
+/** Connection config for an S3 (or S3-compatible) bucket. Credentials are optional
+ *  — when omitted, the AWS default credential chain (env / shared config / IAM
+ *  role) is used. `endpoint` (+ path-style) targets R2 / MinIO / LocalStack. */
+interface S3StoreConfig {
+    bucket: string;
+    region: string;
+    prefix: string;
+    endpoint?: string;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/** Thrown when `@aws-sdk/client-s3` is not installed. Callers degrade to
+ *  local-only behavior; they do not 500. */
+declare class S3UnavailableError extends Error {
+    constructor(message: string);
+}
+/** Content-addressed object key: `<prefix>/<sha256>` (POSIX separators, stable
+ *  across machines + idempotent). A leading/trailing slash on the prefix is
+ *  normalized away. */
+declare function s3Key(prefix: string, sha256: string): string;
+/**
+ * Build a {@link RemoteBlobStore} backed by S3. Throws {@link S3UnavailableError}
+ * if the optional `@aws-sdk/client-s3` dependency is absent — the lazy import
+ * mirrors the `sharp` pattern so the module loads without it.
+ */
+declare function createS3Store(cfg: S3StoreConfig): Promise<RemoteBlobStore>;
+
+/**
+ * The S3 config for a cloud workspace, resolved per-member. `enabled` gates the
+ * whole feature; the rest is the {@link S3StoreConfig} the store consumes. Stored
+ * machine-local + encrypted (see user-config `s3-config.enc`), or supplied via env
+ * for headless / CI.
+ */
+interface S3Config extends S3StoreConfig {
+    enabled: boolean;
+}
+/** Extract the cloud workspace LABEL from a config's `db:` line
+ *  (`db: ${LATTICE_DB:label}`), so the S3 config can be keyed by it. Null when the
+ *  config isn't a labelled cloud connection. */
+declare function activeWorkspaceLabel(configPath: string): string | null;
+/**
+ * Resolve the active workspace's S3 config: the per-member machine-local config
+ * keyed by the workspace label, else the environment. Returns null (S3 off) when
+ * neither is configured — so a non-cloud / S3-disabled workspace is untouched.
+ */
+declare function resolveActiveS3Config(configPath: string | undefined): S3Config | null;
+
 /**
  * Machine-local lattice user config — small files that live outside any
  * single Lattice DB so a user's identity, encryption master key, saved
@@ -3416,7 +3737,7 @@ declare function importLegacyUserConfig(root: string): MigrateResult;
  * local and cloud sources share one set of utilities.
  */
 type RefKind = 'blob' | 'local_ref' | 'cloud_ref';
-type RefProvider = 'fs' | 'web' | 'gdrive';
+type RefProvider = 'fs' | 'web' | 'gdrive' | 's3';
 /** The subset of a `files` row the resolver reads. */
 interface FilesRow {
     id?: string;
@@ -3578,520 +3899,6 @@ declare function referenceUrl(url: string, opts?: {
     allowPrivate?: boolean;
 }): Promise<ReferenceMetadata>;
 
-type ColumnType = 'TEXT' | 'INTEGER' | 'REAL' | 'BLOB' | 'JSONB';
-interface ColumnSpec {
-    type: ColumnType;
-    notNull?: boolean;
-    pk?: true;
-    default?: string;
-}
-interface SchemaSpec {
-    columns: Record<string, ColumnSpec>;
-    primaryKey: string | string[];
-    tableConstraints?: string[];
-    relations?: Record<string, {
-        kind: 'belongsTo';
-        table: string;
-        foreignKey: string;
-    }>;
-    schemaVersion: number;
-}
-
-/**
- * Cloud-connect probe — non-destructive inspection of a candidate
- * target Lattice (typically a BYO Postgres URL the user wants to
- * connect to). Used by the GUI's "Migrate to cloud" and "Connect to
- * existing cloud" wizards to surface team-membership requirements
- * before the user commits, but exported as a public API so library
- * consumers can pre-flight the same check.
- *
- * The function opens a short-lived Lattice against the URL, reads
- * the singleton `__lattice_team_identity` row (if any), then closes.
- * It does NOT mutate the target — `init()` does run, which applies
- * the base schema, but no rows are inserted and no GUI/native
- * registration happens here.
- */
-interface CloudProbeResult {
-    /** True iff a Lattice could be opened + init()'d successfully against the URL. */
-    reachable: boolean;
-    /** Adapter dialect of the probed URL. Useful for the GUI to label cards. */
-    dialect: 'sqlite' | 'postgres';
-    /** True iff the probed Lattice has a populated `__lattice_team_identity` row. */
-    teamEnabled: boolean;
-    /** Team name from `__lattice_team_identity.team_name`, if `teamEnabled`. */
-    teamName?: string;
-    /** Underlying error message when `reachable: false`. */
-    error?: string;
-}
-/**
- * Probe a candidate Lattice URL for reachability + team status.
- *
- * Implementation note: this opens a real Lattice with no schema
- * registered beyond what `init()` applies internally, then queries
- * a single row. The `__lattice_team_identity` table doesn't exist on
- * untouched DBs — the query falls through to a "table not found"
- * which we treat as `teamEnabled: false`. On a Lattice that's been
- * through `lattice gui` (which registers the team-identity table
- * during openConfig), the table exists but may be empty, also
- * `teamEnabled: false`.
- *
- * Never throws. Errors are returned in the result's `error` field
- * with `reachable: false`.
- */
-declare function probeCloud(targetUrl: string): Promise<CloudProbeResult>;
-
-/**
- * Local-side client for a Lattice Teams cloud. Wraps the cloud HTTP API
- * and persists per-team connection metadata into the local lattice's
- * `__lattice_team_connections` table.
- *
- * Phase 2 covers identity + team management: register, redeem-invite,
- * list-teams, create-team, delete-team, list-members, invite, kick.
- * Phases 3 and 4 add object sharing, row link/unlink, and the polling
- * sync loop.
- */
-interface TeamSummary {
-    id: string;
-    name: string;
-    role: string;
-}
-interface RegisterResponse {
-    user: {
-        id: string;
-        email: string;
-        name: string;
-    };
-    raw_token: string;
-    team: TeamSummary;
-}
-interface RedeemResponse {
-    user: {
-        id: string;
-        email: string;
-        name: string;
-    };
-    raw_token: string;
-    team: {
-        id: string;
-        name: string;
-    };
-}
-interface MemberSummary {
-    user_id: string;
-    email: string | null;
-    name: string | null;
-    role: string;
-    joined_at: string;
-}
-/**
- * An invitation that has been issued but not yet redeemed — surfaced in the
- * member list so the owner can see who's been invited but hasn't joined.
- */
-interface PendingInvitationSummary {
-    id: string;
-    invitee_email: string;
-    invited_at: string;
-    expires_at: string | null;
-    expired: boolean;
-}
-interface InviteResponse {
-    id: string;
-    raw_token: string;
-    expires_at: string;
-    team_name: string;
-    invitee_email: string;
-}
-interface TeamConnection {
-    team_id: string;
-    team_name: string;
-    cloud_url: string;
-    my_user_id: string;
-    api_token: string;
-    joined_at: string;
-}
-interface SharedObjectSummary {
-    table: string;
-    schema_version: number;
-    schema_spec: SchemaSpec;
-    created_by_user_id: string;
-    created_at: string;
-    updated_at: string;
-}
-interface ShareObjectResponse {
-    table: string;
-    schema_version: number;
-    seq: number;
-    schema_spec: SchemaSpec;
-}
-interface ChangeEnvelope {
-    seq: number;
-    table_name: string | null;
-    pk: string | null;
-    /**
-     * Cloud-emitted ops are `schema`/`unshare`/`link`/`unlink`/`upsert`/`delete`.
-     * `divergence` is a client-side-only marker the puller writes into the DLQ
-     * when a non-owner local edit was overwritten by an owner update — it is
-     * never emitted by the cloud, and applying it is a no-op (the LWW overwrite
-     * already happened; the entry exists so the lost local content is visible).
-     */
-    op: 'schema' | 'unshare' | 'link' | 'unlink' | 'upsert' | 'delete' | 'divergence';
-    payload: unknown;
-    owner_user_id: string | null;
-    created_at: string;
-}
-/**
- * A parsed dead-letter-queue entry — a change envelope that failed to apply
- * during a pull (or a non-owner-overwrite divergence notice), surfaced so an
- * operator can inspect and retry instead of it sitting invisible behind a
- * count. See {@link TeamsClient.listDlq}.
- */
-interface DlqEntry {
-    id: string;
-    team_id: string;
-    /** Table the failed envelope targeted (null for schema-level ops). */
-    table_name: string | null;
-    /** Primary key the failed envelope targeted (null for schema-level ops). */
-    pk: string | null;
-    /** The envelope op, e.g. `upsert` / `link` / `divergence`. */
-    op: string;
-    /** The error that caused the envelope to land in the DLQ. */
-    error: string;
-    created_at: string;
-    /** The full envelope as stored, for retry / inspection. */
-    envelope: ChangeEnvelope;
-}
-interface DlqRetryResult {
-    retried: number;
-    succeeded: number;
-    failed: number;
-}
-interface SyncStatus {
-    team_id: string;
-    team_name: string;
-    last_change_seq: number | null;
-    outbox_depth: number;
-    outbox_failing: number;
-    dlq_depth: number;
-    local_links: number;
-}
-interface PullResult {
-    applied: number;
-    last_seq: number;
-    dlq_count: number;
-}
-interface PushResult {
-    pushed: number;
-    failed: number;
-}
-interface SyncSharedSchemasResult {
-    applied: {
-        table: string;
-        schema_version: number;
-    }[];
-    conflicts: {
-        table: string;
-        reason: string;
-    }[];
-}
-declare class TeamsClient {
-    private readonly local;
-    private _tablesReady;
-    /**
-     * Set during a pull's envelope application so the local write-hook
-     * skips outbox insertion — otherwise B's pull of A's change would
-     * push it right back to the cloud.
-     */
-    private _isReplaying;
-    /** Tables for which a sync write-hook has already been registered. */
-    private readonly _hookedTables;
-    constructor(local: Lattice);
-    /**
-     * Lazy-register the local `__lattice_team_connections` table on first
-     * use. `defineLate` is idempotent, so calling this on every session
-     * start is safe.
-     */
-    ensureLocalTables(): Promise<void>;
-    /**
-     * Bootstrap-register on a fresh cloud and create the team in one
-     * atomic call. The cloud rejects this once any user exists (subsequent
-     * members join via `redeemInvite`). Returns the new user + bearer
-     * token + team summary so the caller can immediately save a
-     * connection.
-     *
-     * @param teamName The workspace display name (stored as `team_name` for
-     * backward compatibility — a cloud IS a workspace with members).
-     */
-    register(cloudUrl: string, email: string, name: string, teamName: string): Promise<RegisterResponse>;
-    redeemInvite(cloudUrl: string, inviteToken: string, email: string, name: string): Promise<RedeemResponse>;
-    /**
-     * Connect a local project to an existing cloud DB by URL. Probes
-     * the target for team status first; if it's a teams DB, the caller
-     * must pass `invite_token` + identity (email/name) and the method
-     * will redeem the invite and save the resulting bearer to
-     * `~/.lattice/keys/<label>.token`. The saved credential lands in
-     * `~/.lattice/db-credentials.enc` keyed by `label`. Caller is
-     * responsible for rewriting the YAML `db:` line to
-     * `${LATTICE_DB:<label>}` and reopening the active Lattice.
-     *
-     * Returns the probe result + (if redeemed) the member info. Throws
-     * if the target is unreachable, or if it's a teams DB and the
-     * caller omitted `invite_token`.
-     */
-    connectToExistingCloud(opts: {
-        label: string;
-        cloudUrl: string;
-        invite_token?: string;
-        email?: string;
-        name?: string;
-    }): Promise<{
-        probe: CloudProbeResult;
-        joinedAsMember?: {
-            user_id: string;
-            team_id: string;
-        };
-    }>;
-    /**
-     * Initialize a fresh cloud DB's owner: register the first member (who
-     * becomes owner) so the cloud's members + per-table sharing surface
-     * exists. This is NOT a "convert a cloud into a team" step — a cloud
-     * workspace IS a workspace with members; this just bootstraps the owner
-     * the first time a cloud is opened. The hosted server path is the only
-     * supported one:
-     *
-     *   - `http(s)://…` — POST to the cloud's `/api/auth/register` endpoint
-     *     (a hosted `lattice serve` teams server is fronting the Postgres).
-     *   - `postgres(ql)://…` — rejected: direct postgres:// owner bootstrap
-     *     is deprecated. Row-level security is enforced by the hosted server,
-     *     so it is the only supported connection method for new workspaces.
-     *
-     * On success writes the bearer token to `~/.lattice/keys/<label>.token`
-     * **and** persists the local `__lattice_team_connections` row so the
-     * GUI's team-management API calls can authenticate immediately
-     * afterward (members, invites, kick, destroy). v1.13.4 added the
-     * connection-row write — the older v1.13 implementation only wrote
-     * the token file, leaving GUI authenticated calls with no
-     * `cloud_url` + `my_user_id` + `api_token_encrypted` row to read.
-     */
-    registerCloudOwner(opts: {
-        label: string;
-        cloudUrl: string;
-        /** Workspace display name (stored as `team_name` for backward compatibility). */
-        teamName: string;
-        email: string;
-        displayName: string;
-    }): Promise<RegisterResponse>;
-    /**
-     * Idempotently initialize a cloud Postgres DB as a collaborative cloud
-     * workspace (members + sharing). 1.16.3 deprecated the user-facing "team"
-     * concept and the explicit "upgrade to team" step — every cloud workspace
-     * gets this machinery automatically at migrate / connect / open time, so the
-     * members + per-table sharing surface is always available on a cloud DB.
-     *
-     * No-op (returns created:false) when the cloud already carries an identity.
-     * On a fresh cloud the caller becomes the owner. Race-safe: a concurrent
-     * initializer that wins the singleton insert is treated as success.
-     */
-    ensureCloudWorkspaceIdentity(opts: {
-        label: string;
-        cloudUrl: string;
-        workspaceName: string;
-        email: string;
-        displayName?: string;
-    }): Promise<{
-        created: boolean;
-    }>;
-    /** Destroy the singleton team. Creator-only on the cloud side. */
-    destroyTeam(cloudUrl: string, token: string): Promise<void>;
-    listMembers(cloudUrl: string, token: string, teamId: string): Promise<MemberSummary[]>;
-    listPendingInvitations(cloudUrl: string, token: string, teamId: string): Promise<PendingInvitationSummary[]>;
-    invite(cloudUrl: string, token: string, teamId: string, inviteeEmail: string, expiresInHours?: number, inviterUserId?: string): Promise<InviteResponse>;
-    kickMember(cloudUrl: string, token: string, teamId: string, userId: string): Promise<void>;
-    me(cloudUrl: string, token: string): Promise<{
-        user: {
-            id: string;
-            email: string | null;
-            name: string | null;
-        };
-    }>;
-    /**
-     * Share a table with the team. Re-sharing the same table bumps its
-     * `schema_version` and replaces the stored spec — useful for evolving
-     * shared schemas additively.
-     */
-    shareObject(cloudUrl: string, token: string, teamId: string, table: string, schemaSpec: SchemaSpec, inviterUserId?: string): Promise<ShareObjectResponse>;
-    /**
-     * Stop sharing a table. Only the original sharer or the team creator
-     * can call this. The cloud soft-deletes the `__lattice_shared_objects`
-     * row and appends an `unshare` envelope to the change log.
-     */
-    unshareObject(cloudUrl: string, token: string, teamId: string, table: string): Promise<void>;
-    listSharedObjects(cloudUrl: string, token: string, teamId: string): Promise<SharedObjectSummary[]>;
-    /**
-     * Pull change envelopes since the given sequence number. Phase 3
-     * emits `schema` and `unshare` ops; Phase 4 adds row-level ops. The
-     * `has_more` flag tells callers to loop until drained before sleeping.
-     */
-    fetchChangeBatch(cloudUrl: string, token: string, teamId: string, since?: number, limit?: number): Promise<{
-        envelopes: ChangeEnvelope[];
-        has_more: boolean;
-    }>;
-    /**
-     * Fetch every shared object on the team's cloud and apply each spec
-     * to the local lattice. New tables go through `defineLate`; existing
-     * tables get additive ALTER TABLE for any cloud-only columns. PK
-     * mismatches are surfaced as `TeamsSchemaConflictError`s and recorded
-     * in the returned summary so callers can present them to the user.
-     *
-     * Phase 4 will wrap this in a polling loop; Phase 3 invokes it on
-     * demand from the CLI / GUI.
-     */
-    syncSharedSchemas(connection: TeamConnection): Promise<SyncSharedSchemasResult>;
-    /**
-     * Apply a single cloud SchemaSpec to the local lattice. Returns true
-     * if any change was made (new table, new column), false if local was
-     * already in sync. Throws `TeamsSchemaConflictError` on PK mismatch.
-     */
-    applyCloudSchemaLocally(table: string, spec: SchemaSpec): Promise<boolean>;
-    /**
-     * Persist a team connection in the local lattice. If a row already
-     * exists for the same `team_id`, it's overwritten — the caller has
-     * presumably just redeemed a fresh invitation or recreated the team.
-     *
-     * Token encryption: Phase 2 stores tokens in plaintext. Lattice's
-     * existing AES-256-GCM encryption layer can wrap this column when the
-     * caller configures `encryptionKey`, but the entity-context encryption
-     * API doesn't apply to raw `define()`/`defineLate()` tables yet. A
-     * follow-up will enable per-column encryption for these internal
-     * tables; until then operators should keep their lattice DB file safe.
-     */
-    saveConnection(conn: {
-        team_id: string;
-        team_name: string;
-        cloud_url: string;
-        my_user_id: string;
-        api_token: string;
-    }): Promise<void>;
-    deleteConnection(teamId: string): Promise<void>;
-    listConnections(): Promise<TeamConnection[]>;
-    /**
-     * Resolve a team name to a local connection row. Throws if more than
-     * one matches (e.g. user joined two teams with the same name on
-     * different clouds) — caller must disambiguate with team_id.
-     */
-    findConnectionByName(teamName: string): Promise<TeamConnection | null>;
-    /**
-     * Link a local row to a team. Reads the current local row, POSTs the
-     * snapshot to the cloud (which creates a `__lattice_row_links` row +
-     * mirrors the data into the team's shared table + emits link/upsert
-     * envelopes), and records the link on the local side.
-     *
-     * Also ensures the sync write-hook is attached for `table` so future
-     * local writes to this row drain through the outbox to the cloud.
-     */
-    linkRow(connection: TeamConnection, table: string, pk: string): Promise<{
-        owner_user_id: string;
-        seq: number;
-    }>;
-    /**
-     * Remove a row from the team. The cloud verifies the caller is the
-     * owner (or team creator) and emits an `unlink` envelope; the local
-     * link row is removed and the local data row is kept in place (Phase
-     * 4 v1 default — receivers' pullers handle their own removal).
-     */
-    unlinkRow(connection: TeamConnection, table: string, pk: string): Promise<void>;
-    /**
-     * Scan `__lattice_local_links` for tables that currently have at
-     * least one link and ensure a write-hook is registered for each.
-     * Called by CLI sync commands at session start to re-arm hooks after
-     * a process restart (write hooks are bound to the in-memory Lattice
-     * instance, not the underlying DB).
-     */
-    attachWriteHooks(): Promise<void>;
-    /**
-     * Register a sync write-hook for a single table. Idempotent: a second
-     * call for the same table is a no-op. Called automatically by
-     * `linkRow` and `applyCloudSchemaLocally`; manual callers can invoke
-     * directly for tables that exist before any link/share happens.
-     *
-     * The hook captures local writes to linked rows into
-     * `__lattice_team_outbox`. The replay guard (`_isReplaying`) skips
-     * captures during envelope application so pulled changes don't get
-     * pushed back to the cloud.
-     */
-    ensureWriteHook(table: string): void;
-    private captureWrite;
-    /**
-     * Drain the outbox for one team in FIFO order. Each entry POSTs to
-     * the cloud's row endpoint (or DELETEs for soft-delete ops). 2xx
-     * deletes the outbox row; failures increment `attempts` + set
-     * `next_attempt_at` to an exponential-backoff future timestamp,
-     * leaving the row for a later drain.
-     *
-     * Phase 4 v1: no separate dead-letter for outbox entries. Repeated
-     * 4xx responses just keep retrying with a growing backoff — operator
-     * surfaces them via `lattice teams status`.
-     */
-    drainOutbox(connection: TeamConnection): Promise<PushResult>;
-    /**
-     * Pull change envelopes from the cloud and apply them to the local
-     * lattice. Loops internally until the cloud reports no more pending
-     * envelopes, so a single call drains arbitrary backlog. Bookkeeping:
-     * the local connection's `last_change_seq` advances per successful
-     * envelope; the replay guard prevents pulled writes from being re-
-     * pushed back to the cloud via the outbox.
-     *
-     * Individual envelope failures land in `__lattice_team_dlq` so one
-     * bad row doesn't stall the stream.
-     */
-    pullChanges(connection: TeamConnection, batchSize?: number): Promise<PullResult>;
-    private applyEnvelope;
-    /**
-     * Apply an `upsert` envelope to a local row, guarding against silently
-     * clobbering a non-owner's local edit.
-     *
-     * A non-owner who edits a mirrored row locally produces no outbox entry
-     * (only owners push), so the next owner update would overwrite it with no
-     * trace. Before the last-write-wins overwrite, this compares the current
-     * local row against the hash captured at the last sync (`synced_hash` on
-     * the link row): if they differ, the local copy diverged, so we record a
-     * `divergence` entry in the DLQ — capturing the lost local content — then
-     * still apply (LWW keeps sync converging). The loss is now visible via
-     * `lattice teams dlq list` instead of being silent.
-     *
-     * Owner rows are never overwritten by foreign upserts, so they skip the
-     * check. `synced_hash` is (re)stamped from the stored row after every apply.
-     */
-    private applyUpsertEnvelope;
-    private findLocalLink;
-    /**
-     * List the DLQ entries for a team, newest first, with the stored envelope
-     * parsed for inspection.
-     */
-    listDlq(connection: TeamConnection): Promise<DlqEntry[]>;
-    /**
-     * Replay DLQ entries through {@link applyEnvelope}. With `id`, retries just
-     * that entry; otherwise retries every entry for the team (oldest first, so
-     * dependencies replay before dependents). An entry that applies cleanly is
-     * deleted; one that fails again stays, with its `error` refreshed. Runs
-     * under the replay guard so a re-applied row isn't pushed back to the cloud.
-     */
-    retryDlq(connection: TeamConnection, id?: string): Promise<DlqRetryResult>;
-    /**
-     * Delete DLQ entries without applying them. With `id`, purges just that
-     * entry; otherwise purges every entry for the team. Returns the count
-     * removed. Use to discard divergence notices or envelopes that will never
-     * apply.
-     */
-    purgeDlq(connection: TeamConnection, id?: string): Promise<number>;
-    getStatus(connection: TeamConnection): Promise<SyncStatus>;
-    private fetchUnauthed;
-    private fetchAuthed;
-}
-declare class TeamsHttpError extends Error {
-    readonly status: number;
-    constructor(status: number, message: string);
-}
-
 /**
  * Cloud migration — copy a Lattice's data from one backing store to
  * another. Used by the GUI's "Migrate to cloud" flow, but exported as
@@ -4172,58 +3979,420 @@ declare function openTargetLatticeForMigration(configPath: string, targetUrl: st
 declare function archiveLocalSqlite(dbPath: string): string;
 
 /**
- * Shape returned by both the HTTP register path and the Postgres-direct
- * register path. Kept aligned with `RegisterResponse` in
- * `src/teams/client.ts`.
+ * Cloud-connect probe — non-destructive inspection of a candidate target
+ * Lattice (a Postgres URL the user wants to migrate to or join). Used by the
+ * GUI's "Migrate to cloud" and "Join a cloud" flows to tell, before the user
+ * commits, whether a URL points at a fresh database or an already-secured
+ * Lattice cloud. Exported as public API so library consumers can pre-flight the
+ * same check.
+ *
+ * A "cloud" in v3 is a shared Postgres database with Lattice RLS installed —
+ * its tell is the bookkeeping table `__lattice_owners` (created by
+ * `installCloudRls`). The probe opens the URL with `introspectOnly` (NO DDL, so
+ * it works even when the caller holds a scoped, non-superuser member role), asks
+ * Postgres whether that table exists, and closes. It never mutates the target.
  */
-interface DirectRegisterResult {
-    user: {
-        id: string;
-        email: string;
-        name: string;
-    };
-    raw_token: string;
-    team: {
-        id: string;
-        name: string;
-        role: 'creator';
-    };
+interface CloudProbeResult {
+    /** True iff the URL could be opened (connected + authenticated). */
+    reachable: boolean;
+    /** Adapter dialect of the probed URL. */
+    dialect: 'sqlite' | 'postgres';
+    /**
+     * True iff the target is an established Lattice cloud — Postgres with RLS
+     * bookkeeping (`__lattice_owners`) present. A fresh Postgres (no Lattice
+     * schema yet) and any SQLite file are `false`: the former is a migration
+     * target, the latter is a private local store.
+     */
+    isCloud: boolean;
+    /** Underlying error message when `reachable: false`. */
+    error?: string;
 }
+/** Detect the RLS bookkeeping table without assuming SELECT privilege on it.
+ *  `to_regclass` returns the table's OID name when it exists and NULL when it
+ *  doesn't — and, unlike `SELECT FROM __lattice_owners`, it does not require any
+ *  privilege on the table, so a scoped member (who is denied SELECT on the
+ *  bookkeeping tables) still gets a truthful answer. */
+declare function cloudRlsInstalled(probe: Lattice): Promise<boolean>;
 /**
- * True iff `url` parses as a `postgres://` / `postgresql://` URL — used
- * by the GUI's upgrade flow to decide between HTTP `register` and the
- * direct-Postgres path implemented here.
+ * Whether the connected role may create other roles — the capability that
+ * separates a cloud OWNER (ran the migration, owns the rows, can invite members)
+ * from a scoped MEMBER (provisioned `NOCREATEROLE`). Read from
+ * `pg_roles.rolcreaterole` for the live role. SQLite or any error → false.
+ */
+declare function canManageRoles(db: Lattice): Promise<boolean>;
+/**
+ * Probe a candidate Lattice URL for reachability + cloud status.
+ *
+ * Never throws. Errors are returned in the result's `error` field with
+ * `reachable: false`.
+ */
+declare function probeCloud(targetUrl: string): Promise<CloudProbeResult>;
+
+/**
+ * True iff `url` parses as a `postgres://` / `postgresql://` URL. Used by
+ * the GUI to distinguish a cloud (shared Postgres) connection from a local
+ * SQLite file path.
  */
 declare function isPostgresUrl(url: string): boolean;
+
+/**
+ * One-time bootstrap for a cloud: the ownership bookkeeping tables and the shared
+ * `SECURITY DEFINER` helpers. Idempotent (`CREATE TABLE IF NOT EXISTS`,
+ * `CREATE OR REPLACE FUNCTION`). Multi-statement — Postgres-only, so it never hits
+ * the single-statement SQLite migration path.
+ *
+ * Every `SECURITY DEFINER` helper below gets `search_path` pinned at install time
+ * via {@link pinDefinerSearchPath} (see its doc for the threat it closes). The pin
+ * is applied in {@link installCloudRls}, not baked into the literal here, because
+ * the cloud's schema name is only known at runtime (`current_schema()`).
+ */
+/**
+ * Group role every cloud member inherits. Table privileges are granted to the
+ * group, so adding a shared table or a member is a single GRANT — while RLS still
+ * filters rows per individual login role (`session_user`). The group grants
+ * *access*, never *visibility*.
+ */
+declare const MEMBER_GROUP = "lattice_members";
+/** Install the cloud RLS bootstrap (bookkeeping + helper functions). No-op on SQLite. */
+declare function installCloudRls(db: Lattice): Promise<void>;
+/**
+ * Secure the observation substrate (`__lattice_changelog`) so a member reads
+ * only what they're allowed to: a DERIVED observation only when it can reach
+ * EVERY source it was derived from (so a hidden enrichment never reaches the
+ * member — existence-hiding is structural), and a ground-truth / audit entry
+ * only when the member OWNS the row it records. Both predicates route through the
+ * `session_user`-keyed SECURITY DEFINER helpers, so they bind to the real member.
+ * `FORCE ROW LEVEL SECURITY` applies the policy even to the table owner. No-op on
+ * SQLite (single-user; no cross-viewer leak to guard). Run after the change-log
+ * table exists (`Lattice.ensureObservationSubstrate`).
+ *
+ * Ground-truth entries are OWNER-ONLY (v2), not merely "row is visible". A
+ * changelog row carries the full `changes`/`previous` JSON of the underlying row —
+ * EVERY column in cleartext, including ones the `<table>_v` mask hides from a
+ * non-owner (an `owner`-audience secret column, a role-gated column). If a member
+ * who was merely granted the row could read its history, those masked columns
+ * would leak in cleartext, bypassing column masking. The row's full mutation
+ * history is an owner/audit artifact; a non-owner sees the row only through the
+ * masked view, never its raw history. (The derived-observation branch is the
+ * per-viewer enrichment path and is unaffected — it carries enrichment, not the
+ * base row's masked columns.)
+ */
+declare function enableChangelogRls(db: Lattice): Promise<void>;
+/**
+ * Enable RLS on one shared table. No-op on SQLite. Idempotent via a per-table
+ * version key. v3 bumps the key so existing clouds re-install the policy-aware
+ * insert trigger (which now stamps the per-table `default_row_visibility` / forces
+ * private under `never_share`) and pick up the `search_path` pin on the trigger
+ * function — neither of which a v2-stamped clone would otherwise get.
+ */
+declare function enableRlsForTable(db: Lattice, table: string, pkCols: readonly string[]): Promise<void>;
+/**
+ * Stamp the current role as owner of every row that already exists in a table —
+ * for data migrated into a cloud BEFORE the ownership trigger existed (the
+ * trigger only fires on new writes). Without this, migrated rows have no
+ * ownership record and RLS would hide them from everyone. Idempotent; no-op on
+ * SQLite or an unkeyable table.
+ */
+declare function backfillOwnership(db: Lattice, table: string, pkCols: readonly string[]): Promise<void>;
+
+/** A URL-safe random password (48 hex chars) for a new member role. */
+declare function generateMemberPassword(): string;
+/**
+ * Derive a safe, unique Postgres role name from a free-form label (e.g. an email
+ * or display name). Lowercased, non-word chars collapsed to `_`, prefixed so it
+ * always starts legally and namespaced under `lm_`, with a short random suffix so
+ * two people with similar labels never collide.
+ */
+declare function memberRoleName(label: string): string;
+/**
+ * Create (or re-key) a scoped member LOGIN role and add it to the member group.
+ * Idempotent on the role's existence: a re-invite rotates the password. Requires
+ * the connection to hold `CREATEROLE`. After this, the member connects with
+ * `postgres://<role>:<password>@<host>/<db>` and sees only its permitted rows.
+ */
+declare function provisionMemberRole(db: Lattice, role: string, password: string): Promise<void>;
+/**
+ * Change a row's sharing through the owner-only `lattice_set_row_visibility`
+ * SECURITY DEFINER function. Only the row's owner (Postgres raises for anyone
+ * else, enforced inside the function) may call it. `pk` is the row's canonical
+ * primary-key string — a single-column key is the bare value; a composite key is
+ * its columns joined by TAB, matching Lattice's serialization.
+ */
+declare function setRowVisibility(db: Lattice, table: string, pk: string, visibility: string): Promise<void>;
+/**
+ * Per-card audience override: grant (or revoke) one member access to ONE masked
+ * cell — a specific (table, pk, column) — without changing the column's
+ * schema-level audience. Owner-only (the SQL function raises for a non-owner).
+ * `pk` is the row's canonical primary-key string.
+ */
+declare function grantCell(db: Lattice, table: string, pk: string, column: string, grantee: string): Promise<void>;
+declare function revokeCell(db: Lattice, table: string, pk: string, column: string, grantee: string): Promise<void>;
+/**
+ * Remove a member: clear its privileges and drop the role. NOTE: rows the member
+ * owned remain in their tables but become unreachable (their `owner_role` no
+ * longer matches any login role, and RLS shows a row only to its owner / grantees
+ * / everyone) — reassigning or purging a departed member's rows is a separate,
+ * deliberate step, not a side effect of revoking access.
+ */
+declare function revokeMemberRole(db: Lattice, role: string): Promise<void>;
+
+/**
+ * Physical-schema discovery for cloud members. A member connects to a shared
+ * cloud as a scoped role whose local config may declare NO entities — yet the
+ * GUI must show every table the member is allowed to use. Postgres only exposes
+ * a table in `pg_tables` / `information_schema` to a role that holds a privilege
+ * on it, so listing the role's visible user tables is exactly the set RLS lets
+ * it touch: the member's granted tables, never another's bookkeeping.
+ */
+interface DiscoveredTable {
+    name: string;
+    columns: string[];
+    /** Primary-key column(s), in key order. May be empty for a keyless table. */
+    pk: string[];
+}
+/**
+ * List the user tables a member's role is actually privileged to use, excluding
+ * Lattice/GUI bookkeeping (anything starting `_`). `information_schema.tables`
+ * is privilege-filtered — it shows a role only the tables it holds a grant on or
+ * owns — so this returns exactly the member's reachable set, never another
+ * member's bookkeeping (which is granted to no one). Scoped to `current_schema()`
+ * so it follows the connection's search_path (the cloud's `public` in production).
+ * Returns each table's columns + primary key so the caller can register it.
+ * Postgres-only — returns `[]` on SQLite (a private, single-user store).
+ */
+declare function discoverCloudTables(db: Lattice): Promise<DiscoveredTable[]>;
+
+/** Row context the `owner` clause needs (the table literal + pk SQL expression). */
+interface AudienceRowCtx {
+    tableLit: string;
+    pkExpr: string;
+}
+/** True when this audience means "no mask" (visible to whoever can see the row). */
+declare function isRowAudience(audience: string | undefined): boolean;
+/**
+ * Compile a column `audience` spec into a boolean SQL predicate over the helper
+ * functions. Returns `'true'` for the row-audience / everyone case. Throws on an
+ * unknown or malformed clause.
+ */
+declare function audiencePredicate(audience: string, ctx?: AudienceRowCtx): string;
+/** Whether a table needs a masking view at all (any column has a real audience). */
+declare function tableNeedsAudienceView(columnAudience: Record<string, string>): boolean;
+/**
+ * SQL to (re)generate a table's cell-masking view, point members at it, and make
+ * the base table's columns unreachable to members so the mask can't be bypassed:
+ *
+ *  - `CREATE OR REPLACE VIEW <t>_v` — every column passes through, except
+ *    audience columns which become `CASE WHEN <predicate> THEN col END`.
+ *  - The view re-applies ROW visibility with `WHERE lattice_row_visible(t, pk)`.
+ *    This is essential: the view runs with its OWNER's rights, so the base
+ *    table's RLS would be evaluated as the owner (who sees everything). The
+ *    `session_user`-keyed SECURITY DEFINER helper re-binds row filtering to the
+ *    real member, so an owner-defined view still filters per viewer.
+ *  - `GRANT SELECT` on the view + `REVOKE SELECT` on the base from members: a
+ *    member reads only the masked, row-filtered view and cannot reach the raw
+ *    column. (Member writes to such a table flow through the observation path —
+ *    members keep INSERT/UPDATE/DELETE on the base under RLS; only SELECT moves
+ *    to the view.)
+ *
+ * Idempotent. `columns` is the table's full column list (stable order); `pkCols`
+ * its primary key, so the row filter matches the RLS policy's pk serialization.
+ */
+declare function audienceViewSql(table: string, columns: readonly string[], pkCols: readonly string[], columnAudience: Record<string, string>): string;
+/**
+ * Generate + install a table's cell-masking view (Postgres only; no-op on SQLite
+ * and on a table with no audience columns). Versioned by a content hash of the
+ * columns / pk / column-audience so a changed spec regenerates and an unchanged
+ * one is skipped. Run AFTER the table + RLS exist (the view reuses the row
+ * visibility helper and revokes the base SELECT that enableRlsForTable granted).
+ */
+declare function enableAudienceView(db: Lattice, table: string, columns: readonly string[], pkCols: readonly string[], columnAudience: Record<string, string>): Promise<void>;
+/** Read a table's canonical column->audience map from __lattice_column_policy. */
+declare function loadColumnPolicy(db: Lattice, table: string): Promise<Record<string, string>>;
+/** Seed a table's YAML-declared audiences into __lattice_column_policy — ONE TIME
+ *  per table, the migration from the legacy on-disk spec to the DB-canonical store.
+ *  A marker in __lattice_migrations gates it: after the first run we never seed from
+ *  YAML again, because a later secureCloud would otherwise re-insert a policy row
+ *  for a column the owner has since CLEARED through the DB (a cleared column has no
+ *  row, so ON CONFLICT DO NOTHING would NOT protect it) — silently re-masking a
+ *  column the owner deliberately un-masked. Once seeded, the DB is canonical and
+ *  the only path to change a column's audience is setColumnAudience. */
+declare function seedColumnPolicyFromYaml(db: Lattice, table: string, yamlAudience: Record<string, string>): Promise<void>;
+/** Regenerate a table's cell-masking view FROM the DB column-policy (not YAML). If
+ *  the table now has no audience columns, drop the view and restore base SELECT to
+ *  members; otherwise (re)create the masked view and revoke base SELECT. Runs the
+ *  DDL directly (not via db.migrate) so it always reflects the current spec. */
+declare function regenerateAudienceViewFromDb(db: Lattice, table: string, columns: readonly string[], pkCols: readonly string[]): Promise<void>;
+/** Owner-only: set (or clear, with an empty spec) a column's audience in the DB and
+ *  regenerate the table's mask view from the DB. The owner gate is enforced inside
+ *  lattice_set_column_audience (raises for a non-owner). */
+declare function setColumnAudience(db: Lattice, table: string, column: string, audience: string, columns: readonly string[], pkCols: readonly string[]): Promise<void>;
+
+/**
+ * Per-table cloud policy (owner-controlled, Postgres-stored + enforced):
+ *  - `defaultRowVisibility` — the visibility NEW rows in this table are stamped
+ *    with (the per-table insert trigger reads `__lattice_table_policy`); default
+ *    `private` ⇒ unchanged behavior.
+ *  - `neverShare` — a hard exclusion (Secrets/Messages-class): the share/grant
+ *    SECURITY DEFINER functions raise for the table and the trigger forces its rows
+ *    private. Set at the data-model level, so a direct `psql` connection obeys it.
+ *
+ * These are thin wrappers over the owner-gated SQL functions in the RLS bootstrap
+ * (`lattice_set_table_default_visibility` / `lattice_set_table_never_share`), which
+ * raise unless the caller can create roles. No-op / safe defaults on SQLite.
+ */
+type RowVisibilityDefault = 'private' | 'everyone';
+interface TablePolicy {
+    defaultRowVisibility: RowVisibilityDefault;
+    neverShare: boolean;
+}
+/** Read a table's policy. Returns the safe default (private, shareable) on SQLite
+ *  or when no policy row exists. */
+declare function getTablePolicy(db: Lattice, table: string): Promise<TablePolicy>;
+/** Owner-only: set the visibility NEW rows in `table` are created with. Raises (via
+ *  the SQL function) for a non-owner or for `everyone` on a never-share table. */
+declare function setTableDefaultVisibility(db: Lattice, table: string, visibility: RowVisibilityDefault): Promise<void>;
+/** Owner-only: mark (or unmark) a table never-shareable. When on, the share/grant
+ *  functions refuse it and its new rows are forced private. */
+declare function setTableNeverShare(db: Lattice, table: string, on: boolean): Promise<void>;
+
 /**
- * Direct-Postgres equivalent of the cloud's `POST /api/auth/register`.
+ * The per-viewer fold (the "local compile" of the per-viewer enrichment model).
  *
- * The HTTP teams-cloud server (`lattice serve --team-cloud`) handles
- * `register` by running an INSERT sequence inside its own request
- * handler. This helper does the same sequence locally by opening the
- * cloud Postgres directly — useful when the GUI's "Migrate to cloud"
- * or "Connect to existing cloud" flow has saved the **Postgres URL**
- * as the cloud credential (no HTTP teams server in front).
+ * Source-gated enrichment is per-viewer: a value derived from a file that one
+ * member can't see must not appear for that member. Postgres RLS + the generated
+ * mask view handle row visibility and fixed-policy columns; this handles the
+ * remaining case — a column whose VALUE differs by which sources you can reach.
  *
- * Hard browser limitation that motivates this: when `cloudUrl` is a
- * Postgres URL with embedded credentials, the HTTP path's `fetch(url)`
- * throws "Request cannot be constructed from a URL that includes
- * credentials" before any network IO happens. We have to drive the
- * register flow against the database protocol, not HTTP.
+ * The compile is a deterministic, programmatic fold (NOT AI): start from the
+ * broadly-visible ground-truth projection, then replay the observations the
+ * viewer is allowed to see — latest audience-visible observation per attribute
+ * wins. Because observations are additive and only the viewer-visible ones
+ * contribute, the fold is provably leak-free (sound only for additive/monotonic
+ * derivations) and revocation is structural: drop a viewer's access to a source
+ * and every value derived from it silently reverts to the prior visible
+ * observation (or ground truth), with no residue — no promotion, no copy left
+ * behind. Run on the member's local replica over already-audience-gated
+ * observations, so hidden observations never reach them (existence-hiding is
+ * structural) and egress is paid once at pull, never per read.
+ */
+/** One attribute-level observation — a single column's value with its provenance. */
+interface Observation {
+    /** The column this observation sets. */
+    attribute: string;
+    /** The value it sets the column to. */
+    value: unknown;
+    /** Ordering key (ISO timestamp). Latest visible observation per attribute wins. */
+    createdAt: string;
+    /** `ground_truth` (always visible) or `derived` (gated by its source-set). */
+    changeKind?: 'ground_truth' | 'derived' | null;
+    /** Source ids that produced a derived value. The observation is visible to a
+     *  viewer only if the viewer can see EVERY one of them (intersection-of-sources
+     *  reader set — losing any source hides the derived value). */
+    sourceRef?: readonly string[] | null;
+}
+/** What a given member can reach, for deciding observation visibility. */
+interface Viewer {
+    /** Source ids (file primary keys) this member can currently see. */
+    visibleSources: ReadonlySet<string>;
+}
+/**
+ * Whether a viewer may see an observation. Ground-truth is always visible (it is
+ * the broadly-shared projection). A derived observation is visible iff the viewer
+ * can see every source it was derived from — so un-sharing or deleting any one
+ * source drops it. An unsourced derived observation is treated as hidden (fail
+ * closed): a derived value with no recorded provenance can't be proven safe.
+ */
+declare function observationVisible(obs: Observation, viewer: Viewer): boolean;
+/**
+ * Compile one per-viewer entity: overlay the viewer-visible observations onto the
+ * ground-truth projection, latest-per-attribute winning. Pure + deterministic —
+ * the same (ground, observations, viewer) always yields the same row, and an
+ * observation the viewer can't see never affects the result.
+ */
+declare function foldEntity(ground: Row, observations: readonly Observation[], viewer: Viewer): Row;
+/**
+ * Expand a change-log row's `changes` object into per-attribute observations.
+ * The change-log records one row per write with a JSON `changes` map; the fold
+ * works per attribute, so each changed field becomes its own observation carrying
+ * the write's provenance. (Caller supplies the already-parsed change-log entry.)
+ */
+declare function observationsFromChange(entry: {
+    changes: Record<string, unknown> | null;
+    createdAt: string;
+    changeKind?: 'ground_truth' | 'derived' | null;
+    sourceRef?: readonly string[] | null;
+}): Observation[];
+
+declare class FoldCache {
+    private readonly cache;
+    /** Compiled entity for (rowId, viewer), computing + caching it on a miss. */
+    get(rowId: string, ground: Row, observations: readonly Observation[], viewer: Viewer): Row;
+    /** Drop every cached version of a row — call when a new observation lands for
+     *  it (any viewer's compile may have changed). Cheap, exact, no over-eviction
+     *  of other rows. */
+    invalidateRow(rowId: string): void;
+    /** Drop everything (e.g. on a full replica re-pull). */
+    clear(): void;
+    /** Number of cached (row, viewer) compilations — for tests / introspection. */
+    get size(): number;
+}
+
+/**
+ * Turn a Postgres database into a secured Lattice cloud, in place: install the
+ * RLS bootstrap + the observation substrate, then for every registered user
+ * table stamp the current role as owner of the existing rows and force RLS (plus
+ * a cell-masking view for any audience columns). Idempotent and additive — safe
+ * to run on a fresh migration target OR on an already-populated Postgres that
+ * isn't a cloud yet (the "secure this cloud" cutover). No-op on SQLite.
  *
- * Mirrors `handleRegister`'s invariants:
- *   - Refuses if any non-deleted user already exists on the cloud.
- *   - Refuses if the `__lattice_team_identity` singleton already exists.
+ * Must run as a role that owns the tables and can create roles (a cloud
+ * owner / DBA). `backfillOwnership` runs BEFORE `enableRlsForTable` so a
+ * non-superuser owner can still SELECT every row to stamp it before FORCE RLS
+ * filters the table to rows it already owns.
+ */
+declare function secureCloud(db: Lattice): Promise<void>;
+
+/**
+ * Workspace-level settings for a cloud — cloud-wide values the OWNER controls and
+ * members never see in the product surface. Stored in `__lattice_cloud_settings`,
+ * a bookkeeping table members have no grant on — so its VALUE is unreadable to a
+ * member (SELECT is denied, like every other `__lattice_*` table; the System view
+ * may still list the table's existence + column names from the catalog, but never
+ * its contents). It is reached only through two `SECURITY DEFINER` helpers:
  *
- * On success returns the same shape the HTTP route returns so a
- * direct-postgres register can mirror the hosted register path.
+ *   - `lattice_get_cloud_setting(key)` — readable by members, because a member's
+ *     own chat must inject the value (the chat call is assembled in each member's
+ *     LOCAL gui process). This is the deliberate, documented ceiling: secrecy is
+ *     **app-mediated** (hidden from the UI + every API response), NOT cryptographic
+ *     — a member CAN read the value from their own session if they go looking.
+ *   - `lattice_set_cloud_setting(key, value)` — owner-only (RAISEs unless the
+ *     caller can create roles, the same gate as `lattice_assign_role`).
  *
- * @deprecated Since 2.2 — new direct registrations are rejected (a direct
- * connection bypasses row-level security). Retained only for the
- * grandfathered existing-connection path; will be removed in 3.0. Create or
- * join new workspaces through a hosted Teams server (an `http(s)://` URL).
+ * Postgres-only: a local SQLite workspace is single-user, so there is nothing to
+ * keep secret and these are all no-ops / null there.
+ */
+/** Setting key for the chat system prompt an owner bundles into every member's chat. */
+declare const CLOUD_SETTING_SYSTEM_PROMPT = "chat_system_prompt";
+/**
+ * Install the workspace-settings table + helpers. Idempotent (`CREATE TABLE IF
+ * NOT EXISTS` / `CREATE OR REPLACE FUNCTION`). No-op on SQLite. Run as the cloud
+ * owner — `secureCloud` calls it for new clouds, and the owner-only settings
+ * endpoint calls it lazily so an already-secured cloud picks it up on first use.
+ */
+declare function installCloudSettings(db: Lattice): Promise<void>;
+/**
+ * Read a cloud workspace setting via the SECURITY DEFINER getter. Best-effort:
+ * returns null on SQLite, on a cloud that hasn't installed the helper yet (the
+ * function is absent), or on any error — so a caller treats "unset" and "couldn't
+ * read" identically (e.g. the chat path simply injects nothing).
+ */
+declare function getCloudSetting(db: Lattice, key: string): Promise<string | null>;
+/**
+ * Owner-only: write a cloud workspace setting via the SECURITY DEFINER setter.
+ * The function RAISEs if the caller isn't a cloud owner; that surfaces here as a
+ * thrown error which the (already owner-gated) endpoint reports. Not silent.
  */
-declare function registerDirectViaPostgres(cloudUrl: string, email: string, name: string, teamName: string): Promise<DirectRegisterResult>;
+declare function setCloudSetting(db: Lattice, key: string, value: string): Promise<void>;
 
 /** A content block in the Anthropic message format used here. */
 type ContentBlock = {
@@ -4514,4 +4683,4 @@ interface PdfOptions {
  */
 declare function describePdf(auth: ClaudeAuth, path: string, opts?: PdfOptions): Promise<string>;
 
-export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DirectRegisterResult, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type ExtractedObject, type FilesRow, type Filter, type FilterOp, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemoryStateStore, type InitOptions, type InviteResponse, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, type ManyToManySource, type MarkdownTableColumn, type MemberSummary, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RedeemResponse, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type RegisterResponse, type Relation, type RenderHooks, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceMetadata, type SourceQueryOptions, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TeamConnection, type TeamSummary, TeamsClient, TeamsHttpError, type TemplateRenderSpec, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, autoFtsColumns, autoUpdate, classifyLinks, configDir, contentHash, crawlUrl, createReadOnlyHeader, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, encrypt, enrichKnowledge, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, extractObjects, findLatticeRoot, fixSchemaConflicts, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateWriteEntryId, getActiveWorkspace, getDbCredential, getOrCreateMasterKey, getWorkspace, hasFtsIndex, hashFile, importLegacyUserConfig, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, manifestPath, markdownTable, migrateLatticeData, normalizeEntityFiles, openTargetLatticeForMigration, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, registerDirectViaPostgres, registerNativeEntities, registryPath, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, rootConfigDir, saveDbCredential, saveDbCredentialForTeam, setActiveWorkspace, slugify, summarizeText, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };
+export { type AddWorkspaceOptions, type AdoptNativeOptions, type AdoptResult, type ApplyWriteResult, type AudienceRowCtx, type AuditEvent, type AutoUpdateResult, type BelongsToRelation, type BelongsToSource, type BlobMetadata, type BuiltinTemplateName, CLOUD_SETTING_SYSTEM_PROMPT, CONFIG_SUBDIR, type CatalogEntity, type CatalogRecord, type ChangeEntry, type ChangelogOptions, type ClassifyMatch, type CleanupOptions, type CleanupResult, type CloudProbeResult, type CountOptions, type CrawlOptions, type CrawlResult, type CustomSource, DEFAULT_ENTRY_TYPES, DEFAULT_TYPE_ALIASES, type DiscoveredTable, type EmbeddingsConfig, type EnrichOptions, type EnrichResult, type EnrichedSource, type EnrichmentLookup, type EntityContextDefinition, type EntityContextManifestEntry, type EntityFileManifestInfo, type EntityFileSource, type EntityFileSpec, type EntityProfileField, type EntityProfileSection, type EntityProfileTemplate, type EntityRenderSpec, type EntityRenderTemplate, type EntitySectionPerRow, type EntitySectionsTemplate, type EntityTableColumn, type EntityTableTemplate, type ExtractedObject, type FilesRow, type Filter, type FilterOp, FoldCache, type FtsConfig, type FtsGroup, type FtsHit, type FtsOptions, type FtsResult, type HasManyRelation, type HasManySource, InMemorySourceKeyStore, InMemoryStateStore, type InitOptions, LOCAL_DB_RELPATH, Lattice, type LatticeConfig, type LatticeConfigInput, type LatticeEntityDef, type LatticeEntityRenderSpec, type LatticeFieldDef, type LatticeFieldType, type LatticeManifest, type LatticeOptions, type LinkOptions, type LlmClient, type LlmMessage, MEMBER_GROUP, type ManyToManySource, type MarkdownTableColumn, type MigrateResult, type Migration, type MigrationOptions, type MigrationProgress, type MigrationResult, type MultiTableDefinition, NATIVE_ENTITY_DEFS, NATIVE_ENTITY_NAMES, NATIVE_REGISTRY_TABLE, type Observation, type OrderBySpec, type OrganizeOptions, type OrganizeResult, type OrganizedCreation, type OrganizedLink, type ParseError, type ParseResult, type ParsedConfig, type PdfOptions, type PdfSenderInput, type PkLookup, PostgresAdapter, type PostgresAdapterOptions, type PreparedStatement, type PrimaryKey, ProgressThrottle, type QueryOptions, READ_ONLY_HEADER, ROOT_DIRNAME, type ReadOnlyHeaderOptions, type ReconcileOptions, type ReconcileResult, type RefKind, type RefProvider, type ReferenceMetadata, ReferenceUnavailableError, type Relation, type RemoteBlobStore, type RenderHooks, type RenderOptions, type RenderProgress, type RenderProgressCallback, type RenderProgressKind, type RenderResult, type RenderSpec, type ReportConfig, type ReportResult, type ReportSection, type ReportSectionResult, type ResolveOptions, type ReverseSeedDetection, type ReverseSeedResult, type ReverseSeedTableResult, type ReverseSyncError, type ReverseSyncResult, type ReverseSyncUpdate, type RewardScores, type Row, type RowVisibilityDefault, type S3Config, type S3StoreConfig, S3UnavailableError, SQLiteAdapter, type SchemaEntity, type SearchOptions, type SearchResult, type SecurityOptions, type SeedConfig, type SeedLinkSpec, SeedReconciliationError, type SeedResult, type SelfSource, type SessionEntry, type SessionParseOptions, type SessionWriteEntry, type SessionWriteOp, type SessionWriteParseResult, type SourceHandle, type SourceKeyStore, type SourceMetadata, type SourceQueryOptions, SourceShreddedError, type StopFn, type StorageAdapter, type SyncResult, type TableDefinition, type TablePolicy, type TemplateRenderSpec, type TurnParams, type TurnResult, type UnresolvedLink, type UpsertByNaturalKeyOptions, type UserIdentity, type UserPreferences, type Viewer, type VisionOptions, type VisionSenderInput, WORKSPACES_SUBDIR, type WatchOptions, type WorkspacePaths, type WorkspaceRecord, type WorkspaceRegistry, type WriteHook, type WriteHookContext, type WritebackDefinition, type WritebackStateStore, type WritebackValidationResult, activeWorkspaceLabel, addWorkspace, adoptNativeEntities, analyticsEnabled, applyTokenBudget, applyWriteEntry, archiveLocalSqlite, assertSafeUrl, attachBlob, audiencePredicate, audienceViewSql, autoFtsColumns, autoUpdate, backfillOwnership, canManageRoles, classifyLinks, cloudRlsInstalled, configDir, contentHash, crawlUrl, createReadOnlyHeader, createS3Store, createSQLiteStateStore, decrypt, defaultWorkspaceYaml, deleteDbCredential, deleteToken, deriveCanonicalContexts, deriveKey, describeImage, describePdf, discoverCloudTables, enableAudienceView, enableChangelogRls, enableRlsForTable, encrypt, enrichKnowledge, ensureFtsIndex, ensureLatticeRoot, entityFileNames, estimateTokens, extractObjects, findLatticeRoot, fixSchemaConflicts, foldEntity, frontmatter, ftsTableName, fullTextSearch, generateEntryId, generateMemberPassword, generateWriteEntryId, getActiveWorkspace, getCloudSetting, getDbCredential, getOrCreateMasterKey, getTablePolicy, getWorkspace, grantCell, hasFtsIndex, hashFile, importLegacyUserConfig, installCloudRls, installCloudSettings, isEncrypted, isNativeEntity, isPostgresUrl, isPrivateIp, isRowAudience, isV1EntityFiles, listDbCredentials, listNativeBindings, listTokens, listWorkspaces, loadColumnPolicy, manifestPath, markdownTable, memberRoleName, migrateLatticeData, normalizeEntityFiles, observationVisible, observationsFromChange, openTargetLatticeForMigration, openUnderSource, organizeSource, parseConfigFile, parseConfigString, parseMarkdownEntries, parseMatches, parseObjects, parseSessionMD, parseSessionWrites, probeCloud, providerForUrl, provisionMemberRole, readIdentity, readManifest, readPreferences, readRegistry, readToken, referenceLocalFile, referenceUrl, regenerateAudienceViewFromDb, registerNativeEntities, registryPath, resolveActiveS3Config, resolveLatticeRoot, resolveSource, resolveWorkspacePaths, revokeCell, revokeMemberRole, rootConfigDir, s3Key, saveDbCredential, saveDbCredentialForTeam, sealUnderSource, secureCloud, seedColumnPolicyFromYaml, setActiveWorkspace, setCloudSetting, setColumnAudience, setRowVisibility, setTableDefaultVisibility, setTableNeverShare, shredSource, slugify, summarizeText, tableNeedsAudienceView, toSafeDirName, truncate, validateEntryId, workspaceBlobsDir, workspaceConfigPath, workspaceContextDir, workspaceDataDir, workspaceDbPath, workspaceDir, workspacesDir, writeIdentity, writeManifest, writePreferences, writeRegistry, writeToken };