bunsane 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.1 — 2026-06-16
+
+### Added
+
+- **Transaction-aware cache invalidation** — component writes made via
+  `comp.save(trx, id)` inside the new `transaction()` wrapper now bust the
+  component cache on commit, using the same
+  `CacheManager.invalidateEntityComponents` path (L1 + L2 + cross-instance
+  pub/sub) that `Entity.save` uses. Touched `(entityId, typeId)` pairs are
+  tracked automatically (keyed by the transaction handle), then flushed after
+  the transaction commits. The `tx` context also exposes `tx.markDirty(entityId,
+  component)` for components not saved directly and `tx.onCommit(cb)` for
+  post-commit side effects. Exported from `bunsane/core/cache` as `transaction`,
+  `txMarkDirty`, `txOnCommit`. No behavior change for `comp.save` outside the
+  wrapper — tracking is a no-op there.
+- **`ArcheTypeQuery.select(...fields)`** — opt-in projection for archetype
+  queries. Loads data only for the selected component fields instead of every
+  component in the archetype, cutting JSONB wire + parse cost for wide
+  archetypes read with narrow selections. Membership filtering is unaffected
+  (matching still requires all components); unselected fields remain
+  lazy-loadable. Backward-compatible — without `select()`, all components load as
+  before.
+
+### Fixed
+
+- **RedisCache test connects on `127.0.0.1`** instead of `localhost`, which
+  resolves to IPv6 `::1` first on Windows and times out against an IPv4-only
+  Redis. Test-only change.
+
 ## 0.5.0 — 2026-06-15
 
 ### Added

package/core/App.ts

@@ -11,7 +11,20 @@ import {
 } from "../database/DatabaseHelper";
 import { ComponentRegistry } from "./components";
 import { logger as MainLogger } from "./Logger";
+import { readFileSync } from "fs";
 const logger = MainLogger.child({ scope: "App" });
+
+// BunSane framework version, read from the package's own package.json at module
+// load. Resolved relative to this module file so it works regardless of cwd or
+// how the consumer installs the package.
+let BUNSANE_VERSION = "unknown";
+try {
+    BUNSANE_VERSION = JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    ).version;
+} catch {
+    // version stays "unknown" if package.json can't be read
+}
 import ServiceRegistry from "../service/ServiceRegistry";
 import { type Plugin, createPubSub } from "graphql-yoga";
 import * as path from "path";
@@ -351,6 +364,20 @@ export default class App {
         this.maxRequestBodySize = bytes;
     }
 
+    /**
+     * Re-weave the GraphQL schema from the currently registered services and
+     * swap it into the live Yoga instance — no restart, no Yoga recreation.
+     * The next request observes the new schema (Yoga reads it via a factory).
+     *
+     * Phase 0 primitive for runtime schema mutation: register/modify a service
+     * (or its @GraphQLOperation metadata), then call this to reflect it live.
+     * Returns the new schema version number (monotonic, starts at 1).
+     */
+    public rebuildGraphQLSchema(): number {
+        ServiceRegistry.rebuildSchema();
+        return ServiceRegistry.getSchemaVersion();
+    }
+
     private async warmUpPreparedStatementCache(): Promise<void> {
         return warmUpPreparedStatementCacheFn(this);
     }
@@ -396,7 +423,7 @@ export default class App {
             `Server is running on ${new URL(
                 this.yoga?.graphqlEndpoint || "/graphql",
                 `http://${this.server.hostname}:${this.server.port}`
-            )}`
+            )} (BunSane v${BUNSANE_VERSION})`
         );
 
         // Signal handlers now registered in init() via registerProcessHandlers()

package/core/ArcheType.ts

@@ -160,6 +160,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
     private innerQuery: Query<any>;
     private archetypeInstance: T;
     private archetypeCtor: new () => T;
+    private selectedFields: string[] | null = null;
 
     constructor(archetypeCtor: new () => T) {
         this.archetypeCtor = archetypeCtor;
@@ -241,6 +242,50 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
         return this;
     }
 
+    /**
+     * Project: load data only for the given archetype fields (components).
+     *
+     * Membership filtering is unaffected — matching the archetype still requires
+     * all its components. This only limits which component DATA is fetched, so a
+     * wide archetype read with a narrow selection skips the JSONB wire+parse cost
+     * of unselected components. Unselected fields are absent from results; they
+     * remain lazy-loadable later via entity.get() under a request scope.
+     *
+     * Backward-compatible: without select(), exec()/first() load all components.
+     *
+     * @example
+     * ```typescript
+     * const players = await Player.query().select('position', 'health').exec();
+     * // only position + health component data loaded; velocity etc. skipped
+     * ```
+     */
+    public select<K extends keyof ArcheTypeOwnProperties<T>>(...fields: K[]): this {
+        this.selectedFields = fields.map((f) => {
+            const name = String(f);
+            if (!this.archetypeInstance.componentMap[name]) {
+                throw new Error(`Field '${name}' is not a component field on this archetype`);
+            }
+            return name;
+        });
+        return this;
+    }
+
+    private selectedComponentCtors(): Array<new () => BaseComponent> {
+        return (this.selectedFields ?? []).map(
+            (f) => this.archetypeInstance.componentMap[f] as unknown as new () => BaseComponent
+        );
+    }
+
+    /**
+     * Apply the load strategy: projected (eager-load selected components) when
+     * select() was used, otherwise populate() all archetype components.
+     */
+    private withLoadStrategy(): Query<any> {
+        return this.selectedFields
+            ? this.innerQuery.eagerLoadComponents(this.selectedComponentCtors())
+            : this.innerQuery.populate();
+    }
+
     /**
      * Enable populate mode to load all component data
      */
@@ -261,7 +306,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
      * Execute the query and return typed archetype results
      */
     public async exec(): Promise<ArcheTypeResult<T>[]> {
-        const entities = await this.innerQuery.populate().exec();
+        const entities = await this.withLoadStrategy().exec();
         return entities.map(entity => this.wrapAsArchetype(entity as Entity));
     }
 
@@ -269,7 +314,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
      * Execute the query and return the first result (or null)
      */
     public async first(): Promise<ArcheTypeResult<T> | null> {
-        const results = await this.innerQuery.take(1).populate().exec();
+        const results = await this.withLoadStrategy().take(1).exec();
         return results[0] ? this.wrapAsArchetype(results[0] as Entity) : null;
     }
 

package/core/app/graphqlSetup.ts

