@animastor/orchestration 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Animastor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @animastor/orchestration
+
+Generation orchestration and runtime contour of the Animastor backend,
+physically extracted from the host (`backend/src/orchestration/**` +
+`backend/src/runtime/**` — §32.30; recon:
+`docs/architecture/generation-module-extraction-reconnaissance.md` §32.29).
+
+The package owns:
+
+- the orchestration facade (stage executor + FSM-safe scene writers)
+- the dispatch engine and its lease/quota/retry managers
+- the reconciliation engine and counter reconciliation
+- scene window/scheduler/worker-health
+- the runtime-result emitter/consumer
+- the eight O-2…O-10 port contracts (Persistence, SceneData,
+  PlaceholderAudio, ProgressEvents, AudioFsm, VideoFsm, HubCancel,
+  LayerConfig)
+
+## Dependency direction
+
+```
+backend host → @animastor/orchestration → ports / host-bindings / contracts
+```
+
+The package reaches the host (runtime config, Redis-domain state, media
+facades, S-5 seam registry, artifact root, PW-2 workspace resolver)
+**only** through the composition-root host-bindings seam — no
+`backend/src` require, no storage/book/routes/services, no Redis, no PG,
+no Express inside.
+
+Runtime dependencies: `@animastor/contracts`, `@animastor/generation`,
+`music-metadata`.
+
+## Public API
+
+```js
+const orchestration = require('@animastor/orchestration');
+```
+
+| Export | Kind | Description |
+|---|---|---|
+| orchestration facade | lazy | stage executor + FSM scene writers (begin/plan/dispatch/complete/fail/rollback) |
+| `createRuntimeResultConsumer` | eager | Phase-5 result-reporting consumer |
+| `ports` | eager | `{ persistence, sceneData, placeholderAudio, progressEvents, audioFsm, videoFsm, hubCancel, layerConfig }` |
+| `bindHostModules` | eager | composition-root binding surface |
+| `hostBinding` | eager | host-binding accessor |
+| `runtime` | lazy namespace | `{ scheduler, activeScenes, reconciliation, dispatch, leaseManager, counterReconciliation, metrics, workerHealth, sceneWindow, failureTaxonomy, runtimeResultEmitter }` |
+
+Facade exports are **lazy getters** — the FSM-writer re-exports resolve
+the `stateOps` host binding on access. `Object.defineProperties` on the
+root prevents eager evaluation at `require()` time.
+
+Deep imports (`@animastor/orchestration/runtime/…` etc.) are NOT part of
+the public surface — the exports map exposes only `'.'`.
+
+## Host responsibilities (composition root)
+
+1. Call `bindHostModules(…)` to wire config/state/media/seams/artifact
+   root/PW-2 resolver before accessing any lazy export.
+2. Register `createRuntimeResultConsumer` via
+   `runtimeResultEmitter.setConsumer(…)`.
+
+Without host binding, lazy getters throw on first access. This is
+intentional — the package is a pure domain contour until the composition
+root wires it.
+
+## Tests
+
+```bash
+npm test            # package-own suite (standalone, no backend required)
+```
+
+Backend-side guards: `backend/tests/architecture/physical-move-gate.test.js`
+(PM-G suite) ensures the moved files are gone from `backend/src/runtime`
+and the barrel is not consumed.

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@animastor/orchestration",
+    "version": "0.1.1",
+    "description": "Animastor Orchestration — the generation orchestration/runtime contour of the Animastor backend, physically extracted from the host (§32.30): the unified generation lifecycle owner (orchestrator facade, stage executor, scene callbacks/restoration), the dispatch engine and its lease/quota/retry managers, the reconciliation engine and counter reconciliation, the scene window/scheduler/worker-health, the runtime-result emitter/consumer, and the eight O-2..O-10 port contracts (Persistence, SceneData, PlaceholderAudio, ProgressEvents, AudioFsm, VideoFsm, HubCancel, LayerConfig). The package reaches the host (runtime config slices, Redis-domain state layer, media facades, the S-5 seam registry, the artifact root, the PW-2 workspace resolver) ONLY through the composition-root host-bindings seam — no backend/src require, no storage/book/routes/services, no Redis, no PG, no Express inside.",
+    "keywords": [
+        "animastor",
+        "orchestration",
+        "runtime",
+        "dispatch",
+        "reconciliation",
+        "generation"
+    ],
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src/",
+        "test/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "test": "mocha --exit --require test/test-bindings.js test/*.test.js"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Animastor/animastor.git",
+        "directory": "packages/animastor-orchestration"
+    },
+    "homepage": "https://github.com/Animastor/animastor/tree/main/packages/animastor-orchestration#readme",
+    "bugs": {
+        "url": "https://github.com/Animastor/animastor/issues"
+    },
+    "dependencies": {
+        "@animastor/contracts": "^0.1.0",
+        "@animastor/generation": "^0.1.0",
+        "music-metadata": "^11.12.3"
+    },
+    "devDependencies": {
+        "chai": "^6.2.2",
+        "mocha": "^11.7.5"
+    }
+}

package/src/host/host-bindings.js

@@ -0,0 +1,138 @@
+// ======================================================
+// HOST BINDINGS — the package↔host seam (S-6 convention)
+// ======================================================
+// The moved runtime/orchestration files reach the HOST-OWNED modules they
+// were allowed to touch (§32.29 host-stays allowlist) ONLY through this
+// surface. It is the same zero-require contract + fail-fast call-time
+// resolver + one set/wired/reset shape as the ports in ../runtime/*-port.js,
+// but for the host composition instead of one adapter: the composition root
+// (backend/src/backend.cjs) binds the real host modules once at startup and
+// the moved files resolve them lazily at call time.
+//
+// What crosses here (exactly the measured §32.29 host-stays, nothing more):
+//   config        — backend/src/config/runtime-config (runtime slices)
+//   state         — backend/src/state (Redis-domain state layer facade)
+//   stateOps      — backend/src/state/scene-state-ops (pure FSM writers)
+//   journal       — backend/src/state/event-journal (append-only sink)
+//   media         — { audio, image, video } host media facades
+//   genScope      — backend/src/services/gen-scope (single-consumer edge)
+//   seams         — backend/src/runtime/orchestration-seams (S-5 registry)
+//   artifactRoot  — the artifact output root (former process.env.OUTPUT_DIR
+//                   read — the §32.29 step-4a closure of the O-G9 leak)
+//   resolveWorkspaceForBook — the PW-2 workspace routing resolver (former
+//                   scene-window → gpu-dispatcher lazy call — the §32.29
+//                   step-4b closure; optional-load semantics preserved by
+//                   the injected wrapper host-side)
+//
+// Deliberately NOT reachable through here: storage/**, book/**, routes/**,
+// PG clients, Redis clients, Express, gpu-dispatcher internals. The host
+// binds adapters; the package never requires backend/src.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md
+//       §32.29 (gate) · §32.30 (physical extraction landed)
+
+const BINDING_NAMES = [
+    'config',
+    'state',
+    'stateOps',
+    'journal',
+    'media',
+    'genScope',
+    'seams',
+    'artifactRoot',
+    'resolveWorkspaceForBook',
+];
+
+const bindings = new Map();
+
+/**
+ * Wire the host-side implementations. Accepts a partial merge (tests may
+ * rebind individual bindings); unknown binding names are rejected — the
+ * surface cannot grow silently.
+ *
+ * RESOLVER SEMANTICS (§32.30): every binding is a ZERO-ARG FUNCTION that
+ * returns the host module/value. It is invoked at RESOLUTION time (i.e. when
+ * a moved file actually touches the host), not at binding time — the same
+ * deferral the former lazy host-module require call sites had, so host
+ * modules can be stubbed via require.cache after binding and stay visible
+ * to the moved code (test-binding parity).
+ */
+function bindHostModules(impls = {}) {
+    for (const [name, value] of Object.entries(impls)) {
+        if (!BINDING_NAMES.includes(name)) {
+            throw new Error(`host-bindings: unknown binding '${name}' (allowed: ${BINDING_NAMES.join(', ')})`);
+        }
+        if (typeof value !== 'function') {
+            throw new Error(`host-bindings: binding '${name}' must be a resolver function (zero-arg), got ${typeof value}`);
+        }
+        bindings.set(name, value);
+    }
+}
+
+/** Test hygiene: drop all bindings (mocha afterEach hooks). */
+function clearHostBindings() {
+    bindings.clear();
+}
+
+/**
+ * Resolve a binding at CALL time (invokes the resolver). Fail-fast with a
+ * wiring instruction — a missing binding must never degrade into a silent
+ * no-op.
+ */
+function hostBinding(name) {
+    const value = bindings.get(name);
+    if (typeof value !== 'function') {
+        throw new Error(
+            `host-bindings: '${name}' is not wired — the composition root must call ` +
+            `bindHostModules({ ${name}, ... }) before orchestration runs (§32.30)`
+        );
+    }
+    return value();
+}
+
+function isHostBindingWired(name) {
+    return bindings.has(name);
+}
+
+/**
+ * Lazy host-module accessor: returns a proxy that resolves the binding (and
+ * optional sub-path) at PROPERTY-ACCESS time. Lets a moved file keep its
+ * original identifier usage verbatim (`state.getAssetStates(...)`,
+ * `audio.segments.buildSegments(...)`) while the underlying host module is
+ * only resolved when actually used — same deferral the former lazy
+ * `require(...)` call sites had, but through the binding seam.
+ */
+function lazyHostBinding(name) {
+    const [root, ...rest] = name.split('.');
+    return new Proxy({}, {
+        get(_, prop) {
+            let target = hostBinding(root);
+            for (const key of rest) target = target[key];
+            return target[prop];
+        },
+    });
+}
+
+/**
+ * Direct call-time host access for non-member callables (the PW-2 resolver,
+ * the artifact root): `hostCall('resolveWorkspaceForBook')(bookId)`.
+ */
+function hostCall(name) {
+    return hostBinding(name);
+}
+
+/** All names the composition root is expected to wire. */
+function requiredHostBindings() {
+    return [...BINDING_NAMES];
+}
+
+module.exports = {
+    BINDING_NAMES,
+    bindHostModules,
+    clearHostBindings,
+    hostBinding,
+    hostCall,
+    isHostBindingWired,
+    lazyHostBinding,
+    requiredHostBindings,
+};

