@dxo/inspect 0.0.0 → 0.0.9

package/README.md

@@ -1,3 +1,7 @@
 # @dxo/inspect
 
-Placeholder package (0.0.0). Reserved for the DXO project.
+**Placeholder — developer preview, API unstable.**
+
+Run / metric / artifact / profile **protocol types** for Studio and Trainer adapters. Does not depend on VMZ. Append-only run store and live transport arrive in later U1 slices.
+
+See workspace Living design for contracts (`inspect` / Studio product line).

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @dxo/inspect — Run / metric / artifact / profile protocols (v0).
+ */
+export { type ArtifactKindV0, type ArtifactV0, INSPECT_PROTOCOL, INSPECT_PROTOCOL_VERSION, type InspectEventV0, inspectVersion, type MetricV0, type ProfileSpan, type ProfileTraceV0, type RunMetaV0, type RunStatus, } from './schemas.js';
+export type { RunRecorderOptions, RunSummary } from './store.js';
+export { defaultRunsRoot, listRuns, RunRecorder, readEvents, readRunMeta } from './store.js';
+export type { RecordTrainIterOptions, TrainEventLike } from './train-adapter.js';
+export { recordTrainIter, trainEventToInspectEvents } from './train-adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACH,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @dxo/inspect — Run / metric / artifact / profile protocols (v0).
+ */
+export { INSPECT_PROTOCOL, INSPECT_PROTOCOL_VERSION, inspectVersion, } from './schemas.js';
+export { defaultRunsRoot, listRuns, RunRecorder, readEvents, readRunMeta } from './store.js';
+export { recordTrainIter, trainEventToInspectEvents } from './train-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAGH,gBAAgB,EAChB,wBAAwB,EAExB,cAAc,GAMjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,89 @@
+export declare const INSPECT_PROTOCOL: "dxo-inspect";
+export declare const INSPECT_PROTOCOL_VERSION: 0;
+export type RunStatus = 'running' | 'ok' | 'cancelled' | 'error';
+export type RunMetaV0 = {
+    format: typeof INSPECT_PROTOCOL;
+    version: typeof INSPECT_PROTOCOL_VERSION;
+    runId: string;
+    startedAtMs: number;
+    endedAtMs?: number;
+    label?: string;
+    status: RunStatus;
+    hyperparams?: Record<string, unknown>;
+};
+export type MetricV0 = {
+    name: string;
+    value: number;
+    step: number;
+    wallTimeMs: number;
+};
+export type ArtifactKindV0 = 'checkpoint' | 'state' | 'other';
+export type ArtifactV0 = {
+    name: string;
+    kind: ArtifactKindV0;
+    uri: string;
+    digest?: string;
+    wallTimeMs: number;
+};
+export type InspectEventV0 = {
+    type: 'run/start';
+    runId: string;
+    wallTimeMs: number;
+    meta?: Record<string, unknown>;
+} | {
+    type: 'run/end';
+    runId: string;
+    wallTimeMs: number;
+    status: Exclude<RunStatus, 'running'>;
+    error?: string;
+} | {
+    type: 'train/epoch_start';
+    runId: string;
+    wallTimeMs: number;
+    epoch: number;
+    epochs: number;
+} | {
+    type: 'train/batch';
+    runId: string;
+    wallTimeMs: number;
+    epoch: number;
+    step: number;
+    loss: number;
+} | {
+    type: 'train/epoch_end';
+    runId: string;
+    wallTimeMs: number;
+    epoch: number;
+    meanLoss: number;
+    steps: number;
+} | {
+    type: 'metric/scalar';
+    runId: string;
+    wallTimeMs: number;
+    metric: MetricV0;
+} | {
+    type: 'artifact/ref';
+    runId: string;
+    wallTimeMs: number;
+    artifact: ArtifactV0;
+} | {
+    type: 'log';
+    runId: string;
+    wallTimeMs: number;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+};
+export type ProfileSpan = {
+    name: string;
+    category: 'op' | 'kernel' | 'transfer' | 'readback' | 'other';
+    startMs: number;
+    endMs: number;
+    meta?: Record<string, unknown>;
+};
+export type ProfileTraceV0 = {
+    format: 'dxo-profile';
+    version: 0;
+    spans: ProfileSpan[];
+};
+export declare function inspectVersion(): string;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

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

