graphenix-format 1.2.1 → 1.4.0

package/dist/types.d.ts

@@ -82,15 +82,85 @@ export interface SubgraphDefinition {
     metadata?: Record<string, unknown>;
     extensions?: Record<string, unknown>;
 }
+/**
+ * JSON Schema object (typically draft-07) used by tooling to validate runtime payloads.
+ * Kept as a generic object so authors can use `$ref`, `definitions`, etc.
+ */
+export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * Worox-graph entry contract: describes expected execution inputs and structure.
+ * Aligns with `@woroces/worox-graph` `GraphEntryContract` (I/O visibility **layer 01**).
+ */
+export interface GraphEntryContract {
+    /** Short human-readable description of what the graph expects at entry. */
+    summary?: string;
+    /**
+     * Path descriptors for execution branches that must run (shape is engine-specific;
+     * often node-id lists or segmented paths).
+     */
+    requiredExecutionPaths?: unknown[];
+    /**
+     * Optional JSON Schema for the merged **execution** object after graph entry
+     * (validated separately with `validateExecutionAgainstContract` when tooling enables it).
+     */
+    executionSchema?: JsonSchemaObject;
+    /** Notable or optional execution paths for diagnostics or docs. */
+    notableExecutionPaths?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Worox-graph response contract: describes the final output shape.
+ * Aligns with `@woroces/worox-graph` `GraphResponseContract` (I/O visibility **layer 08**).
+ */
+export interface GraphResponseContract {
+    summary?: string;
+    /**
+     * JSON Schema for the graph **final output** value
+     * (validated separately with `validateFinalOutputAgainstContract` when tooling enables it).
+     */
+    finalOutputSchema?: JsonSchemaObject;
+    [key: string]: unknown;
+}
+/**
+ * Optional document-level metadata. Known keys `graphEntry` / `graphResponse` mirror
+ * worox-graph graph JSON and are copied to `variables.__graphModel` by consumers.
+ */
+/**
+ * Planning-only catalog request (worox-graph task `metadata.catalogRequest`).
+ * Execution is unchanged. Canonical shape: `@woroces/worox-graph` `refs.ts`.
+ */
+export type WoroxCatalogRequest = Record<string, unknown>;
+/**
+ * Planning-only catalog binding (worox-graph task `metadata.catalogBinding`).
+ * Execution is unchanged. Canonical shape: `@woroces/worox-graph` `refs.ts`.
+ */
+export type WoroxCatalogBinding = Record<string, unknown>;
+/**
+ * Document-level planning catalog requests (worox-graph `metadata.catalogRequests`).
+ * Execution is unchanged. Canonical shape: `@woroces/worox-graph` `refs.ts`.
+ */
+export type WoroxCatalogRequests = WoroxCatalogRequest[] | Record<string, WoroxCatalogRequest>;
+export type GraphDocumentMetadata = {
+    graphEntry?: GraphEntryContract;
+    graphResponse?: GraphResponseContract;
+    /** Planning-only; aligns with worox-graph graph JSON `metadata.catalogRequests`. */
+    catalogRequests?: WoroxCatalogRequests;
+} & Record<string, unknown>;
 export interface GraphDocument {
     formatVersion: string;
     id: string;
     name?: string;
     description?: string;
     tags?: string[];
+    /** Structural graph (ports, `GraphInput` / `GraphOutput`). */
     graph: Graph;
     types?: TypeDefinition[];
     subgraphs?: SubgraphDefinition[];
+    /**
+     * Optional worox-graph-aligned contracts for planning and I/O documentation.
+     * Prefer this surface over duplicating the same data only under `extensions`.
+     */
+    metadata?: GraphDocumentMetadata;
     extensions?: Record<string, unknown>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validateWorox.d.ts

@@ -0,0 +1,22 @@
+import Ajv from "ajv";
+import type { GraphDocument } from "./types";
+import type { ValidationResult } from "./validate";
+export interface WoroxRuntimeValidationOptions {
+    /**
+     * AJV instance used to compile `executionSchema` / `finalOutputSchema`.
+     * When omitted, a shared default instance (`strict: false`, `allErrors: true`) is used.
+     */
+    ajv?: Ajv;
+}
+/**
+ * Validates `execution` against `document.metadata.graphEntry.executionSchema` when present.
+ * If there is no schema, or `graphEntry` is missing, returns `{ valid: true, errors: [] }`.
+ * This is optional tooling; graphenix planning does not require it.
+ */
+export declare function validateExecutionAgainstContract(document: GraphDocument, execution: unknown, options?: WoroxRuntimeValidationOptions): ValidationResult;
+/**
+ * Validates `finalOutput` against `document.metadata.graphResponse.finalOutputSchema` when present.
+ * If there is no schema, or `graphResponse` is missing, returns `{ valid: true, errors: [] }`.
+ */
+export declare function validateFinalOutputAgainstContract(document: GraphDocument, finalOutput: unknown, options?: WoroxRuntimeValidationOptions): ValidationResult;
+//# sourceMappingURL=validateWorox.d.ts.map

package/dist/validateWorox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateWorox.d.ts","sourceRoot":"","sources":["../src/validateWorox.ts"],"names":[],"mappings":"AAAA,OAAO,GAAgD,MAAM,KAAK,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAyBpE,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAwBlB;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,OAAO,EACpB,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAwBlB"}

package/dist/validateWorox.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateExecutionAgainstContract = validateExecutionAgainstContract;
+exports.validateFinalOutputAgainstContract = validateFinalOutputAgainstContract;
+const ajv_1 = __importDefault(require("ajv"));
+const defaultAjv = new ajv_1.default({
+    allErrors: true,
+    strict: false
+});
+function normalizeError(error) {
+    return {
+        message: error.message ?? "Validation error",
+        path: error.instancePath || error.schemaPath,
+        keyword: error.keyword,
+        params: (error.params ?? {})
+    };
+}
+function runCompiled(validate, data) {
+    const valid = validate(data);
+    if (valid) {
+        return { valid: true, errors: [] };
+    }
+    const errors = (validate.errors ?? []).map(normalizeError);
+    return { valid: false, errors };
+}
+/**
+ * Validates `execution` against `document.metadata.graphEntry.executionSchema` when present.
+ * If there is no schema, or `graphEntry` is missing, returns `{ valid: true, errors: [] }`.
+ * This is optional tooling; graphenix planning does not require it.
+ */
+function validateExecutionAgainstContract(document, execution, options) {
+    const schema = document.metadata?.graphEntry?.executionSchema;
+    if (schema === undefined || schema === null || typeof schema !== "object") {
+        return { valid: true, errors: [] };
+    }
+    const ajv = options?.ajv ?? defaultAjv;
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return {
+            valid: false,
+            errors: [
+                {
+                    message: `Invalid executionSchema: ${message}`,
+                    path: "/metadata/graphEntry/executionSchema",
+                    keyword: "compile",
+                    params: {}
+                }
+            ]
+        };
+    }
+    return runCompiled(validate, execution);
+}
+/**
+ * Validates `finalOutput` against `document.metadata.graphResponse.finalOutputSchema` when present.
+ * If there is no schema, or `graphResponse` is missing, returns `{ valid: true, errors: [] }`.
+ */
+function validateFinalOutputAgainstContract(document, finalOutput, options) {
+    const schema = document.metadata?.graphResponse?.finalOutputSchema;
+    if (schema === undefined || schema === null || typeof schema !== "object") {
+        return { valid: true, errors: [] };
+    }
+    const ajv = options?.ajv ?? defaultAjv;
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return {
+            valid: false,
+            errors: [
+                {
+                    message: `Invalid finalOutputSchema: ${message}`,
+                    path: "/metadata/graphResponse/finalOutputSchema",
+                    keyword: "compile",
+                    params: {}
+                }
+            ]
+        };
+    }
+    return runCompiled(validate, finalOutput);
+}
+//# sourceMappingURL=validateWorox.js.map

