@compforge/harness-common 0.5.9 → 0.5.11

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;
@@ -190,3 +195,11 @@ rendering remain consumer-owned. See [the shared contract](../../../docs/resourc
 State, branches, source repository, revisions and provider timestamps are optional facts.
 See [the shared contract](../../../docs/pull-request.md) for identity and unknown-state semantics.
 Forge access and polling remain consumer/toolkit responsibilities.
+
+## Portable values
+
+`Value`, `ValueCodec`, `Summary`, and JSON normalization are producer-owned data contracts.
+Use `serializeValue` to preserve immutable JSON and reading hints, and `deserializeValue`
+with an explicit matching codec to restore runtime behavior. Encoding and decoding are pure.
+Doctor and its Plugins import these contracts directly from `@compforge/harness-common`;
+Observation identity, evidence and rendering remain with their consumers.

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/dist/index.d.ts

@@ -17,3 +17,6 @@ export * from "./system/knowledge.js";
 export type { Identity } from "./identity.js";
 export * from "./access/file.js";
 export * from "./system/resource.js";
+export * from "./json.js";
+export * from "./summary.js";
+export * from "./value.js";

package/dist/index.js

@@ -15,3 +15,6 @@ export * from "./execution.js";
 export * from "./system/knowledge.js";
 export * from "./access/file.js";
 export * from "./system/resource.js";
+export * from "./json.js";
+export * from "./summary.js";
+export * from "./value.js";

package/dist/json.d.ts

@@ -0,0 +1,18 @@
+/** Normalized protocol data: object absence is represented by an omitted property. */
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+/** Encoder input may express absent object fields as undefined; array elements must have a value. */
+export type JsonInput = JsonPrimitive | readonly JsonInput[] | {
+    readonly [key: string]: JsonInput | undefined;
+};
+/**
+ * @spec Undefined object properties mean absence and are omitted recursively; null remains explicit.
+ * @rule Top-level undefined, undefined array elements and holes are rejected, never converted to null.
+ * @see ../../../../docs/kernel.md
+ */
+export declare function immutableJsonValue(value: unknown, label: string): JsonValue;
+/** Normalize optional fields and create a deeply immutable JSON object without coercing unsupported data. */
+export declare function immutableJsonObject(value: unknown, label: string): JsonObject;

package/dist/json.js

@@ -0,0 +1,79 @@
+function propertyPath(path, key) {
+    return `${path}[${JSON.stringify(key)}]`;
+}
+function cloneJson(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${path} must be a finite JSON number`);
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== "object") {
+        throw new Error(`${path} contains unsupported JSON value '${typeof value}'`);
+    }
+    if (ancestors.has(value))
+        throw new Error(`${path} contains a circular reference`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const copy = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.hasOwn(value, index))
+                    throw new Error(`${path}[${index}] is a sparse array item`);
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!descriptor.enumerable || !("value" in descriptor)) {
+                    throw new Error(`${path}[${index}] must be an enumerable data property`);
+                }
+                copy.push(cloneJson(descriptor.value, `${path}[${index}]`, ancestors));
+            }
+            for (const key of Reflect.ownKeys(value)) {
+                if (key === "length")
+                    continue;
+                if (typeof key !== "string" || !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length) {
+                    throw new Error(`${path} contains a non-JSON array property`);
+                }
+            }
+            return Object.freeze(copy);
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new Error(`${path} must be a plain JSON object`);
+        }
+        const copy = Object.create(null);
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string")
+                throw new Error(`${path} contains a symbol property`);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor.enumerable || !("value" in descriptor)) {
+                throw new Error(`${propertyPath(path, key)} must be an enumerable data property`);
+            }
+            if (descriptor.value === undefined)
+                continue;
+            copy[key] = cloneJson(descriptor.value, propertyPath(path, key), ancestors);
+        }
+        return Object.freeze(copy);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isJsonArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * @spec Undefined object properties mean absence and are omitted recursively; null remains explicit.
+ * @rule Top-level undefined, undefined array elements and holes are rejected, never converted to null.
+ * @see ../../../../docs/kernel.md
+ */
+export function immutableJsonValue(value, label) {
+    return cloneJson(value, label, new Set());
+}
+/** Normalize optional fields and create a deeply immutable JSON object without coercing unsupported data. */
+export function immutableJsonObject(value, label) {
+    const snapshot = immutableJsonValue(value, label);
+    if (snapshot === null || isJsonArray(snapshot) || typeof snapshot !== "object") {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return snapshot;
+}

package/dist/summary.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Producer-owned reading hints for the accompanying evidence.
+ *
+ * @spec text explains what the evidence means and limits on judgment; fields expose supporting counts, objects, and evidence.
+ * @spec The enclosing command or query result owns status: it describes execution completeness, not application health.
+ * @rule For partial results, truncation, zero matches, or failed sources, explain what was obtained, what is missing, and which judgments remain unsupported.
+ * @see ../../../../docs/kernel.md
+ */
+export interface Summary {
+    readonly title: string;
+    /**
+     * A few concise, producer-authored sentences interpreting the result and its limits.
+     * Keep data details, record lists, and raw output in fields or linked evidence; text is not a detailed report.
+     * Avoid repeating field values or inferring unsupported conclusions; bounded views may truncate long text.
+     * Optional when the fields are self-explanatory; the accompanying data remains the machine contract.
+     */
+    readonly text?: string;
+    /** Supporting evidence in reading order, with decisive facts before context for bounded views. Paths are relative to the accompanying data. */
+    readonly fields: readonly {
+        readonly label: string;
+        readonly path: readonly string[];
+    }[];
+}
+export declare function validateSummary(value: unknown): asserts value is Summary;

package/dist/summary.js

@@ -0,0 +1,17 @@
+export function validateSummary(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Summary must be an object");
+    const summary = value;
+    if (typeof summary.title !== "string" || !summary.title.trim())
+        throw new Error("Summary.title must be a non-empty string");
+    if (summary.text !== undefined && typeof summary.text !== "string")
+        throw new Error("Summary.text must be a string");
+    if (!Array.isArray(summary.fields))
+        throw new Error("Summary.fields must be an array");
+    for (const field of summary.fields) {
+        if (!field || typeof field !== "object" || typeof field.label !== "string" || !field.label.trim()
+            || !Array.isArray(field.path) || !field.path.every((key) => typeof key === "string" && key.length > 0)) {
+            throw new Error("Summary field requires a label and a string path");
+        }
+    }
+}

package/dist/value.d.ts

@@ -0,0 +1,27 @@
+import { type JsonInput, type JsonValue } from "./json.js";
+import { type Summary } from "./summary.js";
+/** Runtime business data and its producer-owned reading hints. */
+export interface Value {
+    summary(): Summary;
+}
+/**
+ * @spec decode validates unknown JSON and restores equivalent data and behavior after encode
+ * @rule Both operations are pure: no environment access or resource acquisition
+ * @see ../../../../docs/kernel.md
+ */
+export interface ValueCodec<T extends Value> {
+    encode(value: T): JsonInput;
+    decode(json: unknown): T;
+}
+/** A portable representation of a producer-owned Value, independent of any Command or Observation. */
+export interface SerializedValue {
+    readonly data: JsonValue;
+    readonly summary: Summary;
+}
+/** @spec Serialization normalizes absent object fields and preserves protocol data; the Codec owns domain validation and reconstruction. */
+export declare function serializeValue<T extends Value>(value: T, codec: ValueCodec<T>, options?: {
+    label?: string;
+    maxBytes?: number;
+}): SerializedValue;
+/** @spec Rehydration is explicit and pure; it never replaces a previously saved Summary. */
+export declare function deserializeValue<T extends Value>(json: unknown, codec: ValueCodec<T>): T;

package/dist/value.js

@@ -0,0 +1,21 @@
+import { immutableJsonObject, immutableJsonValue } from "./json.js";
+import { validateSummary } from "./summary.js";
+/** @spec Serialization normalizes absent object fields and preserves protocol data; the Codec owns domain validation and reconstruction. */
+export function serializeValue(value, codec, options = {}) {
+    const label = options.label ?? "Value";
+    const data = immutableJsonValue(codec.encode(value), `${label}.data`);
+    if (options.maxBytes !== undefined && new TextEncoder().encode(JSON.stringify(data)).byteLength > options.maxBytes) {
+        throw new Error(`${label} exceeds JSON byte budget`);
+    }
+    const restored = deserializeValue(data, codec);
+    const summary = restored.summary();
+    validateSummary(summary);
+    return Object.freeze({ data, summary: immutableJsonObject(summary, `${label}.summary`) });
+}
+/** @spec Rehydration is explicit and pure; it never replaces a previously saved Summary. */
+export function deserializeValue(json, codec) {
+    const value = codec.decode(immutableJsonValue(json, "Value.data"));
+    if (!value || typeof value.summary !== "function")
+        throw new Error("Codec must restore a Value with summary()");
+    return value;
+}

package/package.json

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