@revisium/orchestrator 0.0.0

package/dist/engine/dbos.service.js

@@ -0,0 +1,296 @@
+/**
+ * DbosService — the engine layer owns all @dbos-inc/dbos-sdk imports.
+ *
+ * This file (`dbos.service.ts`) is the primary importer; `engine/types.ts` re-exports
+ * type-only symbols (`WorkflowHandle`) so pipeline callers can annotate return types
+ * without importing from @dbos-inc directly. `src/pipeline/*` must import ZERO @dbos-inc.
+ *
+ * Owns DBOS lifecycle (setConfig / launch / shutdown) and thin verbs
+ * (startPingWorkflow / getWorkflowStatus / waitForWorkflow).
+ *
+ * Seam pattern: `dev:ping` is a two-step workflow registered as instance methods
+ * via DBOS.registerWorkflow / DBOS.registerStep (programmatic, decorator-free).
+ * Registration happens in the constructor, BEFORE DBOS.launch() — required by DBOS
+ * (workflows not registered before launch() are not eligible for recovery).
+ *
+ * ── Confirmed SDK symbols (Task 0, @dbos-inc/dbos-sdk@4.19.8) ──────────────
+ *   DBOSConfig.systemDatabaseUrl   ✓  (ТЗ expected systemDatabaseUrl — CONFIRMED)
+ *   DBOS.setConfig(config)          ✓
+ *   DBOS.launch()                   ✓
+ *   DBOS.shutdown()                 ✓
+ *   DBOS.registerWorkflow(fn, cfg)  ✓  returns wrapped fn with same signature
+ *   DBOS.registerStep(fn, cfg)      ✓  returns wrapped fn with same signature
+ *   DBOS.startWorkflow(fn, params)  ✓  params.workflowID ✓; returns fn(args)=>handle
+ *   DBOS.getWorkflowStatus(id)      ✓  returns WorkflowStatus | null
+ *   DBOS.retrieveWorkflow(id)       ✓  returns WorkflowHandle<T>; handle.getResult() ✓
+ *   DBOS.sleep(ms)                  ✓
+ *   ConfiguredInstance              ✓  (fallback path — not used; registerWorkflow used instead)
+ *
+ * ── Recovery seam ───────────────────────────────────────────────────────────
+ *   On restart, DBOS.launch() auto-recovers in-flight workflows by name+className.
+ *   registerWorkflow(boundFn, { name, className }) supplies stable names so DBOS
+ *   can bind back to the freshly-DI-constructed DbosService singleton.
+ *   If M3 (kill-mid-step test) shows recovery fails to re-bind, switch to
+ *   ConfiguredInstance (documented fallback; both paths concrete — OQ-1b).
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Injectable } from '@nestjs/common';
+import { DBOS, WorkflowQueue } from '@dbos-inc/dbos-sdk';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Far-future absolute deadline (year 2100 epoch ms). Fixed constant ⇒ deterministic on replay (G5).
+ * DBOS recv with no timeout/deadline defaults to 60 s; we pass this so human gates wait indefinitely.
+ * Never use Date.now()+X — that differs per replay and breaks DBOS replay-safety.
+ */
+export const GATE_DEADLINE_EPOCH_MS = 4102444800000; // 2100-01-01T00:00:00Z
+/**
+ * Bound on how long DBOS.shutdown() may block before the host detaches anyway (0008 #3).
+ * DBOS.shutdown() drains "pending workflows" — but a workflow PARKED at a human gate
+ * (DBOS.recv) never drains, so app.close() hangs forever after `run start --wait` detaches.
+ * The durable state lives in Postgres and is recovered on the next launch(), so abandoning
+ * the in-memory drain after this bound loses no durability — it only lets the CLI exit 0.
+ */
+export const SHUTDOWN_DRAIN_TIMEOUT_MS = 8_000;
+let DbosService = class DbosService {
+    launched = false;
+    /** Registered WorkflowQueues — guarded map to ensure idempotent registration. */
+    queues = new Map();
+    // Registered DBOS functions — assigned in constructor before launch().
+    pingWorkflow;
+    markStep;
+    sleepStep;
+    constructor() {
+        // Register steps first (workflows may call them; all must be registered before launch).
+        this.markStep = DBOS.registerStep(async function markStepImpl(workflowID, markerFile) {
+            // Idempotent marker (F12): write exactly-once per workflowID by using 'wx' (exclusive
+            // create). If the file already exists (step re-executed after a crash-before-checkpoint),
+            // writeFileSync throws with EEXIST — we catch that and skip the write, ensuring the
+            // marker count is always 1 for a given workflow id regardless of how many times the
+            // step body runs.
+            mkdirSync(dirname(markerFile), { recursive: true });
+            try {
+                writeFileSync(markerFile, `${workflowID}\t${new Date().toISOString()}\n`, { flag: 'wx' });
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+                // EEXIST: marker already written by a prior execution — skip (idempotent).
+            }
+            const content = existsSync(markerFile) ? readFileSync(markerFile, 'utf8') : '';
+            return content.split('\n').filter((l) => l.trim() !== '').length;
+        }, { name: 'markStep', className: 'DbosService' });
+        this.sleepStep = DBOS.registerStep(async function sleepStepImpl(ms) {
+            await DBOS.sleep(ms);
+        }, { name: 'sleepStep', className: 'DbosService' });
+        // Register the workflow (uses bound steps).
+        // Capture step references via .bind(this) so DBOS sees stable registered functions,
+        // not closures that close over `this` directly (avoids S7740 "do not assign this to self").
+        const markStepBound = this.markStep.bind(this);
+        const sleepStepBound = this.sleepStep.bind(this);
+        this.pingWorkflow = DBOS.registerWorkflow(async function pingImpl(workflowID, sleepMs, markerFile) {
+            const markerCount = await markStepBound(workflowID, markerFile);
+            await sleepStepBound(sleepMs);
+            return { workflowID, markerCount };
+        }, { name: 'pingImpl', className: 'DbosService' });
+    }
+    // ── Generic engine verbs (M1 — DBOS seal, TASK 0003) ───────────────────────
+    //
+    // `src/pipeline/*` imports NO `@dbos-inc/dbos-sdk`. These verbs expose the minimal
+    // surface needed for the pipeline module: register a step/workflow (returns the
+    // DBOS-wrapped fn with the same signature), register a queue (idempotent), and enqueue
+    // a workflow by ID + queue name.
+    //
+    // `name` format: 'ClassName.methodName' — split on the LAST dot to fill DBOS's
+    // { name, className } (matching how dev:ping uses { name:'pingImpl', className:'DbosService' }).
+    // Stable across releases — the recovery seam binds on name+className.
+    /**
+     * Register a plain async function as a DBOS step.
+     * Returns the DBOS-wrapped function with the same call signature.
+     * Call in the consumer's constructor, BEFORE DBOS.launch().
+     */
+    registerStep(name, fn) {
+        const lastDot = name.lastIndexOf('.');
+        const className = lastDot >= 0 ? name.slice(0, lastDot) : 'Pipeline';
+        const methodName = lastDot >= 0 ? name.slice(lastDot + 1) : name;
+        return DBOS.registerStep(fn, { name: methodName, className });
+    }
+    /**
+     * Register a plain async function as a DBOS workflow.
+     * Returns the DBOS-wrapped function with the same call signature.
+     * Call in the consumer's constructor, BEFORE DBOS.launch().
+     */
+    registerWorkflow(name, fn) {
+        const lastDot = name.lastIndexOf('.');
+        const className = lastDot >= 0 ? name.slice(0, lastDot) : 'Pipeline';
+        const methodName = lastDot >= 0 ? name.slice(lastDot + 1) : name;
+        return DBOS.registerWorkflow(fn, { name: methodName, className });
+    }
+    /**
+     * Construct and register a WorkflowQueue (idempotent — Map-guarded).
+     * The ONLY place `new WorkflowQueue(...)` is called, keeping @dbos-inc inside this file.
+     * Call before DBOS.launch().
+     */
+    registerQueue(name, opts) {
+        if (!this.queues.has(name)) {
+            this.queues.set(name, new WorkflowQueue(name, opts));
+        }
+    }
+    /**
+     * Enqueue a registered workflow with a stable workflowID and queue name.
+     * Idempotent by workflowID: if a workflow with the same id already exists, DBOS returns
+     * a handle to the existing workflow and does NOT start a second run.
+     *
+     * Generic over the workflow's arg tuple A so it accepts any registered fn signature.
+     *
+     * @param fn        - The DBOS-wrapped workflow function (returned by registerWorkflow).
+     * @param workflowID - Stable dedup key (e.g. the runId).
+     * @param queueName  - Name of the queue to enqueue on.
+     * @param args       - Arguments forwarded to the workflow (persisted as durable input).
+     */
+    startWorkflowOn(fn, workflowID, queueName, ...args) {
+        return DBOS.startWorkflow(fn, { workflowID, queueName })(...args);
+    }
+    /**
+     * Signal a parked workflow's awaitDecision. Wraps DBOS.send; exactly-once via idempotencyKey.
+     *
+     * CANONICAL wrapper arg order: signal(workflowId, topic, payload, idempotencyKey).
+     * The wrapper REORDERS to DBOS's raw order INSIDE:
+     *   wrapper (workflowId, topic, payload) → DBOS.send(workflowId, payload, topic, idempotencyKey).
+     * Every call site MUST use the wrapper order (topic BEFORE payload); the raw DBOS swap lives
+     * ONLY here so it cannot be reintroduced at a call site (G9).
+     */
+    signal(workflowId, topic, payload, idempotencyKey) {
+        // REORDER: wrapper (workflowId, topic, payload) → raw send(destinationID, message, topic, idempotencyKey).
+        return DBOS.send(workflowId, payload, topic, idempotencyKey);
+    }
+    /**
+     * Durable human wait — MUST be called from inside a registered workflow body.
+     * Default DBOS recv timeout is 60 s; pass a far-future deadline so the gate waits indefinitely.
+     * The deadline is a fixed constant (GATE_DEADLINE_EPOCH_MS), never Date.now()+X — that would
+     * differ per replay and break DBOS replay-safety (G5).
+     */
+    awaitDecision(topic, opts) {
+        return DBOS.recv(topic, { deadlineEpochMS: opts?.deadlineEpochMS ?? GATE_DEADLINE_EPOCH_MS });
+    }
+    // ── end generic engine verbs ────────────────────────────────────────────────
+    /**
+     * Configure DBOS with the pid-proven system database URL.
+     * Must be called before launch().
+     */
+    setConfig(systemDatabaseUrl, options = {}) {
+        DBOS.setConfig({
+            name: 'agent-orchestrator',
+            systemDatabaseUrl,
+            ...(options.logLevel ? { logLevel: options.logLevel } : {}),
+        });
+    }
+    /**
+     * Launch DBOS (idempotent — guarded by `launched` flag).
+     * Auto-recovers in-flight workflows.
+     */
+    async launch() {
+        if (this.launched)
+            return;
+        await DBOS.launch();
+        this.launched = true;
+    }
+    /**
+     * Shut down DBOS (no-op if never launched — E9).
+     *
+     * 0008 #3 (shutdown-hang): DBOS.shutdown() awaits in-flight workflows to drain. A workflow
+     * PARKED at a human gate (DBOS.recv) never drains, so after `run start --wait` detaches at a
+     * gate, app.close() → this → DBOS.shutdown() blocks indefinitely and the CLI never exits.
+     * We race the drain against SHUTDOWN_DRAIN_TIMEOUT_MS: on timeout we stop awaiting and let the
+     * host detach. Durability is preserved — the parked workflow's state is checkpointed in
+     * Postgres and is recovered on the next launch(); abandoning the in-memory drain loses nothing.
+     *
+     * @param timeoutMs - drain bound (default SHUTDOWN_DRAIN_TIMEOUT_MS); pass 0/Infinity to disable.
+     */
+    async shutdown(timeoutMs = SHUTDOWN_DRAIN_TIMEOUT_MS) {
+        if (!this.launched)
+            return;
+        // Mark not-launched up front so a timed-out drain cannot leave a re-entrant launch confused.
+        this.launched = false;
+        const drain = DBOS.shutdown();
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            await drain;
+            return;
+        }
+        // Swallow a late drain rejection so a post-detach failure never crashes the exiting host.
+        void drain.catch(() => undefined);
+        let timer;
+        const drained = await Promise.race([
+            drain.then(() => true).catch(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        if (!drained) {
+            console.warn(`[dbos] shutdown drain exceeded ${timeoutMs}ms (likely a workflow parked at a human gate); ` +
+                'detaching — durable state is preserved and recovered on next launch.');
+        }
+    }
+    /**
+     * Start the dev:ping durable workflow.
+     *
+     * CR3: The effective workflow ID is decided in ONE place (the CLI layer — dev.ts) and
+     * must always be non-empty before calling this method. This keeps StartWorkflowParams
+     * and the workflow args consistent: both see the same stable, non-empty id, so
+     * PingResult.workflowID and marker identity are never empty.
+     *
+     * @param workflowID  - Stable, non-empty id (sanitized by the caller — CR1/CR3).
+     * @param sleepMs     - Duration of step2 sleep (default 15 000 ms).
+     * @param markerFile  - Path to the durable marker file written by step1.
+     */
+    async startPingWorkflow(workflowID, sleepMs, markerFile) {
+        return DBOS.startWorkflow(this.pingWorkflow, { workflowID })(workflowID, sleepMs, markerFile);
+    }
+    /**
+     * Get the current status of a workflow by id.
+     */
+    getWorkflowStatus(id) {
+        return DBOS.getWorkflowStatus(id);
+    }
+    /**
+     * Recover-and-wait: retrieve an existing workflow handle and await its result.
+     * Used by `dev:status <id>` — the resume-test command (E10, F2).
+     * `DBOS.retrieveWorkflow()` always returns a handle even if the workflow does not exist yet.
+     *
+     * @deprecated Use `waitForWorkflowResult<T>` for typed workflows. Kept for ping backward compat.
+     */
+    async waitForWorkflow(id) {
+        const handle = DBOS.retrieveWorkflow(id);
+        return handle.getResult();
+    }
+    /**
+     * Generic recover-and-wait: retrieve a workflow handle by id and await its typed result.
+     * Used by `run start` to await workflow completion (C2 fix — so the CLI process does not
+     * close before the workflow finishes). Also used for crash-resume: re-running `run start <id>`
+     * re-attaches to the existing handle and waits for it to finish — not a double-enqueue.
+     *
+     * `DBOS.retrieveWorkflow()` always returns a handle (even for a workflow that does not exist yet),
+     * so callers should confirm the workflow exists (via `getWorkflowStatus`) before calling this if
+     * they want to distinguish "not found" from "in progress".
+     */
+    async waitForWorkflowResult(id) {
+        const handle = DBOS.retrieveWorkflow(id);
+        return handle.getResult();
+    }
+};
+DbosService = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [])
+], DbosService);
+export { DbosService };
+//# sourceMappingURL=dbos.service.js.map

