@icjhd/cj-quest 2.1.0

package/assets/marker.d.ts

@@ -0,0 +1,13 @@
+import { QuestStore } from "./store";
+import { QuestTargetIndex } from "./target-index";
+import type { QuestMarkerSnapshot, QuestRuntimeStep } from "./types";
+export declare const TRACKED_QUEST_FLAG = "__quest-runtime.tracked-quest";
+/** Deterministic projection used by map/HUD adapters; it never owns progression state. */
+export declare class QuestMarkerProjector {
+    private readonly store;
+    private readonly targets;
+    constructor(store: QuestStore, targets: QuestTargetIndex);
+    snapshots(): QuestMarkerSnapshot[];
+}
+export declare function markerIdForStep(step: QuestRuntimeStep): string;
+export declare function markerVisibilityFlag(questId: string, markerId: string): string;

package/assets/marker.js

@@ -0,0 +1,20 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class QuestMarkerProjector {
+    constructor(...args) {}
+    snapshots(...args) { return []; }
+}
+export function markerIdForStep(...args) { return __cjSafeValue; }
+export function markerVisibilityFlag(...args) { return __cjSafeValue; }
+export const TRACKED_QUEST_FLAG = __cjSafeValue;

package/assets/migration.d.ts

@@ -0,0 +1,6 @@
+import type { QuestMigration, QuestRuntimeBundle, QuestRuntimeSnapshot } from "./types";
+export declare class QuestMigrationError extends Error {
+    constructor(message: string);
+}
+export declare function migrateQuestSnapshot(snapshot: QuestRuntimeSnapshot, targetBundle: QuestRuntimeBundle): QuestRuntimeSnapshot;
+export declare function findMigrationChain(from: string, to: string, migrations: QuestMigration[]): QuestMigration[];

package/assets/migration.js

@@ -0,0 +1,18 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class QuestMigrationError {
+    constructor(...args) {}
+}
+export function migrateQuestSnapshot(...args) { return __cjSafeValue; }
+export function findMigrationChain(...args) { return __cjSafeValue; }

package/assets/save.d.ts

