@nimbus-sh/platform 0.1.0

package/dist/oom-discriminator.d.ts

@@ -0,0 +1,176 @@
+/**
+ * oom-discriminator.ts — singleton ring buffer for OOM / failure
+ * forensics + last-known-RPC-frame + last-known-facet-id +
+ * session-recovery-event ring, plus snapshot/rehydrate hooks for DO
+ * storage persistence.
+ *
+ * W5 (Lever 5 / J.1.1) — original module. Pairs with oom-classify.ts.
+ * C'.2 — added the recovery_event ring.
+ *
+ * Why singleton-per-isolate
+ * ─────────────────────────
+ * Same pattern as src/observability/diag-counters.ts. The supervisor bundle
+ * is the consumer; all writers (sqlite-vfs, facet-pool, facet-manager,
+ * supervisor-rpc, npm-installer, nimbus-session) live in the same
+ * isolate. Module scope provides one process-local diagnostic without
+ * threading a handle through each writer.
+ *
+ * Two distinct rings
+ * ──────────────────
+ * - failures: things that failed (the original W5 ring).
+ * - recoveryEvents: lifecycle transitions of the session. Cold isolate
+ *   boot → 'cold' → 'hydrated' → 'active' → 'drained'.
+ *
+ * Bounded-size guarantees
+ * ───────────────────────
+ *   - failures ring: 50 entries (RING_SIZE).
+ *   - recoveryEvents ring: 50 entries (RECOVERY_RING_SIZE).
+ *   - per-message cap: 200 chars (truncated at insert).
+ *   - per-RPC-frame: single slot, one object.
+ *   - per-facet-id: single slot, one object.
+ *
+ * Snapshot size stays bounded even with both rings full.
+ */
+import { type OomCause } from './oom-classify.js';
+export interface RpcFrame {
+    method: string;
+    payloadBytes: number;
+    atMs: number;
+}
+export interface FacetId {
+    codeId: string;
+    slotIndex: number;
+    atMs: number;
+}
+export interface DiagFailure {
+    /** ms epoch */
+    at: number;
+    /** Lifecycle stage (e.g. 'install', 'resolve', 'rpc', 'facet', 'ws'). */
+    phase: string;
+    /** Discriminated cause. See oom-classify.ts. */
+    cause: OomCause;
+    /** Best-effort RSS estimate in bytes (peak observed). */
+    rssEstimateBytes: number;
+    /** process.memoryUsage().heapUsed if available; 0 in DO contexts. */
+    heapUsedBytes: number;
+    /** SqliteVFS LRU hot bytes at time of failure. */
+    lruBytes: number;
+    /** Sum of in-flight RPC payload bytes (best-effort). */
+    inFlightBytes: number;
+    /** Snapshot of the most recent RPC frame, if any. */
+    lastRpcFrame: RpcFrame | null;
+    /** Snapshot of the most recent facet dispatch, if any. */
+    lastFacetId: FacetId | null;
+    /** Optional facet exit code (when failure represents a facet termination). */
+    exitCode?: number;
+    /** Optional facet pid. */
+    pid?: number;
+    /** Free-form message; truncated to MESSAGE_CAP characters. */
+    message?: string;
+}
+/**
+ * Session lifecycle states for the C'.2 recovery_event ring.
+ *
+ * This module records state-machine transitions; it does not enforce them.
+ *
+ * State semantics:
+ * - 'cold'      : fresh DO instance, no in-memory session state yet.
+ * - 'hydrated'  : Phase R completed — SQL state read into in-memory cache.
+ * - 'active'    : Phase B+W+O completed — kernel/shell/terminal wired.
+ * - 'drained'   : webSocketError/Close fired; in-memory caches nulled,
+ *                 SQL state freshly persisted; awaiting next reconnect.
+ *
+ * Trigger labels: human-readable event that caused the transition.
+ * Examples: 'first-fetch', 'ws-upgrade', 'ws-close', 'ws-error',
+ * 'isolate-evicted', 'manual-test'.
+ */
+/** Session state union.
+ *
+ * The original four are the high-level lifecycle markers:
+ *   cold     — never inited
+ *   hydrated — re-init complete (warm path; Phase O skipped)
+ *   active   — live shell processing input
+ *   drained  — webSocketError/Close fired; SQL freshly persisted
+ *
+ * The four [B'.4] additions are the fine-grained phases of
+ * initSession itself, recorded as the function progresses:
+ *   rehydrate — Phase R: loading state from DO SQLite
+ *   build     — Phase B: constructing Kernel/Shell/registry
+ *   wire      — Phase W: attaching terminal, replaying scrollback
+ *   online    — Phase O: cold-start MOTD + starter hint (cold only;
+ *               on warm re-init this phase is skipped and the
+ *               initSession ends with 'hydrated' instead)
+ *
+ * The phase transitions are SUPPLEMENTAL to the high-level markers,
+ * not a replacement. Probes that look for the legacy `'hydrated'`
+ * marker continue to work; probes that want fine-grained debugging
+ * can grep for the phase states.
+ */
+export type SessionState = 'cold' | 'hydrated' | 'active' | 'drained' | 'rehydrate' | 'build' | 'wire' | 'online';
+export interface DiagRecoveryEvent {
+    /** ms epoch */
+    at: number;
+    /** Source state. */
+    fromState: SessionState;
+    /** Destination state. */
+    toState: SessionState;
+    /** Human-readable trigger ('ws-close', 'isolate-evicted', etc.). */
+    trigger: string;
+    /** The isolate generation at the time of the event. Lets a probe detect the
+     *  difference between an in-isolate transition and a cross-isolate one
+     *  (the latter implies workerd recycled the DO). */
+    isolateGen: number;
+    /** True when the transition could not preserve state that should
+     *  have survived (e.g. SQL persist threw or a snapshot was missing). */
+    dataLoss: boolean;
+    /** Number of SQL keys/rows rehydrated on a hydrated transition.
+     *  Zero when the transition is one that doesn't read SQL. */
+    snapshotKeysRehydrated: number;
+    /** Optional free-form notes (200 char cap). */
+    notes?: string;
+}
+/** Append a failure to the ring. Newest first. Capped at RING_SIZE. */
+export declare function recordFailure(f: DiagFailure): void;
+/** Read a snapshot of the ring. Newest first. Caller-side mutations
+ *  do not affect the singleton. */
+export declare function getFailures(): DiagFailure[];
+/** Record the current RPC frame (called at every RPC entry). Bounded
+ *  to a single slot — the LATEST frame wins. */
+export declare function setLastRpcFrame(method: string, payloadBytes: number): void;
+export declare function getLastRpcFrame(): RpcFrame | null;
+/** Record the most recent facet dispatch. */
+export declare function setLastFacetId(codeId: string, slotIndex: number): void;
+export declare function getLastFacetId(): FacetId | null;
+/** Append a recovery event to the ring. Newest first. Capped at
+ *  RECOVERY_RING_SIZE. */
+export declare function recordRecoveryEvent(e: DiagRecoveryEvent): void;
+/** Read a snapshot of the recovery ring. Newest first. */
+export declare function getRecoveryEvents(): DiagRecoveryEvent[];
+/** Reset the recovery ring. Tests + manual operator use only. */
+export declare function resetRecoveryEvents(): void;
+/**
+ * Build a JSON-serializable snapshot suitable for ctx.storage.put.
+ * Bounded ≤ 40 KB even with both rings full of MESSAGE_CAP-truncated
+ * messages. Schema version embedded so a future shape change can
+ * cleanly reject old snapshots.
+ *
+ * Schema version 2 includes both failure and recovery-event rings.
+ */
+export interface DiagSnapshot {
+    /** Schema version. Bump when shape changes. */
+    v: 2;
+    failures: DiagFailure[];
+    recoveryEvents: DiagRecoveryEvent[];
+    lastRpcFrame: RpcFrame | null;
+    lastFacetId: FacetId | null;
+}
+export declare function snapshotForStorage(): DiagSnapshot;
+/**
+ * Restore from a snapshot. Garbage / null / wrong-shape input is
+ * silently ignored. Does NOT throw — constructor-time rehydration must
+ * never block DO startup.
+ *
+ * Only the current v2 schema is accepted.
+ */
+export declare function rehydrateFromStorage(blob: unknown): void;
+//# sourceMappingURL=oom-discriminator.d.ts.map

