@compforge/harness-common 0.4.0 → 0.5.3

package/README.md

@@ -27,6 +27,12 @@ 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`.
+
 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.
@@ -34,20 +40,26 @@ A Service explicitly declares zero or more Workloads. Consumers extend Service w
 capabilities, without duplicating these identities. For example:
 
 ```typescript
-import type { Service } from "@compforge/harness-common";
+import {
+  repositoryId, conceptToMarkdown, knowledgeToMarkdown, stepToMarkdown, workflowToMarkdown,
+  type Service,
+} from "@compforge/harness-common";
 
 const service: Service = {
   name: "chat",
   knowledge: {
-    concepts: [{ id: "conversation", name: "Conversation", description: "Contains Messages; each Message may have multiple execution Attempts." }],
-    workflows: [{ id: "reply", title: "Reply", summary: "Accept and answer a message.", steps: [
-      { id: "execute", title: "Execute", description: "Execute an attempt and persist its response." },
+    markdown() { return knowledgeToMarkdown(this); },
+    concepts: [{ id: "conversation", name: "Conversation", description: "Contains Messages; each Message may have multiple execution Attempts.",
+      markdown() { return conceptToMarkdown(this); } }],
+    workflows: [{ markdown() { return workflowToMarkdown(this); }, id: "reply", title: "Reply", summary: "Accept and answer a message.", steps: [
+      { id: "execute", title: "Execute", description: "Execute an attempt and persist its response.",
+        markdown() { return stepToMarkdown(this); } },
     ] }],
   },
   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: [{
@@ -57,6 +69,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
@@ -85,8 +101,15 @@ Development: bun install, make lint, make test. Published artifacts are Node-com
 
 Product and Service accept an optional `knowledge` declaration. `Knowledge` groups
 `Concept`, `Workflow` (with parent-scoped `Step` records), `Article` (with `Section`
-records), and typed `Dictionary<Entry>` collections. These are plain offline data:
-JSON preserves their content, and the containing consumer owns distribution and version selection.
+records), and typed `Dictionary<Entry>` collections. All eight content interfaces extend
+`Markdown`, whose `markdown(): string` method returns an I/O-free representation.
+Declarations remain ordinary objects; methods can delegate to the shared converters below.
+`KnowledgeSource` describes provenance and does not carry this rendering contract.
+
+JSON preserves the content fields, but not methods. Consumers own source validation,
+method restoration, distribution and version selection. Parsing JSON or asserting a type
+does not create a callable Knowledge object; restore methods on each content object before
+exposing it through these interfaces.
 
 IDs are unique per kind within the owner, and per child collection within its parent.
 Step `parentId` expresses inclusion; sibling order follows the array even when a parent
@@ -98,12 +121,49 @@ published definitions independently of a containing distribution's version.
 `knowledge.ts` also provides deterministic, I/O-free Markdown projections:
 `knowledgeToMarkdown`, `conceptToMarkdown`, `workflowToMarkdown`, `stepToMarkdown`, `articleToMarkdown`,
 `sectionToMarkdown`, `dictionaryToMarkdown` and `entryToMarkdown`.
-Dictionary entries retain their typed domain fields; consumers can supply an entry
-renderer to include these fields. The default renderer uses name, description and aliases.
-Terminal presentation, exact lookup, search, source loading and vector indexes belong to consumers.
+Dictionary entries retain their typed domain fields; implement `Entry.markdown()` to
+include these fields. The shared `entryToMarkdown` uses name, description and aliases.
+Generated headings and ordered steps use compact spacing; authored paragraphs and code
+blocks retain their content. Terminal presentation, exact lookup, search, source loading
+and vector indexes belong to consumers.
 
 ## Upgrade to 0.4
 
 Move the removed Product/Service `concepts` and `workflows` string fields into
 `knowledge.concepts` and `knowledge.workflows`. Use Concept records for domain objects
 and Workflow/Step records for business processes. Knowledge remains optional.
+
+## Upgrade to 0.5
+
+Implement `markdown()` on Knowledge and each contained Concept, Workflow, Step, Article,
+Section, Dictionary and Entry. For example:
+
+```typescript
+import { conceptToMarkdown, type Concept } from "@compforge/harness-common";
+
+const concept: Concept = {
+  id: "carrier",
+  name: "Carrier",
+  description: "Infrastructure capacity.",
+  markdown() { return conceptToMarkdown(this); },
+};
+
+console.log(concept.markdown());
+```
+
+Existing `...ToMarkdown` functions remain available as shared implementations. Each
+parent calls its children's `markdown()` methods: Knowledge groups concepts, workflows,
+articles and dictionaries; Article renders Sections; Dictionary renders Entries; Workflow
+numbers and indents Steps according to `parentId`. Parents preserve child output instead
+of rebuilding it from the child's fields. Helpers never call the receiver's own method,
+so `markdown() { return knowledgeToMarkdown(this); }` does not recurse.
+
+Default headings follow the composition tree: Knowledge categories use level 1; Concepts,
+Workflows, Articles and Dictionaries use level 2; Sections and Entries use level 3.
+Steps return a bold title and body, with numbering supplied by Workflow. Standalone output
+uses the same format. Custom methods own their heading choices; parents do not rewrite
+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.

package/dist/file.d.ts

@@ -0,0 +1,30 @@
+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. */
+    maxBytes: number;
+    /** Includes time waiting for a concurrency slot. */
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+/**
+ * @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.
+ */
+export interface FileClient extends Client {
+    read(options: FileReadOptions): Promise<Uint8Array>;
+}
+/**
+ * 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.
+ * @see {@link component://../../../docs/toolbox.md}
+ */
+export declare abstract class FileDataSource<C extends FileClient = FileClient> implements DataSource<C> {
+    abstract readonly path: 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 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.
+ * @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/knowledge.d.ts

@@ -1,17 +1,24 @@
+/**
+ * @spec Knowledge objects provide an I/O-free Markdown representation of their content.
+ * @rule JSON preserves content only; consumers restore methods when loading declarations.
+ */
+export interface Markdown {
+    markdown(): string;
+}
 /** A named domain object and its relationships or constraints. */
-export interface Concept {
+export interface Concept extends Markdown {
     readonly id: string;
     readonly name: string;
     readonly description: string;
 }
 /** A documented business process; steps are descriptions, not executable actions. */
-export interface Workflow {
+export interface Workflow extends Markdown {
     readonly id: string;
     readonly title: string;
     readonly summary: string;
     readonly steps: readonly Step[];
 }
-export interface Step {
+export interface Step extends Markdown {
     readonly id: string;
     /** Inclusion within this Workflow. Array order determines sibling order. */
     readonly parentId?: string;
@@ -19,20 +26,20 @@ export interface Step {
     readonly description: string;
 }
 /** A self-contained explanation of a topic. */
-export interface Article {
+export interface Article extends Markdown {
     readonly id: string;
     readonly title: string;
     readonly summary: string;
     readonly sections: readonly Section[];
 }
-export interface Section {
+export interface Section extends Markdown {
     readonly id: string;
     readonly title: string;
     /** Markdown authored by the knowledge owner. */
     readonly body: string;
 }
 /** Common reading identity; consumers extend entries with their typed domain fields. */
-export interface Entry {
+export interface Entry extends Markdown {
     readonly id: string;
     readonly name: string;
     readonly description: string;
@@ -45,7 +52,7 @@ export interface KnowledgeSource {
     readonly reference?: string;
 }
 /** Entries retain domain fields. Names and codes need not be unique; IDs must be. */
-export interface Dictionary<T extends Entry = Entry> {
+export interface Dictionary<T extends Entry = Entry> extends Markdown {
     readonly id: string;
     readonly title: string;
     readonly summary: string;
@@ -57,7 +64,7 @@ export interface Dictionary<T extends Entry = Entry> {
  * @rule Top-level IDs are unique per kind; child IDs are unique within their containing object.
  * @see {@link component://docs/kernel.md}
  */
-export interface Knowledge {
+export interface Knowledge extends Markdown {
     readonly concepts?: readonly Concept[];
     readonly workflows?: readonly Workflow[];
     readonly articles?: readonly Article[];
@@ -73,14 +80,14 @@ export declare function validateKnowledge(knowledge: Knowledge): void;
 export declare function conceptToMarkdown(concept: Concept): string;
 export declare function sectionToMarkdown(section: Section): string;
 export declare function articleToMarkdown(article: Article): string;
-export declare function stepToMarkdown(step: Step): string;
 export declare function workflowToMarkdown(workflow: Workflow): string;
+export declare function stepToMarkdown(step: Step): string;
 export declare function entryToMarkdown(entry: Entry): string;
-/** Domain renderers can include fields beyond the common entry reading contract. */
-export declare function dictionaryToMarkdown<T extends Entry>(dictionary: Dictionary<T>, renderEntry?: (entry: T) => string): string;
-export interface KnowledgeMarkdownOptions {
-    /** Consumers own domain-specific entry formatting; omitted renderers use name/description/aliases. */
-    readonly renderEntry?: (dictionary: Dictionary, entry: Entry) => string;
-}
-/** Deterministic Markdown projection. It performs no I/O and does not mutate declarations. */
-export declare function knowledgeToMarkdown(knowledge: Knowledge, options?: KnowledgeMarkdownOptions): string;
+/** Entries own their domain-specific output; the dictionary owns its title, source and order. */
+export declare function dictionaryToMarkdown<T extends Entry>(dictionary: Dictionary<T>): string;
+/**
+ * @spec Parents compose child markdown() output; only the child owns its content rendering.
+ * @rule Helpers never invoke the receiver's own markdown(), so declarations can safely delegate to them.
+ * @case id=knowledge_composition,desc=`Nested objects customize Markdown`,expect=`Root output preserves each child result`
+ */
+export declare function knowledgeToMarkdown(knowledge: Knowledge): string;

package/dist/knowledge.js

@@ -55,16 +55,16 @@ function paragraphs(...parts) {
     return parts.filter(part => part !== undefined && part.length > 0).join("\n\n");
 }
 export function conceptToMarkdown(concept) {
-    return paragraphs(heading(concept.name, 1), concept.description);
+    return `${heading(concept.name, 2)}\n${concept.description}`;
 }
 export function sectionToMarkdown(section) {
-    return paragraphs(heading(section.title, 2), section.body);
+    return `${heading(section.title, 3)}\n${section.body}`;
 }
 export function articleToMarkdown(article) {
     requireIds(`article '${article.id}'`, article.sections);
-    return paragraphs(heading(article.title, 1), article.summary, ...article.sections.map(sectionToMarkdown));
+    return paragraphs(`${heading(article.title, 2)}\n${article.summary}`, ...article.sections.map(section => section.markdown()));
 }
-function workflowMarkdown(workflow, level) {
+export function workflowToMarkdown(workflow) {
     validateWorkflow(workflow);
     const children = new Map();
     for (const step of workflow.steps) {
@@ -76,41 +76,36 @@ function workflowMarkdown(workflow, level) {
         return (children.get(parentId) ?? []).map((step, index) => {
             const marker = `${index + 1}. `;
             const childIndent = indent + " ".repeat(marker.length);
-            const body = step.description.split("\n").map(line => childIndent + line).join("\n");
-            return paragraphs(`${indent}${marker}**${step.title}**`, body, render(step.id, childIndent));
-        }).join("\n\n");
+            const body = step.markdown().split("\n").map((line, lineIndex) => lineIndex === 0 ? `${indent}${marker}${line}` : `${childIndent}${line}`).join("\n");
+            return [body, render(step.id, childIndent)]
+                .filter(part => part.length > 0).join("\n");
+        }).join("\n");
     };
-    return paragraphs(heading(workflow.title, level), workflow.summary, render(undefined, ""));
+    return paragraphs(`${heading(workflow.title, 2)}\n${workflow.summary}`, render(undefined, ""));
 }
 export function stepToMarkdown(step) {
-    return paragraphs(heading(step.title, 1), step.description);
-}
-export function workflowToMarkdown(workflow) {
-    return workflowMarkdown(workflow, 1);
+    // Preserve a block boundary before authored descriptions such as indented code and thematic breaks.
+    return paragraphs(`**${step.title}**`, step.description);
 }
 export function entryToMarkdown(entry) {
-    return paragraphs(heading(entry.name, 2), entry.description, entry.aliases?.length ? `Aliases: ${entry.aliases.join(", ")}` : undefined);
+    return paragraphs(`${heading(entry.name, 3)}\n${entry.description}`, entry.aliases?.length ? `Aliases: ${entry.aliases.join(", ")}` : undefined);
 }
-/** Domain renderers can include fields beyond the common entry reading contract. */
-export function dictionaryToMarkdown(dictionary, renderEntry = entryToMarkdown) {
+/** Entries own their domain-specific output; the dictionary owns its title, source and order. */
+export function dictionaryToMarkdown(dictionary) {
     requireIds(`dictionary '${dictionary.id}'`, dictionary.entries);
     const source = dictionary.source;
-    return paragraphs(heading(dictionary.title, 1), dictionary.summary, source ? `Source: ${source.name}@${source.version}${source.reference ? `\n\n${source.reference}` : ""}` : undefined, ...dictionary.entries.map(entry => renderEntry(entry)));
+    return paragraphs(`${heading(dictionary.title, 2)}\n${dictionary.summary}`, source ? `Source: ${source.name}@${source.version}${source.reference ? `\n\n${source.reference}` : ""}` : undefined, ...dictionary.entries.map(entry => entry.markdown()));
 }
-function articleMarkdown(article, level) {
-    return paragraphs(heading(article.title, level), article.summary, ...article.sections.map(section => paragraphs(heading(section.title, level + 1), section.body)));
-}
-/** Deterministic Markdown projection. It performs no I/O and does not mutate declarations. */
-export function knowledgeToMarkdown(knowledge, options = {}) {
+/**
+ * @spec Parents compose child markdown() output; only the child owns its content rendering.
+ * @rule Helpers never invoke the receiver's own markdown(), so declarations can safely delegate to them.
+ * @case id=knowledge_composition,desc=`Nested objects customize Markdown`,expect=`Root output preserves each child result`
+ */
+export function knowledgeToMarkdown(knowledge) {
     validateKnowledge(knowledge);
     const concepts = knowledge.concepts ?? [];
     const workflows = knowledge.workflows ?? [];
     const articles = knowledge.articles ?? [];
     const dictionaries = knowledge.dictionaries ?? [];
-    return paragraphs(concepts.length ? paragraphs("## Concepts", ...concepts.map(concept => paragraphs(heading(concept.name, 3), concept.description))) : undefined, workflows.length ? paragraphs("## Workflows", ...workflows.map(workflow => workflowMarkdown(workflow, 3))) : undefined, articles.length ? paragraphs("## Articles", ...articles.map(article => articleMarkdown(article, 3))) : undefined, dictionaries.length ? paragraphs("## Dictionaries", ...dictionaries.map(dictionary => {
-        const source = dictionary.source;
-        return paragraphs(heading(dictionary.title, 3), dictionary.summary, source ? `Source: ${source.name}@${source.version}${source.reference ? `\n\n${source.reference}` : ""}` : undefined, ...dictionary.entries.map(entry => options.renderEntry
-            ? options.renderEntry(dictionary, entry)
-            : paragraphs(heading(entry.name, 4), entry.description, entry.aliases?.length ? `Aliases: ${entry.aliases.join(", ")}` : undefined)));
-    })) : undefined);
+    return paragraphs(concepts.length ? paragraphs("# Concepts", ...concepts.map(concept => concept.markdown())) : undefined, workflows.length ? paragraphs("# Workflows", ...workflows.map(workflow => workflow.markdown())) : undefined, articles.length ? paragraphs("# Articles", ...articles.map(article => article.markdown())) : undefined, dictionaries.length ? paragraphs("# Dictionaries", ...dictionaries.map(dictionary => dictionary.markdown())) : undefined);
 }

package/dist/repository.d.ts

@@ -1,6 +1,21 @@
 import type { Forge } from "./forge.js";
-/** A repository identified by its Forge and path within that Forge. */
-export interface Repository {
+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 extends Identity {
     readonly forge: Forge;
     readonly path: string;
+    /**
+     * Direct parent repository path within this same Forge instance; omission/null is unspecified.
+     * Cross-Forge import/mirror provenance belongs in separate metadata.
+     */
+    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.4.0",
+  "version": "0.5.3",
   "description": "Execution-neutral client lifecycle and datasource contracts for harnesses",
   "type": "module",
   "scripts": {