@compforge/harness-common 0.3.7 → 0.5.1

package/README.md

@@ -34,12 +34,23 @@ 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 {
+  conceptToMarkdown, knowledgeToMarkdown, stepToMarkdown, workflowToMarkdown,
+  type Service,
+} from "@compforge/harness-common";
 
 const service: Service = {
   name: "chat",
-  concepts: "A Conversation contains Messages; each Message may have multiple execution Attempts.",
-  workflows: "Accept message → execute attempt → persist response. Acceptance does not imply completion.",
+  knowledge: {
+    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" },
@@ -52,11 +63,14 @@ const service: Service = {
 };
 ```
 
-Service and Product accept an optional description for a short introduction, plus optional
-concepts and workflows Markdown text. Concepts explain
-objects, relationships and constraints; workflows explain collaboration from trigger to completion.
-Service knowledge covers its own responsibilities, while Product knowledge covers end-to-end flows.
-Consumers maintain this offline metadata; it does not change identity, execute a workflow or prove runtime state.
+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
+metadata; it does not change identity, execute a workflow or prove runtime state.
+
+Service `upstream` lists the canonical names of Services that call it, resolved in the consumer's
+catalog. Omission means the relationship is undeclared; `[]` declares no upstream callers.
+This describes architecture; runtime traces determine which calls actually occurred.
 
 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
@@ -72,3 +86,74 @@ Python's corresponding package is sdks/python/common (harness-common). Languages
 and independently versioned packages; they need not implement every model in lockstep.
 
 Development: bun install, make lint, make test. Published artifacts are Node-compatible ESM and declarations.
+
+## Structured knowledge
+
+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. 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
+appears after its child. `validateKnowledge` rejects duplicate/empty IDs, unknown parents
+and parent cycles before references are exposed. Dictionary entry IDs are unique, while
+names and domain keys such as error codes may repeat. `source.version` describes the
+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; 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/index.d.ts

@@ -12,3 +12,4 @@ export * from "./environment.js";
 export * from "./service.js";
 export * from "./execution.js";
 export type { Product } from "./product.js";
+export * from "./knowledge.js";

package/dist/index.js

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

package/dist/knowledge.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @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 extends Markdown {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+}
+/** A documented business process; steps are descriptions, not executable actions. */
+export interface Workflow extends Markdown {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly steps: readonly Step[];
+}
+export interface Step extends Markdown {
+    readonly id: string;
+    /** Inclusion within this Workflow. Array order determines sibling order. */
+    readonly parentId?: string;
+    readonly title: string;
+    readonly description: string;
+}
+/** A self-contained explanation of a topic. */
+export interface Article extends Markdown {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly sections: readonly 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 extends Markdown {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly aliases?: readonly string[];
+}
+export interface KnowledgeSource {
+    readonly name: string;
+    /** Definition version, independently of a consumer's distribution version. */
+    readonly version: string;
+    readonly reference?: string;
+}
+/** Entries retain domain fields. Names and codes need not be unique; IDs must be. */
+export interface Dictionary<T extends Entry = Entry> extends Markdown {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly source?: KnowledgeSource;
+    readonly entries: readonly T[];
+}
+/**
+ * @spec Knowledge is owner-scoped offline content, independent of runtime evidence and identity.
+ * @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 extends Markdown {
+    readonly concepts?: readonly Concept[];
+    readonly workflows?: readonly Workflow[];
+    readonly articles?: readonly Article[];
+    readonly dictionaries?: readonly Dictionary[];
+}
+/**
+ * @spec Parent IDs express inclusion only; missing parents, self-reference and cycles are invalid.
+ * @case id=workflow_hierarchy,desc=`Parent appears after child`,expect=`Sibling array order is preserved`
+ */
+export declare function validateWorkflow(workflow: Workflow): void;
+/** Validate declaration identities before exposing references or rendering any content. */
+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 workflowToMarkdown(workflow: Workflow): string;
+export declare function stepToMarkdown(step: Step): string;
+export declare function entryToMarkdown(entry: Entry): 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

@@ -0,0 +1,111 @@
+function requireIds(kind, values) {
+    const ids = new Set();
+    for (const value of values) {
+        if (!value.id.trim())
+            throw new Error(`${kind}: ID must not be empty`);
+        if (ids.has(value.id))
+            throw new Error(`${kind}: duplicate ID '${value.id}'`);
+        ids.add(value.id);
+    }
+}
+/**
+ * @spec Parent IDs express inclusion only; missing parents, self-reference and cycles are invalid.
+ * @case id=workflow_hierarchy,desc=`Parent appears after child`,expect=`Sibling array order is preserved`
+ */
+export function validateWorkflow(workflow) {
+    const label = `workflow '${workflow.id}'`;
+    requireIds(label, workflow.steps);
+    const steps = new Map(workflow.steps.map(step => [step.id, step]));
+    for (const step of workflow.steps) {
+        if (step.parentId !== undefined && !steps.has(step.parentId)) {
+            throw new Error(`${label}: step '${step.id}' has unknown parent '${step.parentId}'`);
+        }
+    }
+    const visited = new Set();
+    for (const step of workflow.steps) {
+        const path = new Set();
+        let current = step;
+        while (current && !visited.has(current.id)) {
+            if (path.has(current.id))
+                throw new Error(`${label}: parent cycle at step '${current.id}'`);
+            path.add(current.id);
+            current = current.parentId === undefined ? undefined : steps.get(current.parentId);
+        }
+        for (const id of path)
+            visited.add(id);
+    }
+}
+/** Validate declaration identities before exposing references or rendering any content. */
+export function validateKnowledge(knowledge) {
+    requireIds("concept", knowledge.concepts ?? []);
+    requireIds("workflow", knowledge.workflows ?? []);
+    requireIds("article", knowledge.articles ?? []);
+    requireIds("dictionary", knowledge.dictionaries ?? []);
+    for (const workflow of knowledge.workflows ?? [])
+        validateWorkflow(workflow);
+    for (const article of knowledge.articles ?? [])
+        requireIds(`article '${article.id}'`, article.sections);
+    for (const dictionary of knowledge.dictionaries ?? [])
+        requireIds(`dictionary '${dictionary.id}'`, dictionary.entries);
+}
+function heading(title, level) {
+    return `${"#".repeat(level)} ${title}`;
+}
+function paragraphs(...parts) {
+    return parts.filter(part => part !== undefined && part.length > 0).join("\n\n");
+}
+export function conceptToMarkdown(concept) {
+    return `${heading(concept.name, 2)}\n${concept.description}`;
+}
+export function sectionToMarkdown(section) {
+    return `${heading(section.title, 3)}\n${section.body}`;
+}
+export function articleToMarkdown(article) {
+    requireIds(`article '${article.id}'`, article.sections);
+    return paragraphs(`${heading(article.title, 2)}\n${article.summary}`, ...article.sections.map(section => section.markdown()));
+}
+export function workflowToMarkdown(workflow) {
+    validateWorkflow(workflow);
+    const children = new Map();
+    for (const step of workflow.steps) {
+        const siblings = children.get(step.parentId) ?? [];
+        siblings.push(step);
+        children.set(step.parentId, siblings);
+    }
+    const render = (parentId, indent) => {
+        return (children.get(parentId) ?? []).map((step, index) => {
+            const marker = `${index + 1}. `;
+            const childIndent = indent + " ".repeat(marker.length);
+            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, 2)}\n${workflow.summary}`, render(undefined, ""));
+}
+export function stepToMarkdown(step) {
+    // 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, 3)}\n${entry.description}`, entry.aliases?.length ? `Aliases: ${entry.aliases.join(", ")}` : undefined);
+}
+/** 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, 2)}\n${dictionary.summary}`, source ? `Source: ${source.name}@${source.version}${source.reference ? `\n\n${source.reference}` : ""}` : undefined, ...dictionary.entries.map(entry => entry.markdown()));
+}
+/**
+ * @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 => 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/product.d.ts

@@ -1,14 +1,13 @@
+import type { Knowledge } from "./knowledge.js";
 /** A business identity independent of repository layout.
  * Consumers own its many-to-many associations with Components.
- * @spec Description, concepts and workflows describe product-wide knowledge, not identity or runtime evidence.
+ * @spec Description and Knowledge describe the product, independently of identity and runtime evidence.
  * @see {@link component://docs/kernel.md}
  */
 export interface Product {
     readonly name: string;
+    /** Structured offline knowledge; not part of identity or runtime evidence. */
+    readonly knowledge?: Knowledge;
     /** Optional short introduction; not part of Product identity. */
     readonly description?: string;
-    /** Optional Markdown: domain objects, relationships and constraints. */
-    readonly concepts?: string;
-    /** Optional Markdown: collaboration from trigger to completion; not an executable plan. */
-    readonly workflows?: string;
 }

