latticesql 3.4.3 → 3.4.5

package/dist/index.d.cts

@@ -24,10 +24,50 @@ interface EntityContextManifestEntry {
      */
     entities: Record<string, Record<string, EntityFileManifestInfo> | string[]>;
 }
+/**
+ * Monotonic cursor the rendered tree was produced FROM, recorded in the manifest
+ * so a later open can decide whether anything the tree depends on has advanced.
+ *
+ * Each field is a string-comparable high-water mark (or `null` when the substrate
+ * is absent / unreadable in the current scope). Computed THROUGH the same DB
+ * connection + read scope the render used, so for a cloud MEMBER each mark
+ * reflects only what that member can see — making the cursor a per-viewer
+ * freshness key, not a global one.
+ *
+ * - `changelog` — the write log's high-water mark. Captures plain data edits AND
+ *   the per-viewer DERIVED observations a member's tree folds in (both are
+ *   changelog rows), so a new observation advances it even though no entity row's
+ *   count moved.
+ * - `grants` / `owners` — the row-sharing graph's high-water mark. A share or
+ *   un-share changes a member's visible row set without touching any entity row,
+ *   so these capture that class of change. For a member they are derived from the
+ *   member-visible change feed (the only share signal a member may read); for an
+ *   owner / local DB they come from the ownership + grant bookkeeping directly.
+ */
+interface RenderCursor {
+    changelog: string | null;
+    grants: string | null;
+    owners: string | null;
+}
 interface LatticeManifest {
     version: 1 | 2;
     generated_at: string;
     entityContexts: Record<string, EntityContextManifestEntry>;
+    /**
+     * Render-output format version the tree was produced with (see
+     * {@link TEMPLATE_VERSION}). Optional: a manifest written before this field
+     * existed reads as `undefined`, which the staleness gate treats as a mismatch
+     * → full render (fail-open). Set on every render that writes a manifest.
+     */
+    templateVersion?: number;
+    /**
+     * The cursor the tree was rendered from (see {@link RenderCursor}). Optional for
+     * the same backward-compat reason; absence → the gate fails open and renders.
+     * On an INCREMENTAL render this is recomputed from the live DB (a single
+     * top-level cursor reflecting the latest computation), NOT merged per-table — so
+     * it always advances to the newest state the partial render observed.
+     */
+    cursor?: RenderCursor;
 }
 /** Type guard: is the entity files entry in v1 format (string[])? */
 declare function isV1EntityFiles(val: unknown): val is string[];
@@ -1826,6 +1866,18 @@ interface RenderOptions {
      * Omitted → a full render of everything (initial open, explicit `render()`).
      */
     changedTables?: ReadonlySet<string>;
+    /**
+     * Open/restart staleness gate. When set, the render first compares the manifest's
+     * recorded template version + cursor to the live state (through the render's own
+     * scope); if nothing the tree depends on has advanced, it SKIPS the render
+     * entirely — reads no tables, emits no per-table progress, and fires a single
+     * terminal `done` so the GUI shows complete. Used ONLY by the GUI's open-time
+     * background render so a plain restart / version bump doesn't re-render an
+     * unchanged tree. The realtime eager-render and the mutation auto-render never
+     * set it (they must always re-render the table that actually changed). Fails
+     * OPEN: any uncertainty (missing/foreign manifest, unreadable cursor) renders.
+     */
+    gateOnOpen?: boolean;
 }
 /**
  * Coalesces high-frequency `table-progress` events down to ≤ ~5/sec per table,
@@ -1937,6 +1989,14 @@ declare class Lattice {
     private readonly _changelogTables;
     /** Current task context string for relevance filtering. */
     private _taskContext;
+    /**
+     * True when this connection opened against an already-provisioned cloud as a
+     * SCOPED MEMBER (no role-management privilege → no CREATE/ALTER on the schema).
+     * Set during init() by the same probe that decides introspect-only. Drives
+     * {@link addColumn} to route DDL through the owner-side `lattice_member_add_column`
+     * SECURITY DEFINER helper instead of issuing a raw ALTER the member can't run.
+     */
+    private _cloudMemberOpen;
     private readonly _auditHandlers;
     private readonly _renderHandlers;
     private readonly _writebackHandlers;
@@ -2048,6 +2108,22 @@ declare class Lattice {
      * Teams schema spec → DDL translation).
      */
     getDialect(): 'sqlite' | 'postgres';