package/dist/schemas.js

@@ -0,0 +1,6 @@
+export const INSPECT_PROTOCOL = 'dxo-inspect';
+export const INSPECT_PROTOCOL_VERSION = 0;
+export function inspectVersion() {
+    return `${INSPECT_PROTOCOL}@${INSPECT_PROTOCOL_VERSION}`;
+}
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAsB,CAAC;AACvD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAU,CAAC;AAwDnD,MAAM,UAAU,cAAc;IAC1B,OAAO,GAAG,gBAAgB,IAAI,wBAAwB,EAAE,CAAC;AAC7D,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,29 @@
+import { type ArtifactKindV0, type InspectEventV0, type RunMetaV0, type RunStatus } from './schemas.js';
+export type RunRecorderOptions = {
+    /** Root directory; default `{cwd}/.dxo/runs` or `DXO_RUNS_DIR`. */
+    root?: string;
+    runId?: string;
+    label?: string;
+    hyperparams?: Record<string, unknown>;
+};
+export type RunSummary = {
+    runId: string;
+    meta: RunMetaV0;
+};
+export declare function defaultRunsRoot(): string;
+export declare class RunRecorder {
+    #private;
+    readonly runId: string;
+    readonly root: string;
+    readonly runPath: string;
+    private constructor();
+    static open(options?: RunRecorderOptions): Promise<RunRecorder>;
+    append(event: InspectEventV0): Promise<void>;
+    /** Write artifact bytes and emit artifact/ref. Returns relative URI under run dir. */
+    writeArtifact(name: string, kind: ArtifactKindV0, body: string): Promise<string>;
+    close(status: Exclude<RunStatus, 'running'>, error?: string): Promise<void>;
+}
+export declare function listRuns(root?: string): Promise<RunSummary[]>;
+export declare function readRunMeta(root: string, runId: string): Promise<RunMetaV0 | null>;
+export declare function readEvents(root: string, runId: string): Promise<InspectEventV0[]>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAGA,OAAO,EACH,KAAK,cAAc,EAGnB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,EACjB,MAAM,cAAc,CAAC;AAMtB,MAAM,MAAM,kBAAkB,GAAG;IAC7B,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;CACnB,CAAC;AAMF,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAMD,qBAAa,WAAW;;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAIzB,OAAO;WAOM,IAAI,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BnE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD,sFAAsF;IAChF,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBhF,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAcpF;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,MAA0B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CActF;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAOxF;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAUvF"}

package/dist/store.js

