@hydranium/protocol 1.0.0-next.357 → 1.0.0-next.359

package/lib/profile-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile-session.d.ts","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAU,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,8EAA8E;IAC9E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAOtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEjC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IARxC,6FAA6F;IAC7F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAM;IACnD,SAAS,CAAC,QAAQ,CAAC,OAAO,wBAA+B;IAEzD,YACsB,MAAM,EAAE,MAAM,EACjC,KAAK,EAAE,KAAK,EACO,UAAU,EAAE,MAAM,EAGvC;IAED,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IA2BrC,qFAAqF;IACrF,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAcnD;IAED,OAAO,IAAI,SAAS,aAAa,EAAE,CAQlC;IAED,MAAM,CAAC,QAAQ,GAAE,YAAsB,GAAG,IAAI,CAgB7C;CACH"}
+{"version":3,"file":"profile-session.d.ts","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAU,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,8EAA8E;IAC9E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC/B,oGAAoG;IACpG,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAatD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEjC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IAdxC,6FAA6F;IAC7F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC/C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAM;IACnD,iGAAiG;IACjG,SAAS,CAAC,QAAQ,CAAC,OAAO,wBAA+B;IAEzD,YACsB,MAAM,EAAE,MAAM,EACjC,KAAK,EAAE,KAAK,EACO,UAAU,EAAE,MAAM,EAGvC;IAED,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IA2BrC;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAcnD;IAED,OAAO,IAAI,SAAS,aAAa,EAAE,CAQlC;IAED,MAAM,CAAC,QAAQ,GAAE,YAAsB,GAAG,IAAI,CAgB7C;CACH"}

package/lib/profile-session.js