+    /**
+     * True when a table opts into the observation/changelog substrate
+     * (`def.changelog`). Callers that want to bypass the high-level {@link delete}
+     * with a transaction-scoped raw delete use this to know whether the table also
+     * needs the changelog / write-hook / embedding side effects that only
+     * `delete()` performs — so they can keep the high-level path for such tables.
+     */
+    isChangelogTracked(table: string): boolean;
+    /**
+     * True when this connection opened as a scoped cloud MEMBER (see
+     * {@link _cloudMemberOpen}). Callers use it to route DDL-bearing work through
+     * the owner-side SECURITY DEFINER helpers rather than issuing DDL the member's
+     * role can't run (e.g. {@link addColumn} regenerates the masking view inside
+     * `lattice_member_add_column`, so the caller must not also try to regenerate it).
+     */
+    isCloudMemberOpen(): boolean;
     /**
      * Return the normalised primary-key column list for a registered
      * table. Falls back to `['id']` for tables registered via raw DDL
@@ -4847,6 +4923,37 @@ interface PdfOptions {
  */
 declare function describePdf(auth: ClaudeAuth, path: string, opts?: PdfOptions): Promise<string>;
 
+/** How the running copy of the package was installed. */
+type InstallKind = 'global' | 'local' | 'npx' | 'linked-dev' | 'unknown';
+interface InstallContext {
+    kind: InstallKind;
+    /** True only when an `npm install` may safely upgrade this copy in place. */
+    installable: boolean;
+    /** Directory to run the install from (the consumer project root for `local`). */
+    cwd: string;
+    /** Resolved package root of the running copy, if found. */
+    packageRoot: string | null;
+    /** Human-readable explanation (logged / surfaced in `/api/update/status`). */
+    reason: string;
+}
+
+interface UpdateStatus {
+    current: string;
+    latest: string | null;
+    kind: InstallContext['kind'];
+    installable: boolean;
+    checking: boolean;
+    installing: boolean;
+    lastError: string | null;
+}
+interface UpdateService {
+    start(): void;
+    stop(): void;
+    status(): UpdateStatus;
+    /** Run a check now (and install if applicable). Returns the resulting status. */
+    checkNow(force?: boolean): Promise<UpdateStatus>;
+}
+
 interface StartGuiServerOptions {
     /**
      * Active workspace config to open. NULL/empty ⇒ boot into the zero-workspace
@@ -4903,6 +5010,13 @@ interface StartGuiServerOptions {
      * `GET /api/version` + `GET /api/update/status` are served regardless.
      */
     selfUpdate?: boolean;
+    /**
+     * Test seam: supply the update service instead of building one from the real
+     * npm-backed install context. Lets tests exercise the update routes against a
+     * deterministic fake (no real registry check, no real npm install). When set,
+     * it overrides `selfUpdate`'s default factory.
+     */
+    updateServiceFactory?: (emit: (type: string, data: unknown) => void) => UpdateService;
 }
 interface GuiServerHandle {
     server: Server;

package/dist/index.d.ts

@@ -24,10 +24,50 @@ interface EntityContextManifestEntry {
      */
     entities: Record<string, Record<string, EntityFileManifestInfo> | string[]>;
 }
+/**
+ * Monotonic cursor the rendered tree was produced FROM, recorded in the manifest
+ * so a later open can decide whether anything the tree depends on has advanced.
+ *
+ * Each field is a string-comparable high-water mark (or `null` when the substrate
+ * is absent / unreadable in the current scope). Computed THROUGH the same DB
+ * connection + read scope the render used, so for a cloud MEMBER each mark
+ * reflects only what that member can see — making the cursor a per-viewer
+ * freshness key, not a global one.
+ *
+ * - `changelog` — the write log's high-water mark. Captures plain data edits AND
+ *   the per-viewer DERIVED observations a member's tree folds in (both are
+ *   changelog rows), so a new observation advances it even though no entity row's
+ *   count moved.
+ * - `grants` / `owners` — the row-sharing graph's high-water mark. A share or
+ *   un-share changes a member's visible row set without touching any entity row,
+ *   so these capture that class of change. For a member they are derived from the
+ *   member-visible change feed (the only share signal a member may read); for an
+ *   owner / local DB they come from the ownership + grant bookkeeping directly.
+ */
+interface RenderCursor {
+    changelog: string | null;
+    grants: string | null;
+    owners: string | null;
+}
 interface LatticeManifest {
     version: 1 | 2;
     generated_at: string;
     entityContexts: Record<string, EntityContextManifestEntry>;
+    /**
+     * Render-output format version the tree was produced with (see
+     * {@link TEMPLATE_VERSION}). Optional: a manifest written before this field
+     * existed reads as `undefined`, which the staleness gate treats as a mismatch
+     * → full render (fail-open). Set on every render that writes a manifest.
+     */
+    templateVersion?: number;
+    /**
+     * The cursor the tree was rendered from (see {@link RenderCursor}). Optional for
+     * the same backward-compat reason; absence → the gate fails open and renders.
+     * On an INCREMENTAL render this is recomputed from the live DB (a single
+     * top-level cursor reflecting the latest computation), NOT merged per-table — so
+     * it always advances to the newest state the partial render observed.
+     */
+    cursor?: RenderCursor;
 }
 /** Type guard: is the entity files entry in v1 format (string[])? */
 declare function isV1EntityFiles(val: unknown): val is string[];
@@ -1826,6 +1866,18 @@ interface RenderOptions {
      * Omitted → a full render of everything (initial open, explicit `render()`).
      */
     changedTables?: ReadonlySet<string>;
+    /**
+     * Open/restart staleness gate. When set, the render first compares the manifest's
+     * recorded template version + cursor to the live state (through the render's own
+     * scope); if nothing the tree depends on has advanced, it SKIPS the render
+     * entirely — reads no tables, emits no per-table progress, and fires a single
+     * terminal `done` so the GUI shows complete. Used ONLY by the GUI's open-time
+     * background render so a plain restart / version bump doesn't re-render an
+     * unchanged tree. The realtime eager-render and the mutation auto-render never
+     * set it (they must always re-render the table that actually changed). Fails
+     * OPEN: any uncertainty (missing/foreign manifest, unreadable cursor) renders.
+     */
+    gateOnOpen?: boolean;
 }
 /**
  * Coalesces high-frequency `table-progress` events down to ≤ ~5/sec per table,
@@ -1937,6 +1989,14 @@ declare class Lattice {
     private readonly _changelogTables;
     /** Current task context string for relevance filtering. */
     private _taskContext;
+    /**
+     * True when this connection opened against an already-provisioned cloud as a
+     * SCOPED MEMBER (no role-management privilege → no CREATE/ALTER on the schema).
+     * Set during init() by the same probe that decides introspect-only. Drives
+     * {@link addColumn} to route DDL through the owner-side `lattice_member_add_column`
+     * SECURITY DEFINER helper instead of issuing a raw ALTER the member can't run.
+     */
+    private _cloudMemberOpen;
     private readonly _auditHandlers;
     private readonly _renderHandlers;
     private readonly _writebackHandlers;
@@ -2048,6 +2108,22 @@ declare class Lattice {
      * Teams schema spec → DDL translation).
      */
     getDialect(): 'sqlite' | 'postgres';
+    /**
+     * True when a table opts into the observation/changelog substrate
+     * (`def.changelog`). Callers that want to bypass the high-level {@link delete}
+     * with a transaction-scoped raw delete use this to know whether the table also
+     * needs the changelog / write-hook / embedding side effects that only
+     * `delete()` performs — so they can keep the high-level path for such tables.
+     */
+    isChangelogTracked(table: string): boolean;
+    /**
+     * True when this connection opened as a scoped cloud MEMBER (see
+     * {@link _cloudMemberOpen}). Callers use it to route DDL-bearing work through
+     * the owner-side SECURITY DEFINER helpers rather than issuing DDL the member's
+     * role can't run (e.g. {@link addColumn} regenerates the masking view inside
+     * `lattice_member_add_column`, so the caller must not also try to regenerate it).
+     */
+    isCloudMemberOpen(): boolean;
     /**
      * Return the normalised primary-key column list for a registered
      * table. Falls back to `['id']` for tables registered via raw DDL
@@ -4847,6 +4923,37 @@ interface PdfOptions {
  */
 declare function describePdf(auth: ClaudeAuth, path: string, opts?: PdfOptions): Promise<string>;
 
+/** How the running copy of the package was installed. */
+type InstallKind = 'global' | 'local' | 'npx' | 'linked-dev' | 'unknown';
+interface InstallContext {
+    kind: InstallKind;
+    /** True only when an `npm install` may safely upgrade this copy in place. */
+    installable: boolean;
+    /** Directory to run the install from (the consumer project root for `local`). */
+    cwd: string;
+    /** Resolved package root of the running copy, if found. */
+    packageRoot: string | null;
+    /** Human-readable explanation (logged / surfaced in `/api/update/status`). */
+    reason: string;
+}
+
+interface UpdateStatus {
+    current: string;
+    latest: string | null;
+    kind: InstallContext['kind'];
+    installable: boolean;
+    checking: boolean;
+    installing: boolean;
+    lastError: string | null;
+}
+interface UpdateService {
+    start(): void;
+    stop(): void;
+    status(): UpdateStatus;
+    /** Run a check now (and install if applicable). Returns the resulting status. */
+    checkNow(force?: boolean): Promise<UpdateStatus>;
+}
+
 interface StartGuiServerOptions {
     /**
      * Active workspace config to open. NULL/empty ⇒ boot into the zero-workspace
@@ -4903,6 +5010,13 @@ interface StartGuiServerOptions {
      * `GET /api/version` + `GET /api/update/status` are served regardless.
      */
     selfUpdate?: boolean;
+    /**
+     * Test seam: supply the update service instead of building one from the real
+     * npm-backed install context. Lets tests exercise the update routes against a
+     * deterministic fake (no real registry check, no real npm install). When set,
+     * it overrides `selfUpdate`'s default factory.
+     */
+    updateServiceFactory?: (emit: (type: string, data: unknown) => void) => UpdateService;
 }
 interface GuiServerHandle {
     server: Server;