package/dist/repository.d.ts

@@ -1,6 +1,15 @@
 import type { Forge } from "./forge.js";
-/** A repository identified by its Forge and path within that Forge. */
+/**
+ * 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 {
     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;
 }

package/dist/service.d.ts

@@ -1,3 +1,4 @@
+import type { Knowledge } from "./knowledge.js";
 import type { Component } from "./component.js";
 import type { Environment } from "./environment.js";
 import type { Workload } from "./workload.js";
@@ -5,16 +6,21 @@ 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.
- * @spec Description, concepts and workflows are discovery metadata, not identity or runtime evidence.
+ * @spec Description and Knowledge are discovery metadata, independent of identity and runtime evidence.
+ * @spec upstream names callers of this Service; omitted is undeclared and an empty list declares no callers.
  * @see {@link component://docs/kernel.md}
  * Consumers extend this model with their own capabilities and execution policy.
  */
 export interface Service<E extends Environment = Environment> {
     readonly name: string;
-    /** Optional Markdown: domain objects, relationships and constraints. */
-    readonly concepts?: string;
-    /** Optional Markdown: collaboration from trigger to completion; not an executable plan. */
-    readonly workflows?: string;
+    /** Structured offline knowledge; not part of identity or runtime evidence. */
+    readonly knowledge?: Knowledge;
+    /**
+     * Canonical names of Services that call this Service, resolved in the consumer's catalog.
+     * Omitted means undeclared; an empty list declares no upstream callers.
+     * This is offline architecture metadata, independent of identity and observed traffic.
+     */
+    readonly upstream?: readonly string[];
     /** Human-readable discovery metadata; not part of Service identity. */
     readonly description?: string;
     readonly component: Component;

package/package.json

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