package/src/index.js

@@ -0,0 +1,99 @@
+// ======================================================
+// @animastor/orchestration — package root (public API)
+// ======================================================
+// The orchestration/runtime contour physically extracted from the backend
+// host (§32.30; gate: §32.29 — READY FOR PHYSICAL MOVE). This root exports
+// EXACTLY the measured host consumption surface — nothing "just in case":
+//
+//   1. The orchestration facade (former backend/src/orchestration/index.js,
+//      moved verbatim) — the stage executor + FSM-safe scene writers the
+//      host and the S-5 seam registry consume.
+//   2. createRuntimeResultConsumer — the Phase-5 result-reporting consumer
+//      the composition root registers via runtimeResultEmitter.setConsumer.
+//   3. The eight O-2..O-10 port CONTRACT modules (tier-owned, moved with
+//      the contour) — the host storage adapters bind these at startup.
+//   4. bindHostModules / hostBinding — the composition-root binding surface
+//      that wires the host-owned modules the moved files consume
+//      (config/state/media/seams/artifact root/PW-2 resolver).
+//
+// §32.30: the facade exports are LAZY getters (the FSM-writer re-exports
+// resolve the stateOps host binding on access), so the root itself builds
+// its export object with defineProperties — a literal spread would fire
+// those getters at require time, before the composition root binds host
+// modules. The surface (names + facade-wins precedence) is unchanged.
+//
+// Everything else in the package (dispatch-engine, reconciliation-engine,
+// scene-window, scheduler, lease/circuit/retry managers, worker-health,
+// metrics) is INTERNAL: no host module and no host test may deep-import it.
+//
+// Dependency direction after the move (guarded by backend PM-G suite):
+//   backend host → @animastor/orchestration → ports/host-bindings/contracts
+// The package requires @animastor/generation (root specifier only) and
+// @animastor/contracts; it never requires backend/src, storage, book,
+// routes, services, Redis or PG clients.
+//
+// Docs: docs/architecture/generation-module-extraction-reconnaissance.md
+//       §32.29 (frozen API) · §32.30 (physical extraction landed)
+
+const orchestrationFacade = require('./orchestration');
+const { createRuntimeResultConsumer } = require('./orchestration/runtime-result-consumer');
+const hostBindings = require('./host/host-bindings');
+
+// 1 — orchestration facade (lazy accessors over the moved facade modules)
+const FACADE_KEYS = Object.keys(orchestrationFacade);
+const LAZY_FACADE_PROPS = Object.fromEntries(FACADE_KEYS.map((key) => [key, {
+    enumerable: true,
+    get() { return orchestrationFacade[key]; },
+}]));
+
+// 2 + 3 + 4 — eager values (no binding resolution at require time)
+const EAGER_EXPORTS = {
+    createRuntimeResultConsumer,
+    ports: {
+        persistence: require('./runtime/persistence-port'),
+        sceneData: require('./runtime/scene-data-port'),
+        placeholderAudio: require('./runtime/placeholder-audio-port'),
+        progressEvents: require('./runtime/progress-events-port'),
+        audioFsm: require('./runtime/audio-fsm-port'),
+        videoFsm: require('./runtime/video-fsm-port'),
+        hubCancel: require('./runtime/hub-cancel-port'),
+        layerConfig: require('./runtime/layer-config-port'),
+    },
+    bindHostModules: hostBindings.bindHostModules,
+    clearHostBindings: hostBindings.clearHostBindings,
+    hostBinding: hostBindings.hostBinding,
+    isHostBindingWired: hostBindings.isHostBindingWired,
+    lazyHostBinding: hostBindings.lazyHostBinding,
+    requiredHostBindings: hostBindings.requiredHostBindings,
+    BINDING_NAMES: hostBindings.BINDING_NAMES,
+};
+
+// 5 — the host-facing runtime namespace: the measured routes/services/helpers
+// consumption surface (the former backend/src/runtime/index.js barrel minus
+// its host-stay members loop/gpuDispatcher/retentionManager). Lazy getters —
+// no eager module loads at require time.
+const RUNTIME_NS = {
+    scheduler: './runtime/runtime-scheduler',
+    activeScenes: './runtime/active-scenes-index',
+    reconciliation: './runtime/reconciliation-engine',
+    dispatch: './runtime/dispatch-engine',
+    leaseManager: './runtime/lease-manager',
+    counterReconciliation: './runtime/counter-reconciliation',
+    metrics: './runtime/runtime-metrics',
+    workerHealth: './runtime/worker-health',
+    sceneWindow: './runtime/scene-window',
+    failureTaxonomy: './runtime/failure-taxonomy',
+    runtimeResultEmitter: './runtime/runtime-result-emitter',
+};
+const LAZY_RUNTIME_PROPS = Object.fromEntries(Object.entries(RUNTIME_NS).map(([key, target]) => [key, {
+    enumerable: true,
+    get() { return require(target); },
+}]));
+
+const base = { ...EAGER_EXPORTS };
+Object.defineProperties(base, LAZY_FACADE_PROPS);
+Object.defineProperties(base, {
+    runtime: { enumerable: true, value: Object.defineProperties({}, LAZY_RUNTIME_PROPS) },
+});
+
+module.exports = base;