@@ -20,7 +20,13 @@ class DefaultProfileSession {
     identifier;
     /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
     sessionStopwatch;
+    /**
+     * The scopes in flight, innermost last. They must end innermost first:
+     * {@link closeFrame} pops the top frame whichever scope ends, so
+     * overlapping async scopes misattribute their time.
+     */
     stack = [];
+    /** Self-time in milliseconds per id, one sample per closed scope, which {@link records} sums. */
     entries = new Map();
     constructor(logger, clock, identifier) {
         this.logger = logger;
@@ -50,7 +56,10 @@ class DefaultProfileSession {
         this.closeFrame(frame);
         return result;
     }
-    /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
+    /**
+     * Pop the top frame, which is `frame` when scopes end innermost first,
+     * charge its full duration to the new top, and record its self-time.
+     */
     closeFrame(frame) {
         this.stack.pop();
         const duration = this.sessionStopwatch.elapsedMs - frame.start;

package/lib/profile-session.js.map

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

package/lib/profiling.d.ts

@@ -8,15 +8,23 @@
  ********************************************************************************/
 /** Which dimensions to capture, and the two sampling knobs. All off by default. */
 export interface ProfileCaptureOptions {
+    /** Sample the CPU at {@link cpuIntervalMicros} into a `server-cpu` artefact. */
     cpu?: boolean;
+    /** Sample allocations at {@link allocationIntervalBytes} into a `server-alloc` artefact. */
     allocation?: boolean;
+    /** Record every GC pause, summed by kind in `server-summary` rather than as its own artefact. */
     gc?: boolean;
+    /**
+     * Sample event-loop delay, summarised as mean, p50, p99 and max in
+     * `server-summary` rather than as its own artefact. Absent there when the
+     * sampler recorded nothing.
+     */
     eventLoopDelay?: boolean;
     /** Also drop a retained `.heapsnapshot` at stop (for the memory analyzer). */
     heapSnapshot?: boolean;
-    /** CPU sampling interval in µs (implementation default 1000). */
+    /** CPU sampling interval in µs (implementation default `DEFAULT_CPU_INTERVAL_MICROS`). */
     cpuIntervalMicros?: number;
-    /** Allocation sampling interval in bytes (implementation default 32768). */
+    /** Allocation sampling interval in bytes (implementation default `DEFAULT_ALLOCATION_INTERVAL_BYTES`). */
     allocationIntervalBytes?: number;
 }
 export declare const PROFILING_SCHEMA_VERSION = 1;
@@ -39,12 +47,17 @@ export interface ProfilingArtifact {
 }
 /** What a skill reads to know what to expect from a run (browser entries only in `app` mode, etc.). */
 export interface ProfilingEnvironment {
+    /** `harness` for a headless run, `app` for one that drove the real app. */
     mode: 'harness' | 'app';
     /** Whether a cgroup memory controller is present (running in a pod) vs local. */
     container: boolean;
+    /** The commit the run reflects, which a finding's `file:line` is read against. Absent when the caller named none. */
     commit?: string;
+    /** The workspace under test as the caller named it. Absent when it named none. */
     workspace?: string;
+    /** The `process.version` of the process that wrote the manifest, which for an e2e run is the test runner, not the server. */
     node: string;
+    /** Captured windows in capture order, each with its duration in milliseconds. */
     windows: {
         label: string;
         ms: number;

package/lib/profiling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACnC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACnC;AAUD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC5B,YAAY,GACZ,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,sBAAsB,GACtB,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,CAAC;AAEvB,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAC/B,kEAAkE;IAClE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uGAAuG;AACvG,MAAM,WAAW,oBAAoB;IAClC,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,oBAAoB,CAAC;IAClC;;;;;OAKG;IACH,SAAS,EAAE,iBAAiB,EAAE,CAAC;CACjC"}
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACnC,gFAAgF;IAChF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4FAA4F;IAC5F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iGAAiG;IACjG,EAAE,CAAC,EAAE,OAAO,CAAC;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0GAA0G;IAC1G,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACnC;AAUD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC5B,YAAY,GACZ,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,sBAAsB,GACtB,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,CAAC;AAEvB,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAC/B,kEAAkE;IAClE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uGAAuG;AACvG,MAAM,WAAW,oBAAoB;IAClC,2EAA2E;IAC3E,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,qHAAqH;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6HAA6H;IAC7H,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,oBAAoB,CAAC;IAClC;;;;;OAKG;IACH,SAAS,EAAE,iBAAiB,EAAE,CAAC;CACjC"}

package/lib/profiling.js.map

@@ -1 +1 @@
-{"version":3,"file":"profiling.js","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAwBlF;;;;;;GAMG;AAEU,QAAA,wBAAwB,GAAG,CAAC,CAAC"}
+{"version":3,"file":"profiling.js","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAgClF;;;;;;GAMG;AAEU,QAAA,wBAAwB,GAAG,CAAC,CAAC"}

package/lib/reconcile-write.d.ts

@@ -30,6 +30,7 @@ export interface ReconcileWriteHooks<TModel> {
     refetch(): Promise<VersionedModel<TModel> | undefined>;
     /** The last in-sync model the user's intent is measured against. */
     readonly base: TModel;
+    /** Asked for each conflict while writes remain. Its refetch callback runs {@link refetch} only when called. */
     readonly conflictResolver: ConflictResolver;
     /** Writes, the first included, after which a still-conflicting edit is dropped; 3 when absent. */
     readonly maxWrites?: number;
@@ -54,7 +55,9 @@ export type ReconcileWriteOutcome =
      * {@link ReconcileWriteHooks.onUnavailable} ran.
      */
     readonly status: 'merged' | 'already-applied' | 'unchanged' | 'conflict' | 'dropped' | 'unavailable';
+    /** The last conflict a write raised, which on `merged` is the one before the write that landed. */
     readonly conflict: ConflictError;
+    /** Writes made, the first included. `dropped` is reported once they reach {@link ReconcileWriteHooks.maxWrites}. */
     readonly writes: number;
 };
 /**

package/lib/reconcile-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile-write.d.ts","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,6FAA6F;AAC7F,MAAM,WAAW,cAAc,CAAC,MAAM;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACrC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACxC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACvD,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB;AAC9B,8BAA8B;AAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IACG;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;IACrG,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEP;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,SAAS,MAAM,EACvD,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAmChC"}
+{"version":3,"file":"reconcile-write.d.ts","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACnF,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAItD,6FAA6F;AAC7F,MAAM,WAAW,cAAc,CAAC,MAAM;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;CACrC;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACxC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IACvD,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+GAA+G;IAC/G,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB;AAC9B,8BAA8B;AAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC;IACG;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,aAAa,CAAC;IACrG,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,oHAAoH;IACpH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEP;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,SAAS,MAAM,EACvD,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAmChC"}

package/lib/reconcile-write.js.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile-write.js","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,qCAA+D;AAI/D,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAoD7B;;;;;GAKG;AACI,KAAK,yBACT,KAAa,EACb,WAAwB,EACxB,KAAkC;IAElC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,oBAAoB,GAAG,WAAW,CAAC;IACvC,IAAI,QAAmC,CAAC;IACxC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACxD,KAAK,IAAI,MAAM,GAAG,CAAC,GAAI,MAAM,EAAE,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAChG,CAAC;QACD,QAAQ,GAAG,QAAQ,CAAC;QACpB,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAClD,CAAC;QACD,IAAI,SAA6C,CAAC;QAClD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;YAChF,SAAS,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,SAAS,EAAE,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;YACtB,KAAK,QAAQ;gBACV,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;gBAC3B,oBAAoB,GAAG,SAAS,EAAE,WAAW,IAAI,KAAK,CAAC;gBACvD,SAAS;YACZ,KAAK,iBAAiB;gBACnB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YAC1D,KAAK,OAAO;gBACT,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACpD,KAAK,UAAU;gBACZ,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACnD,KAAK,aAAa;gBACf,MAAM,KAAK,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC7C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACzD,CAAC;IACJ,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,KAAK,UAAU,iBAAiB,CAC7B,KAAkC,EAClC,KAAa,EACb,WAAwB;IAExB,IAAI,CAAC;QACF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACxC,OAAO,SAAS,CAAC;IACpB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACrB,IAAI,CAAC,IAAA,wBAAe,EAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,GAAG,CAAC;QACb,CAAC;QACD,OAAO,GAAG,CAAC;IACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"reconcile-write.js","sourceRoot":"","sources":["../src/reconcile-write.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,qCAA+D;AAI/D,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAuD7B;;;;;GAKG;AACI,KAAK,yBACT,KAAa,EACb,WAAwB,EACxB,KAAkC;IAElC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,oBAAoB,GAAG,WAAW,CAAC;IACvC,IAAI,QAAmC,CAAC;IACxC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACxD,KAAK,IAAI,MAAM,GAAG,CAAC,GAAI,MAAM,EAAE,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAChG,CAAC;QACD,QAAQ,GAAG,QAAQ,CAAC;QACpB,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAClD,CAAC;QACD,IAAI,SAA6C,CAAC;QAClD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE;YAChF,SAAS,GAAG,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,SAAS,EAAE,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;YACtB,KAAK,QAAQ;gBACV,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;gBAC3B,oBAAoB,GAAG,SAAS,EAAE,WAAW,IAAI,KAAK,CAAC;gBACvD,SAAS;YACZ,KAAK,iBAAiB;gBACnB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YAC1D,KAAK,OAAO;gBACT,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACpD,KAAK,UAAU;gBACZ,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YACnD,KAAK,aAAa;gBACf,MAAM,KAAK,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC7C,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACzD,CAAC;IACJ,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,KAAK,UAAU,iBAAiB,CAC7B,KAAkC,EAClC,KAAa,EACb,WAAwB;IAExB,IAAI,CAAC;QACF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACxC,OAAO,SAAS,CAAC;IACpB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACrB,IAAI,CAAC,IAAA,wBAAe,EAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,GAAG,CAAC;QACb,CAAC;QACD,OAAO,GAAG,CAAC;IACd,CAAC;AACJ,CAAC"}

package/lib/transfer-document.d.ts

@@ -59,6 +59,7 @@ export interface TextState {
  * see {@link TransferElement}).
  */
 export interface TransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> {
+    /** Need not be spelled as the request named it. */
     uri: string;
     /**
      * Absent when the document does not exist: the server answers an unknown
@@ -103,7 +104,7 @@ export type TransferCreatedDocument<TTransfer extends TransferElement, TDiagnost
 };
 /** What a watch answers, once it is in place. */
 export interface TransferWatchedDocument {
-    /** The key the watch's events name the document by, which a symlinked URI does not spell. */
+    /** The key the watch's events name the document by, which need not be the spelling the watch was asked with. */
     readonly uri: string;
     /** Whether a document exists there; one the server fails to load counts, only a missing one does not. */
     readonly exists: boolean;

package/lib/transfer-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transfer-document.d.ts","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAkB,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEnG,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IACnG,IAAI,EAAE,KAAK,CAAC;IACZ,qFAAqF;IACrF,WAAW,CAAC,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACf;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACvB;;;;OAIG;IACH,OAAO,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB;IAClG,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACtD,6DAA6D;IAC7D,IAAI,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACvH,SAAS,EACT,WAAW,CACb,GAAG;IACD,KAAK,EAAE,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;CACvD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACtH,SAAS,EACT,WAAW,CACb,GAAG;IACD,SAAS,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,IAAI,gBAAgB,CACxH,SAAS,EACT,WAAW,CACb,GAAG;IACD,OAAO,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;CACrC,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACrC,gHAAgH;IAChH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yHAAyH;IACzH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED,yBAAiB,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,SAAgB,QAAQ,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACzF,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,QAAQ,IAAI,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE5D;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EAC7F,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,GAClD,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAKhD;IAED,4DAA4D;IAC5D,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,GACX,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAE1C;IAED;;;OAGG;IACH,SAAgB,MAAM,CAAC,SAAS,SAAS,eAAe,EAAE,WAAW,GAAG,kBAAkB,EACvF,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,WAAW,EAAE,EAC3B,IAAI,CAAC,EAAE,SAAS,GAChB,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAM1C;CACH"}

package/lib/transfer-document.js.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,+DAAmG;AAqHnG,IAAiB,gBAAgB,CAmDhC;AAnDD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC;IACvC,CAAC;IAJe,iBAAA,QAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,iBAAA,YAAY,eAO3B,CAAA;IAED,4DAA4D;IAC5D,SAAgB,MAAM,CACnB,GAAW;QAEX,OAAO,EAAE,GAAG,EAAE,CAAC;IAClB,CAAC;IAJe,iBAAA,MAAM,SAIrB,CAAA;IAED;;;OAGG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,IAAY,EACZ,WAA2B,EAC3B,IAAgB;QAEhB,OAAO;YACJ,GAAG;YACH,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAA,6BAAc,EAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;YAC9G,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;SACzC,CAAC;IACL,CAAC;IAbe,iBAAA,MAAM,SAarB,CAAA;AACJ,CAAC,EAnDgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAmDhC"}
+{"version":3,"file":"transfer-document.js","sourceRoot":"","sources":["../src/transfer-document.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAIlF,+DAAmG;AAsHnG,IAAiB,gBAAgB,CAmDhC;AAnDD,WAAiB,gBAAgB;IAC9B;;;OAGG;IACH,SAAgB,QAAQ,CACrB,QAAkD;QAElD,OAAO,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC;IACvC,CAAC;IAJe,iBAAA,QAAQ,WAIvB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,YAAY,CACzB,QAAkD;QAElD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IAPe,iBAAA,YAAY,eAO3B,CAAA;IAED,4DAA4D;IAC5D,SAAgB,MAAM,CACnB,GAAW;QAEX,OAAO,EAAE,GAAG,EAAE,CAAC;IAClB,CAAC;IAJe,iBAAA,MAAM,SAIrB,CAAA;IAED;;;OAGG;IACH,SAAgB,MAAM,CACnB,GAAW,EACX,OAAe,EACf,IAAe,EACf,IAAY,EACZ,WAA2B,EAC3B,IAAgB;QAEhB,OAAO;YACJ,GAAG;YACH,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAA,6BAAc,EAAC,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE;YAC9G,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;SACzC,CAAC;IACL,CAAC;IAbe,iBAAA,MAAM,SAarB,CAAA;AACJ,CAAC,EAnDgB,gBAAgB,aAAhB,gBAAgB,GAAhB,gBAAgB,QAmDhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/protocol",
-  "version": "1.0.0-next.357",
+  "version": "1.0.0-next.359",
   "description": "Generic, language-agnostic types, constants, and pure utilities for the hydranium framework.",
   "keywords": [
     "hydranium",

package/src/client/data-connection.ts

@@ -143,6 +143,7 @@ export class DataConnection<
    TServer extends DataServerProtocol<TTransfer, DiagnosticOf<TServer>> = DataServerProtocol<TTransfer>,
    TClient extends object = DataClientProtocol<TTransfer>
 > extends RpcConnection<TServer, TClient> {
+   /** Backs {@link liveSessions}, and is what {@link createSession} checks a new id against. */
    protected readonly sessions = new Set<DataSession<TTransfer, TServer>>();
    protected readonly sessionFactory: DataSessionFactory<TTransfer, TServer>;
    protected readonly createSessionEmitter = new Emitter<DataSession<TTransfer, TServer>>();

package/src/client/data-events.ts

@@ -96,6 +96,7 @@ export class DataEvents<
       this.projectsChangedEmitter.fire(event);
    }
 
+   /** Drop every listener. */
    dispose(): void {
       this.documentUpdatedEmitter.dispose();
       this.documentSavedEmitter.dispose();

package/src/client/data-session.ts

@@ -416,7 +416,9 @@ export class DataSession<
    protected readonly resumeToken: string = randomUuid();
    /** The proxy the session is registered on; another one means the connection was replaced. */
    protected registeredOn?: RpcProxy<TServer>;
+   /** The registration on {@link registeredOn}, which {@link connected} awaits. Replaced when the proxy changes. */
    protected registration?: Promise<void>;
+   /** Set by {@link dispose} or {@link detach}, whichever comes first, after which {@link assertLive} throws. */
    protected disposed = false;
    /**
     * Disposed through {@link detach} rather than {@link dispose}, so nothing may
@@ -1552,6 +1554,11 @@ export class DataSession<
       await this.clock.raceTimer(Promise.all(pending.map(tracker => tracker.whenSettled())), this.settleBeforeCloseMs);
    }
 
+   /**
+    * Throw a `SessionClosedError` once the session has ended. {@link connected}
+    * runs it again after each of its waits, since a session disposed during
+    * one would otherwise register or send after the close.
+    */
    protected assertLive(): void {
       if (this.disposed) {
          throw new SessionClosedError(this.clientId);

package/src/client/message-relay.ts

@@ -41,7 +41,9 @@ export const RELAY_REPLAY_FAILED = defineMessage(
  * only who owns the framing, which is why this tier never needs to know.
  */
 export interface RelayTransport {
+   /** Its close or error fires {@link MessageRelay.onClose}. */
    readonly reader: MessageReader;
+   /** A write that rejects is not retried, and whether its message arrived is unknown. */
    readonly writer: MessageWriter;
    /** Release the transport. Called when the relay is disposed. */
    dispose?(): void;

package/src/client/post-message-transport.ts

@@ -75,7 +75,12 @@ export interface PostMessageChannel {
  * the same copy of `vscode-jsonrpc`.
  */
 export interface PostMessageTransport {
+   /** Closes only when the channel's `onClose` fires. */
    readonly reader: MessageReader;
+   /**
+    * A write resolves once the channel's `post` returns, not once the message
+    * arrives, and rejects when `post` throws.
+    */
    readonly writer: MessageWriter;
    /**
     * Release the channel subscriptions. A {@link createMessagePortTransport}

package/src/client/rpc-connection.ts

@@ -79,7 +79,17 @@ export interface ResolvedRpcConnectionOptions<TClient extends object> {
  * and {@link RpcConnection.awaitReady}, so an override has to name it too.
  */
 export interface RpcConnectionGeneration<TServer extends object> {
+   /**
+    * The port's connection. {@link RpcConnection.currentGeneration} reports a
+    * rejection to the port. An opened one is disposed by
+    * {@link RpcConnection.dropGeneration}, and stays with the port when the
+    * generation fails its readiness check.
+    */
    readonly connection: Promise<MessageConnection>;
+   /**
+    * The proxy over {@link connection}, whose calls queue until it opens. Dead
+    * once {@link RpcConnection.dropGeneration} disposes {@link connection}.
+    */
    readonly server: RpcProxy<TServer>;
    /** Set on first use; the shared readiness gate for this generation. */
    ready?: Promise<void>;
@@ -104,12 +114,17 @@ export interface RpcConnectionGeneration<TServer extends object> {
  * call the document methods; nothing at this layer does.
  */
 export class RpcConnection<TServer extends ReadyServer, TClient extends object> {
+   /** The wire prefix of every generation's proxy, fixed for the connection's life. */
    protected readonly methodNamespace: string;
+   /** The only methods of {@link localTarget} bound for the server to call, on each new generation. */
    protected readonly clientMethods: readonly (keyof TClient & string)[];
+   /** The caller's hooks composed with the port's, so both hear each transition. */
    protected readonly lifecycle: RpcConnectionLifecycle;
    /** The current generation, or `undefined` before the first request / after a teardown. */
    protected generation?: RpcConnectionGeneration<TServer>;
+   /** Set by {@link dispose}, after which {@link assertLive} throws. */
    protected disposed = false;
+   /** Drops the generation when the port disposes. Released by {@link dispose}. */
    protected readonly portDisposeListener: { dispose(): void };
 
    constructor(
@@ -222,8 +237,10 @@ export class RpcConnection<TServer extends ReadyServer, TClient extends object>
 
    /** Await the connection and the server's startup gate for one generation. */
    protected async awaitReady(generation: RpcConnectionGeneration<TServer>): Promise<void> {
+      let opened = false;
       try {
          await generation.connection;
+         opened = true;
          // Dropped meanwhile: writing the request would hit a closed transport.
          if (this.generation !== generation) {
             return;
@@ -244,7 +261,10 @@ export class RpcConnection<TServer extends ReadyServer, TClient extends object>
          if (this.generation === generation) {
             this.generation = undefined;
          }
-         this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
+         // A connection that never opened is already reported as a failed connect.
+         if (opened) {
+            this.port.reportError(error, resolve(DATA_SERVER_NOT_READY, { detail: describeError(error) }));
+         }
          throw error;
       }
    }
@@ -273,6 +293,7 @@ export class RpcConnection<TServer extends ReadyServer, TClient extends object>
       generation.connection.then(connection => connection.dispose()).catch(() => undefined);
    }
 
+   /** Throw once disposed, a plain `Error` naming the class rather than a protocol error. */
    protected assertLive(): void {
       if (this.disposed) {
          throw new Error(`${this.constructor.name} is disposed`);

package/src/client/worker-handshake.ts

@@ -63,6 +63,7 @@ export function isWorkerBootstrapMessage(value: unknown): value is WorkerBootstr
 export const WORKER_READY_MESSAGE_TYPE = 'hydranium/ready';
 
 export interface WorkerReadyMessage {
+   /** The only field {@link isWorkerReadyMessage} checks, so {@link workspace} is taken on trust. */
    readonly type: typeof WORKER_READY_MESSAGE_TYPE;
    /** The files the heads came up on, when the worker's host named a root to read them under. */
    readonly workspace?: WorkerWorkspace;
@@ -74,6 +75,7 @@ export interface WorkerReadyMessage {
  * the seed, an editor opened on the seed overwrites the restored document.
  */
 export interface WorkerWorkspace {
+   /** The root the worker's host was given. */
    readonly rootUri: string;
    /** Every file's content, keyed by its path relative to {@link rootUri}. */
    readonly files: Readonly<Record<string, string>>;
@@ -98,9 +100,11 @@ export const WORKER_ERROR_MESSAGE_TYPE = 'hydranium/worker-error';
 export const WORKER_BOOTSTRAP_PHASE = 'bootstrap';
 
 export interface WorkerErrorMessage {
+   /** The page raises this type too, on its own error event, when the `Worker` fires `error`. */
    readonly type: typeof WORKER_ERROR_MESSAGE_TYPE;
    /** What the worker was doing, {@link WORKER_BOOTSTRAP_PHASE} for a failed bootstrap. */
    readonly phase: string;
+   /** The failure described for a log. Never branch on it. */
    readonly message: string;
 }
 

package/src/data/data-server-protocol.ts

@@ -84,7 +84,8 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
     * `created`. The answer is read after the create, so it can already hold
     * another client's write or an integrity repair; a write based on
     * `created.version` then conflicts. It reaches disk with the first save.
-    * Fails when the file exists or any client has the URI open, and with a
+    * Fails when the file exists, any client has the URI open, or a lost
+    * client's unsaved text is held for it, and with a
     * `SessionClosedError` code when `args.clientId` is not a session
     * registered on this connection.
     */

package/src/data/events.ts

@@ -44,14 +44,12 @@ export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 /**
  * Delivered on the data-server when a document's content (or existence)
  * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
- *
- * The `document` field carries the latest built state — diagnostics + root
- * are coherent with each other at the time the event fired.
  */
 export interface TransferDocumentUpdatedEvent<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
+   /** The latest built state: diagnostics and root are coherent with each other at the time the event fired. */
    document: TransferDocument<TTransfer, TDiagnostic>;
    /**
     * The client whose write this event echoes: the author of the version on a
@@ -61,6 +59,7 @@ export interface TransferDocumentUpdatedEvent<
     * instead.
     */
    sourceClientId: string;
+   /** See {@link TransferDocumentUpdateReason} for which reasons the framework sends. */
    reason: TransferDocumentUpdateReason;
    /**
     * The position of this event among the update and deletion events the
@@ -77,29 +76,25 @@ export type TransferDocumentUpdatedListener<
 > = (event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>) => void;
 
 /**
- * Delivered on the data-server when a document was persisted to disk via
- * `DataServerProtocol.saveModelDocument` or `persistModelDocument`. Distinct
- * from {@link TransferDocumentUpdatedEvent}: subscribers that only care about
- * persistence (external sync, editor "saved" indicators, dirty-flag
- * clear) listen for this event family instead of filtering an update
- * stream for `reason: 'saved'`.
- *
- * The `document` field carries the post-save built state — same shape
- * the synchronous `saveModelDocument` RPC response returns, delivered
- * to subscribers (`DataClientProtocol.onDocumentSaved`) so non-caller
- * clients see the persistence event too.
+ * Delivered on the data-server when a subscribed document was saved to disk,
+ * whichever client saved it, an editor's save through the LSP head included.
+ * Distinct from {@link TransferDocumentUpdatedEvent}: subscribers that only
+ * care about persistence (external sync, editor "saved" indicators,
+ * dirty-flag clear) listen for this event family instead of filtering an
+ * update stream for `reason: 'saved'`.
  */
 export interface TransferDocumentSavedEvent<
    TTransfer extends TransferElement,
    TDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
+   /** The latest built state, taken after the save. */
    document: TransferDocument<TTransfer, TDiagnostic>;
    /**
-    * The client whose `saveModelDocument` or `persistModelDocument` call
-    * produced this, also when another client wrote the persisted text. Every
-    * subscriber receives the event including the originator, which already had
-    * the same state as the RPC response — compare against your own id to drop
-    * the echo rather than re-rendering from it.
+    * The client whose save produced this, also when another client wrote the
+    * persisted text: the caller of `saveModelDocument` or
+    * `persistModelDocument`, or `LANGUAGE_CLIENT_ID` for an editor's save
+    * through the LSP head. Every subscriber receives the event, the saving
+    * client included, so compare against your own id to drop the echo.
     */
    sourceClientId: string;
 }

package/src/data/requests.ts

@@ -114,6 +114,10 @@ export interface CreateModelDocumentArgs {
 export interface TransferUpdateDocumentsArgs<TTransfer> {
    /** The id of a live session registered on this connection. */
    clientId: string;
+   /**
+    * One entry per document: a set naming one twice, by any spellings that
+    * share its canonical URI, is refused.
+    */
    updates: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>[];
 }
 
@@ -130,6 +134,7 @@ export interface TransferUpdateDocumentsArgs<TTransfer> {
  * `clientId`).
  */
 export interface WatchModelDocumentArgs {
+   /** Any spelling that the document URI policy maps to the document. */
    uri: string;
    /** Stable identifier for the watching client. */
    clientId: string;

package/src/debouncer.ts

@@ -50,7 +50,9 @@ export interface DebouncerOptions {
  * than a breaking change.
  */
 export class Debouncer implements Disposable {
+   /** {@link DebouncerOptions.delayMs}, read at each {@link schedule}. An armed timer keeps the delay it was armed with. */
    protected readonly delay: ObservableValue<number>;
+   /** {@link DebouncerOptions.maxWaitMs}, fixed at construction unlike {@link delay}. */
    protected readonly maxWaitMs?: number;
    protected timer?: Disposable;
    /** Running since the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
@@ -87,7 +89,7 @@ export class Debouncer implements Disposable {
       this.timer = this.clock.setTimer(() => this.fire(), wait);
    }
 
-   /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+   /** Run {@link fn} now if a fire is pending, clearing the window first, and do nothing otherwise. */
    flush(): void {
       if (this.timer !== undefined) {
          this.fire();
@@ -106,6 +108,7 @@ export class Debouncer implements Disposable {
       this.cancel();
    }
 
+   /** Clears the window before it runs {@link fn}, so a {@link schedule} from inside `fn` opens a new one. */
    protected fire(): void {
       this.timer?.dispose();
       this.timer = undefined;

package/src/errors.ts

@@ -82,6 +82,10 @@ export const CONFLICT_ERROR_CODE = HYDRANIUM_ERROR_CODES.conflict;
 
 /** Structured payload carried in {@link ConflictError.data}. */
 export interface ConflictErrorData extends HydraniumMessageData {
+   /**
+    * The document whose version moved. A write of several documents names
+    * the first stale one in request order, and others may be stale too.
+    */
    readonly uri: string;
    /** The base version the caller authored against. */
    readonly baseVersion: ModelVersion;
@@ -144,6 +148,7 @@ export class ConflictError extends ResponseError<ConflictErrorData> {
       Object.setPrototypeOf(this, ConflictError.prototype);
    }
 
+   /** The document whose version moved, see {@link ConflictErrorData.uri}. */
    get uri(): string {
       return this.data!.uri;
    }

package/src/glsp-edits-settled-actions.ts

@@ -23,6 +23,7 @@
  * `RejectAction`, which ends the wait too.
  */
 export interface RequestEditsSettledAction {
+   /** Answered only by a server that advertises this kind. The framework's dispatcher sends none to a server that does not. */
    kind: typeof RequestEditsSettledAction.KIND;
    /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
    requestId: string;
@@ -46,6 +47,7 @@ export namespace RequestEditsSettledAction {
 
 /** The server's answer to a {@link RequestEditsSettledAction}. */
 export interface EditsSettledAction {
+   /** No client handler takes this kind: the dispatcher settles the request by {@link responseId} instead. */
    kind: typeof EditsSettledAction.KIND;
    /** The `requestId` of the request this answers. The server's dispatcher sets it. */
    responseId: string;

package/src/glsp-save-model-actions.ts

@@ -24,6 +24,10 @@
  * whether a save failed.
  */
 export interface RequestSaveModelAction {
+   /**
+    * Answered only by a server that advertises this kind. The framework's
+    * Theia saveable sends GLSP's `SaveModelAction` to one that does not.
+    */
    kind: typeof RequestSaveModelAction.KIND;
    /** The id the response echoes as its `responseId`. Empty until the dispatcher assigns one. */
    requestId: string;
@@ -45,6 +49,7 @@ export namespace RequestSaveModelAction {
 
 /** The server's answer to a {@link RequestSaveModelAction} that saved. */
 export interface ModelSavedAction {
+   /** No client handler takes this kind: the dispatcher settles the save by {@link responseId} instead. */
    kind: typeof ModelSavedAction.KIND;
    /** The `requestId` of the save this answers. The server's dispatcher sets it. */
    responseId: string;

package/src/latency-collector.ts

@@ -124,7 +124,9 @@ function percentile(sortedAscending: readonly number[], percent: number): number
  * deterministic on a fake clock.
  */
 export class LatencyCollector {
+   /** One tally per method name. Emptied by {@link reset}. */
    protected readonly durations = new Map<string, MethodLatencyTally>();
+   /** Restarted by {@link reset}. Its reading is the report's `windowMs`. */
    protected window: Stopwatch;
 
    constructor(

package/src/pending-work-tracker.ts

@@ -14,6 +14,7 @@
  * races {@link whenSettled} against its own bound.
  */
 export class PendingWorkTracker {
+   /** The tracked work. {@link track} removes each entry once it settles. */
    protected readonly pending = new Set<Promise<unknown>>();
 
    /** Watch `work` until it settles, and hand it back. */

package/src/profile-session.ts

@@ -68,6 +68,7 @@ export interface ProfileSession {
  * {@link DefaultProfileSession.closeFrame}, so a subclass has to name it too.
  */
 export interface ProfileScopeFrame {
+   /** The {@link ProfileSession.scope} id, under which frames sharing it aggregate into one record. */
    readonly id: string;
    /** Session-stopwatch reading when this scope began. */
    readonly start: number;
@@ -83,7 +84,13 @@ export interface ProfileScopeFrame {
 export class DefaultProfileSession implements ProfileSession {
    /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
    protected readonly sessionStopwatch: Stopwatch;
+   /**
+    * The scopes in flight, innermost last. They must end innermost first:
+    * {@link closeFrame} pops the top frame whichever scope ends, so
+    * overlapping async scopes misattribute their time.
+    */
    protected readonly stack: ProfileScopeFrame[] = [];
+   /** Self-time in milliseconds per id, one sample per closed scope, which {@link records} sums. */
    protected readonly entries = new Map<string, number[]>();
 
    constructor(
@@ -122,7 +129,10 @@ export class DefaultProfileSession implements ProfileSession {
       return result;
    }
 
-   /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
+   /**
+    * Pop the top frame, which is `frame` when scopes end innermost first,
+    * charge its full duration to the new top, and record its self-time.
+    */
    protected closeFrame(frame: ProfileScopeFrame): void {
       this.stack.pop();
       const duration = this.sessionStopwatch.elapsedMs - frame.start;