@czap/core 0.1.0

package/dist/receipt.js

@@ -0,0 +1,352 @@
+/**
+ * Receipt -- chain validation and envelope construction.
+ *
+ * Salvaged from `@kit/core`.
+ *
+ * @module
+ */
+import { Effect } from 'effect';
+import { TypedRef as TypedRefModule } from './typed-ref.js';
+import { HLC as HLCOps } from './hlc.js';
+/** Sentinel `previous` value marking the root of a receipt chain. */
+export const GENESIS = 'genesis';
+/**
+ * Compute the content hash of a receipt envelope.
+ *
+ * Normalizes the `previous` field (sorts array form), canonicalizes the
+ * payload, and hashes with SHA-256 via TypedRef.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ *
+ * const hash = yield* Receipt.hashEnvelope(envelope);
+ * // hash === envelope.hash (if envelope is valid)
+ * ```
+ */
+export const hashEnvelope = (envelope) => {
+    const previousNormalized = Array.isArray(envelope.previous)
+        ? [...envelope.previous].sort()
+        : envelope.previous;
+    const hashInput = TypedRefModule.canonicalize({
+        kind: envelope.kind,
+        timestamp: envelope.timestamp,
+        subject: envelope.subject,
+        payload: envelope.payload,
+        previous: previousNormalized,
+    });
+    return TypedRefModule.hash(hashInput);
+};
+/**
+ * Create a new receipt envelope with an auto-computed content hash.
+ *
+ * @example
+ * ```ts
+ * const envelope = yield* Receipt.createEnvelope(
+ *   'state-change',
+ *   { type: 'effect', id: 'actor-1' },
+ *   { _tag: 'TypedRef', mediaType: 'application/json', data: { key: 'value' } },
+ *   hlcTimestamp,
+ *   Receipt.GENESIS,
+ * );
+ * // envelope.hash is the computed SHA-256 content address
+ * ```
+ */
+export const createEnvelope = (kind, subject, payload, timestamp, previousHash) => Effect.gen(function* () {
+    const previousNormalized = Array.isArray(previousHash)
+        ? [...previousHash].sort()
+        : previousHash;
+    const partial = { kind, timestamp, subject, payload, previous: previousNormalized };
+    const h = yield* TypedRefModule.hash(TypedRefModule.canonicalize(partial));
+    return { kind, timestamp, subject, payload, hash: h, previous: previousNormalized };
+});
+/**
+ * Build a linear chain of receipt envelopes from an array of entries.
+ *
+ * Each envelope's `previous` points to the prior envelope's hash,
+ * starting from GENESIS.
+ *
+ * @example
+ * ```ts
+ * const chain = yield* Receipt.buildChain([
+ *   { kind: 'init', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts1 },
+ *   { kind: 'update', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts2 },
+ * ]);
+ * // chain.length === 2
+ * // chain[1].previous === chain[0].hash
+ * ```
+ */
+export const buildChain = (entries) => Effect.gen(function* () {
+    const chain = [];
+    let previousHash = GENESIS;
+    for (const entry of entries) {
+        const envelope = yield* createEnvelope(entry.kind, entry.subject, entry.payload, entry.timestamp, previousHash);
+        chain.push(envelope);
+        previousHash = envelope.hash;
+    }
+    return chain;
+});
+/**
+ * Validate a receipt chain: genesis link, hash integrity, chain continuity, HLC ordering.
+ *
+ * Returns true on success or fails with an Error describing the violation.
+ *
+ * @example
+ * ```ts
+ * const chain = yield* Receipt.buildChain(entries);
+ * const valid = yield* Receipt.validateChain(chain);
+ * // valid === true
+ * ```
+ */
+export const validateChain = (chain) => Effect.gen(function* () {
+    if (chain.length === 0)
+        return true;
+    const first = chain[0];
+    const firstPrev = first.previous;
+    if (firstPrev !== GENESIS && !(Array.isArray(firstPrev) && firstPrev.includes(GENESIS))) {
+        return yield* Effect.fail(new Error('First envelope must have previous=genesis'));
+    }
+    for (let i = 0; i < chain.length; i++) {
+        const envelope = chain[i];
+        const computedHash = yield* hashEnvelope(envelope);
+        if (computedHash !== envelope.hash) {
+            return yield* Effect.fail(new Error(`Envelope ${i}: hash mismatch (expected "${envelope.hash}", computed "${computedHash}")`));
+        }
+        const isMerge = Array.isArray(envelope.previous);
+        if (!isMerge && i > 0 && envelope.previous !== chain[i - 1].hash) {
+            return yield* Effect.fail(new Error(`Envelope ${i}: chain break`));
+        }
+        if (!isMerge && i > 0 && HLCOps.compare(chain[i - 1].timestamp, envelope.timestamp) >= 0) {
+            return yield* Effect.fail(new Error(`Envelope ${i}: HLC not monotonically increasing`));
+        }
+    }
+    return true;
+});
+/**
+ * Validate a receipt chain with detailed, structured error reporting.
+ *
+ * Returns `true` on success or fails with a typed `ChainValidationError`
+ * discriminated union (not_genesis | hash_mismatch | chain_break | hlc_not_increasing).
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ *
+ * const result = yield* Effect.either(Receipt.validateChainDetailed(chain));
+ * // result._tag === 'Right' on success
+ * // result._tag === 'Left' with .left.type on failure
+ * ```
+ */
+export const validateChainDetailed = (chain) => Effect.gen(function* () {
+    if (chain.length === 0)
+        return true;
+    const first = chain[0];
+    const firstPrev = first.previous;
+    const firstIsGenesis = firstPrev === GENESIS || (Array.isArray(firstPrev) && firstPrev.includes(GENESIS));
+    if (!firstIsGenesis) {
+        return yield* Effect.fail({ type: 'not_genesis', index: 0 });
+    }
+    for (let i = 0; i < chain.length; i++) {
+        const envelope = chain[i];
+        const isMerge = Array.isArray(envelope.previous);
+        const computedHash = yield* hashEnvelope(envelope);
+        if (computedHash !== envelope.hash) {
+            return yield* Effect.fail({
+                type: 'hash_mismatch',
+                index: i,
+                computed: computedHash,
+                stored: envelope.hash,
+            });
+        }
+        if (!isMerge && i > 0 && envelope.previous !== chain[i - 1].hash) {
+            return yield* Effect.fail({
+                type: 'chain_break',
+                index: i,
+                expected: chain[i - 1].hash,
+                actual: envelope.previous,
+            });
+        }
+        if (!isMerge && i > 0 && HLCOps.compare(chain[i - 1].timestamp, envelope.timestamp) >= 0) {
+            return yield* Effect.fail({
+                type: 'hlc_not_increasing',
+                index: i,
+            });
+        }
+    }
+    return true;
+});
+/**
+ * Check whether a receipt envelope is a genesis (root) envelope.
+ *
+ * @example
+ * ```ts
+ * const chain = yield* Receipt.buildChain(entries);
+ * Receipt.isGenesis(chain[0]); // true
+ * Receipt.isGenesis(chain[1]); // false
+ * ```
+ */
+export const isGenesis = (receipt) => receipt.previous === GENESIS ||
+    (Array.isArray(receipt.previous) && receipt.previous.includes(GENESIS));
+/**
+ * Get the last (most recent) envelope in a chain.
+ *
+ * @example
+ * ```ts
+ * const latest = Receipt.head(chain);
+ * // latest === chain[chain.length - 1]
+ * ```
+ */
+export const head = (chain) => chain.length > 0 ? chain[chain.length - 1] : undefined;
+/**
+ * Get the first (genesis) envelope in a chain.
+ *
+ * @example
+ * ```ts
+ * const first = Receipt.tail(chain);
+ * // first === chain[0]
+ * ```
+ */
+export const tail = (chain) => chain.length > 0 ? chain[0] : undefined;
+/**
+ * Append a new entry to an existing chain, auto-linking to the previous hash.
+ *
+ * Optionally accepts explicit previous hashes for merge envelopes.
+ *
+ * @example
+ * ```ts
+ * const chain = yield* Receipt.buildChain([entry1]);
+ * const extended = yield* Receipt.append(chain, {
+ *   kind: 'update', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts2,
+ * });
+ * // extended.length === 2
+ * ```
+ */
+export const append = (chain, entry, previousHashes) => Effect.gen(function* () {
+    const previousHash = previousHashes
+        ? previousHashes
+        : chain.length > 0
+            ? chain[chain.length - 1].hash
+            : GENESIS;
+    const envelope = yield* createEnvelope(entry.kind, entry.subject, entry.payload, entry.timestamp, previousHash);
+    return [...chain, envelope];
+});
+/**
+ * Find an envelope in a chain by its content hash.
+ *
+ * @example
+ * ```ts
+ * const found = Receipt.findByHash(chain, targetHash);
+ * // found?.hash === targetHash
+ * ```
+ */
+export const findByHash = (chain, hash) => chain.find((e) => e.hash === hash);
+/**
+ * Find all envelopes in a chain matching a given kind.
+ *
+ * @example
+ * ```ts
+ * const updates = Receipt.findByKind(chain, 'update');
+ * // updates contains all envelopes with kind === 'update'
+ * ```
+ */
+export const findByKind = (chain, kind) => chain.filter((e) => e.kind === kind);
+/**
+ * Generate an HMAC-SHA-256 key for signing receipt envelopes.
+ *
+ * @example
+ * ```ts
+ * const key = yield* Receipt.generateMACKey();
+ * const signed = yield* Receipt.macEnvelope(envelope, key);
+ * // signed.signature is a hex string
+ * ```
+ */
+export const generateMACKey = () => Effect.tryPromise({
+    try: () => crypto.subtle.generateKey({ name: 'HMAC', hash: { name: 'SHA-256' } }, true, ['sign', 'verify']),
+    catch: (error) => new Error(`Failed to generate MAC key: ${error}`),
+});
+/**
+ * Sign a receipt envelope with an HMAC key, adding a `signature` field.
+ *
+ * @example
+ * ```ts
+ * const key = yield* Receipt.generateMACKey();
+ * const signed = yield* Receipt.macEnvelope(envelope, key);
+ * // signed.signature !== undefined
+ * ```
+ */
+export const macEnvelope = (envelope, key) => Effect.gen(function* () {
+    const data = new TextEncoder().encode(envelope.hash);
+    const signatureBuffer = yield* Effect.tryPromise({
+        try: () => crypto.subtle.sign('HMAC', key, data),
+        catch: (error) => new Error(`Failed to MAC envelope: ${error}`),
+    });
+    const signatureArray = Array.from(new Uint8Array(signatureBuffer));
+    const signature = signatureArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    return { ...envelope, signature };
+});
+/**
+ * Verify an envelope's HMAC signature against a key.
+ *
+ * Returns false if the envelope has no signature.
+ *
+ * @example
+ * ```ts
+ * const valid = yield* Receipt.verifyMAC(signedEnvelope, key);
+ * // valid === true if signature matches
+ * ```
+ */
+export const verifyMAC = (envelope, key) => Effect.gen(function* () {
+    if (!envelope.signature)
+        return false;
+    const signatureHex = envelope.signature;
+    if (!/^[0-9a-fA-F]+$/.test(signatureHex) || signatureHex.length % 2 !== 0) {
+        return yield* Effect.fail(new Error('Invalid signature hex: expected even-length hex string'));
+    }
+    const signatureArray = new Uint8Array(signatureHex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16)));
+    const data = new TextEncoder().encode(envelope.hash);
+    const valid = yield* Effect.tryPromise({
+        try: () => crypto.subtle.verify('HMAC', key, signatureArray, data),
+        catch: (error) => new Error(`Failed to verify signature: ${error}`),
+    });
+    return valid;
+});
+/**
+ * Receipt namespace -- chain validation and envelope construction.
+ *
+ * Build, validate, append, query, and sign linear receipt chains.
+ * Each envelope is content-addressed and linked to its predecessor.
+ * Supports HMAC signing/verification for tamper detection.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { Receipt, HLC } from '@czap/core';
+ *
+ * const program = Effect.gen(function* () {
+ *   const ts = HLC.increment(HLC.create('node-1'), Date.now());
+ *   const chain = yield* Receipt.buildChain([
+ *     { kind: 'init', subject: { type: 'effect', id: 'a' }, payload, timestamp: ts },
+ *   ]);
+ *   const valid = yield* Receipt.validateChain(chain);
+ *   const latest = Receipt.head(chain);
+ * });
+ * ```
+ */
+export const Receipt = {
+    GENESIS,
+    createEnvelope,
+    buildChain,
+    validateChain,
+    validateChainDetailed,
+    hashEnvelope,
+    isGenesis,
+    head,
+    tail,
+    append,
+    findByHash,
+    findByKind,
+    generateMACKey,
+    macEnvelope,
+    verifyMAC,
+};
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"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"}

