@compforge/harness-common 0.5.3 → 0.5.5

package/README.md

@@ -27,11 +27,20 @@ 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.
 
-`FileDataSource` is an abstract, runtime-recognizable DataSource for one file path. Its `FileClient.read`
-returns fresh `Uint8Array` bytes with explicit `maxBytes`, `timeoutMs` and optional cancellation.
-An empty file succeeds; an oversized or incomplete read rejects. The source's `path` and concrete
-location metadata let consumers attach provenance. Parsing, configuration precedence and persistence
-belong to consumers. Platform implementations live in `@compforge/harness-toolbox/file`.
+`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;
+missing and oversized files keep independent errors without discarding successful siblings.
+
+Callers specify `maxBytes` per file, `maxTotalBytes` for all retained bytes (including in-progress
+files), `timeoutMs` for the complete operation including queueing, and optional cancellation.
+Cancellation, total-budget exhaustion, the group deadline and transport/protocol failures reject
+the whole operation. Every read observes fresh bytes; a co-acquisition group is not an atomic
+filesystem snapshot. Parsing, configuration precedence and persistence belong to consumers.
+Platform implementations live in `@compforge/harness-toolbox/file`.
+
+Version 0.5.4 replaces the single `path` and byte-only return value; single-file consumers declare
+`paths: [path]` and consume the sole per-file result. There is no implicit legacy adapter.
 
 Service identifies a Component's runtime presence in an Environment. A Component belongs to a Repository
 on a Forge. Product is a separate business identity; consumers own its many-to-many associations
@@ -167,3 +176,10 @@ headings or code blocks in child output.
 Move `KnowledgeMarkdownOptions.renderEntry` or `dictionaryToMarkdown` renderer callbacks
 into each Entry's `markdown()` method. These callback arguments are removed in 0.5; a
 custom Entry now renders consistently when shown alone or through its Dictionary and Knowledge.
+
+## Resource inventory
+
+`Resource` declares a collection held by a running Service; `ServiceResource` records manages/uses
+relationships without duplicating identity. `ResourceSnapshot` retains typed instances, unit-bearing
+measurements, independently known totals and complete/partial/unavailable coverage. Discovery and
+rendering remain consumer-owned. See [the shared contract](../../../docs/resource.md).

package/dist/file.d.ts

@@ -2,28 +2,40 @@ import type { Client } from "./client.js";
 import type { ClientManager } from "./client-manager.js";
 import type { DataSource } from "./datasource.js";
 export interface FileReadOptions {
-    /** Maximum complete file size; exceeding it rejects instead of returning a prefix. */
+    /** Maximum complete size of each file; an oversized file returns an error without partial bytes. */
     maxBytes: number;
-    /** Includes time waiting for a concurrency slot. */
+    /** Maximum bytes retained across the whole read, including in-progress files. */
+    maxTotalBytes: number;
+    /** One deadline for queueing and acquiring the complete group. */
     timeoutMs: number;
     signal?: AbortSignal;
 }
+export type FileReadResult = {
+    readonly path: string;
+    readonly status: "ok";
+    readonly bytes: Uint8Array;
+} | {
+    readonly path: string;
+    readonly status: "error";
+    readonly error: Error;
+};
 /**
- * @spec Each read obtains fresh bytes from the source's bound path. Empty files succeed;
- * missing files, incomplete reads and exceeded limits reject.
- * @rule Parsing, configuration precedence and evidence persistence belong to consumers.
+ * @spec Each read acquires the declared group once and returns one result per path, in declaration order.
+ * Individual file failures do not discard other files; cancellation, the group deadline, total budget
+ * and transport/protocol failures reject the operation. Every read obtains fresh bytes.
+ * @rule Group acquisition is not an atomic filesystem snapshot. Parsing and evidence belong to consumers.
  */
 export interface FileClient extends Client {
-    read(options: FileReadOptions): Promise<Uint8Array>;
+    read(options: FileReadOptions): Promise<readonly FileReadResult[]>;
 }
 /**
- * A single file location, discoverable without creating a client or performing I/O.
- * @why A shared runtime type lets consumers recognize file sources without a second kind registry.
- * @rule clientKey identifies access, not cached file contents or a Service-owned alias.
+ * A nonempty group of distinct paths that the caller declares can be acquired together.
+ * @why The source is the acquisition unit; grouping does not require consumers to guess transport capabilities.
+ * @rule clientKey identifies access and the group, not cached contents or a Service-owned alias.
  * @see {@link component://../../../docs/toolbox.md}
  */
 export declare abstract class FileDataSource<C extends FileClient = FileClient> implements DataSource<C> {
-    abstract readonly path: string;
+    abstract readonly paths: readonly string[];
     readonly description?: string;
     abstract readonly clientKey: string;
     abstract createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): C;

package/dist/file.js

@@ -1,7 +1,7 @@
 /**
- * A single file location, discoverable without creating a client or performing I/O.
- * @why A shared runtime type lets consumers recognize file sources without a second kind registry.
- * @rule clientKey identifies access, not cached file contents or a Service-owned alias.
+ * A nonempty group of distinct paths that the caller declares can be acquired together.
+ * @why The source is the acquisition unit; grouping does not require consumers to guess transport capabilities.
+ * @rule clientKey identifies access and the group, not cached contents or a Service-owned alias.
  * @see {@link component://../../../docs/toolbox.md}
  */
 export class FileDataSource {

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export type { Product } from "./product.js";
 export * from "./knowledge.js";
 export type { Identity } from "./identity.js";
 export * from "./file.js";
+export * from "./resource.js";

package/dist/index.js

@@ -13,3 +13,4 @@ export * from "./service.js";
 export * from "./execution.js";
 export * from "./knowledge.js";
 export * from "./file.js";
+export * from "./resource.js";

package/dist/resource.d.ts

@@ -0,0 +1,62 @@
+import type { Service } from "./service.js";
+/** A category of resources persistently managed or used by a running Service.
+ * @spec A declaration describes what can be inventoried, not the current count or existence.
+ * @rule id identifies the same resource collection across Services; names are presentation only.
+ */
+export interface Resource {
+    readonly id: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly description?: string;
+}
+/** Association does not transfer exclusive ownership or duplicate the underlying resource. */
+export interface ServiceResource<S extends Service = Service> {
+    readonly service: S;
+    readonly resource: Resource;
+    readonly relationship: "manages" | "uses";
+}
+/** Caller-owned environment and collection IDs disambiguate identical local instance IDs. */
+export interface ResourceInstanceRef {
+    readonly environment: string;
+    readonly resource: string;
+    readonly id: string;
+}
+export interface ResourceInstance<Details = Readonly<Record<string, unknown>>> {
+    readonly ref: ResourceInstanceRef;
+    readonly name?: string;
+    /** Domain state, never an implicit health verdict. */
+    readonly state?: string;
+    readonly details?: Details;
+}
+/** Quantities retain their units and aggregation scope; different measures are not additive. */
+export interface ResourceMeasurement {
+    readonly name: string;
+    readonly value: number;
+    readonly unit: string;
+    readonly scope: "observed" | "total";
+}
+export type ResourceCoverage = {
+    readonly status: "complete";
+} | {
+    readonly status: "partial" | "unavailable";
+    readonly reason: string;
+};
+/**
+ * Read-only inventory evidence. Collection, access, pagination policy and rendering belong to consumers.
+ * @spec totalCount is an independently known count for scope, never inferred from a page of instances.
+ * @spec Unknown values are omitted; partial or unavailable acquisition is not a resource health verdict.
+ * @rule source, scope and details contain only safe serializable evidence, never access credentials.
+ */
+export interface ResourceSnapshot<Details = Readonly<Record<string, unknown>>> {
+    readonly resource: Resource;
+    readonly environment: string;
+    readonly observedAt: string;
+    readonly source: string;
+    readonly scope: Readonly<Record<string, string>>;
+    readonly coverage: ResourceCoverage;
+    readonly totalCount?: number;
+    readonly measurements?: readonly ResourceMeasurement[];
+    readonly instances?: readonly ResourceInstance<Details>[];
+    readonly nextCursor?: string;
+}
+export declare function sameResourceInstance(left: ResourceInstanceRef, right: ResourceInstanceRef): boolean;

package/dist/resource.js

@@ -0,0 +1,3 @@
+export function sameResourceInstance(left, right) {
+    return left.environment === right.environment && left.resource === right.resource && left.id === right.id;
+}

package/package.json

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