@@ -0,0 +1,137 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { INSPECT_PROTOCOL, INSPECT_PROTOCOL_VERSION, } from './schemas.js';
+const EVENTS_FILE = 'events.jsonl';
+const META_FILE = 'meta.json';
+const ARTIFACTS_DIR = 'artifacts';
+function nowMs() {
+    return Date.now();
+}
+export function defaultRunsRoot() {
+    const fromEnv = process.env.DXO_RUNS_DIR?.trim();
+    if (fromEnv)
+        return path.resolve(fromEnv);
+    return path.resolve(process.cwd(), '.dxo', 'runs');
+}
+function runDir(root, runId) {
+    return path.join(root, runId);
+}
+export class RunRecorder {
+    runId;
+    root;
+    runPath;
+    #closed = false;
+    #meta;
+    constructor(root, runId, meta) {
+        this.root = root;
+        this.runId = runId;
+        this.runPath = runDir(root, runId);
+        this.#meta = meta;
+    }
+    static async open(options = {}) {
+        const root = options.root ?? defaultRunsRoot();
+        const runId = options.runId ?? randomUUID();
+        const startedAtMs = nowMs();
+        const meta = {
+            format: INSPECT_PROTOCOL,
+            version: INSPECT_PROTOCOL_VERSION,
+            runId,
+            startedAtMs,
+            label: options.label,
+            status: 'running',
+            hyperparams: options.hyperparams,
+        };
+        const dir = runDir(root, runId);
+        await mkdir(path.join(dir, ARTIFACTS_DIR), { recursive: true });
+        await writeFile(path.join(dir, META_FILE), `${JSON.stringify(meta, null, 2)}\n`, 'utf8');
+        const recorder = new RunRecorder(root, runId, meta);
+        await recorder.append({
+            type: 'run/start',
+            runId,
+            wallTimeMs: startedAtMs,
+            meta: options.hyperparams,
+        });
+        return recorder;
+    }
+    async append(event) {
+        if (this.#closed)
+            throw new Error(`run ${this.runId} is closed`);
+        const line = `${JSON.stringify(event)}\n`;
+        await appendFile(path.join(this.runPath, EVENTS_FILE), line, 'utf8');
+    }
+    /** Write artifact bytes and emit artifact/ref. Returns relative URI under run dir. */
+    async writeArtifact(name, kind, body) {
+        const rel = path.join(ARTIFACTS_DIR, name);
+        const abs = path.join(this.runPath, rel);
+        await writeFile(abs, body, 'utf8');
+        const digest = createHash('sha256').update(body).digest('hex');
+        await this.append({
+            type: 'artifact/ref',
+            runId: this.runId,
+            wallTimeMs: nowMs(),
+            artifact: {
+                name,
+                kind,
+                uri: rel.replace(/\\/g, '/'),
+                digest,
+                wallTimeMs: nowMs(),
+            },
+        });
+        return rel;
+    }
+    async close(status, error) {
+        if (this.#closed)
+            return;
+        const endedAtMs = nowMs();
+        this.#meta = { ...this.#meta, status, endedAtMs };
+        await writeFile(path.join(this.runPath, META_FILE), `${JSON.stringify(this.#meta, null, 2)}\n`, 'utf8');
+        await this.append({
+            type: 'run/end',
+            runId: this.runId,
+            wallTimeMs: endedAtMs,
+            status,
+            error,
+        });
+        this.#closed = true;
+    }
+}
+export async function listRuns(root = defaultRunsRoot()) {
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const runId of entries) {
+        const meta = await readRunMeta(root, runId);
+        if (meta)
+            out.push({ runId, meta });
+    }
+    out.sort((a, b) => b.meta.startedAtMs - a.meta.startedAtMs);
+    return out;
+}
+export async function readRunMeta(root, runId) {
+    try {
+        const text = await readFile(path.join(runDir(root, runId), META_FILE), 'utf8');
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readEvents(root, runId) {
+    try {
+        const text = await readFile(path.join(runDir(root, runId), EVENTS_FILE), 'utf8');
+        return text
+            .split('\n')
+            .filter((line) => line.trim().length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/train-adapter.d.ts

@@ -0,0 +1,46 @@
+import type { InspectEventV0 } from './schemas.js';
+import { RunRecorder, type RunRecorderOptions } from './store.js';
+/** Minimal TrainEvent shape (matches @dxo/train without a hard dependency). */
+export type TrainEventLike = {
+    type: 'epoch_start';
+    epoch: number;
+    epochs: number;
+} | {
+    type: 'batch';
+    epoch: number;
+    step: number;
+    loss: number;
+} | {
+    type: 'epoch_end';
+    epoch: number;
+    meanLoss: number;
+    steps: number;
+} | {
+    type: 'checkpoint';
+    epoch: number;
+    document: unknown;
+    state: unknown;
+} | {
+    type: 'aborted';
+    reason: 'signal';
+    epoch: number;
+    step: number;
+} | {
+    type: 'done';
+    epochs: number;
+    steps: number;
+    finalMeanLoss?: number;
+};
+export declare function trainEventToInspectEvents(runId: string, event: TrainEventLike): InspectEventV0[];
+export type RecordTrainIterOptions = RunRecorderOptions & {
+    checkpointEncoder?: (document: unknown) => string;
+};
+/**
+ * Consume a Trainer fitIter stream and append inspect events to the local run store.
+ */
+export declare function recordTrainIter(events: AsyncIterable<TrainEventLike>, options?: RecordTrainIterOptions): Promise<{
+    runId: string;
+    recorder: RunRecorder;
+    status: 'ok' | 'cancelled';
+}>;
+//# sourceMappingURL=train-adapter.d.ts.map

package/dist/train-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"train-adapter.d.ts","sourceRoot":"","sources":["../src/train-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAElE,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GACpB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrE;IACI,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAClB,GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAM9E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,EAAE,CA8DhG;AAED,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,GAAG;IACtD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,CAAC;CACrD,CAAC;AAEF;;GAEG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,OAAO,GAAE,sBAA2B,GACrC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,IAAI,GAAG,WAAW,CAAA;CAAE,CAAC,CA0B/E"}

package/dist/train-adapter.js

@@ -0,0 +1,97 @@
+import { RunRecorder } from './store.js';
+function wallTimeMs() {
+    return Date.now();
+}
+export function trainEventToInspectEvents(runId, event) {
+    const t = wallTimeMs();
+    switch (event.type) {
+        case 'epoch_start':
+            return [{ type: 'train/epoch_start', runId, wallTimeMs: t, epoch: event.epoch, epochs: event.epochs }];
+        case 'batch':
+            return [
+                { type: 'train/batch', runId, wallTimeMs: t, epoch: event.epoch, step: event.step, loss: event.loss },
+                {
+                    type: 'metric/scalar',
+                    runId,
+                    wallTimeMs: t,
+                    metric: { name: 'loss', value: event.loss, step: event.step, wallTimeMs: t },
+                },
+            ];
+        case 'epoch_end':
+            return [
+                {
+                    type: 'train/epoch_end',
+                    runId,
+                    wallTimeMs: t,
+                    epoch: event.epoch,
+                    meanLoss: event.meanLoss,
+                    steps: event.steps,
+                },
+                {
+                    type: 'metric/scalar',
+                    runId,
+                    wallTimeMs: t,
+                    metric: {
+                        name: 'mean_loss',
+                        value: event.meanLoss,
+                        step: event.epoch,
+                        wallTimeMs: t,
+                    },
+                },
+            ];
+        case 'aborted':
+            return [
+                {
+                    type: 'log',
+                    runId,
+                    wallTimeMs: t,
+                    level: 'warn',
+                    message: `training aborted at epoch ${event.epoch} step ${event.step}`,
+                },
+            ];
+        case 'done':
+            return [
+                {
+                    type: 'log',
+                    runId,
+                    wallTimeMs: t,
+                    level: 'info',
+                    message: `training done: epochs=${event.epochs} steps=${event.steps}`,
+                },
+            ];
+        case 'checkpoint':
+            return [];
+        default:
+            return [];
+    }
+}
+/**
+ * Consume a Trainer fitIter stream and append inspect events to the local run store.
+ */
+export async function recordTrainIter(events, options = {}) {
+    const recorder = await RunRecorder.open(options);
+    const encoder = options.checkpointEncoder ?? ((doc) => JSON.stringify(doc));
+    let status = 'ok';
+    try {
+        for await (const event of events) {
+            if (event.type === 'checkpoint') {
+                const name = `checkpoint-epoch-${event.epoch}.json`;
+                await recorder.writeArtifact(name, 'checkpoint', encoder(event.document));
+            }
+            if (event.type === 'aborted') {
+                status = 'cancelled';
+            }
+            for (const inspectEvent of trainEventToInspectEvents(recorder.runId, event)) {
+                await recorder.append(inspectEvent);
+            }
+        }
+        await recorder.close(status);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await recorder.close('error', message);
+        throw err;
+    }
+    return { runId: recorder.runId, recorder, status };
+}
+//# sourceMappingURL=train-adapter.js.map

package/dist/train-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"train-adapter.js","sourceRoot":"","sources":["../src/train-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAA2B,MAAM,YAAY,CAAC;AAgBlE,SAAS,UAAU;IACf,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAa,EAAE,KAAqB;IAC1E,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;IACvB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,aAAa;YACd,OAAO,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3G,KAAK,OAAO;YACR,OAAO;gBACH,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;gBACrG;oBACI,IAAI,EAAE,eAAe;oBACrB,KAAK;oBACL,UAAU,EAAE,CAAC;oBACb,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;iBAC/E;aACJ,CAAC;QACN,KAAK,WAAW;YACZ,OAAO;gBACH;oBACI,IAAI,EAAE,iBAAiB;oBACvB,KAAK;oBACL,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;iBACrB;gBACD;oBACI,IAAI,EAAE,eAAe;oBACrB,KAAK;oBACL,UAAU,EAAE,CAAC;oBACb,MAAM,EAAE;wBACJ,IAAI,EAAE,WAAW;wBACjB,KAAK,EAAE,KAAK,CAAC,QAAQ;wBACrB,IAAI,EAAE,KAAK,CAAC,KAAK;wBACjB,UAAU,EAAE,CAAC;qBAChB;iBACJ;aACJ,CAAC;QACN,KAAK,SAAS;YACV,OAAO;gBACH;oBACI,IAAI,EAAE,KAAK;oBACX,KAAK;oBACL,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE,MAAM;oBACb,OAAO,EAAE,6BAA6B,KAAK,CAAC,KAAK,SAAS,KAAK,CAAC,IAAI,EAAE;iBACzE;aACJ,CAAC;QACN,KAAK,MAAM;YACP,OAAO;gBACH;oBACI,IAAI,EAAE,KAAK;oBACX,KAAK;oBACL,UAAU,EAAE,CAAC;oBACb,KAAK,EAAE,MAAM;oBACb,OAAO,EAAE,yBAAyB,KAAK,CAAC,MAAM,UAAU,KAAK,CAAC,KAAK,EAAE;iBACxE;aACJ,CAAC;QACN,KAAK,YAAY;YACb,OAAO,EAAE,CAAC;QACd;YACI,OAAO,EAAE,CAAC;IAClB,CAAC;AACL,CAAC;AAMD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACjC,MAAqC,EACrC,UAAkC,EAAE;IAEpC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5E,IAAI,MAAM,GAAuB,IAAI,CAAC;IAEtC,IAAI,CAAC;QACD,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC9B,MAAM,IAAI,GAAG,oBAAoB,KAAK,CAAC,KAAK,OAAO,CAAC;gBACpD,MAAM,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC9E,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,GAAG,WAAW,CAAC;YACzB,CAAC;YACD,KAAK,MAAM,YAAY,IAAI,yBAAyB,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;gBAC1E,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YACxC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACX,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACvC,MAAM,GAAG,CAAC;IACd,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/package.json

@@ -1,10 +1,36 @@
 {
-  "name": "@dxo/inspect",
-  "version": "0.0.0",
-  "description": "DXO placeholder — not for production use.",
-  "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
-  ]
+    "name": "@dxo/inspect",
+    "version": "0.0.9",
+    "type": "module",
+    "description": "DXO run / metric / artifact / profile event protocols (placeholder, API unstable)",
+    "license": "MIT OR Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json"
+    },
+    "keywords": [
+        "dxo",
+        "inspect",
+        "metrics",
+        "profiler",
+        "typescript"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ai4waifu/dxo-framework.git"
+    }
 }