@compforge/harness-common 0.5.9 → 0.5.10

package/README.md

@@ -27,6 +27,11 @@ view during initialize, so concurrent consumers share them and dispose before th
 Dependency graphs must be acyclic. A failed initialization permits retry only after successful cleanup;
 failed cleanup poisons that key and is reported again when the root manager is disposed.
 
+Use `clients.create({ createClient })` for a fresh caller-owned client. The caller may dispose it as soon as its work
+finishes; dependencies acquired through `get` remain available to other clients until root disposal. The root also
+disposes created clients as an idempotent safety net. Use `get` when callers should share the client itself; borrowers
+must not dispose those shared instances. Neither API constructs anything before it is called.
+
 `FileDataSource` declares a nonempty group of distinct `paths` that can be acquired together.
 `FileClient.read` obtains the whole group once and returns one `FileReadResult` per declared path,
 in order: `{ path, status: "ok", bytes }` or `{ path, status: "error", error }`. Empty files succeed;

package/dist/access/client-manager.d.ts

@@ -9,5 +9,11 @@ export declare class ClientManager {
     readonly signal: AbortSignal;
     constructor(signal?: AbortSignal);
     get<C extends Client>(provider: ClientProvider<C>): Promise<C>;
+    /**
+     * @spec Create a caller-owned client that can be disposed before this root scope ends.
+     * @rule Dependencies acquired with get remain shared until root disposal; create never caches by identity.
+     * @why Short-lived protocol clients borrow longer-lived transports. Root disposal remains an idempotent safety net.
+     */
+    create<C extends Client>(factory: Pick<ClientProvider<C>, "createClient">): Promise<C>;
     dispose(): Promise<void>;
 }

package/dist/access/client-manager.js

@@ -14,8 +14,18 @@ export class ClientManager {
         this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
     }
     get(provider) {
+        return this.#acquire(provider.clientKey, provider);
+    }
+    /**
+     * @spec Create a caller-owned client that can be disposed before this root scope ends.
+     * @rule Dependencies acquired with get remain shared until root disposal; create never caches by identity.
+     * @why Short-lived protocol clients borrow longer-lived transports. Root disposal remains an idempotent safety net.
+     */
+    create(factory) {
+        return this.#acquire(Symbol("owned client"), factory);
+    }
+    #acquire(key, provider) {
         this.signal.throwIfAborted();
-        const key = provider.clientKey;
         const existing = this.#clients.get(key);
         if (existing)
             return existing;

package/dist/access/client.d.ts

@@ -1,4 +1,9 @@
-/** A protocol client owns its initialization and idempotent cleanup, including partial initialization. */
+/**
+ * Managed access lifecycle, implemented by protocol clients and resource-owning transports.
+ * @spec Initialization failure still requires disposal of every partially created resource.
+ * @spec Successful disposal means owned work has ended; borrowed dependencies belong to their manager.
+ * @rule A timeout waiting for cleanup is a cleanup failure, never proof that resources were released.
+ */
 export interface Client {
     initialize(): Promise<void>;
     dispose(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-common",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {