@toolproof-core/schema 1.0.0 → 1.0.1

package/src/scripts/{generateResourceShells.ts → wrapResourceTypesWithResourceShells.ts}

@@ -3,26 +3,11 @@ import path from 'path';
 import { getConfig } from './_lib/config.js';
 
 /**
- * Generate Resource envelopes for all ResourceTypes defined in Genesis.json
- * 
- * This script wraps each ResourceType definition (from $defs) with a Resource envelope
+ * Wrap each ResourceType definition (from Genesis.nucleusSchema.$defs) with a Resource shell
  * that conforms to the Resource.nucleusSchema pattern defined in Genesis.json.
- * 
- * For the top-level Genesis ResourceType, extractedData is set to {} to avoid
- * duplicating the entire $defs object.
- * 
- * Resource identities follow the pattern RESOURCE-{Name} where Name is the key
- * from the $defs object. Genesis itself uses RESOURCE-Genesis.
- * 
- * Usage: node ./dist/scripts/generateResourceEnvelopes.js
  */
-/**
- * Pure function to generate resource envelopes from a Genesis schema.
- * 
- * @param genesis The Genesis schema object
- * @returns A record mapping resource names to their envelopes
- */
-function generateResourceEnvelopesLogic(genesis: any): Record<string, any> {
+
+function generateResourceShellLogic(genesis: any): Record<string, any> {
     if (!genesis.nucleusSchema || !genesis.nucleusSchema.$defs) {
         throw new Error('Genesis.json must have nucleusSchema.$defs');
     }
@@ -30,39 +15,36 @@ function generateResourceEnvelopesLogic(genesis: any): Record<string, any> {
     const defs = genesis.nucleusSchema.$defs;
     const defKeys = Object.keys(defs);
 
-    // Generate Resource envelopes
     const resources: Record<string, any> = {};
 
     // Genesis timestamp: 2025-11-30T00:00:00.000Z marks the genesis of ToolProof
     const genesisTimestamp = '2025-11-30T00:00:00.000Z';
 
-    // First entry is Genesis itself with empty extractedData
     resources['Genesis'] = {
         identity: 'RESOURCE-Genesis',
-        resourceTypeRef: 'TYPE-ResourceType',
+        resourceTypeHandle: 'TYPE-ResourceType',
         creationContext: {
-            resourceRoleRef: 'ROLE-Genesis',
-            executionRef: 'EXECUTION-Genesis'
+            resourceRoleHandle: 'ROLE-Genesis',
+            jobStepHandle: 'JOB_STEP-Genesis'
         },
         kind: 'materialized',
         timestamp: genesisTimestamp,
-        extractedData: {}
+        nucleus: {}
     };
 
-    // Generate resources for all other $defs
     defKeys.forEach((defName) => {
         const defValue = defs[defName];
 
         resources[defName] = {
             identity: `RESOURCE-${defName}`,
-            resourceTypeRef: 'TYPE-ResourceType',
+            resourceTypeHandle: 'TYPE-ResourceType',
             creationContext: {
-                resourceRoleRef: 'ROLE-Genesis',
-                executionRef: `EXECUTION-${defName}`
+                resourceRoleHandle: 'ROLE-Genesis',
+                jobStepHandle: `JOB_STEP-${defName}`
             },
             kind: 'materialized',
             timestamp: genesisTimestamp,
-            extractedData: defValue
+            nucleus: defValue
         };
     });
 
@@ -71,9 +53,8 @@ function generateResourceEnvelopesLogic(genesis: any): Record<string, any> {
 
 async function main() {
     const config = getConfig();
-    // Use normalized version with anchor refs rewritten to pointers
     const genesisSourcePath = config.getNormalizedSourcePath();
-    const outputPath = path.join(config.getGeneratedResourcesDir(), 'Genesis.json');
+    const outputPath = path.join(config.getResourcesDir(), 'Genesis.json');
 
     if (!fs.existsSync(genesisSourcePath)) {
         console.error(`Genesis source file not found at ${genesisSourcePath}`);
@@ -84,13 +65,11 @@ async function main() {
     const genesis = JSON.parse(raw);
 
     try {
-        const resources = generateResourceEnvelopesLogic(genesis);
+        const resources = generateResourceShellLogic(genesis);
 
-        // Ensure output directory exists
         const outputDir = path.dirname(outputPath);
         fs.mkdirSync(outputDir, { recursive: true });
 
-        // Write the generated resources file
         fs.writeFileSync(outputPath, JSON.stringify(resources, null, 4) + '\n', 'utf-8');
         console.log(`Generated ${Object.keys(resources).length} Resource envelopes -> ${outputPath}`);
     } catch (error: any) {

package/dist/generated/types/Resource_Genesis.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, Genesis as ExtractedData } from './types.js';
-export type Resource_Genesis = ResourceMetaBase & { extractedData: ExtractedData };

package/dist/generated/types/Resource_Job.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, Job as ExtractedData } from './types.js';
-export type Resource_Job = ResourceMetaBase & { extractedData: ExtractedData };

package/dist/generated/types/Resource_RawStrategy.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, RawStrategy as ExtractedData } from './types.js';
-export type Resource_RawStrategy = ResourceMetaBase & { extractedData: ExtractedData };

package/dist/generated/types/Resource_ResourceType.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, ResourceType as ExtractedData } from './types.js';
-export type Resource_ResourceType = ResourceMetaBase & { extractedData: ExtractedData };

package/dist/generated/types/Resource_RunnableStrategy.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, RunnableStrategy as ExtractedData } from './types.js';
-export type Resource_RunnableStrategy = ResourceMetaBase & { extractedData: ExtractedData };

package/src/Roadmap.json

@@ -1,102 +0,0 @@
-{
-    "Tasks": [
-        {
-            "name": "Familiarization",
-            "comment": "Familiarize yourself with the new schema structure and the changes made. Consult the 'Notes' section for specific changes in naming and structure. This will help you understand how to adapt the existing codebase to work with the new schema. Prepare a list of any questions or clarifications needed regarding the new schema structure and we'll discuss them."
-        },
-        {
-            "name": "Scripts",
-            "comment": "Implement the scripts specified in the 'Scripts' section so that they work with the new schema structure. Try to do it with business logic contained in reusable pure functions as much as possible, and with clear separation between this and file I/O. In the future, we might let Ajv take over some of this work since it already has a lot of this functionality built-in (dereferencing, $defs bundling, etc.)."
-        },
-        {
-            "name": "NPM Publishing",
-            "comment": "Publish the schema package to the new npm organization 'toolproof-core' (I have sent you an invite). Take a pull of the latest master and merge it into your branch. For schema/package.json, keep my 'name' change. The package is now called '@toolproof-core/schema' instead of '@toolproof-npm/schema'. The reason for this change is that we can now name all core packages with the '@toolproof-core' prefix, regardless of whether they are published to npm or not. I've also done one change in Genesis.json. ShellMaterializedBase now has a required 'version' property with const value 1. This should not cause any merge conflicts since you've only done changes inside scripts/ and generated/ (in addition to package.json). The only thing that needs to be changed in scripts/ is the generateResourceShells script to add the version property (with value 1)when wrapping ResourceTypes in a ShellMaterialized. Note that while we call the new ToolProof version 'v2' during development, it will officially be called 'v1'. The old version (current 'v1') will be degraded to 'v0' and deprecated. This aligns with our npm package naming, where we've till now given the packages a '0.x.x' version. In the new npm organization 'toolproof-core', we will start with version '1.0.0' for all packages. Note that I've also updated other packages (console, engine, validation, visualization), but that should not cause any merge conflicts."
-        },
-        {
-            "name": "GitHub Actions",
-            "comment": "Create a GitHub Actions workflow for the schema package (like we have in the old ToolProof repository). We'll create actions for other packages later."
-        }
-    ],
-    "Notes": [
-        {
-            "oldName": "-Wrapper",
-            "newName": "-Facet",
-            "comment": "The 'Wrapper' suffix is changed to 'Facet' everywhere."
-        },
-        {
-            "oldName": "Name&DescriptionWrapper",
-            "newName": "DocumentationFacet"
-        },
-        {
-            "oldName": "extractionSchema",
-            "newName": "nucleusSchema",
-            "comment": "This is now a maximum-permissive 'true' schema. We'll validate user-written schemas in a much better way separately."
-        },
-        {
-            "oldName": "extractedData",
-            "newName": "nucleus"
-        },
-        {
-            "oldName": "Execution",
-            "newName": "JobRun"
-        },
-        {
-            "oldName": "WorkStep",
-            "newName": "JobStep"
-        },
-        {
-            "oldName": "ResourceMeta",
-            "newName": "ShellMaterialized"
-        },
-        {
-            "oldName": "StatelessStrategy",
-            "newName": "StepsFacet",
-            "comment": "This is a different concept. We no longer have the concept of Stateless vs Stateful strategies. We'll rather allow RunnableStrategies to be reused with new bindings."
-        },
-        {
-            "oldName": "StatefulStrategy",
-            "newName": "RawStrategy"
-        },
-        {
-            "oldName": "RunRecording",
-            "newName": "StrategyRun"
-        }
-    ],
-    "Scripts": {
-        "rewriteAnchors": {
-            "newName": "rewriteAnchors",
-            "comment": "Rewrites anchor-style refs (e.g. #SomeAnchor) inside Genesis.json’s nucleusSchema to JSON Pointer refs (e.g. #/$defs/SomeAnchor) for stricter tooling compatibility. Outputs normalized Genesis.json written to the configured location.",
-            "status": "Done, In PR"
-        },
-        "extractSchemas": {
-            "newName": "extractSchemas",
-            "comment": "Takes the (normalized) Genesis.json document (expects a top-level nucleusSchema), unwraps nested ResourceTypes into raw JSON Schemas. Outputs a flattened Genesis.json at the configured location.",
-            "status": "Done, In PR"
-        },
-        "extractSubSchemaWithDefs": {
-            "newName": "extractSubSchemaWithDefs",
-            "comment": "Extracts a single $defs.<Name> from the flattened Genesis.json and bundles it into a standalone schema including all direct + transitive local $defs dependencies referenced via #/$defs/...",
-            "status": "Done, In PR"
-        },
-        "generateSchemaShims": {
-            "newName": "generateSchemaShims",
-            "comment": "Generates .ts shim files next to generated .json files so TypeScript/NodeNext can import JSON schemas/resources via import assertions consistently."
-        },
-        "generateResourceEnvelopes": {
-            "newName": "generateResourceShells",
-            "comment": "Wraps every Genesis.nucleusSchema.$defs[DefName] schema in a Resource shell (ToolProof resource object). Special-cases Genesis with nucleus: {} to avoid duplicating all $defs."
-        },
-        "generateTypes": {
-            "newName": "generateTypes",
-            "comment": "Runs json-schema-to-typescript across the extracted schemas directory, with a custom resolver so absolute $id URLs map to local files (no network). Applies a few normalizations (e.g., allOf sibling keyword handling), prunes noisy generated names, and overlays template-literal types for ...Identity/...Ref patterns when possible. Ensures runtime .js shims exist alongside .d.ts. Note that some of this additional processing might be unnecessary or might not fit the new schema structure."
-        },
-        "generateResourceTypeType": {
-            "newName": "generateResourceTypeType",
-            "comment": "Generates a typed Resource variant Resource_<Name> where nucleus is typed to the extracted nucleusSchema <Name>.json."
-        },
-        "generateDependencies": {
-            "newName": "generateDependencies",
-            "comment": "Generates a list of dependencies for each schema."
-        }
-    }
-}

package/src/generated/types/Resource_Genesis.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, Genesis as ExtractedData } from './types.js';
-export type Resource_Genesis = ResourceMetaBase & { extractedData: ExtractedData };

package/src/generated/types/Resource_Job.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, Job as ExtractedData } from './types.js';
-export type Resource_Job = ResourceMetaBase & { extractedData: ExtractedData };

package/src/generated/types/Resource_RawStrategy.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, RawStrategy as ExtractedData } from './types.js';
-export type Resource_RawStrategy = ResourceMetaBase & { extractedData: ExtractedData };

package/src/generated/types/Resource_ResourceType.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, ResourceType as ExtractedData } from './types.js';
-export type Resource_ResourceType = ResourceMetaBase & { extractedData: ExtractedData };

package/src/generated/types/Resource_RunnableStrategy.d.ts

@@ -1,3 +0,0 @@
-// Auto-generated strict composite type. Do not edit.
-import type { ResourceMetaBase, RunnableStrategy as ExtractedData } from './types.js';
-export type Resource_RunnableStrategy = ResourceMetaBase & { extractedData: ExtractedData };

package/src/scripts/extractSchemas.ts

@@ -1,229 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { getConfig } from "./_lib/config.js";
-
-type JSONValue = null | boolean | number | string | JSONValue[] | { [k: string]: JSONValue };
-
-interface ExtractOptions {
-  inPath: string;
-  outPath: string;
-  topLevelId?: string;
-}
-
-function parseArgs(): ExtractOptions {
-  const config = getConfig();
-  const argv = process.argv.slice(2);
-  let inPath = "";
-  let outPath = "";
-  let topLevelId: string | undefined;
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--in" && i + 1 < argv.length) inPath = argv[++i];
-    else if (a === "--out" && i + 1 < argv.length) outPath = argv[++i];
-    else if (a === "--id" && i + 1 < argv.length) {
-      let v = argv[++i];
-      // Strip accidental surrounding quotes from PowerShell/cmd
-      if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) {
-        v = v.slice(1, -1);
-      }
-      topLevelId = v;
-    }
-  }
-
-  // Use config defaults if not provided via CLI
-  if (!inPath) {
-    // Use generated/normalized version with anchor refs rewritten to pointers
-    inPath = config.getNormalizedSourcePath();
-  }
-  if (!outPath) {
-    outPath = config.getOutputPath(config.getSourceFile());
-  }
-  if (!topLevelId) {
-    topLevelId = config.getSchemaId('Genesis');
-  }
-
-  // Resolve to absolute paths from project root
-  const cwd = config.getRoot();
-  const wasInRelative = !path.isAbsolute(inPath);
-  const wasOutRelative = !path.isAbsolute(outPath);
-  if (wasInRelative) inPath = path.join(cwd, inPath);
-  if (wasOutRelative) outPath = path.join(cwd, outPath);
-  // Fallback: resolve relative to script directory if not found
-  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-  if (!fs.existsSync(inPath) && wasInRelative) inPath = path.resolve(scriptDir, inPath);
-  const outDir = path.dirname(outPath);
-  if (!fs.existsSync(outDir) && wasOutRelative) {
-    // Try making directory relative to script dir
-    const altOut = path.resolve(scriptDir, outPath);
-    const altOutDir = path.dirname(altOut);
-    if (!fs.existsSync(path.dirname(outPath))) {
-      // Prefer creating outDir at cwd location if possible; otherwise fallback below when writing
-    } else {
-      outPath = altOut;
-    }
-  }
-  return { inPath, outPath, topLevelId };
-}
-
-// Heuristic: determine if a node is a Type envelope
-function isTypeEnvelope(node: any): boolean {
-  return (
-    node && typeof node === "object" && !Array.isArray(node) &&
-    // Treat any object that has an 'nucleusSchema' AND 'identity' as a Type envelope
-    // This prevents false positives where 'nucleusSchema' is just a regular schema property
-    node.nucleusSchema && typeof node.nucleusSchema === "object" &&
-    node.identity && typeof node.identity === "string"
-  );
-}
-
-// Merge $defs into target, without overwriting existing keys unless identical
-function mergeDefs(target: Record<string, JSONValue>, source?: any, label?: string) {
-  if (!source || typeof source !== "object") return;
-  const src = (source as any)["$defs"];
-  if (!src || typeof src !== "object") return;
-  for (const [k, v] of Object.entries(src)) {
-    if (!(k in target)) {
-      target[k] = v as JSONValue;
-    } else {
-      // Best-effort: if duplicate key, require structural equality; otherwise, namespace
-      const existing = JSON.stringify(target[k]);
-      const incoming = JSON.stringify(v);
-      if (existing !== incoming) {
-        const altKey = `${k}__from_${(label || "defs").replace(/[^A-Za-z0-9_]+/g, "_")}`;
-        if (!(altKey in target)) target[altKey] = v as JSONValue;
-      }
-    }
-  }
-}
-
-// Deeply traverse an object replacing any Type envelope with its nucleusSchema,
-// and hoist its inner $defs to topDefs. Prevent infinite recursion with a visited set.
-function unwrapTypes(node: JSONValue, topDefs: Record<string, JSONValue>, labelPath: string[] = [], visited = new Set<any>()): JSONValue {
-  if (node && typeof node === "object") {
-    if (visited.has(node)) return node; // avoid cycles
-    visited.add(node);
-  }
-
-  if (isTypeEnvelope(node)) {
-    const env = node as any;
-    const inner = env.nucleusSchema;
-    // Hoist inner $defs before stripping
-    mergeDefs(topDefs, inner, labelPath.join("_"));
-    // Return the inner schema itself, after also unwrapping any nested envelopes it may contain
-    const unwrappedInner = unwrapTypes(inner as JSONValue, topDefs, labelPath.concat([String(env.identity || "env")]), visited);
-    return unwrappedInner;
-  }
-
-  if (Array.isArray(node)) {
-    return node.map((v, i) => unwrapTypes(v, topDefs, labelPath.concat([String(i)]), visited)) as JSONValue;
-  }
-
-  if (node && typeof node === "object") {
-    const out: Record<string, JSONValue> = {};
-    for (const [k, v] of Object.entries(node)) {
-      if (k === "$defs" && v && typeof v === "object" && !Array.isArray(v)) {
-        // Process nested $defs: unwrap each entry value if it's a Type envelope
-        const defsOut: Record<string, JSONValue> = {};
-        for (const [dk, dv] of Object.entries(v as any)) {
-          const unwrapped = unwrapTypes(dv as JSONValue, topDefs, labelPath.concat(["$defs", dk]), visited);
-          defsOut[dk] = unwrapped;
-        }
-        out[k] = defsOut;
-      } else {
-        out[k] = unwrapTypes(v as JSONValue, topDefs, labelPath.concat([k]), visited);
-      }
-    }
-    return out;
-  }
-
-  return node;
-}
-
-/**
- * Pure function that takes a schema document and options, and returns the flattened schema.
- * Performs no I/O operations.
- */
-function extractSchemaLogic(doc: any, topLevelId?: string): any {
-  if (!doc || typeof doc !== "object" || !doc.nucleusSchema) {
-    throw new Error("Input must be a Type JSON with an nucleusSchema at the top level");
-  }
-
-  const topSchema = (doc as any).nucleusSchema;
-  const outDefs: Record<string, JSONValue> = {};
-
-  // Seed with top-level $defs (if any) before unwrapping
-  mergeDefs(outDefs, topSchema, "top");
-
-  // Unwrap the entire top schema tree so that any nested Type envelopes become raw schemas
-  const flattened = unwrapTypes(topSchema as JSONValue, outDefs, ["nucleusSchema"]);
-
-  // Assemble output: force $schema, optionally set $id, hoist collected $defs
-  let base: any;
-  if (flattened && typeof flattened === "object" && !Array.isArray(flattened)) {
-    base = { ...(flattened as any) };
-  } else {
-    // If flattened is not an object (should be rare for a top-level schema), wrap it
-    base = { const: flattened };
-  }
-  // Assemble, but avoid duplicating $id: if the flattened base already has $id, prefer it.
-  const output: Record<string, JSONValue> = {
-    $schema: "https://json-schema.org/draft/2020-12/schema",
-    ...base,
-  };
-  if (topLevelId && !(output as any).$id) {
-    (output as any).$id = topLevelId;
-  }
-
-  // Enforce presence of $id: schema must declare an absolute identity.
-  if (!(output as any).$id) {
-    throw new Error(
-      "Flattened schema must define $id. Provide it via CLI --id or include $id in the source nucleusSchema."
-    );
-  }
-
-  // Merge collected defs into output.$defs, taking care not to clobber any existing
-  if (!("$defs" in output)) output.$defs = {} as any;
-  const finalDefs: Record<string, JSONValue> = (output.$defs as any) || {};
-  for (const [k, v] of Object.entries(outDefs)) {
-    if (!(k in finalDefs)) finalDefs[k] = v;
-  }
-  output.$defs = finalDefs as any;
-
-  // Ensure a stable order for readability
-  return orderKeys(output, ["$id", "$schema", "$vocabulary", "$defs", "title", "description", "type", "allOf", "anyOf", "oneOf", "not", "if", "then", "else", "properties", "required", "additionalProperties", "unevaluatedProperties"]);
-}
-
-function main() {
-  const { inPath, outPath, topLevelId } = parseArgs();
-
-  if (!fs.existsSync(inPath)) {
-    console.error(`Input file not found at ${inPath}`);
-    process.exit(1);
-  }
-
-  const raw = fs.readFileSync(inPath, "utf8");
-  const doc = JSON.parse(raw);
-
-  // Core logic is now in a pure function
-  const ordered = extractSchemaLogic(doc, topLevelId);
-
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, JSON.stringify(ordered, null, 4), "utf8");
-  console.log(`Wrote flattened schema to ${outPath}`);
-}
-
-function orderKeys(obj: any, preferred: string[]): any {
-  if (Array.isArray(obj)) return obj.map((v) => orderKeys(v, preferred));
-  if (!obj || typeof obj !== "object") return obj;
-  const keys = Object.keys(obj);
-  const sorted = [
-    ...preferred.filter((k) => keys.includes(k)),
-    ...keys.filter((k) => !preferred.includes(k)).sort()
-  ];
-  const out: any = {};
-  for (const k of sorted) out[k] = orderKeys(obj[k], preferred);
-  return out;
-}
-
-main();