@jgengine/core 0.9.0 → 0.11.0

package/dist/work/jobQueue.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Generic timed work queue — a pure-data model for discrete jobs that reserve
+ * inputs, advance over game time, can be paused/cancelled, and emit an output on
+ * completion. It backs unit training, crafting jobs, construction, research,
+ * respawns, downloads, and fabrication without any of them re-implementing the
+ * reservation → progress → completion → output-routing loop.
+ *
+ * The state ({@link WorkQueueState}) is plain serializable data; all policy —
+ * duration, ordering, capacity, concurrency, input reservation, refund, and
+ * output mapping — lives in {@link WorkQueueConfig}, which is supplied by the
+ * caller and is never serialized. Side effects (charging a wallet, spawning an
+ * entity) are the caller's: reservations and refunds are returned as data, and
+ * completion emits a typed event carrying a pure output payload for an external
+ * completion adapter to route.
+ */
+export type JobId = string;
+/** Lifecycle phase of a single queued job. Terminal jobs are removed from state. */
+export type JobStatus = "queued" | "active" | "paused";
+/** One unit of timed work. Plain serializable data (given serializable `TSpec`/`TReserve`). */
+export interface Job<TSpec, TReserve = undefined> {
+    /** Stable id, unique within the queue for its lifetime. */
+    readonly id: JobId;
+    /** Caller-owned description of the work (e.g. `{ unitId }`). */
+    readonly spec: TSpec;
+    /** Reserved inputs computed at enqueue time (e.g. resource cost, population). */
+    readonly reservation: TReserve;
+    readonly status: JobStatus;
+    /** Seconds of work the job requires. */
+    readonly duration: number;
+    /** Seconds of work completed so far (0…duration). */
+    readonly elapsed: number;
+    /** Higher runs sooner under priority ordering; FIFO within equal priority. */
+    readonly priority: number;
+    /** Monotonic enqueue index — the FIFO tiebreak. */
+    readonly seq: number;
+}
+/** Serializable queue state. Holds only non-terminal jobs, so it stays bounded. */
+export interface WorkQueueState<TSpec, TReserve = undefined> {
+    readonly jobs: readonly Job<TSpec, TReserve>[];
+    readonly nextId: number;
+    readonly seq: number;
+}
+/** Comparator over jobs; negative means the first job runs sooner. */
+export type JobOrdering<TSpec, TReserve = undefined> = (a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>) => number;
+/** Result of pre-enqueue validation (population caps, prerequisites, affordability). */
+export interface JobValidation {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/** Optional per-enqueue overrides. */
+export interface EnqueueOptions {
+    /** Higher runs sooner under priority ordering. Defaults to 0. */
+    readonly priority?: number;
+    /** Explicit id; defaults to a queue-assigned `job-<n>`. */
+    readonly id?: string;
+}
+/**
+ * Injected policy for a queue. Never serialized — pass the same config to every
+ * {@link enqueue}/{@link tick}/{@link cancelJob} call for a given queue.
+ */
+export interface WorkQueueConfig<TSpec, TReserve = undefined, TOutput = undefined> {
+    /** Seconds of work a spec requires. Negative values clamp to 0 (instant). */
+    duration: (spec: TSpec) => number;
+    /** Max concurrent active jobs (multi-server queue). Defaults to 1. */
+    concurrency?: number;
+    /** Max non-terminal jobs; further enqueues are rejected with `"capacity"`. */
+    capacity?: number;
+    /** Selection order for queued jobs. Defaults to {@link priorityOrdering}. */
+    ordering?: JobOrdering<TSpec, TReserve>;
+    /** Compute the reservation stored on the job (charge-now is the caller's job). */
+    reserve?: (spec: TSpec) => TReserve;
+    /** Validate before enqueue; a non-ok result rejects with its reason. */
+    validate?: (spec: TSpec, state: WorkQueueState<TSpec, TReserve>) => JobValidation;
+    /** Map a completed job to its output payload for a completion adapter to route. */
+    output?: (job: Job<TSpec, TReserve>) => TOutput;
+    /** Compute a refund on cancellation from the reservation and progress (0…1). */
+    refund?: (job: Job<TSpec, TReserve>, progress: number) => TReserve | null;
+}
+/** Typed lifecycle event emitted from {@link tick}. */
+export type WorkQueueEvent<TSpec, TReserve = undefined, TOutput = undefined> = {
+    readonly type: "started";
+    readonly job: Job<TSpec, TReserve>;
+} | {
+    readonly type: "completed";
+    readonly job: Job<TSpec, TReserve>;
+    readonly output: TOutput;
+};
+/** Outcome of {@link tick}: advanced state plus the events produced. */
+export interface TickResult<TSpec, TReserve = undefined, TOutput = undefined> {
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly events: readonly WorkQueueEvent<TSpec, TReserve, TOutput>[];
+}
+/** Outcome of {@link enqueue}. On rejection the state is returned unchanged. */
+export type EnqueueResult<TSpec, TReserve = undefined> = {
+    readonly ok: true;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly job: Job<TSpec, TReserve>;
+} | {
+    readonly ok: false;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly reason: string;
+};
+/** Outcome of {@link cancelJob}, carrying the removed job and its computed refund. */
+export type CancelResult<TSpec, TReserve = undefined> = {
+    readonly ok: true;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly job: Job<TSpec, TReserve>;
+    readonly refund: TReserve | null;
+} | {
+    readonly ok: false;
+    readonly state: WorkQueueState<TSpec, TReserve>;
+    readonly reason: string;
+};
+/**
+ * Pure FIFO ordering by enqueue sequence.
+ *
+ * @capability work-order-fifo order queued jobs by enqueue sequence
+ */
+export declare function fifoOrdering<TSpec, TReserve = undefined>(a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>): number;
+/**
+ * Priority-first ordering (higher priority sooner), FIFO within equal priority.
+ *
+ * @capability work-order-priority order queued jobs by priority, then FIFO within equal priority
+ */
+export declare function priorityOrdering<TSpec, TReserve = undefined>(a: Job<TSpec, TReserve>, b: Job<TSpec, TReserve>): number;
+/**
+ * Create an empty timed work queue.
+ *
+ * @capability work-queue a serializable timed job queue with reservation, cancellation, completion, and output routing
+ */
+export declare function createWorkQueue<TSpec, TReserve = undefined>(): WorkQueueState<TSpec, TReserve>;
+/**
+ * Non-terminal job count (queued + active + paused).
+ *
+ * @capability work-queue-size count non-terminal jobs in a work queue
+ */
+export declare function queueSize<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>): number;
+/**
+ * Look up a job by id, or `null` if absent/terminal.
+ *
+ * @capability work-job-by-id look up a queued job by id
+ */
+export declare function jobById<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): Job<TSpec, TReserve> | null;
+/**
+ * Jobs waiting for a slot, in selection order.
+ *
+ * @capability work-queued-jobs list jobs waiting for a slot, in selection order
+ */
+export declare function queuedJobs<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, ordering?: JobOrdering<TSpec, TReserve>): Job<TSpec, TReserve>[];
+/**
+ * Jobs currently progressing.
+ *
+ * @capability work-active-jobs list jobs currently progressing in a work queue
+ */
+export declare function activeJobs<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>): Job<TSpec, TReserve>[];
+/**
+ * Fractional progress of a job (0…1); a zero-duration job reads as complete.
+ *
+ * @capability work-job-progress compute a job's fractional progress
+ */
+export declare function jobProgress<TSpec, TReserve>(job: Job<TSpec, TReserve>): number;
+/**
+ * Enqueue a new job. Validates capacity and the injected `validate` policy, then
+ * computes and stores the reservation. Charging the reservation (now or later) is
+ * the caller's responsibility using {@link EnqueueResult.job}'s `reservation`.
+ *
+ * @capability enqueue-work reserve inputs and add a timed job, honoring capacity and validation policy
+ */
+export declare function enqueue<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, spec: TSpec, options?: EnqueueOptions): EnqueueResult<TSpec, TReserve>;
+/**
+ * Cancel a job and compute its refund. Removes the job from the queue and returns
+ * a refund payload (full reservation by default, or `config.refund` applied to the
+ * job's progress for partial/no refund). Applying the refund is the caller's job.
+ *
+ * @capability cancel-work remove a job and compute its refund from reservation and progress
+ */
+export declare function cancelJob<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, id: JobId): CancelResult<TSpec, TReserve>;
+/**
+ * Pause a queued or active job in place; a paused job keeps its progress and yields its slot.
+ *
+ * @capability pause-work pause a queued or active job in place, retaining its progress
+ */
+export declare function pauseJob<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): WorkQueueState<TSpec, TReserve>;
+/**
+ * Resume a paused job; it re-enters the queue and competes for a slot by ordering.
+ *
+ * @capability resume-work resume a paused job back into the queue's slot competition
+ */
+export declare function resumeJob<TSpec, TReserve>(state: WorkQueueState<TSpec, TReserve>, id: JobId): WorkQueueState<TSpec, TReserve>;
+/**
+ * Advance the queue by `dt` seconds. Promotes queued jobs into up to `concurrency`
+ * active slots, advances active jobs, and completes those that reach their
+ * duration — emitting `started`/`completed` events in deterministic order. A large
+ * `dt` catches up across many jobs in one call: when a job completes with leftover
+ * time, the freed slot promotes the next queued job and applies the remainder, so a
+ * reconnect or save/load gap resolves in a single bounded pass. Completed jobs are
+ * removed from the returned state.
+ *
+ * @capability tick-work advance jobs over time, completing work and emitting typed lifecycle events
+ */
+export declare function tick<TSpec, TReserve, TOutput>(state: WorkQueueState<TSpec, TReserve>, config: WorkQueueConfig<TSpec, TReserve, TOutput>, dt: number): TickResult<TSpec, TReserve, TOutput>;

