@compforge/harness-common 0.5.4 → 0.5.6

package/README.md

@@ -176,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/{context.d.ts → access/context.d.ts}

@@ -1,5 +1,5 @@
 import type { ClientManager } from "./client-manager.js";
-import type { Environment } from "./environment.js";
+import type { Environment } from "../system/environment.js";
 /**
  * Execution-scoped environment access, independent of fixture orchestration.
  * @rule Borrows clients; does not initialize or dispose resources.

package/dist/{datasource.d.ts → access/datasource.d.ts}

@@ -1,6 +1,6 @@
 import type { Client } from "./client.js";
 import type { ClientProvider } from "./client-provider.js";
-import type { Service } from "./service.js";
+import type { Service } from "../system/service.js";
 /** A source of data; accessible environments implement ClientProvider directly. */
 export interface DataSource<C extends Client> extends ClientProvider<C> {
     /** Safe descriptive metadata for discovery; never credentials or part of clientKey. */

package/dist/execution.d.ts

@@ -1,4 +1,4 @@
-import type { Service } from "./service.js";
+import type { Service } from "./system/service.js";
 /** Stable capability identity, independent of access configuration. */
 export interface Operation {
     readonly name: string;

package/dist/index.d.ts

@@ -1,17 +1,18 @@
-export * from "./client.js";
-export * from "./client-provider.js";
-export * from "./context.js";
-export { ClientManager } from "./client-manager.js";
-export * from "./datasource.js";
-export * from "./workload.js";
-export * from "./forge.js";
-export * from "./repository.js";
-export * from "./component.js";
-export * from "./host.js";
-export * from "./environment.js";
-export * from "./service.js";
+export * from "./access/client.js";
+export * from "./access/client-provider.js";
+export * from "./access/context.js";
+export { ClientManager } from "./access/client-manager.js";
+export * from "./access/datasource.js";
+export * from "./system/workload.js";
+export * from "./system/forge.js";
+export * from "./system/repository.js";
+export * from "./system/component.js";
+export * from "./system/host.js";
+export * from "./system/environment.js";
+export * from "./system/service.js";
 export * from "./execution.js";
-export type { Product } from "./product.js";
-export * from "./knowledge.js";
+export type { Product } from "./system/product.js";
+export * from "./system/knowledge.js";
 export type { Identity } from "./identity.js";
-export * from "./file.js";
+export * from "./access/file.js";
+export * from "./system/resource.js";

package/dist/index.js

@@ -1,15 +1,16 @@
-export * from "./client.js";
-export * from "./client-provider.js";
-export * from "./context.js";
-export { ClientManager } from "./client-manager.js";
-export * from "./datasource.js";
-export * from "./workload.js";
-export * from "./forge.js";
-export * from "./repository.js";
-export * from "./component.js";
-export * from "./host.js";
-export * from "./environment.js";
-export * from "./service.js";
+export * from "./access/client.js";
+export * from "./access/client-provider.js";
+export * from "./access/context.js";
+export { ClientManager } from "./access/client-manager.js";
+export * from "./access/datasource.js";
+export * from "./system/workload.js";
+export * from "./system/forge.js";
+export * from "./system/repository.js";
+export * from "./system/component.js";
+export * from "./system/host.js";
+export * from "./system/environment.js";
+export * from "./system/service.js";
 export * from "./execution.js";
-export * from "./knowledge.js";
-export * from "./file.js";
+export * from "./system/knowledge.js";
+export * from "./access/file.js";
+export * from "./system/resource.js";

package/dist/{repository.d.ts → system/repository.d.ts}

@@ -1,5 +1,5 @@
 import type { Forge } from "./forge.js";
-import type { Identity } from "./identity.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.

package/dist/system/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/system/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.4",
+  "version": "0.5.6",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {