bunsane 0.5.0 → 0.5.2

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;
     }
 
@@ -990,7 +1035,7 @@ export class BaseArcheType {
 
     public buildFilterBranches(filter?: FilterSchema<any>): any[] {
         if (!filter) return [];
-        const branches = [];
+        const branches: Array<{ component: any; filters: Array<{ field: string; operator: any; value: any }> }> = [];
 
         for (const [fieldName, componentCtor] of Object.entries(this.componentMap)) {
             const fieldOption = this.fieldOptions[fieldName];

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/app/metricsCollector.ts

@@ -2,11 +2,12 @@ import { logger as MainLogger } from "../Logger";
 import { SchedulerManager } from "../SchedulerManager";
 import { preparedStatementCache } from "../../database/PreparedStatementCache";
 import { getDbStats } from "../../database/instrumentedDb";
+import type { CacheManager } from "../cache/CacheManager";
 
 const logger = MainLogger.child({ scope: "App" });
 
 export async function collectMetrics(app: any) {
-    let cacheStats = null;
+    let cacheStats: Awaited<ReturnType<CacheManager["getStats"]>> | null = null;
     try {
         const { CacheManager } = await import('../cache/CacheManager');
         cacheStats = await CacheManager.getInstance().getStats();

package/core/app/studioRouter.ts

@@ -20,6 +20,20 @@ export async function routeStudio(
         return await studioEndpoint.handleStudioComponentsRequest();
     }
 
+    if (url.pathname === "/studio/api/entities") {
+        const limit = url.searchParams.get("limit");
+        const offset = url.searchParams.get("offset");
+        const search = url.searchParams.get("search");
+        const includeDeleted = url.searchParams.get("include_deleted");
+
+        return await studioEndpoint.handleEntityListRequest({
+            limit: limit ? parseInt(limit, 10) : undefined,
+            offset: offset ? parseInt(offset, 10) : undefined,
+            search: search ?? undefined,
+            include_deleted: includeDeleted === "true",
+        });
+    }
+
     if (url.pathname === "/studio/api/query" && method === "POST") {
         const body = await req.json();
         return await studioEndpoint.handleStudioQueryRequest(body);

package/core/archetype/zodSchemaBuilder.ts

@@ -521,7 +521,12 @@ export function buildZodObjectSchema(
         graphqlSchema: graphqlSchemaString,
     });
 
-    allArchetypeZodObjects.set(nameFromStorage, r);
+    // Only cache the canonical full variant in the shared map. Function-less /
+    // relation-less variants (e.g. from getInputSchema) must not overwrite it,
+    // or weaveAllArchetypes welds SDL missing @ArcheTypeFunction fields → resolver/schema mismatch.
+    if (!excludeRelations && !excludeFunctions) {
+        allArchetypeZodObjects.set(nameFromStorage, r);
+    }
 
     return r;
 }

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

@@ -226,8 +226,8 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
         }
 
         // Batch inserts and updates for better performance
-        const componentsToInsert = [];
-        const componentsToUpdate = [];
+        const componentsToInsert: Array<{ id: string; entity_id: string; name: string; type_id: string; data: Record<string, any> }> = [];
+        const componentsToUpdate: Array<{ id: string; entity_id: string; name: string; type_id: string; data: Record<string, any> }> = [];
 
         for (const comp of entity.components.values()) {
             const compName = comp.constructor.name;
@@ -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/core/metadata/metadata-storage.ts

@@ -4,9 +4,16 @@ import type {
     ComponentPropertyMetadata,
     IndexedFieldMetadata
  } from "./definitions/Component";
-import type { ArcheTypeMetadata, ArcheTypeFieldOptions } from './definitions/ArcheType';
+import type { ArcheTypeMetadata, ArcheTypeFieldOptions, ArcheTypeFunctionMetadata } from './definitions/ArcheType';
 import type { RelationOptions } from '../ArcheType';
 
+// Mirror of decorators.archetypeFunctionsSymbol — referenced via the global symbol
+// registry to avoid a circular import between metadata-storage and archetype/decorators.
+const archetypeFunctionsSymbol = Symbol.for("bunsane:archetypeFunctions");
+
+type ArcheTypeFunctionOptions = ArcheTypeFunctionMetadata["options"];
+type ArcheTypeFunctionHandler = (entity: any, ...args: any[]) => any;
+
 function generateTypeId(name: string): string {
   return createHash('sha256').update(name).digest('hex');
 }
@@ -87,6 +94,57 @@ export class MetadataStorage {
         this.archetypes_relations_map.get(archetype_id)!.push({fieldName, relatedArcheType, relationType, options, type});
     }
 
+    /**
+     * Register a computed (@ArcheTypeFunction-equivalent) field at runtime, with no decorator.
+     *
+     * Wires all three sites the decorator path touches in one call:
+     *  - prototype symbol array → instances pick it up via `this.functions`
+     *  - prototype method → resolver invokes `archetype[propertyKey](entity, ...)`
+     *  - archetype metadata.functions → weaver emits the field in the SDL
+     *
+     * The archetype must already be registered (via @ArcheType or runtime registration)
+     * so its target class is known; throws otherwise.
+     */
+    collectArchetypeFunction(
+        name: string,
+        propertyKey: string,
+        handler: ArcheTypeFunctionHandler,
+        options?: ArcheTypeFunctionOptions
+    ) {
+        const metadata = this.archetypes.find(a => a.name === name);
+        if (!metadata) {
+            throw new Error(`Cannot register function '${propertyKey}': archetype '${name}' is not registered`);
+        }
+
+        const prototype = (metadata.target as any).prototype;
+
+        // 1. prototype symbol array (consumed by BaseArcheType ctor → this.functions)
+        if (!prototype[archetypeFunctionsSymbol]) {
+            prototype[archetypeFunctionsSymbol] = [];
+        }
+        const protoFns: ArcheTypeFunctionMetadata[] = prototype[archetypeFunctionsSymbol];
+        const protoIdx = protoFns.findIndex(f => f.propertyKey === propertyKey);
+        if (protoIdx !== -1) {
+            protoFns[protoIdx] = { propertyKey, options };
+        } else {
+            protoFns.push({ propertyKey, options });
+        }
+
+        // 2. prototype method (invoked by the field resolver)
+        prototype[propertyKey] = handler;
+
+        // 3. metadata.functions (read by the weaver to build SDL)
+        if (!metadata.functions) {
+            metadata.functions = [];
+        }
+        const metaIdx = metadata.functions.findIndex(f => f.propertyKey === propertyKey);
+        if (metaIdx !== -1) {
+            metadata.functions[metaIdx] = { propertyKey, options };
+        } else {
+            metadata.functions.push({ propertyKey, options });
+        }
+    }
+
     collectArcheTypeMetadata(metadata: ArcheTypeMetadata) {
         // Check if archetype already exists and update it
         const existingIndex = this.archetypes.findIndex(