package/dist/work/jobQueue.js

@@ -0,0 +1,253 @@
+/**
+ * Generic timed work queue — a pure-data model for discrete jobs that reserve
+ * inputs, advance over game time, can be paused/cancelled, and emit an output on
+ * completion. It backs unit training, crafting jobs, construction, research,
+ * respawns, downloads, and fabrication without any of them re-implementing the
+ * reservation → progress → completion → output-routing loop.
+ *
+ * The state ({@link WorkQueueState}) is plain serializable data; all policy —
+ * duration, ordering, capacity, concurrency, input reservation, refund, and
+ * output mapping — lives in {@link WorkQueueConfig}, which is supplied by the
+ * caller and is never serialized. Side effects (charging a wallet, spawning an
+ * entity) are the caller's: reservations and refunds are returned as data, and
+ * completion emits a typed event carrying a pure output payload for an external
+ * completion adapter to route.
+ */
+/**
+ * Pure FIFO ordering by enqueue sequence.
+ *
+ * @capability work-order-fifo order queued jobs by enqueue sequence
+ */
+export function fifoOrdering(a, b) {
+    return a.seq - b.seq;
+}
+/**
+ * Priority-first ordering (higher priority sooner), FIFO within equal priority.
+ *
+ * @capability work-order-priority order queued jobs by priority, then FIFO within equal priority
+ */
+export function priorityOrdering(a, b) {
+    return b.priority - a.priority || a.seq - b.seq;
+}
+/**
+ * Create an empty timed work queue.
+ *
+ * @capability work-queue a serializable timed job queue with reservation, cancellation, completion, and output routing
+ */
+export function createWorkQueue() {
+    return { jobs: [], nextId: 1, seq: 0 };
+}
+/**
+ * Non-terminal job count (queued + active + paused).
+ *
+ * @capability work-queue-size count non-terminal jobs in a work queue
+ */
+export function queueSize(state) {
+    return state.jobs.length;
+}
+/**
+ * Look up a job by id, or `null` if absent/terminal.
+ *
+ * @capability work-job-by-id look up a queued job by id
+ */
+export function jobById(state, id) {
+    return state.jobs.find((job) => job.id === id) ?? null;
+}
+/**
+ * Jobs waiting for a slot, in selection order.
+ *
+ * @capability work-queued-jobs list jobs waiting for a slot, in selection order
+ */
+export function queuedJobs(state, ordering = priorityOrdering) {
+    return state.jobs.filter((job) => job.status === "queued").sort(ordering);
+}
+/**
+ * Jobs currently progressing.
+ *
+ * @capability work-active-jobs list jobs currently progressing in a work queue
+ */
+export function activeJobs(state) {
+    return state.jobs.filter((job) => job.status === "active");
+}
+/**
+ * Fractional progress of a job (0…1); a zero-duration job reads as complete.
+ *
+ * @capability work-job-progress compute a job's fractional progress
+ */
+export function jobProgress(job) {
+    if (job.duration <= 0)
+        return 1;
+    return Math.min(1, Math.max(0, job.elapsed / job.duration));
+}
+/**
+ * Enqueue a new job. Validates capacity and the injected `validate` policy, then
+ * computes and stores the reservation. Charging the reservation (now or later) is
+ * the caller's responsibility using {@link EnqueueResult.job}'s `reservation`.
+ *
+ * @capability enqueue-work reserve inputs and add a timed job, honoring capacity and validation policy
+ */
+export function enqueue(state, config, spec, options) {
+    if (config.capacity !== undefined && state.jobs.length >= config.capacity) {
+        return { ok: false, state, reason: "capacity" };
+    }
+    const validation = config.validate?.(spec, state);
+    if (validation !== undefined && !validation.ok) {
+        return { ok: false, state, reason: validation.reason ?? "invalid" };
+    }
+    const reservation = (config.reserve ? config.reserve(spec) : undefined);
+    const job = {
+        id: options?.id ?? `job-${state.nextId}`,
+        spec,
+        reservation,
+        status: "queued",
+        duration: Math.max(0, config.duration(spec)),
+        elapsed: 0,
+        priority: options?.priority ?? 0,
+        seq: state.seq,
+    };
+    return {
+        ok: true,
+        job,
+        state: { jobs: [...state.jobs, job], nextId: state.nextId + 1, seq: state.seq + 1 },
+    };
+}
+/**
+ * Cancel a job and compute its refund. Removes the job from the queue and returns
+ * a refund payload (full reservation by default, or `config.refund` applied to the
+ * job's progress for partial/no refund). Applying the refund is the caller's job.
+ *
+ * @capability cancel-work remove a job and compute its refund from reservation and progress
+ */
+export function cancelJob(state, config, id) {
+    const job = state.jobs.find((entry) => entry.id === id);
+    if (job === undefined)
+        return { ok: false, state, reason: "not-found" };
+    const refund = config.refund
+        ? config.refund(job, jobProgress(job))
+        : (job.reservation ?? null);
+    return { ok: true, state: { ...state, jobs: state.jobs.filter((entry) => entry.id !== id) }, job, refund };
+}
+function setStatus(state, id, from, to) {
+    let changed = false;
+    const jobs = state.jobs.map((job) => {
+        if (job.id === id && job.status === from) {
+            changed = true;
+            return { ...job, status: to };
+        }
+        return job;
+    });
+    return changed ? { ...state, jobs } : state;
+}
+/**
+ * Pause a queued or active job in place; a paused job keeps its progress and yields its slot.
+ *
+ * @capability pause-work pause a queued or active job in place, retaining its progress
+ */
+export function pauseJob(state, id) {
+    const active = setStatus(state, id, "active", "paused");
+    return active !== state ? active : setStatus(state, id, "queued", "paused");
+}
+/**
+ * Resume a paused job; it re-enters the queue and competes for a slot by ordering.
+ *
+ * @capability resume-work resume a paused job back into the queue's slot competition
+ */
+export function resumeJob(state, id) {
+    return setStatus(state, id, "paused", "queued");
+}
+/**
+ * Advance the queue by `dt` seconds. Promotes queued jobs into up to `concurrency`
+ * active slots, advances active jobs, and completes those that reach their
+ * duration — emitting `started`/`completed` events in deterministic order. A large
+ * `dt` catches up across many jobs in one call: when a job completes with leftover
+ * time, the freed slot promotes the next queued job and applies the remainder, so a
+ * reconnect or save/load gap resolves in a single bounded pass. Completed jobs are
+ * removed from the returned state.
+ *
+ * @capability tick-work advance jobs over time, completing work and emitting typed lifecycle events
+ */
+export function tick(state, config, dt) {
+    if (dt <= 0 || state.jobs.length === 0)
+        return { state, events: [] };
+    const concurrency = Math.max(1, Math.floor(config.concurrency ?? 1));
+    const ordering = config.ordering ?? priorityOrdering;
+    const jobs = state.jobs.map((job) => ({ ...job }));
+    const events = [];
+    const budget = new Map();
+    const completedIds = new Set();
+    const activeCount = () => jobs.reduce((n, job) => (job.status === "active" ? n + 1 : n), 0);
+    const nextQueued = () => {
+        let best;
+        for (const job of jobs) {
+            if (job.status !== "queued")
+                continue;
+            if (best === undefined || ordering(job, best) < 0)
+                best = job;
+        }
+        return best;
+    };
+    const promote = (job, slotBudget) => {
+        job.status = "active";
+        budget.set(job.id, Math.max(0, slotBudget));
+        events.push({ type: "started", job: { ...job } });
+    };
+    // Jobs already active from a prior tick get a fresh full budget this tick.
+    for (const job of jobs) {
+        if (job.status === "active")
+            budget.set(job.id, dt);
+    }
+    // Fill idle slots up to concurrency with a full tick budget each.
+    while (activeCount() < concurrency) {
+        const next = nextQueued();
+        if (next === undefined)
+            break;
+        promote(next, dt);
+    }
+    // Step through completions in time order; each freed slot pulls the next queued
+    // job forward with the leftover time. Bounded by the job count.
+    const guardMax = jobs.length * 2 + concurrency + 8;
+    for (let guard = 0; guard <= guardMax; guard += 1) {
+        let chosen;
+        let chosenRemaining = Infinity;
+        for (const job of jobs) {
+            if (job.status !== "active")
+                continue;
+            const available = budget.get(job.id) ?? 0;
+            if (available <= 0)
+                continue;
+            const remaining = job.duration - job.elapsed;
+            if (remaining > available)
+                continue;
+            if (chosen === undefined ||
+                remaining < chosenRemaining ||
+                (remaining === chosenRemaining && ordering(job, chosen) < 0)) {
+                chosen = job;
+                chosenRemaining = remaining;
+            }
+        }
+        if (chosen === undefined)
+            break;
+        const leftover = (budget.get(chosen.id) ?? 0) - Math.max(0, chosenRemaining);
+        chosen.elapsed = chosen.duration;
+        budget.delete(chosen.id);
+        completedIds.add(chosen.id);
+        const finished = { ...chosen, status: "active" };
+        const output = (config.output ? config.output(finished) : undefined);
+        events.push({ type: "completed", job: finished, output });
+        const next = nextQueued();
+        if (next !== undefined)
+            promote(next, leftover);
+    }
+    // Advance any active job that still holds budget but did not complete.
+    for (const job of jobs) {
+        if (job.status !== "active" || completedIds.has(job.id))
+            continue;
+        const available = budget.get(job.id) ?? 0;
+        if (available > 0)
+            job.elapsed = Math.min(job.duration, job.elapsed + available);
+    }
+    const remaining = jobs
+        .filter((job) => !completedIds.has(job.id))
+        .map((job) => ({ ...job }));
+    return { state: { ...state, jobs: remaining }, events };
+}