package/src/orchestration/index.js

@@ -0,0 +1,40 @@
+// ======================================================
+// Orchestration Module - v2.0.0
+// ======================================================
+
+// Existing contract: orchestration.dispatchStage / handle*Completed
+// are consumed by dispatch-engine.js (require('../orchestration')).
+// We preserve those exports and add the new Orchestrator facade alongside,
+// so callers can migrate to orchestration.orchestrator.* incrementally
+// without breaking the existing surface (Шаг 0, docs-claude/03_Orchestrator.md).
+//
+// Orchestrator facade functions (markDirtyScene, planScene, beginStage, etc.)
+// are also spread to the top level so callers that receive 'orchestrator' via
+// deps (reconciliation-engine, scene-asset-registry, etc.) can access them
+// directly as deps.orchestrator.markDirtyScene() without the .orchestrator
+// indirection. When names overlap (completeStage, failStage), the orchestrator
+// facade version wins (it's the newer canonical implementation).
+//
+// §32.30: the FSM-writer re-exports in orchestrator.js are LAZY getters
+// (they resolve the stateOps host binding on access). A literal object
+// spread would fire them at require time — before the composition root
+// binds host modules. Enumerate + defineProperties keeps every accessor
+// lazy while preserving the exact surface and the facade-wins precedence.
+const sceneOrchestrator = require('./scene-orchestrator');
+const orchestratorFacade = require('./orchestrator');
+
+const FACADE_KEYS = [
+    ...new Set([...Object.keys(sceneOrchestrator), ...Object.keys(orchestratorFacade)]),
+];
+
+const LAZY_FACADE_PROPS = Object.fromEntries(FACADE_KEYS.map((key) => [key, {
+    enumerable: true,
+    get() {
+        return key in orchestratorFacade ? orchestratorFacade[key] : sceneOrchestrator[key];
+    },
+}]));
+
+module.exports = Object.defineProperties(
+    { orchestrator: orchestratorFacade },
+    LAZY_FACADE_PROPS,
+);