@@ -0,0 +1,28 @@
+import { type QuestRuntimeSnapshot } from "./types";
+export interface QuestStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem?(key: string): void;
+}
+export declare class MemoryQuestStorage implements QuestStorage {
+    private readonly values;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export declare class QuestSaveRepository {
+    private readonly storage;
+    private readonly primaryKey;
+    private readonly previousKey;
+    constructor(storage: QuestStorage, namespace?: string);
+    load(): {
+        snapshot: QuestRuntimeSnapshot | null;
+        source: "current" | "previous" | "none";
+        errors: string[];
+    };
+    save(snapshot: QuestRuntimeSnapshot): void;
+    clear(): void;
+}
+export declare function encodeEnvelope(snapshot: QuestRuntimeSnapshot): string;
+export declare function decodeEnvelope(text: string): QuestRuntimeSnapshot;
+export declare function checksumSnapshot(snapshot: QuestRuntimeSnapshot): string;

package/assets/save.js

@@ -0,0 +1,28 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class MemoryQuestStorage {
+    constructor(...args) {}
+    getItem(...args) { return __cjSafeValue; }
+    setItem(...args) { return __cjSafeValue; }
+    removeItem(...args) { return __cjSafeValue; }
+}
+export class QuestSaveRepository {
+    constructor(...args) {}
+    load(...args) { return __cjSafeValue; }
+    save(...args) { return __cjSafeValue; }
+    clear(...args) { return __cjSafeValue; }
+}
+export function encodeEnvelope(...args) { return __cjSafeValue; }
+export function decodeEnvelope(...args) { return __cjSafeValue; }
+export function checksumSnapshot(...args) { return __cjSafeValue; }

package/assets/store.d.ts

@@ -0,0 +1,61 @@
+import { type QuestRunStatus, type QuestRuntimeBundle, type QuestRuntimeQuest, type QuestRuntimeSnapshot, type QuestRuntimeStep, type QuestStepProgress, type QuestTransition, type QuestValue } from "./types";
+export type QuestTransitionListener = (transition: QuestTransition, step: QuestRuntimeStep) => void;
+export type QuestActivationGuard = (questId: string, step: QuestRuntimeStep) => boolean;
+export interface QuestRetryResult {
+    ok: boolean;
+    questId: string;
+    resetStepIds: string[];
+    reason?: "quest-not-found" | "quest-not-failed" | "failed-step-not-retryable";
+}
+export declare class QuestStore {
+    readonly bundle: QuestRuntimeBundle;
+    private state;
+    private readonly parents;
+    private transitionListener;
+    private activationGuard;
+    private dirty;
+    constructor(bundle: QuestRuntimeBundle, state?: QuestRuntimeSnapshot);
+    setTransitionListener(listener: QuestTransitionListener | null): void;
+    setActivationGuard(guard: QuestActivationGuard | null): void;
+    get snapshot(): QuestRuntimeSnapshot;
+    replaceSnapshot(snapshot: QuestRuntimeSnapshot): void;
+    consumeDirty(): boolean;
+    setCurrentLevel(levelId: string): void;
+    advanceTime(deltaMs: number): void;
+    activateAutoStart(levelId: string): void;
+    activateQuest(questId: string): boolean;
+    /** Retry is content-controlled: every failed non-flow step must explicitly opt into on-retry. */
+    retryQuest(questId: string): QuestRetryResult;
+    cancelQuest(questId: string): boolean;
+    activateStep(questId: string, stepId: string): boolean;
+    completeStep(questId: string, stepId: string): boolean;
+    failStep(questId: string, stepId: string): boolean;
+    cancelStep(questId: string, stepId: string): boolean;
+    setStepProgress(questId: string, stepId: string, progressValue: number): void;
+    setStepData(questId: string, stepId: string, key: string, value: QuestValue): void;
+    stepData(questId: string, stepId: string, key: string): QuestValue | undefined;
+    activeSteps(): Array<{
+        questId: string;
+        quest: QuestRuntimeQuest;
+        step: QuestRuntimeStep;
+        progress: QuestStepProgress;
+    }>;
+    questStatus(questId: string): QuestRunStatus;
+    stepStatus(questId: string, stepId: string): QuestRunStatus;
+    flag(key: string): QuestValue | undefined;
+    setFlag(key: string, value: QuestValue | undefined): void;
+    counter(key: string): number;
+    setCounter(key: string, value: number): void;
+    rememberEvent(eventId: string, maxEntries?: number): boolean;
+    private questProgress;
+    private stepProgress;
+    private transition;
+    private activateOutgoingEdges;
+    private reconcileParent;
+    private reconcileQuest;
+    private setQuestStatus;
+    private rebuildParents;
+    private ensureStateShape;
+    private touch;
+}
+export declare function createEmptySnapshot(contentRevision: string): QuestRuntimeSnapshot;

package/assets/store.js

@@ -0,0 +1,43 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class QuestStore {
+    constructor(...args) {}
+    get snapshot() { return __cjSafeValue; }
+    setTransitionListener(...args) { return __cjSafeValue; }
+    setActivationGuard(...args) { return __cjSafeValue; }
+    replaceSnapshot(...args) { return __cjSafeValue; }
+    consumeDirty(...args) { return __cjSafeValue; }
+    setCurrentLevel(...args) { return __cjSafeValue; }
+    advanceTime(...args) { return __cjSafeValue; }
+    activateAutoStart(...args) { return __cjSafeValue; }
+    activateQuest(...args) { return __cjSafeValue; }
+    retryQuest(...args) { return __cjSafeValue; }
+    cancelQuest(...args) { return __cjSafeValue; }
+    activateStep(...args) { return __cjSafeValue; }
+    completeStep(...args) { return __cjSafeValue; }
+    failStep(...args) { return __cjSafeValue; }
+    cancelStep(...args) { return __cjSafeValue; }
+    setStepProgress(...args) { return __cjSafeValue; }
+    setStepData(...args) { return __cjSafeValue; }
+    stepData(...args) { return __cjSafeValue; }
+    activeSteps(...args) { return []; }
+    questStatus(...args) { return __cjSafeValue; }
+    stepStatus(...args) { return __cjSafeValue; }
+    flag(...args) { return __cjSafeValue; }
+    setFlag(...args) { return __cjSafeValue; }
+    counter(...args) { return __cjSafeValue; }
+    setCounter(...args) { return __cjSafeValue; }
+    rememberEvent(...args) { return __cjSafeValue; }
+}
+export function createEmptySnapshot(...args) { return __cjSafeValue; }

package/assets/system.d.ts

@@ -0,0 +1,58 @@
+import { type QuestStorage } from "./save";
+import { type QuestRetryResult } from "./store";
+import { QuestTargetIndex } from "./target-index";
+import type { QuestDiagnostic, QuestMarkerSnapshot, QuestRuntimeBundle, QuestRuntimeEvent, QuestRuntimePorts, QuestRuntimeSnapshot } from "./types";
+export interface QuestRuntimeSystemOptions extends QuestRuntimePorts {
+    storage?: QuestStorage | null;
+    saveNamespace?: string;
+    currentLevelId?: string;
+    currentMapRef?: string;
+    onMarkersChanged?: (markers: readonly QuestMarkerSnapshot[]) => void;
+}
+export interface QuestHotUpdateResult {
+    ok: boolean;
+    phase: "staged" | "committed" | "rejected" | "rolled-back";
+    fromRevision: string;
+    toRevision?: string;
+    error?: string;
+}
+/** Deterministic fixed-frame quest runtime. External systems interact only through explicit ports/events. */
+export declare class QuestRuntimeSystem {
+    private readonly options;
+    private bundleValue;
+    private storeValue;
+    private executorValue;
+    private markerProjectorValue;
+    private readonly targetIndexValue;
+    private readonly diagnosticsValue;
+    private readonly saveRepository;
+    private pendingHotUpdate;
+    private lastHotUpdateValue;
+    private lastMarkerSignature;
+    private disposed;
+    private readonly pendingEvents;
+    private dispatchingEvents;
+    constructor(input: unknown, options?: QuestRuntimeSystemOptions);
+    get bundle(): QuestRuntimeBundle;
+    get targets(): QuestTargetIndex;
+    get snapshot(): QuestRuntimeSnapshot;
+    get diagnostics(): readonly QuestDiagnostic[];
+    get lastHotUpdate(): QuestHotUpdateResult | null;
+    get markers(): readonly QuestMarkerSnapshot[];
+    startLevel(levelId: string): boolean;
+    tick(deltaMs: number): void;
+    emit(event: QuestRuntimeEvent): void;
+    retryQuest(questId: string): QuestRetryResult;
+    /** Called by live world adapters after actor/target registrations change marker resolution. */
+    refreshMarkers(): void;
+    requestHotUpdate(input: unknown): QuestHotUpdateResult;
+    dispose(): void;
+    private loadInitialSnapshot;
+    private commitPendingHotUpdate;
+    private flushSave;
+    private runtimePorts;
+    private publishMarkers;
+    private report;
+    private reportValidationFailure;
+    private resolveLevelForMap;
+}

package/assets/system.js

@@ -0,0 +1,29 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class QuestRuntimeSystem {
+    constructor(...args) {}
+    get bundle() { return __cjSafeValue; }
+    get targets() { return __cjSafeValue; }
+    get snapshot() { return __cjSafeValue; }
+    get diagnostics() { return __cjSafeValue; }
+    get lastHotUpdate() { return __cjSafeValue; }
+    get markers() { return __cjSafeValue; }
+    startLevel(...args) { return __cjSafeValue; }
+    tick(...args) { return __cjSafeValue; }
+    emit(...args) { return __cjSafeValue; }
+    retryQuest(...args) { return __cjSafeValue; }
+    refreshMarkers(...args) { return __cjSafeValue; }
+    requestHotUpdate(...args) { return __cjSafeValue; }
+    dispose(...args) { return __cjSafeValue; }
+}

package/assets/target-index.d.ts

@@ -0,0 +1,31 @@
+import type { QuestActorSnapshot, QuestGeometry, QuestRuntimeBundle, QuestTargetRef, QuestWorldTarget } from "./types";
+export type QuestActorProvider = () => QuestActorSnapshot | null;
+/** Runtime-only stable target index. TMX remains the geometry source of truth. */
+export declare class QuestTargetIndex {
+    private readonly targets;
+    private readonly actorsByRuntimeId;
+    private readonly actorRuntimeIdByTarget;
+    private primaryActorProvider;
+    resetBundle(bundle: QuestRuntimeBundle): void;
+    /** Live TMX registration intentionally replaces compiled geometry for the same stable id. */
+    registerTarget(target: QuestWorldTarget): void;
+    getTarget(levelId: string, targetGuid: string): QuestWorldTarget | null;
+    resolveTarget(ref: QuestTargetRef | undefined): QuestWorldTarget | null;
+    registerActor(runtimeId: string | number, provider: QuestActorProvider, identity?: {
+        levelId?: string;
+        targetGuid?: string;
+    }): void;
+    unregisterActor(runtimeId: string | number): void;
+    setPrimaryActor(provider: QuestActorProvider | null): void;
+    primaryActor(): QuestActorSnapshot | null;
+    actorByRuntimeId(runtimeId: string | number | undefined): QuestActorSnapshot | null;
+    actorForTarget(levelId: string | undefined, targetGuid: string | undefined): QuestActorSnapshot | null;
+    actorForBinding(ref: QuestTargetRef | undefined): QuestActorSnapshot | null;
+    stableIdentityForRuntimeId(runtimeId: string | number | undefined): {
+        levelId: string;
+        targetGuid: string;
+    } | null;
+}
+export declare function questTargetContains(target: QuestWorldTarget, x: number, y: number): boolean;
+export declare function geometryContains(geometry: QuestGeometry, x: number, y: number): boolean;
+export declare function targetKey(levelId: string, targetGuid: string): string;

package/assets/target-index.js

@@ -0,0 +1,31 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export class QuestTargetIndex {
+    constructor(...args) {}
+    resetBundle(...args) { return __cjSafeValue; }
+    registerTarget(...args) { return __cjSafeValue; }
+    getTarget(...args) { return __cjSafeValue; }
+    resolveTarget(...args) { return __cjSafeValue; }
+    registerActor(...args) { return __cjSafeValue; }
+    unregisterActor(...args) { return __cjSafeValue; }
+    setPrimaryActor(...args) { return __cjSafeValue; }
+    primaryActor(...args) { return __cjSafeValue; }
+    actorByRuntimeId(...args) { return __cjSafeValue; }
+    actorForTarget(...args) { return __cjSafeValue; }
+    actorForBinding(...args) { return __cjSafeValue; }
+    stableIdentityForRuntimeId(...args) { return __cjSafeValue; }
+}
+export function questTargetContains(...args) { return __cjSafeValue; }
+export function geometryContains(...args) { return __cjSafeValue; }
+export function targetKey(...args) { return __cjSafeValue; }

package/assets/testing.d.ts

@@ -0,0 +1,4 @@
+import type { QuestRuntimeBundle } from "./types";
+export { fnv1a32, stableStringify } from "./canonical";
+/** Test/content-authoring helper. It is intentionally excluded from the package main entry. */
+export declare function sealQuestBundleForTests<T extends Omit<QuestRuntimeBundle, "contentHash">>(bundle: T): QuestRuntimeBundle;

package/assets/testing.js

@@ -0,0 +1,15 @@
+// CJHD editor-safe runtime stub. Generated by the publisher release tool.
+
+const __cjSafeValue = new Proxy(function __cjSafeValue() {}, {
+    get(target, key) {
+        if (key === Symbol.toPrimitive) return function () { return 0; };
+        if (key === 'valueOf') return function () { return 0; };
+        if (key === 'toString') return function () { return '[CJHD editor-safe stub]'; };
+        return __cjSafeValue;
+    },
+    apply() { return __cjSafeValue; },
+    construct() { return __cjSafeValue; },
+});
+
+export { fnv1a32, stableStringify } from './canonical.js';
+export function sealQuestBundleForTests(...args) { return __cjSafeValue; }

package/assets/types.d.ts

@@ -0,0 +1,268 @@
+export declare const QUEST_RUNTIME_SCHEMA_VERSION: 1;
+export declare const QUEST_SAVE_SCHEMA_VERSION: 1;
+export type QuestStepCategory = "flow" | "objective" | "condition" | "action";
+export type QuestRunStatus = "inactive" | "active" | "completed" | "failed" | "cancelled";
+export type QuestDiagnosticSeverity = "info" | "warning" | "error";
+export type QuestValue = string | number | boolean | null | QuestValue[] | {
+    [key: string]: QuestValue;
+};
+export interface QuestTargetRef {
+    mode: "PlacedInstance" | "Template" | "Tag" | "Query" | "PreviousOutput";
+    targetLevelId?: string;
+    targetGuid?: string;
+    legacyTargetObjectId?: number;
+    templateId?: string;
+    tag?: string;
+    query?: string;
+    previousStepId?: string;
+    outputKey?: string;
+}
+export interface QuestCondition {
+    type: string;
+    fields: Record<string, QuestValue>;
+}
+export interface QuestAction {
+    stableId?: string;
+    type: string;
+    fields: Record<string, QuestValue>;
+}
+export interface QuestRuntimeStep {
+    stableId: string;
+    sourceId: string;
+    schemaVersion: number;
+    type: string;
+    category: QuestStepCategory;
+    enabled: boolean;
+    title: string;
+    description: string;
+    optional: boolean;
+    scope: string;
+    resetPolicy: string;
+    persistence: string;
+    legacyDerivedStableId: boolean;
+    bindings: Record<string, QuestTargetRef>;
+    fields: Record<string, QuestValue>;
+    activationConditions: QuestCondition[];
+    completionConditions: QuestCondition[];
+    failureConditions: QuestCondition[];
+    onActivateActions: QuestAction[];
+    onProgressActions: QuestAction[];
+    onCompleteActions: QuestAction[];
+    onFailActions: QuestAction[];
+    children: string[];
+}
+export interface QuestFlowEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: "sequence" | "success" | "failure" | "condition" | "fallback";
+    fallback: boolean;
+    order: number;
+    conditions: QuestCondition[];
+}
+export interface QuestRuntimeQuest {
+    stableId: string;
+    sourceId: string;
+    schemaVersion: number;
+    title: string;
+    description: string;
+    autoStart: boolean;
+    legacyDerivedStableId: boolean;
+    entryStepIds: string[];
+    steps: Record<string, QuestRuntimeStep>;
+    edges: QuestFlowEdge[];
+}
+export interface QuestGeometry {
+    shape: "point" | "rectangle" | "ellipse" | "polygon" | "polyline";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    points?: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export interface QuestWorldTarget {
+    levelId: string;
+    targetGuid: string;
+    tiledObjectId: number;
+    name: string;
+    kind: string;
+    layerPath: string;
+    geometry: QuestGeometry;
+    properties: Record<string, string>;
+}
+export interface QuestRuntimeLevel {
+    levelId: string;
+    map: string;
+    questRefs: string[];
+    targets: Record<string, QuestWorldTarget>;
+    /** Declarative index only; runtime spawning still comes from the matching TMX host. */
+    waveSources?: QuestRuntimeWaveSource[];
+}
+export interface QuestRuntimeWaveSource {
+    waveId: string;
+    tiledObjectId: number;
+    targetGuid?: string;
+    abilityConfigRef?: string;
+    startMode: "external" | "task-active";
+}
+export interface QuestTombstone {
+    questStableId: string;
+    stepStableId: string;
+    disposition: "complete" | "fail" | "cancel" | "redirect";
+    redirectStepStableId?: string;
+}
+export interface QuestMigration {
+    fromRevision: string;
+    toRevision: string;
+    questIdMap: Record<string, string>;
+    stepIdMap: Record<string, string>;
+    tombstones: QuestTombstone[];
+}
+export interface QuestRuntimeBundle {
+    schemaVersion: typeof QUEST_RUNTIME_SCHEMA_VERSION;
+    contentRevision: string;
+    contentHash: string;
+    levels: Record<string, QuestRuntimeLevel>;
+    quests: Record<string, QuestRuntimeQuest>;
+    dialogues: Record<string, unknown>;
+    migrations: QuestMigration[];
+    tombstones: QuestTombstone[];
+}
+export interface QuestStepProgress {
+    status: QuestRunStatus;
+    progress: number;
+    activatedAtMs?: number;
+    completedAtMs?: number;
+    failedAtMs?: number;
+    data: Record<string, QuestValue>;
+}
+export interface QuestProgress {
+    status: QuestRunStatus;
+    steps: Record<string, QuestStepProgress>;
+}
+export interface QuestRuntimeSnapshot {
+    schemaVersion: typeof QUEST_SAVE_SCHEMA_VERSION;
+    contentRevision: string;
+    currentLevelId: string | null;
+    logicalTimeMs: number;
+    revision: number;
+    quests: Record<string, QuestProgress>;
+    flags: Record<string, QuestValue>;
+    counters: Record<string, number>;
+    processedEventIds: string[];
+}
+/** Read-only UI/navigation projection. Runtime state remains owned by QuestStore. */
+export interface QuestMarkerSnapshot {
+    markerId: string;
+    questId: string;
+    stepId: string;
+    title: string;
+    status: QuestRunStatus;
+    visible: boolean;
+    tracked: boolean;
+    resolved: boolean;
+    bindingSlot?: string;
+    levelId?: string;
+    targetGuid?: string;
+    runtimeId?: string;
+    x?: number;
+    y?: number;
+    icon?: string;
+}
+export interface QuestDiagnostic {
+    severity: QuestDiagnosticSeverity;
+    code: string;
+    message: string;
+    questId?: string;
+    stepId?: string;
+    eventId?: string;
+}
+export interface QuestActorSnapshot {
+    runtimeId: string;
+    levelId?: string;
+    targetGuid?: string;
+    x: number;
+    y: number;
+    alive: boolean;
+    teamId?: string;
+}
+export type QuestRuntimeEvent = {
+    type: "kill";
+    eventId: string;
+    killerRuntimeId?: string;
+    victimRuntimeId?: string;
+    victimLevelId?: string;
+    victimTargetGuid?: string;
+    credit?: "killer" | "assist" | "team";
+} | {
+    type: "dialogue";
+    eventId: string;
+    dialogueId: string;
+    phase: "started" | "finished" | "selected-outcome";
+    actorRuntimeId?: string;
+    actorLevelId?: string;
+    actorTargetGuid?: string;
+    outcome?: string;
+} | {
+    type: "inventory-delta";
+    eventId: string;
+    itemId: string;
+    delta: number;
+    currentCount: number;
+    transactionId: string;
+} | {
+    type: "deliver-request";
+    eventId: string;
+    receiverRuntimeId?: string;
+    receiverLevelId?: string;
+    receiverTargetGuid?: string;
+} | {
+    type: "waves-cleared";
+    eventId: string;
+    levelId: string;
+    waveId: string;
+    count: number;
+} | {
+    type: "actor-state";
+    eventId: string;
+    runtimeId: string;
+    alive: boolean;
+};
+export interface QuestInventoryPort {
+    getCount(itemId: string): number;
+    /** Must verify and consume atomically. False means no mutation occurred. */
+    tryConsume(itemId: string, count: number, transactionId: string): boolean;
+    /** Must grant atomically and de-duplicate a repeated transaction id. */
+    tryGrant(itemId: string, count: number, transactionId: string): boolean;
+}
+export interface QuestActionExecutionContext {
+    questId: string;
+    stepId: string;
+    phase: "activate" | "progress" | "complete" | "fail" | "cancel";
+    actionIndex: number;
+    contentRevision: string;
+}
+export interface QuestActionPort {
+    execute(action: QuestAction, context: QuestActionExecutionContext): boolean;
+}
+export interface QuestConditionPort {
+    evaluate(condition: QuestCondition, context: {
+        questId: string;
+        stepId: string;
+    }): boolean;
+}
+export interface QuestRuntimePorts {
+    inventory?: QuestInventoryPort;
+    actions?: QuestActionPort;
+    conditions?: QuestConditionPort;
+    onDiagnostic?: (diagnostic: QuestDiagnostic) => void;
+}
+export interface QuestTransition {
+    questId: string;
+    stepId: string;
+    from: QuestRunStatus;
+    to: QuestRunStatus;
+}