package/dist/engine/dbos.service.js.map

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

package/dist/engine/ensure-postgres.js

@@ -0,0 +1,80 @@
+/**
+ * ensurePostgres() — creates the `dbos` database in Revisium's embedded Postgres if absent.
+ *
+ * Idempotent: checks pg_database first; only issues CREATE DATABASE when absent.
+ * Uses the pid-proven pg port from runtime.json (never hardcodes it — ADR-0001 #4).
+ *
+ * PG creds default: `revisium`/`password` — confirmed from @revisium/standalone 2.8.2 (F5).
+ * Kept parameterized so a future config change is one line.
+ *
+ * Race safety (F17): Two concurrent first-run hosts may both observe count=0 and both issue
+ * CREATE DATABASE. PostgreSQL raises SQLSTATE 42P04 (duplicate_database) for the loser.
+ * We catch 42P04 and treat it as success — the database now exists, which is the desired
+ * postcondition. All other errors are re-thrown verbatim.
+ *
+ * Testability (F20): ensurePostgres accepts an optional `deps.createClient` factory so tests
+ * can inject a fake client that exercises the real 42P04 catch / SELECT fast-path without a
+ * live Postgres. The production default constructs a real `pg.Client`.
+ */
+import pg from 'pg';
+const DBOS_DB_NAME = 'dbos';
+const MAINTENANCE_DB = 'postgres';
+/** PostgreSQL SQLSTATE for "database already exists" (duplicate_database). */
+const PG_SQLSTATE_DUPLICATE_DATABASE = '42P04';
+const DEFAULT_CREDS = {
+    user: 'revisium',
+    password: 'password',
+    adminDb: MAINTENANCE_DB,
+};
+/**
+ * Ensure the `dbos` database exists on the Revisium embedded Postgres.
+ * @param pgPort - The pid-proven pg port from runtime.json.
+ * @param opts   - Optional credential overrides (default: revisium/password).
+ * @param deps   - Optional injectable dependencies for testing (F20).
+ */
+export async function ensurePostgres(pgPort, opts = {}, deps = {}) {
+    const { user, password, adminDb } = { ...DEFAULT_CREDS, ...opts };
+    // pg.Client.connect() returns Promise<Client> while ClientLike.connect() returns
+    // Promise<void>; they are structurally compatible at the call sites used here, but
+    // TypeScript requires an explicit cast via unknown to bridge the return-type difference.
+    const pgClientFactory = () => new pg.Client({ host: 'localhost', port: pgPort, user, password, database: adminDb });
+    const createClient = deps.createClient ?? pgClientFactory;
+    const client = createClient();
+    try {
+        await client.connect();
+        const result = await client.query(`SELECT count(*)::text AS count FROM pg_database WHERE datname = $1`, [DBOS_DB_NAME]);
+        const exists = result.rows[0]?.count !== '0';
+        if (!exists) {
+            // CREATE DATABASE cannot be parameterized; `dbos` is a fixed literal with no injection surface.
+            // Race backstop (F17): if two hosts both observed count=0 and both issue CREATE DATABASE,
+            // PostgreSQL raises 42P04 (duplicate_database) for the loser. Treat it as success
+            // (idempotent — the database now exists). Re-throw any other error.
+            try {
+                await client.query(`CREATE DATABASE ${DBOS_DB_NAME}`);
+            }
+            catch (err) {
+                if (err.code === PG_SQLSTATE_DUPLICATE_DATABASE) {
+                    // Another concurrent host already created it — this is fine.
+                    return;
+                }
+                throw err;
+            }
+        }
+    }
+    finally {
+        await client.end();
+    }
+}
+/**
+ * Build the DBOS system database URL from the pid-proven pg port.
+ * Single place; never hardcodes the port.
+ *
+ * CR4: user and password are percent-encoded via encodeURIComponent so that
+ * reserved characters (e.g. '@', ':', '/', '%') do not break the URI.
+ * The default credentials ('revisium'/'password') contain no reserved chars
+ * and encode to themselves, so existing behaviour is unchanged.
+ */
+export function dbosSystemDatabaseUrl(pgPort, user = 'revisium', password = 'password') {
+    return `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}@localhost:${pgPort}/${DBOS_DB_NAME}`;
+}
+//# sourceMappingURL=ensure-postgres.js.map