package/dist/validateWorox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateWorox.js","sourceRoot":"","sources":["../src/validateWorox.ts"],"names":[],"mappings":"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"}

package/docs/interop-worox-graph.md

@@ -0,0 +1,32 @@
+# Interop: worox-graph JSON and graphenix-format `Graph`
+
+This note clarifies how **worox-graph** graph JSON relates to the **port-based** `Graph` type in graphenix-format. It applies to authors using both `@woroces/worox-graph` and `graphenix-format` validation.
+
+## Two representations
+
+| Area | worox-graph | graphenix-format core `Graph` |
+|------|----------------|--------------------------------|
+| Topology | Task nodes, edges, `outputMapping`, finalizers | Nodes, edges, **ports**, `GraphInput` / `GraphOutput` |
+| Execution shape | Engine-specific (tasks, DAG scheduling) | **Execution-agnostic** static description |
+| I/O contracts | Often embedded in graph JSON and tooling | **Optional** `metadata.graphEntry` / `metadata.graphResponse` on the **document** |
+| Planning (catalog) | Optional `metadata.catalogRequests`; per task node `metadata.catalogRequest` / `metadata.catalogBinding` | Same optional keys on **`GraphDocument.metadata`** and **node `metadata`** in this package’s schema (execution unchanged) |
+
+worox-graph focuses on runnable task graphs and visibility into execution paths. graphenix-format describes a **static** graph layout (ports, graph-level inputs/outputs) without prescribing how the runtime schedules tasks.
+
+Planning-only catalog fields do not alter execution; canonical shapes live in `@woroces/worox-graph` (`refs.ts`). graphenix-format exposes matching optional JSON Schema `$defs` (`WoroxCatalogRequest`, `WoroxCatalogBinding`, `WoroxCatalogRequests`) for tooling that wants a single validator story.
+
+## Where worox-graph JSON lives
+
+- **Canonical for this package:** optional **`GraphDocument.metadata.graphEntry`** and **`GraphDocument.metadata.graphResponse`** (first-class optional fields). These match the worox contracts used when values are copied to `variables.__graphModel` and keep a single place for validation and docs.
+- **`extensions`:** you may still place namespaced worox-only payloads under `extensions` (e.g. legacy or engine-specific blobs). That does **not** replace `metadata.graphEntry` / `metadata.graphResponse` when you want graphenix-format schema and types to validate the same shapes as worox-graph.
+
+FR-GXF-1 does **not** change graphenix-format’s execution model: the core `Graph` remains port-based.
+
+## DAG nodes vs ports: is there a converter?
+
+**Not in graphenix-format today.** A future **optional** converter could map worox task nodes ↔ port graphs; nothing in the entry/response metadata requires or implies that mapping. Until such a tool exists, treat worox graph JSON and graphenix `Graph` as related **documentation and planning** layers, not automatic transforms of each other.
+
+## See also
+
+- README: **Worox-graph alignment** (I/O layers 01 / 08).
+- `schema/graphenix-format-1.0.0.schema.json`: `$defs/GraphEntryContract`, `$defs/GraphResponseContract`, and optional worox planning `$defs` (`WoroxCatalogRequest`, `WoroxCatalogBinding`, `WoroxCatalogRequests`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphenix-format",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Graphenix graph description format: JSON schema, validation, and CRUD helpers.",
   "license": "MIT",
   "main": "dist/index.cjs",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist",
-    "schema"
+    "schema",
+    "docs"
   ],
   "keywords": [
     "graph",