package/dist/work/unitTraining.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Thin unit-training composition over the generic {@link WorkQueueConfig}. Turns a
+ * catalog of trainable units into a queue config whose reservation is the unit's
+ * cost/population, whose duration is its train time, and whose completion output is
+ * a plain spawn descriptor. The queue never spawns or moves anything: routing the
+ * descriptor to a spawn primitive (and rally movement) is the caller's completion
+ * adapter, keeping this genre-agnostic across RTS producers, respawn bays, and any
+ * "make one of X after T seconds" flow.
+ */
+import type { JobValidation, WorkQueueConfig, WorkQueueState } from "./jobQueue.js";
+/** Resource costs keyed by currency/resource id. */
+export type ResourceCost = Readonly<Record<string, number>>;
+/** A unit the producer can train. */
+export interface TrainableUnitDef {
+    /** Catalog id of the produced unit. */
+    readonly id: string;
+    /** Seconds to train. */
+    readonly trainSeconds: number;
+    /** Resources reserved at enqueue. */
+    readonly cost?: ResourceCost;
+    /** Population/supply reserved at enqueue. */
+    readonly population?: number;
+}
+/** What the caller asks the queue to build. */
+export interface UnitTrainingSpec {
+    readonly unitId: string;
+}
+/** Reservation stored on a training job — the inputs to charge and refund. */
+export interface UnitReservation {
+    readonly cost: ResourceCost;
+    readonly population: number;
+}
+/** Completion payload: everything a spawn/rally adapter needs, and nothing it doesn't. */
+export interface UnitSpawnOrder {
+    readonly unitId: string;
+    readonly reservation: UnitReservation;
+}
+/** Config knobs for {@link unitTrainingConfig}. */
+export interface UnitTrainingOptions {
+    /** Trainable units by id. */
+    readonly units: Record<string, TrainableUnitDef>;
+    /** Producers building at once (default 1 — a classic single build queue). */
+    readonly concurrency?: number;
+    /** Max queued+building units. */
+    readonly capacity?: number;
+    /** Refund fraction of cost on cancel (0 = none, 1 = full). Defaults to 1. */
+    readonly refundFraction?: number;
+    /** Extra pre-enqueue gate (affordability, tech, population cap). */
+    readonly canEnqueue?: (spec: UnitTrainingSpec, state: WorkQueueState<UnitTrainingSpec, UnitReservation>) => JobValidation;
+}
+/**
+ * Build a {@link WorkQueueConfig} for training units from a catalog. Reservation is
+ * the unit's cost + population; duration is its train time; completion output is a
+ * {@link UnitSpawnOrder} for the caller to route to its spawn primitive.
+ *
+ * @capability unit-training compose a timed work queue that trains catalog units into spawn orders
+ */
+export declare function unitTrainingConfig(options: UnitTrainingOptions): WorkQueueConfig<UnitTrainingSpec, UnitReservation, UnitSpawnOrder>;

