@darkhorseprojects/circuitry 0.2.99 → 0.3.0

package/dist/graph.d.ts

@@ -1,4 +1,4 @@
-export declare const CIRCUITRY_SPEC_VERSION: "0.2.99";
+export declare const CIRCUITRY_SPEC_VERSION: "0.3.0";
 export type CircuitrySpecVersion = typeof CIRCUITRY_SPEC_VERSION | "0.2";
 export type CircuitryNodeKind = "agent" | "input" | "tool" | "output" | string;
 export type CircuitryEdgeKind = "context" | "dependency" | "message" | "control" | string;
@@ -170,20 +170,23 @@ export type CircuitryRuntimeInputs = Record<string, unknown>;
  * graph source stable and catches misspelled input names before execution.
  */
 export declare const applyCircuitryRuntimeInputs: (graph: CircuitryGraph, inputs?: CircuitryRuntimeInputs) => CircuitryGraph;
-export type CircuitryGraphLink = string | {
+/** Import declaration for bringing resources from another graph file. */
+export type CircuitryImport = {
     /** Path to another .circuitry.yaml/.json file, resolved relative to this file. */
     path: string;
-    /** Optional id prefix applied to imported resources. */
-    prefix?: string;
+    /** Resource id to import from the source file. */
+    resource: string;
+    /** Optional local name (alias) for the imported resource. */
+    as?: string;
 };
 export type CircuitryGraph = {
-    /** Spec version. Use "0.2.99" for linked graph files. */
+    /** Spec version. Use "0.3.0" for import-based graph files. */
     circuitry: CircuitrySpecVersion | string;
     id?: string;
     title?: string;
     description?: string;
-    /** Files whose resources are merged into this graph before validation/execution. */
-    links?: CircuitryGraphLink[];
+    /** Explicit imports of specific resources from other graph files. */
+    imports?: CircuitryImport[];
     resources?: Record<string, CircuitryResourceEntry>;
     /** Internal normalized execution nodes. Authored graph files must not set this. */
     nodes?: CircuitryNode[];
@@ -223,7 +226,7 @@ export type CircuitryValidationResult = {
 };
 export declare const DEFAULT_CIRCUITRY_VALIDATION_RULES: CircuitryValidationRuleEntry[];
 export declare const DEFAULT_CIRCUITRY_VALIDATION_STANDARD: {
-    readonly version: "0.2.99";
+    readonly version: "0.3.0";
     readonly requireSpecVersion: true;
     readonly rules: CircuitryValidationRuleEntry[];
     readonly executableKinds: ["agent", "tool", "output"];

package/dist/index.js

@@ -27,7 +27,7 @@ var isNodeElement = (element) => {
 };
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2.99";
+var CIRCUITRY_SPEC_VERSION = "0.3.0";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -136,7 +136,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.3"]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -160,19 +160,22 @@ var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   }
   if (options.sourceFormat) {
     if (!graphObject.resources || Object.keys(graphObject.resources).length === 0) {
-      addError("missing_resources", "Circuitry v0.2 graphs must use a resources: section", ["resources"]);
+      addError("missing_resources", "Circuitry v0.3 graphs must use a resources: section", ["resources"]);
     }
     if (graphObject.agents && Object.keys(graphObject.agents).length > 0) {
-      addError("forbidden_agents", "Circuitry v0.2 graph files must not use top-level agents:; use resources:", ["agents"]);
+      addError("forbidden_agents", "Circuitry v0.3 graph files must not use top-level agents:; use resources:", ["agents"]);
     }
     if (graphObject.inputs && Object.keys(graphObject.inputs).length > 0) {
-      addError("forbidden_inputs", "Circuitry v0.2 graph files must not use top-level inputs:; use resources:", ["inputs"]);
+      addError("forbidden_inputs", "Circuitry v0.3 graph files must not use top-level inputs:; use resources:", ["inputs"]);
     }
     if (graphObject.nodes && graphObject.nodes.length > 0) {
-      addError("forbidden_nodes", "Circuitry v0.2 graph files must not use top-level nodes:; use resources:", ["nodes"]);
+      addError("forbidden_nodes", "Circuitry v0.3 graph files must not use top-level nodes:; use resources:", ["nodes"]);
     }
     if (graphObject.edges && graphObject.edges.length > 0) {
-      addError("forbidden_edges", "Circuitry v0.2 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+      addError("forbidden_edges", "Circuitry v0.3 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry v0.3 graph files must use imports: instead of links:", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);

package/dist/node.d.ts

@@ -8,11 +8,9 @@ export declare class NodeCircuitryHost implements CircuitryHost {
     private exists;
     private parseIssue;
     private parseGraphForValidation;
-    private linkPath;
-    private linkPrefix;
-    private prefixResourceIds;
-    private mergeResources;
-    private resolveGraphLinks;
+    private resolveGraphImports;
+    /** Rewrite inputs in imported resource to use aliased resource ids. */
+    private rewriteImportInputs;
     private parseAndResolveGraph;
     private readGraphFile;
     readGraph(input?: {

package/dist/node.js

@@ -8,7 +8,7 @@ import os from "node:os";
 import YAML from "yaml";
 
 // src/graph.ts
-var CIRCUITRY_SPEC_VERSION = "0.2.99";
+var CIRCUITRY_SPEC_VERSION = "0.3.0";
 var runtimeInputToText = (value) => {
   if (typeof value === "string") return value;
   if (value === void 0) return "";
@@ -117,7 +117,7 @@ var normalizeCircuitryGraph = (graph) => {
   const { nodes, edges } = expandResources(graph.resources);
   return { ...graph, nodes, edges };
 };
-var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.2", CIRCUITRY_SPEC_VERSION]);
+var VALID_SPEC_VERSIONS = /* @__PURE__ */ new Set(["0.3"]);
 var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   const resolvedStandard = createCircuitryValidationStandard(
     standard,
@@ -141,19 +141,22 @@ var validateCircuitryGraphInternal = (graph, standard = {}, options) => {
   }
   if (options.sourceFormat) {
     if (!graphObject.resources || Object.keys(graphObject.resources).length === 0) {
-      addError("missing_resources", "Circuitry v0.2 graphs must use a resources: section", ["resources"]);
+      addError("missing_resources", "Circuitry v0.3 graphs must use a resources: section", ["resources"]);
     }
     if (graphObject.agents && Object.keys(graphObject.agents).length > 0) {
-      addError("forbidden_agents", "Circuitry v0.2 graph files must not use top-level agents:; use resources:", ["agents"]);
+      addError("forbidden_agents", "Circuitry v0.3 graph files must not use top-level agents:; use resources:", ["agents"]);
     }
     if (graphObject.inputs && Object.keys(graphObject.inputs).length > 0) {
-      addError("forbidden_inputs", "Circuitry v0.2 graph files must not use top-level inputs:; use resources:", ["inputs"]);
+      addError("forbidden_inputs", "Circuitry v0.3 graph files must not use top-level inputs:; use resources:", ["inputs"]);
     }
     if (graphObject.nodes && graphObject.nodes.length > 0) {
-      addError("forbidden_nodes", "Circuitry v0.2 graph files must not use top-level nodes:; use resources:", ["nodes"]);
+      addError("forbidden_nodes", "Circuitry v0.3 graph files must not use top-level nodes:; use resources:", ["nodes"]);
     }
     if (graphObject.edges && graphObject.edges.length > 0) {
-      addError("forbidden_edges", "Circuitry v0.2 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+      addError("forbidden_edges", "Circuitry v0.3 graph files must not use top-level edges:; use resource inputs:", ["edges"]);
+    }
+    if (graphObject.links && graphObject.links.length > 0) {
+      addError("forbidden_links", "Circuitry v0.3 graph files must use imports: instead of links:", ["links"]);
     }
   }
   const normalized = normalizeCircuitryGraph(graphObject);
@@ -837,66 +840,53 @@ var NodeCircuitryHost = class {
       return { error: this.parseIssue(error, filename) };
     }
   }
-  linkPath(link) {
-    return typeof link === "string" ? link : link.path;
-  }
-  linkPrefix(link) {
-    return typeof link === "string" ? "" : link.prefix || "";
-  }
-  prefixResourceIds(resources, prefix) {
-    if (!prefix) return resources;
-    const ids = new Set(Object.keys(resources));
-    const prefixed = {};
-    for (const [id, resource] of Object.entries(resources)) {
-      const next = { ...resource };
-      if ((next.type === "agent" || next.type === "tool") && next.inputs) {
-        next.inputs = next.inputs.map((input) => ids.has(input) ? `${prefix}${input}` : input);
-      }
-      prefixed[`${prefix}${id}`] = next;
-    }
-    return prefixed;
-  }
-  mergeResources(target, source, fromFile) {
-    for (const [id, resource] of Object.entries(source)) {
-      if (target[id]) {
-        throw new Error(`Linked Circuitry resource id collision: ${id} from ${fromFile}`);
-      }
-      target[id] = resource;
-    }
-  }
-  async resolveGraphLinks(graph, filename, standard, stack = []) {
+  async resolveGraphImports(graph, filename, standard, stack = []) {
     const graphFile = path.resolve(filename);
     if (stack.includes(graphFile)) {
-      throw new Error(`Circuitry graph link cycle: ${[...stack, graphFile].join(" -> ")}`);
+      throw new Error(`Circuitry graph import cycle: ${[...stack, graphFile].join(" -> ")}`);
     }
-    const linkedResources = {};
+    const importedResources = {};
+    const aliasMap = {};
     const nextStack = [...stack, graphFile];
-    for (const link of graph.links || []) {
-      const rawPath = this.linkPath(link);
-      if (!rawPath) throw new Error(`Circuitry graph link is missing path in ${graphFile}`);
-      const linkedFile = path.resolve(path.dirname(graphFile), rawPath);
+    for (const imp of graph.imports || []) {
+      const linkedFile = path.resolve(path.dirname(graphFile), imp.path);
       const linkedText = await readFile(linkedFile, "utf8");
       const parsed = parseCircuitryText(linkedText, linkedFile, standard, { validate: false });
-      const resolved = await this.resolveGraphLinks(parsed, linkedFile, standard, nextStack);
-      this.mergeResources(
-        linkedResources,
-        this.prefixResourceIds(resolved.resources || {}, this.linkPrefix(link)),
-        linkedFile
-      );
+      const resolved = await this.resolveGraphImports(parsed, linkedFile, standard, nextStack);
+      const resourceId = imp.resource;
+      const resource = resolved.resources?.[resourceId];
+      if (!resource) {
+        throw new Error(`Imported resource not found: ${resourceId} in ${imp.path}`);
+      }
+      const localId = imp.as || resourceId;
+      if (importedResources[localId]) {
+        throw new Error(`Imported Circuitry resource id collision: ${localId} from ${imp.path}`);
+      }
+      if (imp.as) aliasMap[resourceId] = localId;
+      const resourceWithRewrittenInputs = this.rewriteImportInputs(resource, aliasMap);
+      importedResources[localId] = resourceWithRewrittenInputs;
     }
     return {
       ...graph,
       resources: {
-        ...linkedResources,
+        ...importedResources,
         ...graph.resources || {}
       }
     };
   }
+  /** Rewrite inputs in imported resource to use aliased resource ids. */
+  rewriteImportInputs(resource, aliasMap) {
+    if (resource.type === "agent" || resource.type === "tool") {
+      const newInputs = (resource.inputs || []).map((input) => aliasMap[input] || input);
+      return { ...resource, inputs: newInputs };
+    }
+    return resource;
+  }
   async parseAndResolveGraph(text, filename, standard) {
     const parsed = this.parseGraphForValidation(text, filename, standard);
     if (!parsed.graph) return parsed;
     try {
-      return { graph: await this.resolveGraphLinks(parsed.graph, filename, standard) };
+      return { graph: await this.resolveGraphImports(parsed.graph, filename, standard) };
     } catch (error) {
       return { error: this.parseIssue(error, filename) };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkhorseprojects/circuitry",
-  "version": "0.2.99",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",