package/dist/runtime-coordinator.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RuntimeCoordinator -- shared host/runtime coordination surface.
+ *
+ * Bridges Plan and ECS into the live host path by:
+ * - defining the execution graph for runtime passes
+ * - backing quantizer state indices and dirty epochs with dense stores
+ *
+ * The coordinator is intentionally light-weight on the hot path: the plan is
+ * constructed once up front, and dense stores are used for numeric state that
+ * is read repeatedly during runtime work.
+ *
+ * @module
+ */
+import { EntityId } from './ecs.js';
+import type { DenseStore } from './ecs.js';
+import { Plan } from './plan.js';
+/**
+ * Named stages of the runtime frame pass, in canonical topological order:
+ * discrete quantization first, then blend weights, then target emitters.
+ */
+export type RuntimePhase = 'compute-discrete' | 'compute-blend' | 'emit-css' | 'emit-glsl' | 'emit-aria';
+/** Options accepted by {@link RuntimeCoordinator.create}: entity capacity and plan name. */
+export interface RuntimeCoordinatorConfig {
+    readonly capacity?: number;
+    readonly name?: string;
+}
+/**
+ * Live coordinator surface: the immutable runtime {@link Plan}, ordered phase
+ * list, dense stores for state index + dirty epoch, and registration/mutation
+ * APIs used by the compositor on the hot path.
+ */
+export interface RuntimeCoordinatorShape {
+    readonly plan: Plan.IR;
+    readonly phases: readonly RuntimePhase[];
+    readonly stores: {
+        readonly stateIndex: DenseStore;
+        readonly dirtyEpoch: DenseStore;
+    };
+    reset(registrations?: readonly {
+        readonly name: string;
+        readonly states: readonly string[];
+    }[]): void;
+    registerQuantizer(name: string, states: readonly string[]): EntityId;
+    removeQuantizer(name: string): void;
+    hasQuantizer(name: string): boolean;
+    setState(name: string, state: string): void;
+    applyState(name: string, state: string): number;
+    getStateIndex(name: string): number;
+    markDirty(name: string): void;
+    getDirtyEpoch(name: string): number;
+    registeredNames(): readonly string[];
+}
+/**
+ * Build a fresh {@link RuntimeCoordinator} with dense backing stores and the
+ * canonical runtime plan. Prefer {@link RuntimeCoordinator.create}, which is
+ * the exported entry point.
+ */
+export declare function createRuntimeCoordinator(config?: RuntimeCoordinatorConfig): RuntimeCoordinatorShape;
+/**
+ * Runtime coordinator namespace — single entry point for building the shared
+ * {@link Plan} + ECS store bundle consumed by every host adapter.
+ */
+export declare const RuntimeCoordinator: {
+    /** Create a fresh coordinator. See {@link createRuntimeCoordinator}. */
+    readonly create: typeof createRuntimeCoordinator;
+};
+export declare namespace RuntimeCoordinator {
+    /** Alias for `RuntimeCoordinatorShape`. */
+    type Shape = RuntimeCoordinatorShape;
+    /** Alias for `RuntimeCoordinatorConfig`. */
+    type Config = RuntimeCoordinatorConfig;
+    /** Alias for `RuntimePhase`. */
+    type Phase = RuntimePhase;
+}
+//# sourceMappingURL=runtime-coordinator.d.ts.map

