@compforge/harness-common 0.5.1 → 0.5.4

package/README.md

@@ -27,6 +27,21 @@ 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` 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
 with Components. Repository discovery and directory ownership remain consumer responsibilities.
@@ -35,7 +50,7 @@ capabilities, without duplicating these identities. For example:
 
 ```typescript
 import {
-  conceptToMarkdown, knowledgeToMarkdown, stepToMarkdown, workflowToMarkdown,
+  repositoryId, conceptToMarkdown, knowledgeToMarkdown, stepToMarkdown, workflowToMarkdown,
   type Service,
 } from "@compforge/harness-common";
 
@@ -53,7 +68,7 @@ const service: Service = {
   upstream: ["gateway"],
   component: {
     name: "api",
-    repository: { forge: { name: "github" }, path: "example/app" },
+    repository: { forge: { name: "github" }, path: "example/app", id() { return repositoryId(this); } },
   },
   environment: { name: "test" },
   workloads: [{
@@ -63,6 +78,10 @@ const service: Service = {
 };
 ```
 
+Repository extends Identity: `id()` returns `forge.name/path`, excluding `forkedFrom`.
+Use `repositoryId(this)` when implementing the method, including when restoring a Repository
+from JSON; methods are not serialized.
+
 Service and Product accept an optional description for a short introduction, and structured
 `knowledge` for concepts, workflows, articles and dictionaries. Service knowledge covers its own
 responsibilities, while Product knowledge covers end-to-end flows. Consumers maintain this offline

package/dist/file.d.ts

@@ -0,0 +1,42 @@
+import type { Client } from "./client.js";
+import type { ClientManager } from "./client-manager.js";
+import type { DataSource } from "./datasource.js";
+export interface FileReadOptions {
+    /** Maximum complete size of each file; an oversized file returns an error without partial bytes. */
+    maxBytes: number;
+    /** 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 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<readonly FileReadResult[]>;
+}
+/**
+ * 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 paths: readonly string[];
+    readonly description?: string;
+    abstract readonly clientKey: string;
+    abstract createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): C;
+}

package/dist/file.js

@@ -0,0 +1,9 @@
+/**
+ * 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 {
+    description;
+}

package/dist/identity.d.ts

@@ -0,0 +1,7 @@
+/**
+ * An object referenced by a string identifier; the model owns its format and uniqueness scope.
+ * @spec The same business identity yields the same identifier; descriptive metadata is excluded.
+ */
+export interface Identity {
+    id(): string;
+}

package/dist/identity.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -13,3 +13,5 @@ export * from "./service.js";
 export * from "./execution.js";
 export type { Product } from "./product.js";
 export * from "./knowledge.js";
+export type { Identity } from "./identity.js";
+export * from "./file.js";

package/dist/index.js

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

package/dist/repository.d.ts

@@ -1,10 +1,11 @@
 import type { Forge } from "./forge.js";
+import type { Identity } from "./identity.js";
 /**
  * A repository identified by its Forge and path within that Forge.
  * @spec forkedFrom is the direct parent path within the same Forge instance, not repository identity.
  * @see {@link component://docs/kernel.md}
  */
-export interface Repository {
+export interface Repository extends Identity {
     readonly forge: Forge;
     readonly path: string;
     /**
@@ -13,3 +14,8 @@ export interface Repository {
      */
     readonly forkedFrom?: string | null;
 }
+/**
+ * Derive the Repository.id() value from identity fields.
+ * @spec Repository identity is forge.name/path; fork provenance is excluded.
+ */
+export declare function repositoryId(repository: Pick<Repository, "forge" | "path">): string;

package/dist/repository.js

@@ -1 +1,7 @@
-export {};
+/**
+ * Derive the Repository.id() value from identity fields.
+ * @spec Repository identity is forge.name/path; fork provenance is excluded.
+ */
+export function repositoryId(repository) {
+    return `${repository.forge.name}/${repository.path}`;
+}

package/package.json

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