@compforge/harness-common 0.0.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Harness Common for TypeScript
 
-Execution-neutral client lifecycle and datasource contracts, shared by harnesses and toolbox clients.
+Execution-neutral service topology, client lifecycle, environment context and datasource contracts, shared by harnesses and toolbox clients.
 No database drivers, Kubernetes adapters, Doctor concepts or business configuration live here.
 
 ```typescript
@@ -15,9 +15,48 @@ try {
 }
 ```
 
-A DataSource key identifies the complete configuration and access policy. Equal keys share client
-initialization, not query results. Use dataSourceKey to hash configuration without exposing credentials.
-ServiceDataSource associates a consumer-owned Service model with a source without changing its key.
+A ClientProvider clientKey identifies the complete configuration and access policy. Equal keys share client
+initialization, not query results. Use clientKey to hash configuration without exposing credentials.
+ServiceDataSource associates a shared Service (or a consumer extension) with a source without changing its key.
+DataSource extends ClientProvider with data-access semantics; accessible concrete environments implement
+ClientProvider directly. Both use the same manager. EnvironmentContext binds an Environment (or a consumer
+extension), a get-only client view and monotonic deadlineMs (performance.now()).
+It needs no fixture and owns neither disposal nor cancellation; forward remainingMs into operations.
+Providers receive a get-only ClientManager view and the root AbortSignal. Acquire dependencies through that
+view during initialize, so concurrent consumers share them and dispose before their dependencies.
+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.
+
+Service identifies a Component's runtime presence in an Environment. A Component belongs to a Repository
+on a Forge; a Service explicitly declares zero or more Workloads. Consumers extend Service with business
+capabilities, without duplicating these identities. For example:
+
+```typescript
+import type { Service } from "@compforge/harness-common";
+
+const service: Service = {
+  name: "chat",
+  component: {
+    name: "api",
+    repository: { forge: { name: "github" }, path: "example/app" },
+  },
+  environment: { name: "test" },
+  workloads: [{
+    name: "web", platform: "kubernetes",
+    location: { kind: "resource", resource_kind: "Deployment", name: "api-server" },
+  }],
+};
+```
+
+Environment carries identity and an optional local/SSH Host declaration, not a connection. HostEnvironment
+describes a target running directly on that host. Concrete accessible environments, such as toolbox's
+KubernetesEnvironment, additionally implement ClientProvider. A Host declaration alone does not add SSH
+support to a client. Service<E> and EnvironmentContext<E> preserve the concrete environment's access type.
+
+Workload describes a logical runtime carrier and its resource, Kubernetes Service or labels location.
+WorkloadInstance records an observed Pod incarnation with environment and UID identity.
+These contracts perform no discovery or I/O; callers resolve declarations in their selected environment.
+Container selection affects access routing, not Pod identity. See [the shared model](../../../docs/workload.md).
 
 Python's corresponding package is sdks/python/common (harness-common). Languages keep idiomatic APIs
 and independently versioned packages; they need not implement every model in lockstep.

package/dist/client-manager.d.ts

@@ -1,14 +1,13 @@
 import type { Client } from "./client.js";
-import type { DataSource } from "./datasource.js";
-/** Consumers borrow clients; only the root owner receives the disposal capability. */
-export interface ClientProvider {
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
-}
-/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
-export declare class ClientManager implements ClientProvider {
+import type { ClientProvider } from "./client-provider.js";
+/**
+ * @spec One root execution shares successful initialization per identity and closes clients at finalize.
+ * @rule Failed cleanup poisons the identity and remains a root disposal error; it never permits retry.
+ */
+export declare class ClientManager {
     #private;
     readonly signal: AbortSignal;
     constructor(signal?: AbortSignal);
-    get<C extends Client>(source: DataSource<C>): Promise<C>;
+    get<C extends Client>(provider: ClientProvider<C>): Promise<C>;
     dispose(): Promise<void>;
 }

package/dist/client-manager.js

@@ -1,22 +1,28 @@
-/** @spec One root execution shares successful initialization per identity and closes clients at finalize. */
+/**
+ * @spec One root execution shares successful initialization per identity and closes clients at finalize.
+ * @rule Failed cleanup poisons the identity and remains a root disposal error; it never permits retry.
+ */
 export class ClientManager {
     #controller = new AbortController();
     signal;
     #clients = new Map();
     #ready = [];
+    #unclean = new Set();
+    #cleanupErrors = [];
     #disposal;
     constructor(signal) {
         this.signal = signal ? AbortSignal.any([signal, this.#controller.signal]) : this.#controller.signal;
     }
-    get(source) {
+    get(provider) {
         this.signal.throwIfAborted();
-        const existing = this.#clients.get(source.key);
+        const key = provider.clientKey;
+        const existing = this.#clients.get(key);
         if (existing)
             return existing;
-        // Publish before construction so concurrent callers never dispatch a second factory.
+        // Publish before construction so concurrent callers never dispatch a second provider.
         const pending = Promise.resolve().then(async () => {
             this.signal.throwIfAborted();
-            const client = source.createClient(this.signal);
+            const client = provider.createClient(this, this.signal);
             try {
                 await client.initialize();
                 this.signal.throwIfAborted();
@@ -28,24 +34,27 @@ export class ClientManager {
                     await client.dispose();
                 }
                 catch (cleanup) {
+                    this.#unclean.add(key);
+                    this.#cleanupErrors.push(cleanup);
                     throw new AggregateError([error, cleanup], "Client initialization and cleanup failed");
                 }
                 throw error;
             }
         });
-        this.#clients.set(source.key, pending);
-        void pending.catch(() => { if (this.#clients.get(source.key) === pending)
-            this.#clients.delete(source.key); });
+        this.#clients.set(key, pending);
+        void pending.catch(() => {
+            if (!this.#unclean.has(key) && this.#clients.get(key) === pending)
+                this.#clients.delete(key);
+        });
         return pending;
     }
     dispose() {
         return this.#disposal ??= (async () => {
             this.#controller.abort(new Error("Client manager disposed"));
-            const settled = await Promise.allSettled(this.#clients.values());
+            await Promise.allSettled(this.#clients.values());
             this.#clients.clear();
             // Dependencies must be acquired before their consumers initialize, so reverse readiness is safe.
-            const errors = settled.flatMap(result => result.status === "rejected" && result.reason instanceof AggregateError
-                ? [result.reason] : []);
+            const errors = [...this.#cleanupErrors];
             for (const client of this.#ready.splice(0).reverse()) {
                 try {
                     await client.dispose();

package/dist/client-provider.d.ts

@@ -0,0 +1,16 @@
+import type { Client } from "./client.js";
+import type { ClientManager } from "./client-manager.js";
+/**
+ * Keyed construction independent of data or environment semantics.
+ * @spec Both environment access and data access share ClientManager ownership.
+ * @rule Identity covers implementation, target, credentials and capacity policy.
+ */
+export interface ClientProvider<C extends Client> {
+    readonly clientKey: string;
+    /** Construct only; initialize borrows dependencies through clients before publishing readiness.
+     * Dependencies must be acyclic; borrowers never dispose them. No environment model is required.
+     */
+    createClient(clients: Pick<ClientManager, "get">, signal: AbortSignal): C;
+}
+/** Stable configuration identity; credentials never appear in observable keys. */
+export declare function clientKey(protocol: string, configuration: unknown): string;

package/dist/client-provider.js

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+/** Stable configuration identity; credentials never appear in observable keys. */
+export function clientKey(protocol, configuration) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
+        return value;
+    };
+    return `${protocol}:${createHash("sha256").update(JSON.stringify(canonical(configuration))).digest("hex")}`;
+}

package/dist/component.d.ts

@@ -0,0 +1,6 @@
+import type { Repository } from "./repository.js";
+/** A buildable component within a repository; one repository may own many. */
+export interface Component {
+    readonly repository: Repository;
+    readonly name: string;
+}

package/dist/component.js

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

package/dist/context.d.ts

@@ -0,0 +1,16 @@
+import type { ClientManager } from "./client-manager.js";
+import type { Environment } from "./environment.js";
+/**
+ * Execution-scoped environment access, independent of fixture orchestration.
+ * @rule Borrows clients; does not initialize or dispose resources.
+ * Deadline uses performance.now() milliseconds, not wall-clock time.
+ * Consumers propagate remainingMs; the context itself does not cancel work.
+ * Consumers extend the shared Environment identity with their own platform access.
+ */
+export declare class EnvironmentContext<E extends Environment = Environment> {
+    readonly environment: E;
+    readonly clients: Pick<ClientManager, "get">;
+    readonly deadlineMs: number;
+    constructor(environment: E, clients: Pick<ClientManager, "get">, deadlineMs: number);
+    get remainingMs(): number;
+}

package/dist/context.js

@@ -0,0 +1,20 @@
+/**
+ * Execution-scoped environment access, independent of fixture orchestration.
+ * @rule Borrows clients; does not initialize or dispose resources.
+ * Deadline uses performance.now() milliseconds, not wall-clock time.
+ * Consumers propagate remainingMs; the context itself does not cancel work.
+ * Consumers extend the shared Environment identity with their own platform access.
+ */
+export class EnvironmentContext {
+    environment;
+    clients;
+    deadlineMs;
+    constructor(environment, clients, deadlineMs) {
+        this.environment = environment;
+        this.clients = clients;
+        this.deadlineMs = deadlineMs;
+    }
+    get remainingMs() {
+        return Math.max(0, this.deadlineMs - performance.now());
+    }
+}

package/dist/datasource.d.ts

@@ -1,17 +1,14 @@
 import type { Client } from "./client.js";
-/** Identity includes protocol, target, configuration and credentials, never an object address. */
-export interface DataSource<C extends Client> {
-    readonly key: string;
-    /** Construct only; Client.initialize owns external work. */
-    createClient(signal: AbortSignal): C;
+import type { ClientProvider } from "./client-provider.js";
+import type { Service } from "./service.js";
+/** A source of data; accessible environments implement ClientProvider directly. */
+export interface DataSource<C extends Client> extends ClientProvider<C> {
 }
 /**
  * @spec A Service association does not own a client or change the source identity.
- * @why Service models belong to consumers; binding the same source must not fragment client reuse.
+ * @why Business ownership must not fragment reuse of the same source's client.
  */
-export interface ServiceDataSource<Service, C extends Client> {
-    readonly service: Service;
+export interface ServiceDataSource<S extends Service, C extends Client> {
+    readonly service: S;
     readonly source: DataSource<C>;
 }
-/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
-export declare function dataSourceKey(protocol: string, configuration: unknown): string;

package/dist/datasource.js

@@ -1,12 +1 @@
-import { createHash } from "node:crypto";
-/** Stable in-memory identity; connection credentials must not appear in observable cache keys. */
-export function dataSourceKey(protocol, configuration) {
-    const canonical = (value) => {
-        if (Array.isArray(value))
-            return value.map(canonical);
-        if (value && typeof value === "object")
-            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
-        return value;
-    };
-    return `${protocol}:${createHash("sha256").update(JSON.stringify(canonical(configuration))).digest("hex")}`;
-}
+export {};

package/dist/environment.d.ts

@@ -0,0 +1,16 @@
+import type { Host } from "./host.js";
+/**
+ * Named deployment environment, independent of any access mechanism.
+ * @rule Accessible environments additionally implement ClientProvider; identity alone grants no access.
+ */
+export interface Environment {
+    readonly name: string;
+    /** Omission denotes a generic environment. Concrete platforms declare their kind. */
+    readonly kind?: string;
+    /** Omission uses the current execution host, without changing environment identity. */
+    readonly host?: Host;
+}
+/** Target processes run directly on the optional host, locally or through SSH. */
+export interface HostEnvironment extends Environment {
+    readonly kind: "host";
+}

package/dist/environment.js

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

package/dist/forge.d.ts

@@ -0,0 +1,4 @@
+/** Stable identity of a system hosting source-code repositories. */
+export interface Forge {
+    readonly name: string;
+}

package/dist/forge.js

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

package/dist/host.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An optional environment access host, not necessarily the target's execution host.
+ * Kubernetes access paths belong to this host's filesystem, not the Pod's.
+ * SSH addresses use the caller's SSH configuration; credentials do not belong here.
+ * This declaration does not imply a consumer supports SSH execution.
+ */
+export type Host = {
+    readonly name: string;
+} & ({
+    readonly transport?: "local";
+    readonly address?: never;
+} | {
+    readonly transport: "ssh";
+    readonly address: string;
+});

package/dist/host.js

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

package/dist/index.d.ts

@@ -1,3 +1,12 @@
 export * from "./client.js";
-export * from "./client-manager.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";

package/dist/index.js

@@ -1,3 +1,12 @@
 export * from "./client.js";
-export * from "./client-manager.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";

package/dist/repository.d.ts

@@ -0,0 +1,6 @@
+import type { Forge } from "./forge.js";
+/** A repository identified by its Forge and path within that Forge. */
+export interface Repository {
+    readonly forge: Forge;
+    readonly path: string;
+}

package/dist/repository.js

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

package/dist/service.d.ts

@@ -0,0 +1,16 @@
+import type { Component } from "./component.js";
+import type { Environment } from "./environment.js";
+import type { Workload } from "./workload.js";
+/**
+ * One Component's logical runtime presence in an Environment.
+ * @spec Identity is scoped by name, Component and Environment, not platform resource names.
+ * @rule Workload mappings may change without changing Service identity; declarations prove no live instances.
+ * Consumers extend this model with their own capabilities and execution policy.
+ */
+export interface Service<E extends Environment = Environment> {
+    readonly name: string;
+    readonly component: Component;
+    readonly environment: E;
+    /** Zero or more runtime carriers; an empty array declares no workloads. */
+    readonly workloads: readonly Workload[];
+}

package/dist/service.js

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

package/dist/workload.d.ts

@@ -0,0 +1,38 @@
+/** Logical carrier, not proof of existence. Location is data, not a discovery executor. */
+export interface Workload {
+    readonly name: string;
+    readonly platform: "kubernetes";
+    /** Omission requires a resolver default; never means all namespaces. */
+    readonly namespace?: string;
+    readonly location: {
+        readonly kind: "resource";
+        readonly resource_kind: "Deployment" | "StatefulSet" | "DaemonSet" | "Pod";
+        readonly name: string;
+    } | {
+        readonly kind: "service";
+        readonly name: string;
+    } | {
+        readonly kind: "labels";
+        readonly labels: Readonly<Record<string, string>>;
+    };
+    /** Operation default, not workload identity. */
+    readonly container?: string;
+}
+/**
+ * Observed Pod incarnation. No access credentials belong in instance evidence.
+ * @spec Environment and UID separate clusters and same-name Pod replacements.
+ * @rule Container participates in access/cache keys, not Pod identity.
+ */
+export interface WorkloadInstance {
+    readonly platform: "kubernetes";
+    /** Stable caller-owned key distinguishing clusters/contexts, not a display label. */
+    readonly environment: string;
+    /** Declaration name scoped by owning Service; provenance, not Pod identity. */
+    readonly workload: string;
+    readonly namespace: string;
+    readonly pod: string;
+    readonly uid: string;
+    readonly container?: string;
+}
+/** Physical identity only; callers retain workload provenance separately. */
+export declare function sameWorkloadInstance(left: WorkloadInstance, right: WorkloadInstance): boolean;

package/dist/workload.js

@@ -0,0 +1,8 @@
+/** Physical identity only; callers retain workload provenance separately. */
+export function sameWorkloadInstance(left, right) {
+    return left.platform === right.platform
+        && left.environment === right.environment
+        && left.namespace === right.namespace
+        && left.pod === right.pod
+        && left.uid === right.uid;
+}

package/package.json

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