package/dist/work/unitTraining.js

@@ -0,0 +1,52 @@
+/**
+ * Thin unit-training composition over the generic {@link WorkQueueConfig}. Turns a
+ * catalog of trainable units into a queue config whose reservation is the unit's
+ * cost/population, whose duration is its train time, and whose completion output is
+ * a plain spawn descriptor. The queue never spawns or moves anything: routing the
+ * descriptor to a spawn primitive (and rally movement) is the caller's completion
+ * adapter, keeping this genre-agnostic across RTS producers, respawn bays, and any
+ * "make one of X after T seconds" flow.
+ */
+function scaleCost(cost, fraction) {
+    if (fraction >= 1)
+        return cost;
+    if (fraction <= 0)
+        return {};
+    const out = {};
+    for (const [resource, amount] of Object.entries(cost))
+        out[resource] = Math.floor(amount * fraction);
+    return out;
+}
+/**
+ * Build a {@link WorkQueueConfig} for training units from a catalog. Reservation is
+ * the unit's cost + population; duration is its train time; completion output is a
+ * {@link UnitSpawnOrder} for the caller to route to its spawn primitive.
+ *
+ * @capability unit-training compose a timed work queue that trains catalog units into spawn orders
+ */
+export function unitTrainingConfig(options) {
+    const refundFraction = options.refundFraction ?? 1;
+    const unitFor = (unitId) => options.units[unitId];
+    return {
+        concurrency: options.concurrency,
+        capacity: options.capacity,
+        duration: (spec) => Math.max(0, unitFor(spec.unitId)?.trainSeconds ?? 0),
+        reserve: (spec) => {
+            const def = unitFor(spec.unitId);
+            return { cost: def?.cost ?? {}, population: def?.population ?? 0 };
+        },
+        validate: (spec, state) => {
+            if (unitFor(spec.unitId) === undefined)
+                return { ok: false, reason: "unknown-unit" };
+            return options.canEnqueue?.(spec, state) ?? { ok: true };
+        },
+        output: (job) => ({
+            unitId: job.spec.unitId,
+            reservation: job.reservation,
+        }),
+        refund: (job) => ({
+            cost: scaleCost(job.reservation.cost, refundFraction),
+            population: job.reservation.population,
+        }),
+    };
+}

