@fadhilp/stateql 0.10.0 → 0.10.1

package/README.md

@@ -555,6 +555,15 @@ session-scoped, allocated atomically with the result, stable on cache reuse, and
 cannot be reassigned by `setAlias`; explicit aliases and all old handles continue
 to resolve.
 
+Connections likewise retain canonical `conn_*` IDs and receive persistent random
+10-character lowercase base32 aliases, exposed as `alias` and `display_alias` by
+`connect()` and `snapshot().connection` (optional in snapshot types for older
+producers). Connection aliases are unique within the state store, allocated
+atomically with the connection, and backfilled for existing records on startup.
+They survive reopening; reconnecting creates a new ID and alias. They are display
+identities only, separate from result aliases; internal references and lookups
+continue to use canonical connection IDs.
+
 ### Safe profile updates
 
 ```ts

package/dist/src/migrations.js

@@ -115,6 +115,17 @@ const MIGRATIONS = [
             requireIndexes(db, ["history_session_category"]);
         },
     },
+    {
+        name: "connection_aliases_v1",
+        apply(db) {
+            addColumn(db, "connections", "alias", "TEXT");
+            db.exec("CREATE UNIQUE INDEX IF NOT EXISTS connections_alias ON connections(alias)");
+        },
+        validate(db) {
+            requireColumns(db, "connections", ["alias"]);
+            requireIndexes(db, ["connections_alias"]);
+        },
+    },
 ];
 export function runMigrations(db, now) {
     db.exec(`

package/dist/src/stateql.js

@@ -223,6 +223,8 @@ export class StateQL {
             return {
                 data: {
                     connection_id: connection.id,
+                    alias: connection.alias,
+                    display_alias: connection.alias,
                     driver,
                     database: databaseName,
                     name: connection.name,
@@ -368,6 +370,8 @@ export class StateQL {
             connection: connection
                 ? {
                     connection_id: connection.id,
+                    alias: connection.alias,
+                    display_alias: connection.alias,
                     name: connection.name,
                     status: "connected",
                     driver: connection.driver,

package/dist/src/store.d.ts

@@ -11,6 +11,7 @@ export interface SessionRecord {
 }
 export interface ConnectionRecord {
     id: string;
+    alias?: string;
     session_id: string;
     name: string;
     driver: Driver;
@@ -166,6 +167,8 @@ export declare class StateStore {
         credentialRef?: string;
         readOnly: boolean;
     }): ConnectionRecord | undefined;
+    private allocateConnectionAlias;
+    private backfillConnectionAliases;
     getConnection(id: string): ConnectionRecord | undefined;
     activeConnection(session: SessionRecord): ConnectionRecord | undefined;
     disconnect(sessionId: string, actorId: string): boolean;

package/dist/src/store.js

@@ -36,6 +36,7 @@ export class StateStore {
             this.db.exec("PRAGMA busy_timeout = 5000");
             this.db.exec("PRAGMA foreign_keys = ON");
             runMigrations(this.db, this.now);
+            this.backfillConnectionAliases();
             this.backfillGeneratedAliases();
             this.recoverStaleCommittingTransactions();
             this.deleteExpiredData();
@@ -285,6 +286,7 @@ export class StateStore {
              credential_ref, read_only, version, created_at)
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?)`)
                 .run(id, input.sessionId, input.name, input.driver, input.databaseName, input.source, input.secretEnv ?? null, input.credentialRef ?? null, input.readOnly ? 1 : 0, timestamp);
+            this.allocateConnectionAlias(id);
             this.db
                 .prepare(`UPDATE sessions
            SET active_connection_id = ?, updated_at = ?
@@ -298,6 +300,28 @@ export class StateStore {
             throw error;
         }
     }
+    allocateConnectionAlias(connectionId) {
+        for (let attempt = 0; attempt < 64; attempt++) {
+            this.db.prepare("UPDATE OR IGNORE connections SET alias = ? WHERE id = ? AND alias IS NULL").run(randomBase32Alias(), connectionId);
+            const connection = this.getConnection(connectionId);
+            if (connection?.alias)
+                return connection.alias;
+        }
+        throw new Error("Could not allocate a unique connection alias.");
+    }
+    backfillConnectionAliases() {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const connections = this.db.prepare("SELECT id FROM connections WHERE alias IS NULL").all();
+            for (const connection of connections)
+                this.allocateConnectionAlias(connection.id);
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
     getConnection(id) {
         return this.db
             .prepare("SELECT * FROM connections WHERE id = ?")

package/dist/src/types.d.ts

@@ -106,6 +106,9 @@ export interface StateQLSnapshot {
     actor_id: string;
     connection: {
         connection_id: string;
+        /** Generated display identity; optional for older snapshot producers. */
+        alias?: string;
+        display_alias?: string;
         name: string;
         status: "connected";
         driver: Driver;
@@ -379,6 +382,9 @@ export type Row = Record<string, unknown>;
 /** Data returned by the stable, non-dynamic StateQL public methods. */
 export interface ConnectionData {
     connection_id: string;
+    /** Persistent generated display identity; connection_id remains canonical. */
+    alias: string;
+    display_alias: string;
     driver: Driver;
     database: string;
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fadhilp/stateql",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Stateful, agent-oriented database CLI for safe result reuse",
   "repository": {
     "type": "git",