bunsane 0.5.0 → 0.5.2

package/database/DatabaseHelper.ts

@@ -77,6 +77,41 @@ export const PrepareDatabase = async () => {
     // `entity_components` is no longer created or written. `components`
     // (UNIQUE(entity_id, type_id)) is the single source of membership truth
     // as of Phase 3 of docs/ENTITY_COMPONENTS_REMOVAL_PLAN.md.
+    try {
+        await MigrateTimestampsToTimestamptz();
+    } catch (error) {
+        logger.error(`Failed to migrate timestamp columns to timestamptz: ${error}`);
+        throw error;
+    }
+}
+
+/**
+ * Auto-migrate base-table timestamp columns from `timestamp without time zone`
+ * to `timestamptz`. Idempotent: only ALTERs columns still typed as bare
+ * timestamp, so fresh DBs (created with TIMESTAMPTZ DDL) and already-migrated
+ * DBs are no-ops. Existing bare-timestamp values are interpreted as UTC — the
+ * framework only ever writes them via NOW()/CURRENT_TIMESTAMP, which assume the
+ * DB session timezone; UTC is the correct assumption for any DB run in UTC.
+ * `components` is partitioned — PostgreSQL propagates the type change to every
+ * partition (a rewrite that briefly locks the table; one-time cost).
+ */
+export const MigrateTimestampsToTimestamptz = async () => {
+    const targets: Array<{ table: string; columns: string[] }> = [
+        { table: "entities", columns: ["created_at", "updated_at", "deleted_at"] },
+        { table: "components", columns: ["created_at", "updated_at", "deleted_at"] },
+    ];
+    for (const { table, columns } of targets) {
+        for (const col of columns) {
+            const rows = await db.unsafe(`
+                SELECT data_type FROM information_schema.columns
+                WHERE table_schema = 'public' AND table_name = '${table}' AND column_name = '${col}'
+            `);
+            if (rows.length === 0) continue; // table or column absent
+            if ((rows[0] as any).data_type !== "timestamp without time zone") continue; // already timestamptz
+            logger.warn(`Migrating ${table}.${col} timestamp → timestamptz (assuming stored values are UTC)...`);
+            await db.unsafe(`ALTER TABLE ${table} ALTER COLUMN ${col} TYPE timestamptz USING ${col} AT TIME ZONE 'UTC'`);
+        }
+    }
 }
 
 export const GetDatabaseDataSize = async () => {
@@ -101,9 +136,9 @@ export const SetupDatabaseExtensions = async () => {
 export const CreateEntityTable = async () => {
     await db`CREATE TABLE IF NOT EXISTS entities (
         id UUID PRIMARY KEY,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ
     );`;
 
     // Add partial index for soft-delete queries - critical for 1M+ scale
@@ -148,15 +183,15 @@ export const CreateComponentTable = async () => {
             type_id varchar(64) NOT NULL,
             name varchar(128),
             data jsonb,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW(),
-            deleted_at TIMESTAMP,
+            created_at TIMESTAMPTZ DEFAULT NOW(),
+            updated_at TIMESTAMPTZ DEFAULT NOW(),
+            deleted_at TIMESTAMPTZ,
             PRIMARY KEY (id, type_id),
             UNIQUE(entity_id, type_id)
         ) PARTITION BY LIST (type_id);`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id)`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id)`;
-        await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+        await ensureDataGinIndex();
         await db`CREATE INDEX IF NOT EXISTS idx_components_entity_type_deleted ON components (entity_id, type_id, deleted_at)`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_type_deleted ON components (type_id, deleted_at) WHERE deleted_at IS NULL`;
         await db`CREATE INDEX IF NOT EXISTS idx_components_deleted_entity ON components (deleted_at, entity_id) WHERE deleted_at IS NULL`;
@@ -226,6 +261,30 @@ const dropOrphanedPartitionTables = async () => {
     }
 }
 
+/**
+ * The whole-`data` GIN index (`idx_components_data_gin`) only serves top-level
+ * JSONB containment / existence on the entire `data` column (`data @> ...`,
+ * `data ? key`, `data ?| / ?&`). The Query layer never emits those forms — it
+ * uses per-field text extraction (`data->>'field'`, served by per-field
+ * btree/expression indexes) and sub-path containment (`data->'field' @> ...`,
+ * served by per-field sub-path GIN). So this index is pure write amplification
+ * for framework queries AND it blocks HOT updates (any `data` write must touch
+ * it). It is therefore OPT-IN. Set BUNSANE_COMPONENTS_DATA_GIN=true only if you
+ * run raw SQL doing top-level containment on the whole component payload.
+ */
+const ensureDataGinIndex = async (): Promise<void> => {
+    if (process.env.BUNSANE_COMPONENTS_DATA_GIN === 'true') {
+        await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+        logger.info("Created whole-data GIN index idx_components_data_gin (BUNSANE_COMPONENTS_DATA_GIN=true).");
+    } else {
+        logger.info(
+            "Skipped whole-data GIN index idx_components_data_gin to cut write amplification and enable HOT updates " +
+            "(BUNSANE_COMPONENTS_DATA_GIN!=true). Per-field indexes serve all framework queries. A pre-existing DB " +
+            "that still has it can drop it manually: DROP INDEX CONCURRENTLY IF EXISTS idx_components_data_gin;"
+        );
+    }
+};
+
 export const CreateHashPartitionedComponentTable = async (partitionCount: number = 16) => {
     await db`CREATE TABLE IF NOT EXISTS components (
         id UUID,
@@ -233,9 +292,9 @@ export const CreateHashPartitionedComponentTable = async (partitionCount: number
         type_id varchar(64) NOT NULL,
         name varchar(128),
         data jsonb,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ,
         PRIMARY KEY (id, type_id),
         UNIQUE(entity_id, type_id)
     ) PARTITION BY HASH (type_id);`;
@@ -249,7 +308,7 @@ export const CreateHashPartitionedComponentTable = async (partitionCount: number
 
     await db`CREATE INDEX IF NOT EXISTS idx_components_entity_id ON components (entity_id)`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_type_id ON components (type_id)`;
-    await db`CREATE INDEX IF NOT EXISTS idx_components_data_gin ON components USING GIN (data)`;
+    await ensureDataGinIndex();
     await db`CREATE INDEX IF NOT EXISTS idx_components_entity_type_deleted ON components (entity_id, type_id, deleted_at)`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_type_deleted ON components (type_id, deleted_at) WHERE deleted_at IS NULL`;
     await db`CREATE INDEX IF NOT EXISTS idx_components_deleted_entity ON components (deleted_at, entity_id) WHERE deleted_at IS NULL`;
@@ -459,9 +518,9 @@ export const CreateEntityComponentTable = async () => {
         entity_id UUID REFERENCES entities(id) ON DELETE CASCADE,
         type_id VARCHAR(64) NOT NULL,
         component_id UUID,
-        created_at TIMESTAMP DEFAULT NOW(),
-        updated_at TIMESTAMP DEFAULT NOW(),
-        deleted_at TIMESTAMP,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW(),
+        deleted_at TIMESTAMPTZ,
         UNIQUE(entity_id, type_id)
     );`;
     const concurrently = process.env.USE_PGLITE ? '' : ' CONCURRENTLY';
@@ -622,9 +681,9 @@ export const BenchmarkPartitionCounts = async (partitionCounts: number[] = [8, 1
             type_id varchar(64) NOT NULL,
             name varchar(128),
             data jsonb,
-            created_at TIMESTAMP DEFAULT NOW(),
-            updated_at TIMESTAMP DEFAULT NOW(),
-            deleted_at TIMESTAMP,
+            created_at TIMESTAMPTZ DEFAULT NOW(),
+            updated_at TIMESTAMPTZ DEFAULT NOW(),
+            deleted_at TIMESTAMPTZ,
             PRIMARY KEY (id, type_id),
             UNIQUE(entity_id, type_id)
         ) PARTITION BY HASH (type_id);`);

package/endpoints/entity.ts

@@ -1,8 +1,93 @@
 import db from "../database";
-import type { EntityInspectorResponse } from "./types";
+import type {
+    EntityInspectorResponse,
+    StudioEntityListQueryParams,
+    StudioEntityListResponse,
+    EntityListItem,
+} from "./types";
 
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
+export async function handleEntityListRequest(
+    params: StudioEntityListQueryParams = {}
+): Promise<Response> {
+    const limit = Math.min(Math.max(params.limit ?? 50, 1), 1000);
+    const offset = Math.max(params.offset ?? 0, 0);
+    const searchTerm = params.search?.trim() ?? "";
+    const includeDeleted = params.include_deleted ?? false;
+
+    const deletedFilter = includeDeleted ? "" : "AND e.deleted_at IS NULL";
+
+    try {
+        let rows: Record<string, unknown>[];
+        let totalResult: { count: number }[];
+
+        if (searchTerm) {
+            const searchPattern = `%${searchTerm}%`;
+            rows = await db.unsafe(
+                `SELECT e.id, e.created_at, e.updated_at, e.deleted_at,
+                        (SELECT COUNT(*) FROM components c
+                         WHERE c.entity_id = e.id AND c.deleted_at IS NULL) AS component_count
+                 FROM entities e
+                 WHERE e.id::text ILIKE $1 ${deletedFilter}
+                 ORDER BY e.created_at DESC NULLS LAST
+                 LIMIT $2 OFFSET $3`,
+                [searchPattern, limit, offset]
+            );
+            totalResult = await db.unsafe(
+                `SELECT COUNT(*) AS count FROM entities e
+                 WHERE e.id::text ILIKE $1 ${deletedFilter}`,
+                [searchPattern]
+            );
+        } else {
+            rows = await db.unsafe(
+                `SELECT e.id, e.created_at, e.updated_at, e.deleted_at,
+                        (SELECT COUNT(*) FROM components c
+                         WHERE c.entity_id = e.id AND c.deleted_at IS NULL) AS component_count
+                 FROM entities e
+                 WHERE TRUE ${deletedFilter}
+                 ORDER BY e.created_at DESC NULLS LAST
+                 LIMIT $1 OFFSET $2`,
+                [limit, offset]
+            );
+            totalResult = await db.unsafe(
+                `SELECT COUNT(*) AS count FROM entities e WHERE TRUE ${deletedFilter}`
+            );
+        }
+
+        const entities: EntityListItem[] = rows.map((row) => ({
+            id: row.id as string,
+            created_at: row.created_at as string,
+            updated_at: row.updated_at as string,
+            deleted_at: (row.deleted_at as string) ?? null,
+            component_count: Number(row.component_count ?? 0),
+        }));
+
+        const responseData: StudioEntityListResponse = {
+            entities,
+            total: Number(totalResult[0]?.count ?? 0),
+            limit,
+            offset,
+        };
+
+        return new Response(JSON.stringify(responseData), {
+            headers: { "Content-Type": "application/json" },
+        });
+    } catch (error) {
+        const errorMessage =
+            error instanceof Error ? error.message : "Unknown error";
+        return new Response(
+            JSON.stringify({
+                error: `Failed to fetch entities: ${errorMessage}`,
+            }),
+            {
+                status: 500,
+                headers: { "Content-Type": "application/json" },
+            }
+        );
+    }
+}
+
 export async function handleEntityInspectorRequest(
     entityId: string
 ): Promise<Response> {

package/endpoints/index.ts

@@ -7,7 +7,7 @@ import {
     handleStudioArcheTypeRecordsRequest,
     handleStudioArcheTypeDeleteRequest,
 } from "./archetypes";
-import { handleEntityInspectorRequest } from "./entity";
+import { handleEntityInspectorRequest, handleEntityListRequest } from "./entity";
 import { handleStudioStatsRequest } from "./stats";
 import { handleStudioComponentsRequest } from "./components";
 import { handleStudioQueryRequest } from "./query";
@@ -18,6 +18,7 @@ const studioEndpoint = {
     handleStudioTableDeleteRequest,
     handleStudioArcheTypeDeleteRequest,
     handleEntityInspectorRequest,
+    handleEntityListRequest,
     handleStudioStatsRequest,
     handleStudioComponentsRequest,
     handleStudioQueryRequest,

package/endpoints/types.ts

@@ -88,6 +88,28 @@ interface EntityInspectorResponse {
     components: EntityComponent[];
 }
 
+interface StudioEntityListQueryParams {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    include_deleted?: boolean;
+}
+
+interface EntityListItem {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+    component_count: number;
+}
+
+interface StudioEntityListResponse {
+    entities: EntityListItem[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
 interface ComponentTypeStats {
     name: string;
     count: number;
@@ -145,6 +167,9 @@ export type {
     DeleteResponse,
     EntityComponent,
     EntityInspectorResponse,
+    StudioEntityListQueryParams,
+    EntityListItem,
+    StudioEntityListResponse,
     ComponentTypeStats,
     ArcheTypeStats,
     StudioStatsResponse,

package/gql/index.ts

@@ -149,8 +149,19 @@ export interface YogaInstanceOptions {
     maxComplexity?: number;
 }
 
+/**
+ * A schema provider may be a concrete `GraphQLSchema` or a factory returning
+ * the current schema. A factory is read per-request by Yoga, which lets the
+ * schema be swapped at runtime (e.g. ServiceRegistry.rebuildSchema()) without
+ * recreating the Yoga instance. Returning `null`/`undefined` falls back to the
+ * static placeholder schema.
+ */
+export type SchemaProvider =
+    | GraphQLSchema
+    | (() => GraphQLSchema | null | undefined);
+
 export function createYogaInstance(
-    schema?: GraphQLSchema,
+    schema?: SchemaProvider,
     plugins: Plugin[] = [],
     contextFactory?: (context: any) => any,
     options?: YogaInstanceOptions
@@ -188,16 +199,30 @@ export function createYogaInstance(
         yogaConfig.context = contextFactory;
     }
 
-    if (schema) {
+    // Memoized static placeholder schema. Kept stable so Yoga's per-schema
+    // internal caches (parse/validate) are not thrashed when a factory falls
+    // back to it across requests.
+    let fallbackSchema: GraphQLSchema | undefined;
+    const getFallback = (): GraphQLSchema => {
+        if (!fallbackSchema) {
+            fallbackSchema = createSchema({
+                typeDefs: staticTypeDefs,
+                resolvers: staticResolvers,
+            });
+        }
+        return fallbackSchema;
+    };
+
+    if (typeof schema === "function") {
+        // Factory form: read per request so runtime swaps reflect live.
+        // Stable refs keep Yoga's caches warm; only a changed ref re-primes.
+        yogaConfig.schema = () => schema() ?? getFallback();
+    } else if (schema) {
         yogaConfig.schema = schema;
-        return createYoga(yogaConfig);
     } else {
-        yogaConfig.schema = createSchema({
-            typeDefs: staticTypeDefs,
-            resolvers: staticResolvers,
-        });
-        return createYoga(yogaConfig);
+        yogaConfig.schema = getFallback();
     }
+    return createYoga(yogaConfig);
 }
 
 export const Upload = z.union([z.literal("Upload"), z.any()]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.5.0",
+    "version": "0.5.2",
     "author": {
         "name": "yaaruu"
     },

package/service/ServiceRegistry.ts

@@ -14,6 +14,7 @@ export class ServiceRegistry {
 
     private services: Map<string, BaseService> = new Map();
     private schema: GraphQLSchema | null = null;
+    private schemaVersion: number = 0;
     private phaseListener: ((event: PhaseChangeEvent) => void) | null = null;
 
 
@@ -29,13 +30,7 @@ export class ServiceRegistry {
         this.phaseListener = (event: PhaseChangeEvent) => {
             switch(event.detail) {
                 case ApplicationPhase.SYSTEM_REGISTERING: {
-                    const servicesArray = Array.from(this.services.values());
-
-                    const result = generateGraphQLSchemaV2(servicesArray, {
-                        enableArchetypeOperations: false
-                    });
-
-                    this.schema = result.schema;
+                    this.rebuildSchema();
                     ApplicationLifecycle.setPhase(ApplicationPhase.SYSTEM_READY);
                     break;
                 };
@@ -74,6 +69,30 @@ export class ServiceRegistry {
     public getSchema(): GraphQLSchema | null {
         return this.schema;
     }
+
+    public getSchemaVersion(): number {
+        return this.schemaVersion;
+    }
+
+    /**
+     * Re-generate the GraphQL schema from the currently registered services
+     * and swap the stored reference. The live Yoga instance reads the schema
+     * via a factory (see graphqlSetup), so the next request observes the new
+     * schema without recreating Yoga or restarting the process.
+     *
+     * This is the Phase 0 "live re-weave" primitive: register a service (or
+     * mutate one's __graphqlOperations) then call this to reflect it.
+     * Returns the new schema (or null if generation produced none).
+     */
+    public rebuildSchema(): GraphQLSchema | null {
+        const servicesArray = Array.from(this.services.values());
+        const result = generateGraphQLSchemaV2(servicesArray, {
+            enableArchetypeOperations: false
+        });
+        this.schema = result.schema;
+        this.schemaVersion++;
+        return this.schema;
+    }
 }
 
 export default ServiceRegistry.instance;