package/dist/world/authoredObjects.d.ts

@@ -0,0 +1,58 @@
+import type { SceneMarkerLike } from "./sceneShapes.js";
+/**
+ * One authored catalog prop resolved from an editor marker — grounded at `x`/`z` with yaw, ready
+ * for `ctx.scene.object.place` or {@link placeAuthoredObjects}.
+ */
+export interface AuthoredObject {
+    catalogId: string;
+    x: number;
+    z: number;
+    rotationY: number;
+    instanceId: string;
+    /** Extra lift in meters from the marker (`catalogId` field / meta), applied on top of terrain height. */
+    verticalOffset: number;
+}
+/** Minimal marker shape {@link resolveAuthoredObjects} reads; any `EditorMarker` satisfies it. */
+export interface AuthoredObjectMarkerLike extends SceneMarkerLike {
+    catalogId?: string;
+    rotationY?: number;
+}
+/** Minimal document shape {@link resolveAuthoredObjects} walks; any `EditorDocument` satisfies it. */
+export interface AuthoredObjectsDocumentLike {
+    markers: readonly AuthoredObjectMarkerLike[];
+}
+/** Structural place target — any `ObjectStore` satisfies it. */
+export interface AuthoredObjectPlaceTarget {
+    place(catalogId: string, x: number, y: number, z: number, options?: {
+        instanceId?: string;
+        rotation?: number;
+        onExisting?: "throw" | "replace" | "keep";
+    }): string;
+}
+/** Options for {@link placeAuthoredObjects}. */
+export interface PlaceAuthoredObjectsOptions {
+    /** Extra lift in meters applied to every placement after terrain height + per-object offset. */
+    verticalOffset?: number;
+    /** How to treat instance ids already in the store. Default `"throw"` (ObjectStore default). */
+    onExisting?: "throw" | "replace" | "keep";
+}
+/**
+ * Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias.
+ * Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export declare function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null;
+/**
+ * Every marker carrying a catalog id, as placeable props — pure, no terrain sample. Parallel to
+ * {@link resolveScatter}: games and headless tests read the same list `<AuthoredObjects>` places.
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export declare function resolveAuthoredObjects(document: AuthoredObjectsDocumentLike): AuthoredObject[];
+/**
+ * Places resolved authored objects into an object store, grounding each on `sampleHeight(x,z)` plus
+ * per-object and options vertical offsets. Returns the instance ids that were placed (or kept).
+ * @capability authored-objects place catalog mesh props from an editor document
+ */
+export declare function placeAuthoredObjects(store: AuthoredObjectPlaceTarget, objects: readonly AuthoredObject[], sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];
+/** Convenience: resolve a document then place every authored catalog prop. */
+export declare function placeAuthoredObjectsFromDocument(store: AuthoredObjectPlaceTarget, document: AuthoredObjectsDocumentLike, sampleHeight: (x: number, z: number) => number, options?: PlaceAuthoredObjectsOptions): string[];