package/dist/engine/ensure-postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-postgres.js","sourceRoot":"","sources":["../../src/engine/ensure-postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,MAAM,YAAY,GAAG,MAAM,CAAC;AAC5B,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC,8EAA8E;AAC9E,MAAM,8BAA8B,GAAG,OAAO,CAAC;AAQ/C,MAAM,aAAa,GAAwB;IACzC,IAAI,EAAE,UAAU;IAChB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,cAAc;CACxB,CAAC;AAkBF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,OAAqC,EAAE,EACvC,OAA2B,EAAE;IAE7B,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,aAAa,EAAE,GAAG,IAAI,EAAE,CAAC;IAClE,iFAAiF;IACjF,mFAAmF;IACnF,yFAAyF;IACzF,MAAM,eAAe,GAAG,GAAe,EAAE,CACvC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,CAA0B,CAAC;IACjH,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,eAAe,CAAC;IAE1D,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAE9B,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B,oEAAoE,EACpE,CAAC,YAAY,CAAC,CACf,CAAC;QACF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,GAAG,CAAC;QAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,gGAAgG;YAChG,0FAA0F;YAC1F,kFAAkF;YAClF,oEAAoE;YACpE,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,CAAC,mBAAmB,YAAY,EAAE,CAAC,CAAC;YACxD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAK,GAAyB,CAAC,IAAI,KAAK,8BAA8B,EAAE,CAAC;oBACvE,6DAA6D;oBAC7D,OAAO;gBACT,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc,EACd,IAAI,GAAG,UAAU,EACjB,QAAQ,GAAG,UAAU;IAErB,OAAO,gBAAgB,kBAAkB,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC,QAAQ,CAAC,cAAc,MAAM,IAAI,YAAY,EAAE,CAAC;AACxH,CAAC"}

package/dist/engine/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/engine/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":""}