package/dist/runtime-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-coordinator.d.ts","sourceRoot":"","sources":["../src/runtime-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAQ,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;AAEzG,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;QAChC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;KACjC,CAAC;IACF,KAAK,CACH,aAAa,CAAC,EAAE,SAAS;QACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,EAAE,GACF,IAAI,CAAC;IACR,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAAC;IACrE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,eAAe,IAAI,SAAS,MAAM,EAAE,CAAC;CACtC;AAkCD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,wBAAwB,GAAG,uBAAuB,CAmHnG;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC7B,wEAAwE;;CAEhE,CAAC;AAEX,MAAM,CAAC,OAAO,WAAW,kBAAkB,CAAC;IAC1C,2CAA2C;IAC3C,KAAY,KAAK,GAAG,uBAAuB,CAAC;IAC5C,4CAA4C;IAC5C,KAAY,MAAM,GAAG,wBAAwB,CAAC;IAC9C,gCAAgC;IAChC,KAAY,KAAK,GAAG,YAAY,CAAC;CAClC"}

package/dist/runtime-coordinator.js

@@ -0,0 +1,149 @@
+/**
+ * RuntimeCoordinator -- shared host/runtime coordination surface.
+ *
+ * Bridges Plan and ECS into the live host path by:
+ * - defining the execution graph for runtime passes
+ * - backing quantizer state indices and dirty epochs with dense stores
+ *
+ * The coordinator is intentionally light-weight on the hot path: the plan is
+ * constructed once up front, and dense stores are used for numeric state that
+ * is read repeatedly during runtime work.
+ *
+ * @module
+ */
+import { Part, EntityId } from './ecs.js';
+import { Plan } from './plan.js';
+const DEFAULT_RUNTIME_CAPACITY = 128;
+function makeRuntimePlan(name) {
+    return Plan.make(name)
+        .step('compute-discrete', { type: 'noop' }, { phase: 'compute-discrete' })
+        .step('compute-blend', { type: 'noop' }, { phase: 'compute-blend' })
+        .step('emit-css', { type: 'noop' }, { phase: 'emit-css' })
+        .step('emit-glsl', { type: 'noop' }, { phase: 'emit-glsl' })
+        .step('emit-aria', { type: 'noop' }, { phase: 'emit-aria' })
+        .seq('step-1', 'step-2')
+        .par('step-2', 'step-3')
+        .par('step-2', 'step-4')
+        .par('step-2', 'step-5')
+        .build();
+}
+function orderedPhases(plan) {
+    const sorted = Plan.topoSort(plan).sorted;
+    const stepsById = new Map(plan.steps.map((step) => [step.id, step]));
+    return sorted
+        .map((id) => stepsById.get(id)?.metadata?.['phase'])
+        .filter((phase) => typeof phase === 'string');
+}
+const RUNTIME_PLAN_TEMPLATE = makeRuntimePlan('czap-runtime');
+const RUNTIME_PHASES = orderedPhases(RUNTIME_PLAN_TEMPLATE);
+/**
+ * Build a fresh {@link RuntimeCoordinator} with dense backing stores and the
+ * canonical runtime plan. Prefer {@link RuntimeCoordinator.create}, which is
+ * the exported entry point.
+ */
+export function createRuntimeCoordinator(config) {
+    const name = config?.name ?? 'czap-runtime';
+    const plan = name === RUNTIME_PLAN_TEMPLATE.name ? RUNTIME_PLAN_TEMPLATE : { ...RUNTIME_PLAN_TEMPLATE, name };
+    const phases = RUNTIME_PHASES;
+    const stateIndex = Part.dense('state-index', config?.capacity ?? DEFAULT_RUNTIME_CAPACITY);
+    const dirtyEpoch = Part.dense('dirty-epoch', config?.capacity ?? DEFAULT_RUNTIME_CAPACITY);
+    const quantizerByName = new Map();
+    let nextEntity = 0;
+    const ensureQuantizer = (name) => quantizerByName.get(name);
+    return {
+        plan,
+        phases,
+        stores: {
+            stateIndex,
+            dirtyEpoch,
+        },
+        reset(registrations) {
+            quantizerByName.clear();
+            nextEntity = 0;
+            stateIndex.reset();
+            dirtyEpoch.reset();
+            for (const registration of registrations ?? []) {
+                this.registerQuantizer(registration.name, registration.states);
+            }
+        },
+        registerQuantizer(name, states) {
+            const existing = ensureQuantizer(name);
+            if (existing) {
+                return existing.entityId;
+            }
+            const entityId = EntityId(`runtime-${++nextEntity}`);
+            const stateLookup = Object.create(null);
+            for (let index = 0; index < states.length; index++) {
+                stateLookup[states[index]] = index;
+            }
+            quantizerByName.set(name, {
+                entityId,
+                stateLookup,
+            });
+            stateIndex.set(entityId, 0);
+            dirtyEpoch.set(entityId, 1);
+            return entityId;
+        },
+        removeQuantizer(name) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return;
+            }
+            quantizerByName.delete(name);
+            stateIndex.delete(quantizer.entityId);
+            dirtyEpoch.delete(quantizer.entityId);
+        },
+        hasQuantizer(name) {
+            return quantizerByName.has(name);
+        },
+        setState(name, state) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return;
+            }
+            stateIndex.set(quantizer.entityId, quantizer.stateLookup[state] ?? 0);
+        },
+        applyState(name, state) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return 0;
+            }
+            const nextIndex = quantizer.stateLookup[state] ?? 0;
+            stateIndex.set(quantizer.entityId, nextIndex);
+            return nextIndex;
+        },
+        getStateIndex(name) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return 0;
+            }
+            return stateIndex.get(quantizer.entityId);
+        },
+        markDirty(name) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return;
+            }
+            dirtyEpoch.set(quantizer.entityId, dirtyEpoch.get(quantizer.entityId) + 1);
+        },
+        getDirtyEpoch(name) {
+            const quantizer = ensureQuantizer(name);
+            if (!quantizer) {
+                return 0;
+            }
+            return dirtyEpoch.get(quantizer.entityId);
+        },
+        registeredNames() {
+            return Array.from(quantizerByName.keys());
+        },
+    };
+}
+/**
+ * Runtime coordinator namespace — single entry point for building the shared
+ * {@link Plan} + ECS store bundle consumed by every host adapter.
+ */
+export const RuntimeCoordinator = {
+    /** Create a fresh coordinator. See {@link createRuntimeCoordinator}. */
+    create: createRuntimeCoordinator,
+};
+//# sourceMappingURL=runtime-coordinator.js.map

package/dist/runtime-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-coordinator.js","sourceRoot":"","sources":["../src/runtime-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/scheduler.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Scheduler -- clock abstraction decoupling animation from requestAnimationFrame.
+ *
+ * Four implementations:
+ *   - raf: browser real-time (default)
+ *   - noop: SSR-safe
+ *   - fixedStep: deterministic timestamps at target fps (video rendering)
+ *   - audioSync: ticks in lockstep with an AVBridge sample counter
+ *
+ * @module
+ */
+import type { AVBridge } from './av-bridge.js';
+interface SchedulerShape {
+    readonly _tag: 'FrameScheduler';
+    schedule(callback: (now: number) => void): number;
+    cancel(id: number): void;
+}
+interface FixedStepShape extends SchedulerShape {
+    step(): void;
+    readonly frame: number;
+}
+/** Default: requestAnimationFrame. Used by Timeline/animate in browser. */
+declare function _raf(): SchedulerShape;
+/** SSR-safe: noop scheduler for server environments. */
+declare function _noop(): SchedulerShape;
+declare function _fixedStep(fps: number): FixedStepShape;
+interface AudioSyncShape extends SchedulerShape {
+    poll(): void;
+    readonly frame: number;
+    readonly bridge: AVBridge.Shape;
+}
+declare function _audioSync(bridge: AVBridge.Shape): AudioSyncShape;
+/**
+ * Scheduler — clock abstraction that decouples animation driver from real time.
+ * Pick the impl that matches the runtime: `raf` in browser, `noop` on the
+ * server, `fixedStep` for deterministic video render, `audioSync` to drive UI
+ * in lockstep with an {@link AVBridge}.
+ */
+export declare const Scheduler: {
+    /** `requestAnimationFrame`-backed scheduler for browser real-time work. */
+    raf: typeof _raf;
+    /** No-op scheduler for SSR / environments without rAF. */
+    noop: typeof _noop;
+    /** Fixed-step scheduler at the given fps — deterministic timestamps for offline rendering. */
+    fixedStep: typeof _fixedStep;
+    /** Scheduler that polls an {@link AVBridge} and fires callbacks when the sample frame advances. */
+    audioSync: typeof _audioSync;
+};
+export declare namespace Scheduler {
+    /** Common structural shape every scheduler variant satisfies. */
+    type Shape = SchedulerShape;
+    /** Fixed-step scheduler with manual `step()` advancement. */
+    type FixedStep = FixedStepShape;
+    /** Audio-synchronized scheduler bound to an {@link AVBridge}. */
+    type AudioSync = AudioSyncShape;
+}
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM/C,UAAU,cAAc;IACtB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC;IAClD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,UAAU,cAAe,SAAQ,cAAc;IAC7C,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAMD,2EAA2E;AAC3E,iBAAS,IAAI,IAAI,cAAc,CAM9B;AAED,wDAAwD;AACxD,iBAAS,KAAK,IAAI,cAAc,CAM/B;AAqCD,iBAAS,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAE/C;AAMD,UAAU,cAAe,SAAQ,cAAc;IAC7C,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC;CACjC;AAED,iBAAS,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,GAAG,cAAc,CAkC1D;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS;IACpB,2EAA2E;;IAE3E,0DAA0D;;IAE1D,8FAA8F;;IAE9F,mGAAmG;;CAEpG,CAAC;AAEF,MAAM,CAAC,OAAO,WAAW,SAAS,CAAC;IACjC,iEAAiE;IACjE,KAAY,KAAK,GAAG,cAAc,CAAC;IACnC,6DAA6D;IAC7D,KAAY,SAAS,GAAG,cAAc,CAAC;IACvC,iEAAiE;IACjE,KAAY,SAAS,GAAG,cAAc,CAAC;CACxC"}