@@ -4,7 +4,10 @@ import { createYogaInstance } from "../../gql";
 import { createRequestContextPlugin } from "../RequestContext";
 
 export function setupGraphQL(app: any): void {
-    const schema = ServiceRegistry.getSchema();
+    // Provide the schema as a live factory rather than a fixed reference, so
+    // ServiceRegistry.rebuildSchema() is observed by the next request without
+    // recreating Yoga. Falls back to the static placeholder while null.
+    const schemaProvider = () => ServiceRegistry.getSchema();
 
     const wrappedContextFactory = app.contextFactory
         ? async (yogaContext: any) => {
@@ -38,19 +41,10 @@ export function setupGraphQL(app: any): void {
         ? [createRequestContextPlugin(), ...app.yogaPlugins]
         : [...app.yogaPlugins];
 
-    if (schema) {
-        app.yoga = createYogaInstance(
-            schema,
-            effectivePlugins,
-            wrappedContextFactory,
-            yogaOptions,
-        );
-    } else {
-        app.yoga = createYogaInstance(
-            undefined,
-            effectivePlugins,
-            wrappedContextFactory,
-            yogaOptions,
-        );
-    }
+    app.yoga = createYogaInstance(
+        schemaProvider,
+        effectivePlugins,
+        wrappedContextFactory,
+        yogaOptions,
+    );
 }

package/core/cache/index.ts

@@ -3,4 +3,13 @@ export { MemoryCache } from './MemoryCache';
 export type { MemoryCacheConfig } from './MemoryCache';
 export { NoOpCache } from './NoOpCache';
 export { CacheManager } from './CacheManager';
-export { CacheFactory } from './CacheFactory';
+export { CacheFactory } from './CacheFactory';
+export {
+    transaction,
+    markDirty as txMarkDirty,
+    registerOnCommit as txOnCommit,
+    trackComponentDirty,
+    beginTxTracking,
+    flushTxTracking,
+} from './txInvalidation';
+export type { TxContext } from './txInvalidation';

package/core/cache/txInvalidation.ts

@@ -0,0 +1,183 @@
+/**
+ * Transaction-aware cache invalidation.
+ *
+ * `comp.save(trx, id)` writes the DB but does no cache invalidation on its own.
+ * Inside a tracked transaction we accumulate the (entityId, typeId) pairs that
+ * were touched and, once the transaction COMMITS, run the same invalidation that
+ * entity.save() uses (CacheManager.invalidateEntityComponents → deleteMany +
+ * cross-instance pub/sub).
+ *
+ * Bun.SQL exposes no commit hook, so "on commit" means: after the
+ * `db.transaction(cb)` promise resolves. The `transaction()` wrapper below owns
+ * that boundary. Tracking is keyed by the trx object via a WeakMap, so
+ * `trackComponentDirty` is a cheap no-op for any comp.save() that runs outside a
+ * tracked transaction (top-level db, or entity.save() which handles its own
+ * cache) — zero behavior change for existing callers.
+ */
+import { logger as MainLogger } from '../Logger';
+
+const logger = MainLogger.child({ scope: 'TxCacheInvalidation' });
+
+/** Anything carrying a component type_id — avoids a hard BaseComponent import (cycle). */
+type ComponentRef = string | { _typeId?: string } | (new (...args: any[]) => any);
+
+type SQLLike = Bun.SQL;
+
+interface TxState {
+    /** entityId -> set of touched component type_ids */
+    dirty: Map<string, Set<string>>;
+    onCommit: Array<() => void | Promise<void>>;
+}
+
+/** Tracking state keyed by the transaction's SQL handle. */
+const txRegistry = new WeakMap<SQLLike, TxState>();
+
+/** Begin tracking for a transaction handle. Idempotent. */
+export function beginTxTracking(trx: SQLLike): TxState {
+    let state = txRegistry.get(trx);
+    if (!state) {
+        state = { dirty: new Map(), onCommit: [] };
+        txRegistry.set(trx, state);
+    }
+    return state;
+}
+
+export function getTxState(trx: SQLLike): TxState | undefined {
+    return txRegistry.get(trx);
+}
+
+/**
+ * Record that a component (entityId + typeId) was written under this trx.
+ * No-op when the trx is not tracked (i.e. not inside transaction()).
+ */
+export function trackComponentDirty(trx: SQLLike, entityId: string, typeId: string): void {
+    const state = txRegistry.get(trx);
+    if (!state || !entityId || !typeId) return;
+    let set = state.dirty.get(entityId);
+    if (!set) {
+        set = new Set();
+        state.dirty.set(entityId, set);
+    }
+    set.add(typeId);
+}
+
+/** Resolve a component ctor / instance / raw typeId string to its type_id. */
+function resolveTypeId(component: ComponentRef): string | null {
+    if (typeof component === 'string') return component;
+    // Instance carrying a _typeId (BaseComponent) — duck-typed to avoid an import cycle.
+    const instanceTypeId = (component as { _typeId?: string })._typeId;
+    if (typeof instanceTypeId === 'string' && instanceTypeId.length > 0) return instanceTypeId;
+    // Constructor: derive from class name via metadata.
+    if (typeof component === 'function') {
+        try {
+            const { getMetadataStorage } = require('../metadata');
+            return getMetadataStorage().getComponentId(component.name);
+        } catch {
+            return null;
+        }
+    }
+    return null;
+}
+
+/**
+ * Explicitly mark a component dirty for invalidation on commit.
+ * Accepts a component constructor, instance, or raw type_id string.
+ */
+export function markDirty(trx: SQLLike, entityId: string, component: ComponentRef): void {
+    const typeId = resolveTypeId(component);
+    if (!typeId) {
+        logger.warn({ entityId, msg: 'markDirty: could not resolve component type_id; skipping' });
+        return;
+    }
+    trackComponentDirty(trx, entityId, typeId);
+}
+
+/** Register a callback to run after the transaction commits. */
+export function registerOnCommit(trx: SQLLike, cb: () => void | Promise<void>): void {
+    const state = beginTxTracking(trx);
+    state.onCommit.push(cb);
+}
+
+/**
+ * Flush accumulated invalidations + run onCommit callbacks. Call ONLY after the
+ * transaction has committed. Errors are logged, never thrown — a cache flush
+ * failure must not surface as a transaction failure (the data is already
+ * committed; stale cache is recoverable, a thrown error is not).
+ */
+export async function flushTxTracking(state: TxState | undefined): Promise<void> {
+    if (!state) return;
+    try {
+        if (state.dirty.size > 0) {
+            const { CacheManager } = require('./CacheManager');
+            const cacheManager = CacheManager.getInstance();
+            await Promise.all(
+                Array.from(state.dirty.entries()).map(([entityId, typeIds]) =>
+                    cacheManager
+                        .invalidateEntityComponents(entityId, Array.from(typeIds), { includeEntityKey: true })
+                        .catch((error: unknown) =>
+                            logger.error({ entityId, error, msg: 'Failed to invalidate entity components on commit' }),
+                        ),
+                ),
+            );
+        }
+    } catch (error) {
+        logger.error({ error, msg: 'Error during transaction cache flush' });
+    }
+
+    for (const cb of state.onCommit) {
+        try {
+            await cb();
+        } catch (error) {
+            logger.error({ error, msg: 'onCommit callback threw' });
+        }
+    }
+}
+
+/** Context handed to the transaction() callback for explicit control. */
+export interface TxContext {
+    /** Mark a component dirty for invalidation on commit. */
+    markDirty(entityId: string, component: ComponentRef): void;
+    /** Run a callback after the transaction commits (cache already flushed). */
+    onCommit(cb: () => void | Promise<void>): void;
+}
+
+/**
+ * Run a transaction with automatic, transaction-aware cache invalidation.
+ *
+ * Any `comp.save(trx, entityId)` performed with the provided `trx` is tracked
+ * automatically; on commit, those components are invalidated using the same
+ * logic entity.save() uses. The `tx` context adds explicit markDirty/onCommit
+ * escape hatches.
+ *
+ * Invalidation runs inline (awaited) after commit, so when this resolves the
+ * cache is already consistent.
+ *
+ * @example
+ * ```typescript
+ * await transaction(async (trx, tx) => {
+ *   await positionComp.save(trx, entityId);   // auto-tracked
+ *   tx.markDirty(entityId, Velocity);          // explicit
+ *   tx.onCommit(() => metrics.bump());         // after commit
+ * });
+ * ```
+ */
+export async function transaction<T>(
+    fn: (trx: SQLLike, tx: TxContext) => Promise<T>,
+): Promise<T> {
+    const { getDb } = require('../../database');
+    const db: SQLLike = getDb();
+
+    let state: TxState | undefined;
+    const result = await db.transaction(async (trx: SQLLike) => {
+        state = beginTxTracking(trx);
+        const ctx: TxContext = {
+            markDirty: (entityId, component) => markDirty(trx, entityId, component),
+            onCommit: (cb) => registerOnCommit(trx, cb),
+        };
+        return await fn(trx, ctx);
+    });
+
+    // Transaction committed (resolved without throwing) → flush invalidations.
+    await flushTxTracking(state);
+    return result as T;
+}

package/core/components/BaseComponent.ts

@@ -5,6 +5,7 @@ import ComponentRegistry from "./ComponentRegistry";
 import { type ComponentDataType } from './Interfaces';
 import { uuidv7 } from '../../utils/uuid';
 import { getMetadataStorage } from '../metadata';
+import { trackComponentDirty } from '../cache/txInvalidation';
 const logger = MainLogger.child({ scope: "Components" });
 
 // Cached property-name arrays keyed by typeId. Metadata is immutable after
@@ -104,6 +105,10 @@ export class BaseComponent {
             await this.insert(trx, entity_id);
             this._persisted = true;
         }
+        // Transaction-aware cache invalidation: record this write so the
+        // transaction() wrapper can bust the component cache on commit.
+        // No-op outside a tracked transaction (cheap WeakMap miss).
+        trackComponentDirty(trx, entity_id, this._typeId);
     }
 
     async insert(trx: Bun.SQL, entity_id: string) {

package/core/entity/saveEntity.ts

@@ -254,8 +254,13 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
                 (comp as any).setPersisted(true);
                 (comp as any).setDirty(false);
             } else if ((comp as any)._dirty) {
+                // Full columns so the batched upsert below can encode every row
+                // through the same sql(arr, cols) path as the INSERT batch.
                 componentsToUpdate.push({
                     id: comp.id,
+                    entity_id: entity.id,
+                    name: compName,
+                    type_id: comp.getTypeID(),
                     data: comp.serializableData()
                 });
                 (comp as any).setDirty(false);
@@ -267,12 +272,15 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
             await run(saveTrx`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'name', 'type_id', 'data')}`);
         }
 
-        // Perform updates. Validate all ids up front (synchronous, fails
-        // fast), then issue the UPDATEs sequentially. They were previously
-        // fired together via Promise.all to "pipeline" on the transaction
-        // connection, but multiple concurrent in-flight queries on one
-        // connection deadlock single-backend servers (PGlite test harness),
-        // and a single wire serializes them regardless — no real gain.
+        // Perform updates as a SINGLE batched upsert. Dirty components already
+        // exist (persisted, live), so the ON CONFLICT path always fires and
+        // updates `data` for every row in one round-trip — replacing the
+        // previous N sequential UPDATEs (N wire round-trips inside the txn).
+        // Conflict target is the (id, type_id) PRIMARY KEY, which contains the
+        // partition key `type_id` — required for ON CONFLICT on the partitioned
+        // `components` table. Reuses the same sql(arr, cols) encoder as the
+        // INSERT batch, so jsonb encoding is identical across PostgreSQL and
+        // PGlite. `created_at` is preserved (DO UPDATE only touches `data`).
         if (componentsToUpdate.length > 0) {
             const traceEnabled = logger.isLevelEnabled?.('trace') === true;
             for (const comp of componentsToUpdate) {
@@ -287,9 +295,7 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
                     logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
                 }
             }
-            for (const comp of componentsToUpdate) {
-                await run(saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`);
-            }
+            await run(saveTrx`INSERT INTO components ${sql(componentsToUpdate, 'id', 'entity_id', 'name', 'type_id', 'data')} ON CONFLICT (id, type_id) DO UPDATE SET data = EXCLUDED.data`);
         }
     };
 

package/database/DatabaseHelper.ts

@@ -156,7 +156,7 @@ export const CreateComponentTable = async () => {
         ) 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 +226,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,
@@ -249,7 +273,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`;

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.1",
     "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;