package/dist/oom-discriminator.d.ts.map

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

package/dist/oom-discriminator.js

@@ -0,0 +1,272 @@
+/**
+ * oom-discriminator.ts — singleton ring buffer for OOM / failure
+ * forensics + last-known-RPC-frame + last-known-facet-id +
+ * session-recovery-event ring, plus snapshot/rehydrate hooks for DO
+ * storage persistence.
+ *
+ * W5 (Lever 5 / J.1.1) — original module. Pairs with oom-classify.ts.
+ * C'.2 — added the recovery_event ring.
+ *
+ * Why singleton-per-isolate
+ * ─────────────────────────
+ * Same pattern as src/observability/diag-counters.ts. The supervisor bundle
+ * is the consumer; all writers (sqlite-vfs, facet-pool, facet-manager,
+ * supervisor-rpc, npm-installer, nimbus-session) live in the same
+ * isolate. Module scope provides one process-local diagnostic without
+ * threading a handle through each writer.
+ *
+ * Two distinct rings
+ * ──────────────────
+ * - failures: things that failed (the original W5 ring).
+ * - recoveryEvents: lifecycle transitions of the session. Cold isolate
+ *   boot → 'cold' → 'hydrated' → 'active' → 'drained'.
+ *
+ * Bounded-size guarantees
+ * ───────────────────────
+ *   - failures ring: 50 entries (RING_SIZE).
+ *   - recoveryEvents ring: 50 entries (RECOVERY_RING_SIZE).
+ *   - per-message cap: 200 chars (truncated at insert).
+ *   - per-RPC-frame: single slot, one object.
+ *   - per-facet-id: single slot, one object.
+ *
+ * Snapshot size stays bounded even with both rings full.
+ */
+import { isOomCause } from './oom-classify.js';
+const RING_SIZE = 50;
+const RECOVERY_RING_SIZE = 50;
+const MESSAGE_CAP = 200;
+const state = {
+    failures: [],
+    recoveryEvents: [],
+    lastRpcFrame: null,
+    lastFacetId: null,
+};
+function getState() {
+    return state;
+}
+/** Append a failure to the ring. Newest first. Capped at RING_SIZE. */
+export function recordFailure(f) {
+    const s = getState();
+    // Defensive copy + message cap.
+    const entry = {
+        at: Number(f.at) || Date.now(),
+        phase: String(f.phase ?? 'unknown'),
+        cause: f.cause,
+        rssEstimateBytes: Number(f.rssEstimateBytes) || 0,
+        heapUsedBytes: Number(f.heapUsedBytes) || 0,
+        lruBytes: Number(f.lruBytes) || 0,
+        inFlightBytes: Number(f.inFlightBytes) || 0,
+        lastRpcFrame: f.lastRpcFrame ?? s.lastRpcFrame,
+        lastFacetId: f.lastFacetId ?? s.lastFacetId,
+    };
+    if (typeof f.exitCode === 'number')
+        entry.exitCode = f.exitCode;
+    if (typeof f.pid === 'number')
+        entry.pid = f.pid;
+    if (f.message) {
+        const m = String(f.message);
+        entry.message = m.length > MESSAGE_CAP ? m.slice(0, MESSAGE_CAP) : m;
+    }
+    s.failures.unshift(entry);
+    if (s.failures.length > RING_SIZE)
+        s.failures.length = RING_SIZE;
+}
+/** Read a snapshot of the ring. Newest first. Caller-side mutations
+ *  do not affect the singleton. */
+export function getFailures() {
+    return getState().failures.slice(0);
+}
+/** Record the current RPC frame (called at every RPC entry). Bounded
+ *  to a single slot — the LATEST frame wins. */
+export function setLastRpcFrame(method, payloadBytes) {
+    const s = getState();
+    s.lastRpcFrame = {
+        method: String(method),
+        payloadBytes: Number(payloadBytes) || 0,
+        atMs: Date.now(),
+    };
+}
+export function getLastRpcFrame() {
+    return getState().lastRpcFrame;
+}
+/** Record the most recent facet dispatch. */
+export function setLastFacetId(codeId, slotIndex) {
+    const s = getState();
+    s.lastFacetId = {
+        codeId: String(codeId),
+        slotIndex: Number(slotIndex) || 0,
+        atMs: Date.now(),
+    };
+}
+export function getLastFacetId() {
+    return getState().lastFacetId;
+}
+// ── C'.2 recovery_event ring ────────────────────────────────────────────
+//
+// The ring is bounded at RECOVERY_RING_SIZE; the diag endpoint reads via
+// getRecoveryEvents() (newest first).
+/** Append a recovery event to the ring. Newest first. Capped at
+ *  RECOVERY_RING_SIZE. */
+export function recordRecoveryEvent(e) {
+    const s = getState();
+    // Defensive copy + notes cap. We intentionally do NOT validate the
+    // state-machine direction here (e.g. that 'drained' only follows
+    // 'active') — the state machine lives elsewhere; this ring is a
+    // recorder, not an enforcer. If a probe sees an impossible
+    // transition, that's a real bug in the state machine and the
+    // probe must fail.
+    const entry = {
+        at: Number(e.at) || Date.now(),
+        fromState: e.fromState,
+        toState: e.toState,
+        trigger: String(e.trigger ?? 'unknown'),
+        isolateGen: Number(e.isolateGen) || 0,
+        dataLoss: !!e.dataLoss,
+        snapshotKeysRehydrated: Number(e.snapshotKeysRehydrated) || 0,
+    };
+    if (e.notes) {
+        const n = String(e.notes);
+        entry.notes = n.length > MESSAGE_CAP ? n.slice(0, MESSAGE_CAP) : n;
+    }
+    s.recoveryEvents.unshift(entry);
+    if (s.recoveryEvents.length > RECOVERY_RING_SIZE) {
+        s.recoveryEvents.length = RECOVERY_RING_SIZE;
+    }
+}
+/** Read a snapshot of the recovery ring. Newest first. */
+export function getRecoveryEvents() {
+    return getState().recoveryEvents.slice(0);
+}
+/** Reset the recovery ring. Tests + manual operator use only. */
+export function resetRecoveryEvents() {
+    getState().recoveryEvents.length = 0;
+}
+export function snapshotForStorage() {
+    const s = getState();
+    return {
+        v: 2,
+        failures: s.failures.slice(0),
+        recoveryEvents: s.recoveryEvents.slice(0),
+        lastRpcFrame: s.lastRpcFrame,
+        lastFacetId: s.lastFacetId,
+    };
+}
+/**
+ * Restore from a snapshot. Garbage / null / wrong-shape input is
+ * silently ignored. Does NOT throw — constructor-time rehydration must
+ * never block DO startup.
+ *
+ * Only the current v2 schema is accepted.
+ */
+export function rehydrateFromStorage(blob) {
+    if (!isRecord(blob) || blob.v !== 2)
+        return;
+    const b = blob;
+    if (!Array.isArray(b.failures))
+        return;
+    const s = getState();
+    s.failures.length = 0;
+    for (const f of b.failures) {
+        const entry = parseFailure(f);
+        if (!entry)
+            continue;
+        s.failures.push(entry);
+        if (s.failures.length >= RING_SIZE)
+            break;
+    }
+    s.recoveryEvents.length = 0;
+    if (Array.isArray(b.recoveryEvents)) {
+        for (const e of b.recoveryEvents) {
+            const entry = parseRecoveryEvent(e);
+            if (!entry)
+                continue;
+            s.recoveryEvents.push(entry);
+            if (s.recoveryEvents.length >= RECOVERY_RING_SIZE)
+                break;
+        }
+    }
+    const lastRpcFrame = parseRpcFrame(b.lastRpcFrame);
+    if (lastRpcFrame)
+        s.lastRpcFrame = lastRpcFrame;
+    const lastFacetId = parseFacetId(b.lastFacetId);
+    if (lastFacetId)
+        s.lastFacetId = lastFacetId;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseRpcFrame(value) {
+    if (!isRecord(value)
+        || typeof value.method !== 'string'
+        || typeof value.payloadBytes !== 'number'
+        || typeof value.atMs !== 'number')
+        return null;
+    return { method: value.method, payloadBytes: value.payloadBytes, atMs: value.atMs };
+}
+function parseFacetId(value) {
+    if (!isRecord(value)
+        || typeof value.codeId !== 'string'
+        || typeof value.slotIndex !== 'number'
+        || typeof value.atMs !== 'number')
+        return null;
+    return { codeId: value.codeId, slotIndex: value.slotIndex, atMs: value.atMs };
+}
+function parseFailure(value) {
+    if (!isRecord(value)
+        || typeof value.at !== 'number'
+        || typeof value.phase !== 'string'
+        || !isOomCause(value.cause)
+        || typeof value.rssEstimateBytes !== 'number'
+        || typeof value.heapUsedBytes !== 'number'
+        || typeof value.lruBytes !== 'number'
+        || typeof value.inFlightBytes !== 'number')
+        return null;
+    const entry = {
+        at: value.at,
+        phase: value.phase,
+        cause: value.cause,
+        rssEstimateBytes: value.rssEstimateBytes,
+        heapUsedBytes: value.heapUsedBytes,
+        lruBytes: value.lruBytes,
+        inFlightBytes: value.inFlightBytes,
+        lastRpcFrame: parseRpcFrame(value.lastRpcFrame),
+        lastFacetId: parseFacetId(value.lastFacetId),
+    };
+    if (typeof value.exitCode === 'number')
+        entry.exitCode = value.exitCode;
+    if (typeof value.pid === 'number')
+        entry.pid = value.pid;
+    if (typeof value.message === 'string')
+        entry.message = value.message.slice(0, MESSAGE_CAP);
+    return entry;
+}
+const SESSION_STATES = [
+    'cold', 'hydrated', 'active', 'drained',
+    'rehydrate', 'build', 'wire', 'online',
+];
+function isSessionState(value) {
+    return SESSION_STATES.some((state) => state === value);
+}
+function parseRecoveryEvent(value) {
+    if (!isRecord(value)
+        || typeof value.at !== 'number'
+        || !isSessionState(value.fromState)
+        || !isSessionState(value.toState)
+        || typeof value.trigger !== 'string'
+        || typeof value.isolateGen !== 'number'
+        || typeof value.dataLoss !== 'boolean'
+        || typeof value.snapshotKeysRehydrated !== 'number')
+        return null;
+    const entry = {
+        at: value.at,
+        fromState: value.fromState,
+        toState: value.toState,
+        trigger: value.trigger,
+        isolateGen: value.isolateGen,
+        dataLoss: value.dataLoss,
+        snapshotKeysRehydrated: value.snapshotKeysRehydrated,
+    };
+    if (typeof value.notes === 'string')
+        entry.notes = value.notes.slice(0, MESSAGE_CAP);
+    return entry;
+}

package/dist/rpc-dispose.d.ts

@@ -0,0 +1,4 @@
+export declare function disposeRpcResource(value: unknown): boolean;
+export declare function disposeRpcResources(values: Iterable<unknown>): void;
+export declare function useRpcResource<T, R>(promise: Promise<T>, use: (value: T) => R | Promise<R>): Promise<R>;
+//# sourceMappingURL=rpc-dispose.d.ts.map

package/dist/rpc-dispose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-dispose.d.ts","sourceRoot":"","sources":["../src/rpc-dispose.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAY1D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,EACvC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/rpc-dispose.js

@@ -0,0 +1,30 @@
+export function disposeRpcResource(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') || value === null)
+        return false;
+    const disposerKey = Symbol.dispose;
+    if (!disposerKey)
+        return false;
+    const disposer = Reflect.get(value, disposerKey);
+    if (typeof disposer !== 'function')
+        return false;
+    try {
+        Reflect.apply(disposer, value, []);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function disposeRpcResources(values) {
+    for (const value of values)
+        disposeRpcResource(value);
+}
+export async function useRpcResource(promise, use) {
+    const value = await promise;
+    try {
+        return await use(value);
+    }
+    finally {
+        disposeRpcResource(value);
+    }
+}

package/dist/w7-frame.d.ts

@@ -0,0 +1,107 @@
+/**
+ * W7 v3 — incremental typed records for streamed bulk filesystem writes.
+ * The format is internal: every producer and consumer deploys together.
+ */
+export type VfsInodeKind = 'file' | 'directory' | 'symlink';
+/** Entry for bulk inode creation via writeBatch(). */
+export interface BatchInodeEntry {
+    path: string;
+    parentPath: string;
+    /** Defaults to isDir ? directory : file for legacy/non-symlink producers. */
+    kind?: VfsInodeKind;
+    isDir: boolean;
+    size: number;
+    atime?: number;
+    mtime: number;
+    mode: number;
+    uid?: number;
+    gid?: number;
+    chunkCount: number;
+}
+/** Entry for bulk chunk creation via writeBatch(). */
+export interface BatchChunkEntry {
+    path: string;
+    chunkId: number;
+    data: Uint8Array;
+}
+/** Payload for writeBatch() — all inodes + chunks written in ONE transactionSync(). */
+export interface BatchWritePayload {
+    inodes: BatchInodeEntry[];
+    chunks: BatchChunkEntry[];
+    /** Paths to delete before writing (for clean reinstall). */
+    deletePaths?: string[];
+}
+export declare const W7_MAGIC: Uint8Array<ArrayBuffer>;
+export declare const W7_MAX_PATHS_PER_BATCH = 128;
+export declare const W7_MAX_OWNED_PATH_BYTES: number;
+export declare const W7_MAX_RECORD_BYTES: number;
+declare const MODE: "path-atomic-committed-prefix";
+export interface W7BatchSummary {
+    recordCount: number;
+    pathCount: number;
+    deleteCount: number;
+    directoryCount: number;
+    fileCount: number;
+    chunkCount: number;
+    byteCount: number;
+    check: number;
+}
+export interface W7ChunkRetention {
+    readonly bytes: number;
+    release(): void;
+}
+export interface W7DecodeOptions {
+    signal?: AbortSignal;
+    retainChunk?: (byteLength: number, signal?: AbortSignal) => Promise<W7ChunkRetention>;
+}
+type W7DirectoryInode = BatchInodeEntry & {
+    kind: 'directory';
+    isDir: true;
+};
+type W7ContentInode = BatchInodeEntry & {
+    kind: 'file' | 'symlink';
+    isDir: false;
+};
+export type W7DecodedRecord = {
+    type: 'delete';
+    path: string;
+} | {
+    type: 'directory';
+    inode: W7DirectoryInode;
+} | {
+    type: 'file-begin';
+    streamContentId: string;
+    inode: W7ContentInode;
+} | {
+    type: 'file-chunk';
+    streamContentId: string;
+    path: string;
+    chunkId: number;
+    data: Uint8Array;
+    retention: W7ChunkRetention;
+} | {
+    type: 'file-end';
+    streamContentId: string;
+    path: string;
+    size: number;
+    chunkCount: number;
+    check: number;
+} | {
+    type: 'batch-end';
+    summary: W7BatchSummary;
+};
+export interface W7DecodedStream {
+    readonly batchId: string;
+    readonly mode: typeof MODE;
+    readonly records: AsyncIterable<W7DecodedRecord>;
+}
+/** Encode one bounded record per pull; no batch-sized metadata header exists. */
+export declare function encodeWriteBatchStream(payload: BatchWritePayload): ReadableStream<Uint8Array>;
+/**
+ * Parse the v3 preamble eagerly, then expose validated operation records
+ * incrementally. Chunk credit is acquired after its bounded header validates
+ * and before its payload bytes are read or copied.
+ */
+export declare function decodeWriteBatchStream(stream: ReadableStream<Uint8Array>, options?: W7DecodeOptions): Promise<W7DecodedStream>;
+export {};
+//# sourceMappingURL=w7-frame.d.ts.map

package/dist/w7-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"w7-frame.d.ts","sourceRoot":"","sources":["../src/w7-frame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5D,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,QAAQ,yBAA2C,CAAC;AAOjE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,uBAAuB,QAAY,CAAC;AACjD,eAAO,MAAM,mBAAmB,QAAgD,CAAC;AAYjF,QAAA,MAAM,IAAI,EAAG,8BAAuC,CAAC;AAoCrD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvF;AAED,KAAK,gBAAgB,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAAC;AAC7E,KAAK,cAAc,GAAG,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC9C;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,cAAc,CAAC;CACvB,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,gBAAgB,CAAC;CAC7B,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAClD;AAaD,iFAAiF;AACjF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAAC,UAAU,CAAC,CAoC7F;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,CAAC,CA4C1B"}