@compforge/harness-common 0.5.10 → 0.5.11

package/README.md

@@ -195,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/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.10",
+  "version": "0.5.11",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {