@pose_flow/babylon 0.2.0 → 0.3.0

package/dist/core/controller.d.ts

@@ -1,11 +1,24 @@
 import { PoseSearch } from './search.js';
 import type { Database, Match, Query } from './types.js';
+import type { SearchReport } from './search.js';
 export interface Playback {
     clip: number;
     time: number;
     switched: boolean;
     match: Match | null;
 }
+export interface MatcherDecision {
+    searched: boolean;
+    reason: string;
+    previousClip: number;
+    currentClip: number;
+    currentCost: number | null;
+    candidateCost: number | null;
+    sinceSwitch: number;
+    minimumHold: number;
+    jumpPenalty: number;
+    improvement: number;
+}
 export interface MatcherOptions {
     searchInterval: number;
     minimumHold: number;
@@ -13,6 +26,12 @@ export interface MatcherOptions {
     jumpPenalty: number;
     timeSeparation: number;
     reselectDelay: number;
+    /** Active only when the query explicitly requests idle alone. */
+    idleVariation?: {
+        interval: number;
+        historySize: number;
+    };
+    diagnostics?: boolean;
 }
 /** Owns animation time only. Caller retains movement and action authority. */
 export declare class MotionMatcher {
@@ -26,6 +45,13 @@ export declare class MotionMatcher {
     private last;
     private completed;
     private indices;
+    private idleElapsed;
+    private idleHistory;
+    private effectiveQuery?;
+    private decisionState;
+    /** Snapshot of the last continuity decision. Query copying requires diagnostics=true. */
+    get decision(): MatcherDecision | null;
+    inspect(limit?: number): SearchReport | null;
     constructor(database: Database, options?: Partial<MatcherOptions>);
     reset(): void;
     update(dt: number, query: Query): Playback;

package/dist/core/controller.js

@@ -1,4 +1,5 @@
 import { PoseSearch } from './search.js';
+import { withinWindows } from './selection.js';
 /** Owns animation time only. Caller retains movement and action authority. */
 export class MotionMatcher {
     database;
@@ -11,22 +12,36 @@ export class MotionMatcher {
     last = null;
     completed = new Map();
     indices;
+    idleElapsed = 0;
+    idleHistory = [];
+    effectiveQuery;
+    decisionState = null;
+    /** Snapshot of the last continuity decision. Query copying requires diagnostics=true. */
+    get decision() { return this.decisionState ? { ...this.decisionState } : null; }
+    inspect(limit = 5) { return this.options.diagnostics && this.effectiveQuery ? this.search.inspect(this.effectiveQuery, limit) : null; }
     constructor(database, options = {}) {
         this.database = database;
         this.search = new PoseSearch(database);
         this.options = { searchInterval: 0.1, minimumHold: 0.12, improvement: 0.1, jumpPenalty: 0.5, timeSeparation: 0.2, reselectDelay: 0.6, ...options };
-        if (!Object.values(this.options).every(v => Number.isFinite(v) && v >= 0) || this.options.searchInterval === 0 || this.options.improvement >= 1)
+        const { idleVariation, diagnostics, ...numeric } = this.options;
+        if (!Object.values(numeric).every(v => Number.isFinite(v) && v >= 0) || this.options.searchInterval === 0 || this.options.improvement >= 1)
             throw new Error('Invalid matcher options');
+        if (idleVariation && (!Number.isFinite(idleVariation.interval) || idleVariation.interval <= 0 || !Number.isInteger(idleVariation.historySize) || idleVariation.historySize < 1))
+            throw new Error('Invalid idle variation policy');
+        if (diagnostics !== undefined && typeof diagnostics !== 'boolean')
+            throw new Error('Invalid diagnostics option');
         this.indices = database.manifest.clips.map((_, clip) => database.manifest.frames.flatMap((f, i) => f.clip === clip ? [i] : []).sort((a, b) => database.manifest.frames[a].time - database.manifest.frames[b].time));
         if (this.indices.some(i => !i.length))
             throw new Error('Every clip must have indexed samples');
     }
-    reset() { this.clip = -1; this.time = 0; this.sinceSearch = this.sinceSwitch = Infinity; this.last = null; this.completed.clear(); }
+    reset() { this.clip = -1; this.time = 0; this.sinceSearch = this.sinceSwitch = Infinity; this.last = null; this.completed.clear(); this.idleElapsed = 0; this.idleHistory = []; this.effectiveQuery = undefined; this.decisionState = null; }
     update(dt, query) {
         if (!Number.isFinite(dt) || dt < 0)
             throw new Error('Invalid delta time');
         // Validate identity even while continuity skips a search this frame.
         this.search.validateQuery(query);
+        const previousClip = this.clip;
+        let reason = 'search-interval', searched = false, currentCost = null, candidateCost = null;
         let switched = false, ended = false;
         for (const [clip, remaining] of this.completed) {
             if (remaining <= dt)
@@ -42,15 +57,47 @@ export class MotionMatcher {
         }
         this.sinceSearch += dt;
         this.sinceSwitch += dt;
-        const allowed = this.clip >= 0 && !query.excludedClips?.has(this.clip) && (!query.gaits || query.gaits.has(this.database.manifest.clips[this.clip].gait));
+        const allowed = this.search.allowsClip(this.clip, query);
+        const idleOnly = query.gaits?.size === 1 && query.gaits.has('idle') && !!this.options.idleVariation;
+        if (idleOnly && allowed)
+            this.idleElapsed += dt;
+        else {
+            this.idleElapsed = 0;
+            this.idleHistory = [];
+        }
         if (this.sinceSearch >= this.options.searchInterval || !allowed || ended) {
+            searched = true;
             this.sinceSearch = 0;
             // A finished one-shot must yield to another clip, rather than selecting
             // its terminal pose and restarting forever. User exclusions still apply.
             if (ended)
                 this.completed.set(this.clip, this.options.reselectDelay);
             const excludedClips = new Set([...(query.excludedClips ?? []), ...this.completed.keys()]);
-            const best = this.search.search({ ...query, excludedClips });
+            let variation = false;
+            let best = null;
+            const runSearch = (effective) => {
+                // Keep the query that actually produced the candidate, including idle
+                // history/completion exclusions. Features are snapshotted for later UI.
+                if (this.options.diagnostics)
+                    this.effectiveQuery = { ...effective, features: effective.features.slice(), context: effective.context ? { ...effective.context } : undefined,
+                        gaits: effective.gaits ? new Set(effective.gaits) : undefined, excludedClips: effective.excludedClips ? new Set(effective.excludedClips) : undefined };
+                return this.search.search(effective);
+            };
+            if (idleOnly && allowed && !ended) {
+                if (this.idleElapsed >= this.options.idleVariation.interval) {
+                    // Relax oldest history first when the pool is small, but never force
+                    // a restart of the current clip or relax the consumer's context.
+                    const history = [...this.idleHistory];
+                    do {
+                        best = runSearch({ ...query, excludedClips: new Set([...excludedClips, this.clip, ...history]) });
+                    } while (!best && history.shift() !== undefined);
+                    variation = best !== null;
+                }
+                if (!best)
+                    best = runSearch({ ...query, excludedClips: new Set([...excludedClips, ...this.database.manifest.clips.flatMap((_, i) => i === this.clip ? [] : [i])]) });
+            }
+            else
+                best = runSearch({ ...query, excludedClips });
             this.last = best;
             if (best) {
                 const current = this.clip >= 0 ? this.nearestFrame(this.clip, this.time) : -1;
@@ -60,21 +107,39 @@ export class MotionMatcher {
                     gap = Math.min(gap, duration - gap);
                 const distant = best.clip !== this.clip || gap > this.options.timeSeparation;
                 const better = current < 0 || best.cost + this.options.jumpPenalty < this.search.cost(current) * (1 - this.options.improvement);
+                currentCost = current < 0 ? null : this.search.cost(current);
+                candidateCost = best.cost;
                 const incompatibleVelocity = current >= 0 && distant && this.sinceSwitch >= this.options.minimumHold && query.velocityTolerance !== undefined
                     && this.search.rootVelocityError(current, query) > Math.max(query.velocityTolerance, this.search.rootVelocityError(best.index, query) + 1e-6);
                 const mayReselectTime = query.allowTemporalReselection !== false || best.clip !== this.clip || !this.database.manifest.clips[best.clip].looping;
-                if (current < 0 || !allowed || ended || (mayReselectTime && (incompatibleVelocity || (distant && better && this.sinceSwitch >= this.options.minimumHold)))) {
+                const mayExit = this.clip < 0 || withinWindows(this.time, this.database.manifest.clips[this.clip].exitWindows);
+                const shouldSwitch = current < 0 || !allowed || ended || (mayExit && mayReselectTime && (incompatibleVelocity || (distant && (better || variation) && this.sinceSwitch >= this.options.minimumHold)));
+                reason = current < 0 ? 'initial' : !allowed ? 'incompatible-current' : ended ? 'clip-ended' : !mayExit ? 'exit-window' : !mayReselectTime ? 'phase-preserved'
+                    : incompatibleVelocity ? 'velocity-incompatible' : !distant ? 'nearby-candidate' : this.sinceSwitch < this.options.minimumHold ? 'minimum-hold' : variation ? 'idle-variation' : better ? 'better-candidate' : 'insufficient-improvement';
+                if (shouldSwitch) {
                     this.clip = best.clip;
                     this.time = best.time;
                     this.sinceSwitch = 0;
                     switched = true;
+                    this.idleElapsed = 0;
+                    if (this.database.manifest.clips[this.clip].gait === 'idle') {
+                        this.idleHistory.push(this.clip);
+                        this.idleHistory = this.idleHistory.slice(-(this.options.idleVariation?.historySize ?? 1));
+                    }
+                    else
+                        this.idleHistory = [];
                 }
             }
-            else if (!allowed || ended) {
-                this.clip = -1;
-                this.time = 0;
+            else {
+                reason = !allowed || ended ? 'no-candidate-cleared' : 'no-entry-continue';
+                if (!allowed || ended) {
+                    this.clip = -1;
+                    this.time = 0;
+                }
             }
         }
+        this.decisionState = { searched, reason, previousClip, currentClip: this.clip, currentCost, candidateCost, sinceSwitch: this.sinceSwitch,
+            minimumHold: this.options.minimumHold, improvement: this.options.improvement, jumpPenalty: this.options.jumpPenalty };
         return { clip: this.clip, time: this.time, switched, match: this.last };
     }
     nearestFrame(clip, time) {

package/dist/core/database.js

@@ -1,5 +1,6 @@
 import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
 import { parseRootOrientation } from './profile.js';
+import { validateSelection } from './selection.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 export function validateDatabase(db) {
     const m = db?.manifest;
@@ -30,6 +31,7 @@ export function validateDatabase(db) {
             || !['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(clip.gait))
             throw new Error('Invalid clip');
         ids.add(clip.id);
+        validateSelection(clip, clip.duration);
         if (clip.sourceStart !== undefined && (!Number.isFinite(clip.sourceStart) || clip.sourceStart < 0))
             throw new Error('Invalid source start');
         if (clip.averageVelocity !== undefined && (!Array.isArray(clip.averageVelocity) || clip.averageVelocity.length !== 3 || !clip.averageVelocity.every(Number.isFinite)))

package/dist/core/inertialization.d.ts

@@ -0,0 +1,3 @@
+/** Critically damped residual. With zero initial velocity, offset halves at halfLife.
+ * Does not integrate gameplay/root displacement. */
+export declare function decayInertialOffset(offset: number, velocity: number, elapsed: number, halfLife: number): number;

package/dist/core/inertialization.js

@@ -0,0 +1,15 @@
+/** Critically damped residual. With zero initial velocity, offset halves at halfLife.
+ * Does not integrate gameplay/root displacement. */
+export function decayInertialOffset(offset, velocity, elapsed, halfLife) {
+    if (![offset, velocity, elapsed, halfLife].every(Number.isFinite) || elapsed < 0 || halfLife <= 0)
+        throw new Error('Invalid inertial residual');
+    if (elapsed === 0)
+        return offset;
+    const exponent = (1.67834699001666 / halfLife) * elapsed;
+    if (exponent > 745)
+        return 0;
+    const decay = Math.exp(-exponent);
+    // Reassociate products: avoid Infinity * 0 after a long pause, and avoid
+    // overflowing omega*offset while the final damped value is representable.
+    return offset * ((1 + exponent) * decay) + velocity * (elapsed * decay);
+}

package/dist/core/profile.d.ts

@@ -1,5 +1,6 @@
 import type { Gait, Quat, Vec3 } from './types.js';
 import { type PoseSchema } from './schema.js';
+import { type SelectionMetadata, type SelectionContext } from './selection.js';
 export interface CharacterProfile {
     version: 2;
     id: string;
@@ -18,11 +19,19 @@ export interface CharacterProfile {
     boneMap?: Record<string, string>;
     /** Model node whose position/heading tracks are excluded by the player. */
     stripRoot?: string;
+    /** Exact model node names for optional runtime layers. */
+    masks?: Record<string, readonly string[]>;
+    /** Lab-only presentation preview. Does not authorize a gameplay action. */
+    layerPreview?: {
+        baseMask: string;
+        overlayMask: string;
+        context: SelectionContext;
+    };
 }
 export interface AnimationSet {
     version: 1;
     id: string;
-    clips: {
+    clips: (SelectionMetadata & {
         id: string;
         file: string;
         animation: string;
@@ -33,7 +42,7 @@ export interface AnimationSet {
         rootOrientation?: Quat;
         /** Source interval in seconds. */
         range?: readonly [number, number];
-    }[];
+    })[];
 }
 export interface ResolvedProfile extends CharacterProfile {
     schemaDefinition: PoseSchema;

package/dist/core/profile.js

@@ -1,4 +1,5 @@
 import { compileSchema, parseSchema } from './schema.js';
+import { validateContext, validateSelection } from './selection.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const name = (v) => typeof v === 'string' && v.trim().length > 0;
 const asset = (v) => name(v) && !v.includes('\\') && !v.includes('..') && !/[?#:]/.test(v);
@@ -25,6 +26,18 @@ export function parseProfile(input) {
         throw new Error('Profile: required bones must be distinct');
     if (input.stripRoot !== undefined && !name(input.stripRoot))
         throw new Error('Profile: invalid stripRoot');
+    if (input.masks !== undefined && (!record(input.masks) || !Object.entries(input.masks).length || !Object.entries(input.masks).every(([key, values]) => name(key)
+        && Array.isArray(values) && values.length > 0 && values.every(name) && new Set(values).size === values.length)))
+        throw new Error('Profile: invalid masks');
+    if (input.layerPreview !== undefined) {
+        const preview = input.layerPreview, masks = input.masks;
+        if (!record(preview) || !name(preview.baseMask) || !name(preview.overlayMask) || !masks || !Object.hasOwn(masks, preview.baseMask) || !Object.hasOwn(masks, preview.overlayMask)
+            || masks[preview.baseMask].some(node => masks[preview.overlayMask].includes(node)))
+            throw new Error('Profile: layer preview requires two disjoint masks');
+        validateContext(preview.context);
+        if (!Object.keys(preview.context).length)
+            throw new Error('Profile: layer preview requires explicit context');
+    }
     if (input.boneMap !== undefined && (!record(input.boneMap) || !Object.entries(input.boneMap).every(([k, v]) => name(k) && name(v)) || new Set(Object.values(input.boneMap)).size !== Object.values(input.boneMap).length))
         throw new Error('Profile: boneMap must map distinct nonempty names');
     return structuredClone(input);
@@ -42,6 +55,7 @@ export function parseAnimationSet(input) {
             parseRootOrientation(clip.rootOrientation);
         if (clip.range !== undefined && (!Array.isArray(clip.range) || clip.range.length !== 2 || !clip.range.every(Number.isFinite) || clip.range[0] < 0 || clip.range[1] <= clip.range[0]))
             throw new Error('Invalid clip range');
+        validateSelection(clip, Array.isArray(clip.range) ? clip.range[1] - clip.range[0] : Infinity);
         const nominal = clip.nominalVelocity !== undefined, measured = clip.motionFile !== undefined;
         if (nominal === measured)
             throw new Error(`Profile ${clip.id}: declare exactly one of nominalVelocity or motionFile`);

package/dist/core/scenario.d.ts

@@ -0,0 +1,29 @@
+import { type MatcherOptions, type Playback } from './controller.js';
+import type { Database, Gait, Query, Vec3 } from './types.js';
+export interface RecordedQuery extends Omit<Query, 'features' | 'gaits' | 'excludedClips'> {
+    features: number[];
+    gaits?: Gait[];
+    excludedClips?: number[];
+}
+export interface ScenarioFrame {
+    dt: number;
+    query: RecordedQuery;
+    controller: {
+        position: Vec3;
+        yaw: number;
+    };
+    playback: Omit<Playback, 'match'>;
+    presentation?: Omit<Playback, 'match'>;
+}
+export interface MotionScenario {
+    version: 1;
+    databaseIdentity: string;
+    matcherOptions: Partial<MatcherOptions>;
+    frames: ScenarioFrame[];
+}
+/** Content identity for exact replay, not a cryptographic/security signature. */
+export declare function scenarioDatabaseIdentity(db: Database): string;
+export declare function restoreScenarioQuery(recorded: RecordedQuery): Query;
+export declare function captureScenarioFrame(dt: number, query: Query, position: Vec3, yaw: number, playback: Playback, presentation?: Playback): ScenarioFrame;
+/** Import only validated local data, never execute content from a scenario file. */
+export declare function parseMotionScenario(input: unknown, db: Database): MotionScenario;

package/dist/core/scenario.js

@@ -0,0 +1,57 @@
+import { encodeFeatures } from './database.js';
+import { MotionMatcher } from './controller.js';
+import { PoseSearch } from './search.js';
+/** Content identity for exact replay, not a cryptographic/security signature. */
+export function scenarioDatabaseIdentity(db) {
+    let hash = 2166136261;
+    for (const char of JSON.stringify(db.manifest))
+        hash = Math.imul(hash ^ char.charCodeAt(0), 16777619);
+    for (const byte of new Uint8Array(encodeFeatures(db)))
+        hash = Math.imul(hash ^ byte, 16777619);
+    return 'scenario-db-v1:' + (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function restoreScenarioQuery(recorded) {
+    return { ...recorded, features: Float32Array.from(recorded.features), gaits: recorded.gaits ? new Set(recorded.gaits) : undefined,
+        excludedClips: recorded.excludedClips ? new Set(recorded.excludedClips) : undefined };
+}
+export function captureScenarioFrame(dt, query, position, yaw, playback, presentation) {
+    return { dt, query: { ...query, features: [...query.features], ...(query.context ? { context: { ...query.context } } : {}),
+            gaits: query.gaits ? [...query.gaits] : undefined, excludedClips: query.excludedClips ? [...query.excludedClips] : undefined },
+        controller: { position: [...position], yaw }, playback: { clip: playback.clip, time: playback.time, switched: playback.switched },
+        ...(presentation ? { presentation: { clip: presentation.clip, time: presentation.time, switched: presentation.switched } } : {}) };
+}
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** Import only validated local data, never execute content from a scenario file. */
+export function parseMotionScenario(input, db) {
+    if (!record(input) || input.version !== 1 || input.databaseIdentity !== scenarioDatabaseIdentity(db) || !Array.isArray(input.frames)
+        || !input.frames.length || input.frames.length > 6000 || input.frames.length * db.manifest.dimensions > 2_000_000 || !record(input.matcherOptions))
+        throw new Error('Invalid/incompatible motion scenario');
+    const options = input.matcherOptions;
+    if (Object.keys(options).some(k => !['searchInterval', 'minimumHold', 'improvement', 'jumpPenalty', 'timeSeparation', 'reselectDelay', 'idleVariation', 'diagnostics'].includes(k)))
+        throw new Error('Invalid scenario matcher options');
+    new MotionMatcher(db, options);
+    const search = new PoseSearch(db);
+    for (const frame of input.frames) {
+        if (!record(frame) || typeof frame.dt !== 'number' || !Number.isFinite(frame.dt) || frame.dt < 0 || frame.dt > 10 || !record(frame.query)
+            || !record(frame.controller) || !record(frame.playback))
+            throw new Error('Invalid scenario frame');
+        const q = frame.query, p = frame.playback, controller = frame.controller;
+        if (Object.keys(q).some(k => !['features', 'schemaSignature', 'gaits', 'excludedClips', 'velocityTolerance', 'allowTemporalReselection', 'context'].includes(k))
+            || !Array.isArray(q.features) || q.features.length !== db.manifest.dimensions || !q.features.every(Number.isFinite)
+            || (q.gaits !== undefined && (!Array.isArray(q.gaits) || !q.gaits.every(g => ['idle', 'walk', 'run', 'strafe', 'turn', 'stop'].includes(g))))
+            || (q.excludedClips !== undefined && (!Array.isArray(q.excludedClips) || !q.excludedClips.every(c => Number.isInteger(c) && c >= 0 && c < db.manifest.clips.length))))
+            throw new Error('Invalid scenario query');
+        search.validateQuery(restoreScenarioQuery(q));
+        if (!Array.isArray(controller.position) || controller.position.length !== 3 || !controller.position.every(Number.isFinite) || typeof controller.yaw !== 'number' || !Number.isFinite(controller.yaw)
+            || !Number.isInteger(p.clip) || p.clip < -1 || p.clip >= db.manifest.clips.length || typeof p.time !== 'number' || !Number.isFinite(p.time) || p.time < 0
+            || (p.clip >= 0 && p.time > db.manifest.clips[p.clip].duration + 1e-6) || typeof p.switched !== 'boolean')
+            throw new Error('Invalid scenario playback/controller');
+        if (frame.presentation !== undefined) {
+            const p = frame.presentation;
+            if (!record(p) || !Number.isInteger(p.clip) || p.clip < -1 || p.clip >= db.manifest.clips.length || typeof p.time !== 'number' || !Number.isFinite(p.time) || p.time < 0
+                || (p.clip >= 0 && p.time > db.manifest.clips[p.clip].duration + 1e-6) || typeof p.switched !== 'boolean')
+                throw new Error('Invalid scenario presentation');
+        }
+    }
+    return structuredClone(input);
+}

package/dist/core/search.d.ts

@@ -1,6 +1,33 @@
 import { type Database, type Match, type Query } from './types.js';
 import { type PoseSchema } from './schema.js';
 export declare function defaultWeights(schema?: PoseSchema): Float32Array;
+export type RejectionReason = 'excluded-clip' | 'gait' | 'context' | 'entry-window' | 'excluded-window' | 'velocity';
+export interface CandidateCost extends Match {
+    channels: {
+        id: string;
+        cost: number;
+    }[];
+    velocityError: number | null;
+}
+export interface SearchReport {
+    best: Match | null;
+    candidates: CandidateCost[];
+    rejected: Record<RejectionReason, number>;
+    examples: {
+        index: number;
+        clip: number;
+        time: number;
+        reason: RejectionReason;
+    }[];
+    eligible: number;
+    total: number;
+    velocityLimit: number | null;
+}
+export declare function readCandidateTrajectory(database: Database, index: number): {
+    horizon: number;
+    position?: readonly [number, number];
+    facing?: readonly [number, number];
+}[];
 export declare class PoseSearch {
     readonly database: Database;
     private normalized;
@@ -9,9 +36,14 @@ export declare class PoseSearch {
     readonly weights: Float32Array;
     constructor(database: Database, weights?: Float32Array);
     validateQuery(query: Query): void;
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip: number, query: Query): boolean;
+    allowsFrame(index: number, query: Query): boolean;
     normalize(query: Query): void;
     cost(index: number): number;
     /** Physical error, independent of normalization/pose weights. Query must have been validated. */
     rootVelocityError(index: number, query: Query): number;
     search(query: Query): Match | null;
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query: Query, limit?: number): SearchReport;
 }

package/dist/core/search.js

@@ -1,5 +1,6 @@
 import { validateDatabase } from './database.js';
 import { compileSchema, LOCOMOTION_SCHEMA } from './schema.js';
+import { matchesContext, validateContext, withinWindows } from './selection.js';
 export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
     const layout = compileSchema(schema), weights = new Float32Array(layout.dimensions);
     for (const { channel, offset, dimensions } of layout.channels)
@@ -9,6 +10,20 @@ export function defaultWeights(schema = LOCOMOTION_SCHEMA) {
     return weights;
 }
 const legacySignature = compileSchema(LOCOMOTION_SCHEMA).signature;
+export function readCandidateTrajectory(database, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= database.manifest.frames.length)
+        throw new Error('Invalid candidate frame');
+    const { dimensions, mean, std } = database.manifest, layout = compileSchema(database.manifest.schema);
+    const points = new Map(layout.horizons.map(horizon => [horizon, { horizon }]));
+    for (const { channel, offset } of layout.channels)
+        if (channel.kind === 'trajectory-position' || channel.kind === 'trajectory-facing') {
+            channel.horizons.forEach((horizon, h) => {
+                const j = offset + h * 2, value = [database.features[index * dimensions + j] * std[j] + mean[j], database.features[index * dimensions + j + 1] * std[j + 1] + mean[j + 1]];
+                points.get(horizon)[channel.kind === 'trajectory-position' ? 'position' : 'facing'] = value;
+            });
+        }
+    return [...points.values()];
+}
 export class PoseSearch {
     database;
     normalized;
@@ -27,6 +42,8 @@ export class PoseSearch {
         this.weights = weights.slice();
     }
     validateQuery(query) {
+        if (query.context !== undefined)
+            validateContext(query.context);
         if (query.schemaSignature !== this.database.manifest.schemaSignature && !(query.schemaSignature === undefined && this.database.manifest.schemaSignature === legacySignature))
             throw new Error('Incompatible query schema');
         if (query.features.length !== this.dimensions || !query.features.every(Number.isFinite))
@@ -36,6 +53,16 @@ export class PoseSearch {
         if (query.velocityTolerance !== undefined && (!Number.isFinite(query.velocityTolerance) || query.velocityTolerance < 0 || this.rootOffset === undefined))
             throw new Error('Velocity tolerance requires a root-velocity channel and a finite nonnegative value');
     }
+    /** Context/gait validity is separate from eligibility to enter at a sample. */
+    allowsClip(clip, query) {
+        const descriptor = this.database.manifest.clips[clip];
+        return !!descriptor && !query.excludedClips?.has(clip) && (!query.gaits || query.gaits.has(descriptor.gait)) && (!query.context || matchesContext(descriptor.context, query.context));
+    }
+    allowsFrame(index, query) {
+        const frame = this.database.manifest.frames[index], clip = this.database.manifest.clips[frame.clip];
+        return this.allowsClip(frame.clip, query) && withinWindows(frame.time, clip.entryWindows)
+            && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows));
+    }
     normalize(query) {
         this.validateQuery(query);
         const { mean, std } = this.database.manifest;
@@ -66,24 +93,28 @@ export class PoseSearch {
     search(query) {
         this.normalize(query);
         const { frames, clips } = this.database.manifest;
+        // Context is clip-level: resolve it once per clip, rather than once per
+        // sample in each of the velocity and ranking passes.
+        const eligibleClips = clips.map((_, clip) => this.allowsClip(clip, query));
+        const candidates = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i], clip = clips[frame.clip];
+            if (eligibleClips[frame.clip] && withinWindows(frame.time, clip.entryWindows)
+                && (clip.excludedWindows === undefined || !withinWindows(frame.time, clip.excludedWindows)))
+                candidates.push(i);
+        }
         let index = -1, cost = Infinity;
         let velocityLimit = Infinity;
         if (query.velocityTolerance !== undefined) {
             let nearest = Infinity;
-            for (let i = 0; i < frames.length; i++) {
-                if (query.excludedClips?.has(frames[i].clip) || (query.gaits && !query.gaits.has(clips[frames[i].clip].gait)))
-                    continue;
+            for (const i of candidates) {
                 nearest = Math.min(nearest, this.rootVelocityError(i, query));
             }
             // Sparse datasets retain a deterministic nearest-velocity fallback. Never
             // expand the pool to arbitrary stationary poses just because coverage is missing.
             velocityLimit = Math.max(query.velocityTolerance, nearest + 1e-6);
         }
-        for (let i = 0; i < frames.length; i++) {
-            if (query.excludedClips?.has(frames[i].clip))
-                continue;
-            if (query.gaits && !query.gaits.has(clips[frames[i].clip].gait))
-                continue;
+        for (const i of candidates) {
             if (query.velocityTolerance !== undefined && this.rootVelocityError(i, query) > velocityLimit)
                 continue;
             const score = this.cost(i);
@@ -94,4 +125,57 @@ export class PoseSearch {
         }
         return index < 0 ? null : { ...frames[index], index, cost };
     }
+    /** Opt-in diagnostic pass. Bounded output, exact ranking, no change to filters/weights. */
+    inspect(query, limit = 5) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+            throw new Error('Invalid diagnostic limit');
+        const best = this.search(query), { frames, clips } = this.database.manifest;
+        const rejected = { 'excluded-clip': 0, gait: 0, context: 0, 'entry-window': 0, 'excluded-window': 0, velocity: 0 };
+        const examples = [], candidates = [];
+        const layout = compileSchema(this.database.manifest.schema);
+        let nearest = Infinity, eligible = 0;
+        if (query.velocityTolerance !== undefined)
+            for (let i = 0; i < frames.length; i++)
+                if (this.allowsFrame(i, query))
+                    nearest = Math.min(nearest, this.rootVelocityError(i, query));
+        const velocityLimit = query.velocityTolerance === undefined ? null : Math.max(query.velocityTolerance, nearest + 1e-6);
+        for (let index = 0; index < frames.length; index++) {
+            const frame = frames[index], clip = clips[frame.clip];
+            let reason;
+            if (query.excludedClips?.has(frame.clip))
+                reason = 'excluded-clip';
+            else if (query.gaits && !query.gaits.has(clip.gait))
+                reason = 'gait';
+            else if (!matchesContext(clip.context, query.context))
+                reason = 'context';
+            else if (!withinWindows(frame.time, clip.entryWindows))
+                reason = 'entry-window';
+            else if (clip.excludedWindows !== undefined && withinWindows(frame.time, clip.excludedWindows))
+                reason = 'excluded-window';
+            else if (velocityLimit !== null && this.rootVelocityError(index, query) > velocityLimit)
+                reason = 'velocity';
+            if (reason) {
+                rejected[reason]++;
+                if (examples.length < limit)
+                    examples.push({ index, ...frame, reason });
+                continue;
+            }
+            eligible++;
+            const cost = this.cost(index);
+            if (candidates.length >= limit && cost >= candidates[candidates.length - 1].cost)
+                continue;
+            const channels = layout.channels.map(({ channel, offset, dimensions }) => {
+                let cost = 0;
+                for (let j = offset; j < offset + dimensions; j++)
+                    cost += this.weights[j] * (this.normalized[j] - this.database.features[index * this.dimensions + j]) ** 2;
+                return { id: channel.id, cost };
+            });
+            const candidate = { index, ...frame, cost, channels, velocityError: this.rootOffset === undefined ? null : this.rootVelocityError(index, query) };
+            const at = candidates.findIndex(c => c.cost > cost);
+            candidates.splice(at < 0 ? candidates.length : at, 0, candidate);
+            if (candidates.length > limit)
+                candidates.pop();
+        }
+        return { best, candidates, rejected, examples, eligible, total: frames.length, velocityLimit: Number.isFinite(velocityLimit) ? velocityLimit : null };
+    }
 }

package/dist/core/selection.d.ts

@@ -0,0 +1,24 @@
+/** Exact, consumer-defined semantic values. Missing keys never act as wildcards. */
+export type SelectionContext = Readonly<Record<string, string>>;
+/** Closed intervals, in seconds relative to the cropped playback clip. */
+export type TimeWindow = readonly [number, number];
+export interface SelectionMetadata {
+    context?: SelectionContext;
+    entryWindows?: readonly TimeWindow[];
+    exitWindows?: readonly TimeWindow[];
+    excludedWindows?: readonly TimeWindow[];
+}
+export declare function validateContext(value: unknown): asserts value is SelectionContext;
+export declare function matchesContext(metadata: SelectionContext | undefined, requested?: SelectionContext): boolean;
+export declare function withinWindows(time: number, windows: readonly TimeWindow[] | undefined): boolean;
+export declare function validateSelection(value: SelectionMetadata, duration?: number): void;
+import type { Database } from './types.js';
+export interface ContextBank {
+    id: string;
+    context: SelectionContext;
+    database: Database;
+}
+/** Route before searching; costs from independent normalizations are never compared.
+ * Caller must use the selected bank's schema, compatible rig/player and matcher.
+ */
+export declare function selectContextBank(banks: readonly ContextBank[], context: SelectionContext): ContextBank | null;

package/dist/core/selection.js

@@ -0,0 +1,41 @@
+export function validateContext(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || !Object.entries(value).every(([k, v]) => k.trim().length > 0 && typeof v === 'string' && v.trim().length > 0))
+        throw new Error('Invalid selection context');
+}
+export function matchesContext(metadata, requested = {}) {
+    return Object.entries(requested).every(([key, value]) => metadata !== undefined && Object.hasOwn(metadata, key) && metadata[key] === value);
+}
+export function withinWindows(time, windows) {
+    return windows === undefined || windows.some(([start, end]) => time >= start && time <= end);
+}
+export function validateSelection(value, duration = Infinity) {
+    if (value.context !== undefined)
+        validateContext(value.context);
+    for (const key of ['entryWindows', 'exitWindows', 'excludedWindows']) {
+        const windows = value[key];
+        if (windows !== undefined && (!Array.isArray(windows) || !windows.every(w => Array.isArray(w) && w.length === 2 && w.every(Number.isFinite)
+            && w[0] >= 0 && w[1] >= w[0] && w[1] <= duration)))
+            throw new Error('Invalid selection windows: ' + key);
+    }
+}
+/** Route before searching; costs from independent normalizations are never compared.
+ * Caller must use the selected bank's schema, compatible rig/player and matcher.
+ */
+export function selectContextBank(banks, context) {
+    validateContext(context);
+    const ids = new Set();
+    let selected = null;
+    for (const bank of banks) {
+        if (!bank.id.trim() || ids.has(bank.id))
+            throw new Error('Invalid/duplicate context bank id');
+        ids.add(bank.id);
+        validateContext(bank.context);
+        if (!matchesContext(bank.context, context))
+            continue;
+        if (selected)
+            throw new Error('Ambiguous context bank selection');
+        selected = bank;
+    }
+    return selected;
+}