better-dsh 0.3.0-r → 0.3.1

package/lib/index.d.ts

@@ -379,7 +379,7 @@ interface ReplRuntimeSurface {
 //#region src/runtime.d.ts
 /** Plugin config: every tunable, changeable from `cordis.yml` (no hardcoded tunables). */
 interface Config$1 {
-  /** Python interpreter with `ipykernel` installed. The bare sentinel `python3` (or absent) selects a managed venv under {@link Config.kernelEnvDir}. */
+  /** Python >=3.9 interpreter. The bare sentinel `python3` (or absent) selects a managed venv under {@link Config.kernelEnvDir}. */
   python?: string;
   /** Budget for kernel spawn → ready, in milliseconds. */
   startupTimeoutMs?: number;
@@ -388,8 +388,7 @@ interface Config$1 {
   /** Grace between a timeout/abort interrupt and the force-settle, in milliseconds. */
   interruptGraceMs?: number;
   /**
-   * Confirm window between the control-channel interrupt and the SIGALRM
-   * escalation, in milliseconds; must stay below {@link Config.interruptGraceMs}.
+   * Confirm window before repeating SIGINT, in milliseconds; must stay below {@link Config.interruptGraceMs}.
    * See the bridge's two-phase interrupt for why the escalation is deferred.
    */
   interruptConfirmMs?: number;
@@ -399,15 +398,15 @@ interface Config$1 {
   snapshotTimeoutMs?: number;
   /** Hard cap for serialized log-array, completion-value, and failure-message payloads. */
   maxOutputBytes?: number;
-  /** Directory for per-session namespace snapshots (`state.dill` + `manifest.json`); none when absent. */
+  /** Per-session immutable checkpoints. Defaults to the official profile home; empty string disables, standalone callers opt in. */
   snapshotDir?: string;
-  /** Serialized-size cap for a turn-end snapshot, in bytes; over-cap snapshots are skipped with a one-time model warning. */
+  /** Serialized graph cap in bytes; each over-cap attempt reports the last successful checkpoint. */
   snapshotSizeCapBytes?: number;
   /** Managed venv directory (used when `python` is absent/`python3`); defaults to `<package>/.venv-kernel`. */
   kernelEnvDir?: string;
   /** Preferred CPython version for a managed venv. */
   kernelPythonVersion?: string;
-  /** Provision the managed venv (ipykernel + dill) on first use; default true. */
+  /** Provision a stdlib-only managed venv on first use; default true. */
   kernelAutoInstall?: boolean;
   username?: string;
 }
@@ -428,6 +427,7 @@ declare class DashrRuntime extends ReplRuntime {
   /** One entry per session principal that has run code (lazy — never pre-seeded). */
   private readonly kernels;
   private disposed;
+  private readonly transactions;
   /** Lazily-resolved (and, when managed, provisioned) kernel interpreter. */
   private kernelEnvPromise;
   constructor(ctx: Context, config: Config$1);
@@ -446,7 +446,9 @@ declare class DashrRuntime extends ReplRuntime {
    * @param request - the program, its bindings, and the abort signal.
    * @returns the run's outcome per the seam contract.
    */
+  private transaction;
   run(request: CodeRunRequest): Promise<CodeRunResult>;
+  private runTransaction;
   /**
    * Read one user-namespace variable by name on the session's kernel. A
    * bare/empty name lists the namespace's user-variable names; a
@@ -459,6 +461,7 @@ declare class DashrRuntime extends ReplRuntime {
    * @param principal - the session key (absent → the shared default).
    */
   queryVar(name: string, principal?: string): Promise<ReplVarQuery>;
+  private queryTransaction;
   /**
    * Assign one lossless-JSON value into the user namespace under `name` on
    * the session's kernel. `name` must be a usable identifier (and not a
@@ -470,6 +473,7 @@ declare class DashrRuntime extends ReplRuntime {
    * @param principal - the session key (absent → the shared default).
    */
   setVar(name: string, value: unknown, principal?: string): Promise<void>;
+  private setTransaction;
   /** Map one cell outcome onto the seam's result shape under the output ledger. */
   private assembleResult;
   /** Reject malformed binding globals or typed-error declarations as contract misuse. */
@@ -486,40 +490,14 @@ declare class DashrRuntime extends ReplRuntime {
    * @param key - the run principal (or the agentless default).
    */
   private ensureKernel;
-  /**
-   * Restore a key's on-disk snapshot into a freshly booted kernel, when one
-   * exists and its manifest is plausible. Called once per entry boot. The
-   * kernel-side restore cell performs the authoritative environment checks
-   * (python version, interpreter identity, skills); this method only gates on
-   * the manifest the host can read cheaply, then records the turn so the
-   * first-run notice and the revive chain can name it.
-   */
+  /** Restore once before user admission; any degraded load retires that child. */
   private restoreEntry;
-  /** Read the per-key manifest's host-relevant fields; absent when unreadable/missing. */
-  private readSnapshotManifest;
-  /**
-   * Revive one session's kernel after death: respawn a fresh kernel, restore
-   * the nearest replayable snapshot onto it (the normal restore path), and
-   * return the death-observing run's explicit error naming the turn. When no
-   * replayable snapshot exists the message falls back to M3-A's fresh-empty
-   * contract. The run itself does NOT execute — an error that lies about a
-   * NameError costs the model more than one dropped cell (blueprint §8.3).
-   * @param key - the run principal.
-   * @param dead - the entry that died (its `turn` is the last completed turn).
-   */
+  private omissionNotice;
+  /** Restore a fresh child and report whether the observing call had started. */
   private reviveAfterDeath;
-  /**
-   * Write one key's turn-end snapshot, when a snapshot directory is
-   * configured. A size-cap skip is reported (so the run can warn the model
-   * once); other failures log without disturbing the run.
-   */
+  /** Save completed mutations and expose partial/failed coverage within output limits. */
   private snapshotTurnEnd;
-  /**
-   * Dispose to quiescence: snapshot every live key's namespace when a
-   * snapshot directory is configured (each under its own per-key
-   * subdirectory), then shut the subprocesses down. Registered as the
-   * plugin's `ctx.effect` disposer.
-   */
+  /** Cancel active work, drain admitted transactions, and reap every owned child. */
   private teardown;
   /**
    * Tear one session's kernel down (session end via the `agent/disposed`
@@ -530,11 +508,9 @@ declare class DashrRuntime extends ReplRuntime {
   /**
    * Reset one session's kernel to a fresh, empty namespace: dispose the live
    * subprocess WITHOUT a turn-end snapshot and clear its on-disk snapshot, so
-   * the next ensureKernel spawns empty (restore finds nothing to replay).
+   * the next ensureKernel spawns empty (restore finds no checkpoint).
    */
   private resetKey;
-  /** Snapshot (when configured) then dispose one key's kernel; failures log, never throw into a listener. */
-  private teardownKernel;
 }
 //#endregion
 //#region src/tool-call-id.d.ts
@@ -619,7 +595,7 @@ declare function resolveMaxParallelSubCalls(value: number | undefined): number;
  * `dashr/repl-dispatch-log` waterfall — dashr's OWN dispatch-log event,
  * self-registered via the cordis Events merge below. Decoupled from
  * upstream's `tools/ptc-dispatch-log` (PTC `run_code` sub-dispatches): `eval`
- * is a broader session-persistent REPL (IPython kernel) than upstream's
+ * is a broader session-persistent REPL (OMP Python child) than upstream's
  * `run_code` TS-worker tool, so its durable-log reshape extension point is
  * dashr-owned and version-independent — no coupling to upstream's
  * `CodeDispatchLog`/`PtcDispatchLog` rename or the PTC tool's event name.