@toolproof-core/schema 1.0.9 → 1.0.11

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export { default as SchemaGenesis } from './generated/schemas/Genesis.js';
+export { default as SchemaResourceType } from './generated/schemas/standalone/ResourceType.js';
 export { default as SchemaJob } from './generated/schemas/standalone/Job.js';
+export { default as SchemaRunnableStrategy } from './generated/schemas/standalone/RunnableStrategy.js';
 export { default as SchemaStrategyRun } from './generated/schemas/standalone/StrategyRun.js';
-export { default as ResourceTypeGenesis } from './generated/resources/Genesis.js';
-export { default as CONSTANTS } from './generated/constants/constants.js';
+export { default as ResourceGenesis } from './generated/resources/Genesis.js';
+export { default as CONSTANTS } from './generated/artifacts/constants.js';
+export { default as MAPPINGS } from './generated/artifacts/mappings.js';
 export type { Resource_Genesis as Resource_GenesisJson } from './generated/types/standalone/Resource_Genesis.js';
 export type { Resource_ResourceType as Resource_ResourceTypeJson } from './generated/types/standalone/Resource_ResourceType.js';
 export type { Resource_Job as Resource_JobJson } from './generated/types/standalone/Resource_Job.js';
 export type { Resource_RawStrategy as Resource_RawStrategyJson } from './generated/types/standalone/Resource_RawStrategy.js';
 export type { Resource_RunnableStrategy as Resource_RunnableStrategyJson } from './generated/types/standalone/Resource_RunnableStrategy.js';
-export type { DocumentationFacet as DocumentationFacetJson, NucleusFacet as NucleusFacetJson, ResourceTypeIdentity as ResourceTypeIdentityJson, ResourceType as ResourceTypeJson, ResourceRoleIdentity as ResourceRoleIdentityJson, ResourceRoleValue as ResourceRoleValueJson, Conditional as ConditionalJson, RoleMap as RoleMapJson, Roles as RolesJson, RoleBindings as RoleBindingsJson, ResourceIdentity as ResourceIdentityJson, JobStepIdentity as JobStepIdentityJson, BranchStepIdentity as BranchStepIdentityJson, WhileStepIdentity as WhileStepIdentityJson, ForStepIdentity as ForStepIdentityJson, JobStep as JobStepJson, BranchStep as BranchStepJson, WhileStep as WhileStepJson, ForStep as ForStepJson, StepKind as StepKindJson, StepIdentity as StepIdentityJson, Step as StepJson, CreationContext as CreationContextJson, ResourceMissing as ResourceMissingJson, Resource as ResourceJson, StrategyState as StrategyStateJson, StepsFacet as StepsFacetJson, RawStrategy as RawStrategyJson, RunnableStrategyIdentity as RunnableStrategyIdentityJson, RunnableStrategyStatus as RunnableStrategyStatusJson, RunnableStrategy as RunnableStrategyJson, RunnableStrategyUpdate as RunnableStrategyUpdateJson, JobIdentity as JobIdentityJson, Job as JobJson, JsonData as JsonDataJson, StrategyThreadIdentity as StrategyThreadIdentityJson, StrategyThreadMap as StrategyThreadMapJson, JobStepSocket as JobStepSocketJson, Timestamp as TimestampJson, StrategyRunIdentity as StrategyRunIdentityJson, GoalIdentity as GoalIdentityJson, Goal as GoalJson, ShellMaterializedBase as ShellMaterializedBaseJson, } from './generated/types/types.js';
+export type { DocumentationFacetJson, NucleusFacetJson, ResourceTypeIdentityJson, ResourceTypeJson, ResourceRoleIdentityJson, ResourceRoleValueJson, ResourceRoleJson, ConditionalJson, RoleDictJson, RolesJson, RoleBindingsJson, ResourceIdentityJson, JobStepIdentityJson, BranchStepIdentityJson, WhileStepIdentityJson, ForStepIdentityJson, JobStepJson, BranchStepJson, WhileStepJson, ForStepJson, StepKindJson, StepIdentityJson, StepJson, CreationContextJson, ResourceMissingJson, ResourceInputPotentialJson, ResourceOutputPotentialJson, ShellMaterializedBaseJson, ResourceJson, StrategyStateJson, StepsFacetJson, RawStrategyJson, RunnableStrategyIdentityJson, RunnableStrategyStatusJson, RunnableStrategyJson, RunnableStrategyUpdateJson, JobIdentityJson, JobJson, JsonDataJson, StrategyThreadIdentityJson, StrategyThreadDictJson, JobStepSocketJson, TimestampJson, StrategyRunIdentityJson, GoalIdentityJson, GoalJson, ErrorJson, } from './generated/types/types.js';

package/dist/index.js

@@ -1,6 +1,9 @@
 // Re-export JSON schemas via .ts shims to avoid .json re-exports in declarations
 export { default as SchemaGenesis } from './generated/schemas/Genesis.js';
+export { default as SchemaResourceType } from './generated/schemas/standalone/ResourceType.js';
 export { default as SchemaJob } from './generated/schemas/standalone/Job.js';
+export { default as SchemaRunnableStrategy } from './generated/schemas/standalone/RunnableStrategy.js';
 export { default as SchemaStrategyRun } from './generated/schemas/standalone/StrategyRun.js';
-export { default as ResourceTypeGenesis } from './generated/resources/Genesis.js';
-export { default as CONSTANTS } from './generated/constants/constants.js';
+export { default as ResourceGenesis } from './generated/resources/Genesis.js';
+export { default as CONSTANTS } from './generated/artifacts/constants.js';
+export { default as MAPPINGS } from './generated/artifacts/mappings.js';

package/dist/scripts/_lib/config.d.ts

@@ -12,9 +12,8 @@ export declare class SchemaConfig {
     private readonly sourceFile;
     private readonly normalizedDir;
     private readonly schemasDir;
-    private readonly constantsDir;
+    private readonly artifactsDir;
     private readonly resourcesDir;
-    private readonly dependencyMapPath;
     private readonly typesSrcDir;
     private readonly typesDistDir;
     private readonly baseUrl;
@@ -29,8 +28,8 @@ export declare class SchemaConfig {
     getNormalizedSourcePath(): string;
     getSchemasDir(): string;
     getSchemaPath(filename: string): string;
-    getConstantsDir(): string;
-    getConstantsPath(filename: string): string;
+    getArtifactsDir(): string;
+    getArtifactsPath(filename: string): string;
     getStandaloneSchemaDir(): string;
     getStandaloneSchemaPath(filename: string): string;
     getTypesSrcDir(): string;
@@ -42,7 +41,6 @@ export declare class SchemaConfig {
     getStandaloneTypeSrcPath(filename: string): string;
     getStandaloneTypeDistPath(filename: string): string;
     getResourcesDir(): string;
-    getDependencyMapPath(): string;
     getBaseUrl(): string;
     getVersion(): string;
     getSchemaId(schemaName: string): string;

package/dist/scripts/_lib/config.js

@@ -22,13 +22,12 @@ export class SchemaConfig {
         this.sourceFile = getEnv('TP_SCHEMA_SOURCE_FILE', 'Genesis.json');
         this.normalizedDir = getEnv('TP_SCHEMA_NORMALIZED_DIR', 'src/generated/normalized');
         this.schemasDir = getEnv('TP_SCHEMA_SCHEMAS_DIR', 'src/generated/schemas');
-        this.constantsDir = getEnv('TP_SCHEMA_CONSTANTS_DIR', 'src/generated/constants');
+        this.artifactsDir = getEnv('TP_SCHEMA_ARTIFACTS_DIR', 'src/generated/artifacts');
         this.resourcesDir = getEnv('TP_SCHEMA_RESOURCES_DIR', 'src/generated/resources');
-        this.dependencyMapPath = getEnv('TP_SCHEMA_DEPENDENCY_MAP_PATH', 'src/generated/dependencies/dependencyMap.json');
         this.typesSrcDir = getEnv('TP_SCHEMA_TYPES_SRC_DIR', 'src/generated/types');
         this.typesDistDir = getEnv('TP_SCHEMA_TYPES_DIST_DIR', 'dist/generated/types');
         this.baseUrl = getEnv('TP_SCHEMA_BASE_URL', 'https://schemas.toolproof.com');
-        this.version = getEnv('TP_SCHEMA_VERSION', 'v0');
+        this.version = getEnv('TP_SCHEMA_VERSION', 'v1');
     }
     // Path getters
     getRoot() {
@@ -67,13 +66,13 @@ export class SchemaConfig {
     getSchemaPath(filename) {
         return path.join(this.getSchemasDir(), filename);
     }
-    getConstantsDir() {
-        return path.isAbsolute(this.constantsDir)
-            ? this.constantsDir
-            : path.join(this.root, this.constantsDir);
+    getArtifactsDir() {
+        return path.isAbsolute(this.artifactsDir)
+            ? this.artifactsDir
+            : path.join(this.root, this.artifactsDir);
     }
-    getConstantsPath(filename) {
-        return path.join(this.getConstantsDir(), filename);
+    getArtifactsPath(filename) {
+        return path.join(this.getArtifactsDir(), filename);
     }
     getStandaloneSchemaDir() {
         return path.join(this.getSchemasDir(), 'standalone');
@@ -114,11 +113,6 @@ export class SchemaConfig {
             ? this.resourcesDir
             : path.join(this.root, this.resourcesDir);
     }
-    getDependencyMapPath() {
-        return path.isAbsolute(this.dependencyMapPath)
-            ? this.dependencyMapPath
-            : path.join(this.root, this.dependencyMapPath);
-    }
     // Schema URL methods
     getBaseUrl() {
         return this.baseUrl;

package/dist/scripts/generateConstantsAndMappings.d.ts

@@ -0,0 +1,31 @@
+export type GeneratedConstants = {
+    Names: Record<string, string>;
+    Enums: Record<string, Record<string, string>>;
+};
+export type GeneratedMappings = {
+    IdentityNameToIdentityPrefix: Record<string, string>;
+    StepKindToStepIdentityPrefix: Record<string, string>;
+};
+export type DeriveStepKindToStepIdentityPrefixResult = {
+    mapping: Record<string, string>;
+    missing: Array<{
+        stepKind: string;
+        identityName: string;
+    }>;
+};
+export declare function extractIdentityPrefixes(schema: unknown): Record<string, string>;
+export declare function extractSubschemaNames(schema: unknown): Record<string, string>;
+export declare function extractEnums(schema: unknown): Record<string, Record<string, string>>;
+export declare function deriveStepKindToStepIdentityPrefix(enums: Record<string, Record<string, string>>, identityNameToIdentityPrefix: Record<string, string>): DeriveStepKindToStepIdentityPrefixResult;
+export declare function extractGeneratedConstantsAndMappings(schema: unknown): {
+    CONSTANTS: GeneratedConstants;
+    MAPPINGS: GeneratedMappings;
+    DIAGNOSTICS: {
+        missingStepKindIdentityPrefixes: Array<{
+            stepKind: string;
+            identityName: string;
+        }>;
+    };
+};
+export declare function renderConstantsTs(constants: GeneratedConstants): string;
+export declare function renderMappingsTs(mappings: GeneratedMappings): string;

package/dist/scripts/generateConstantsAndMappings.js

@@ -0,0 +1,243 @@
+import fs from 'fs';
+import path from 'path';
+import { getConfig } from './_lib/config.js';
+// PURE: Convert a string enum member into PascalCase.
+// Examples: 'job' -> 'Job', 'graph_start' -> 'GraphStart'
+function toPascalCase(value) {
+    return value
+        .split(/[^A-Za-z0-9]+/g)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+// PURE: Attempt to derive a canonical identity prefix from a canonical identity regex pattern.
+function deriveIdentityPrefixFromPattern(pattern) {
+    // Canonical (currently used across schemas): ^PREFIX-.+$
+    const match = /^\^([^$]+)\.\+\$$/.exec(pattern);
+    if (!match)
+        return undefined;
+    const prefix = match[1];
+    if (!prefix || /[`\n\r]/.test(prefix))
+        return undefined;
+    return prefix;
+}
+// PURE: Extract all identity prefixes from `$defs/*Identity` string-pattern definitions.
+export function extractIdentityPrefixes(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const defs = schema.$defs;
+    if (!defs || typeof defs !== 'object')
+        return {};
+    const defEntries = Object.entries(defs);
+    defEntries.sort(([a], [b]) => a.localeCompare(b));
+    const out = {};
+    for (const [defName, defVal] of defEntries) {
+        if (!/Identity$/.test(defName))
+            continue;
+        if (!defVal || typeof defVal !== 'object' || Array.isArray(defVal))
+            continue;
+        const v = defVal;
+        if (v.type !== 'string')
+            continue;
+        if (typeof v.pattern !== 'string')
+            continue;
+        const prefix = deriveIdentityPrefixFromPattern(v.pattern);
+        if (!prefix)
+            continue;
+        out[defName] = prefix;
+    }
+    return out;
+}
+// PURE: Extract all subschema names from `$defs/*`.
+// Shape: { JobStep: 'JobStep', StepKind: 'StepKind', ... }
+export function extractSubschemaNames(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const defs = schema.$defs;
+    if (!defs || typeof defs !== 'object')
+        return {};
+    const defEntries = Object.entries(defs);
+    defEntries.sort(([a], [b]) => a.localeCompare(b));
+    const out = {};
+    for (const [defName] of defEntries) {
+        if (!defName || /[\n\r`]/.test(defName))
+            continue;
+        out[defName] = defName;
+    }
+    return out;
+}
+// PURE: Extract all string enums from `$defs/*Kind|*Status` definitions.
+// Shape: { StepKind: { job: 'job', ... }, ResourceShellKind: { inputPotential': 'inputPotential', ... } }
+export function extractEnums(schema) {
+    if (!schema || typeof schema !== 'object')
+        return {};
+    const defs = schema.$defs;
+    if (!defs || typeof defs !== 'object')
+        return {};
+    const defEntries = Object.entries(defs);
+    defEntries.sort(([a], [b]) => a.localeCompare(b));
+    const out = {};
+    for (const [defName, defVal] of defEntries) {
+        if (!/(Kind|Status)$/.test(defName))
+            continue;
+        if (!defVal || typeof defVal !== 'object' || Array.isArray(defVal))
+            continue;
+        const v = defVal;
+        if (v.type !== 'string')
+            continue;
+        if (!Array.isArray(v.enum) || v.enum.length === 0)
+            continue;
+        if (v.enum.some((x) => typeof x !== 'string'))
+            continue;
+        const members = {};
+        for (const member of v.enum) {
+            members[member] = member;
+        }
+        out[defName] = members;
+    }
+    return out;
+}
+// PURE: Derive a StepKind -> StepIdentityPrefix mapping.
+// Example: { job: 'job' } + IdentityNameToIdentityPrefix['JobStepIdentity']='JOB_STEP-' => { job: 'JOB_STEP-' }
+export function deriveStepKindToStepIdentityPrefix(enums, identityNameToIdentityPrefix) {
+    const stepKindEnum = enums.StepKind;
+    if (!stepKindEnum || typeof stepKindEnum !== 'object')
+        return { mapping: {}, missing: [] };
+    const stepKinds = Object.keys(stepKindEnum).sort((a, b) => a.localeCompare(b));
+    const mapping = {};
+    const missing = [];
+    for (const stepKind of stepKinds) {
+        const identityName = `${toPascalCase(stepKind)}StepIdentity`;
+        const prefix = identityNameToIdentityPrefix[identityName];
+        if (!prefix) {
+            missing.push({ stepKind, identityName });
+            continue;
+        }
+        mapping[stepKind] = prefix;
+    }
+    return { mapping, missing };
+}
+// PURE: Extract generated CONSTANTS + MAPPINGS from a parsed schema.
+export function extractGeneratedConstantsAndMappings(schema) {
+    const names = extractSubschemaNames(schema);
+    const enums = extractEnums(schema);
+    const identityPrefixes = extractIdentityPrefixes(schema);
+    const derivedStepKind = deriveStepKindToStepIdentityPrefix(enums, identityPrefixes);
+    return {
+        CONSTANTS: {
+            Names: names,
+            Enums: enums,
+        },
+        MAPPINGS: {
+            IdentityNameToIdentityPrefix: identityPrefixes,
+            StepKindToStepIdentityPrefix: derivedStepKind.mapping,
+        },
+        DIAGNOSTICS: {
+            missingStepKindIdentityPrefixes: derivedStepKind.missing,
+        },
+    };
+}
+// PURE: Render helpers for TS keys/strings.
+function escapeTsString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\t/g, '\\t')
+        .replace(/'/g, "\\'");
+}
+function renderTsStringLiteral(value) {
+    return `'${escapeTsString(value)}'`;
+}
+function isValidTsIdentifier(key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key);
+}
+function renderTsKey(key) {
+    return isValidTsIdentifier(key) ? key : renderTsStringLiteral(key);
+}
+// PURE: Render constants TypeScript source.
+export function renderConstantsTs(constants) {
+    const nameKeys = Object.keys(constants.Names).sort((a, b) => a.localeCompare(b));
+    const enumKeys = Object.keys(constants.Enums).sort((a, b) => a.localeCompare(b));
+    const lines = [];
+    lines.push('const CONSTANTS = {');
+    lines.push('    Names: {');
+    for (const key of nameKeys) {
+        const value = constants.Names[key] ?? '';
+        lines.push(`        ${renderTsKey(key)}: ${renderTsStringLiteral(value)},`);
+    }
+    lines.push('    },');
+    lines.push('    Enums: {');
+    for (const key of enumKeys) {
+        const members = constants.Enums[key] ?? {};
+        lines.push(`        ${renderTsKey(key)}: {`);
+        for (const memberKey of Object.keys(members)) {
+            const value = members[memberKey] ?? '';
+            lines.push(`            ${renderTsKey(memberKey)}: ${renderTsStringLiteral(value)},`);
+        }
+        lines.push('        },');
+    }
+    lines.push('    }');
+    lines.push('} as const;');
+    lines.push('');
+    lines.push('export default CONSTANTS;');
+    lines.push('');
+    return lines.join('\n');
+}
+// PURE: Render mappings TypeScript source.
+export function renderMappingsTs(mappings) {
+    const identityKeys = Object.keys(mappings.IdentityNameToIdentityPrefix).sort((a, b) => a.localeCompare(b));
+    const stepKindKeys = Object.keys(mappings.StepKindToStepIdentityPrefix).sort((a, b) => a.localeCompare(b));
+    const lines = [];
+    lines.push('const MAPPINGS = {');
+    lines.push('    IdentityNameToIdentityPrefix: {');
+    for (const key of identityKeys) {
+        const value = mappings.IdentityNameToIdentityPrefix[key] ?? '';
+        lines.push(`        ${renderTsKey(key)}: ${renderTsStringLiteral(value)},`);
+    }
+    lines.push('    },');
+    lines.push('    StepKindToStepIdentityPrefix: {');
+    for (const key of stepKindKeys) {
+        const value = mappings.StepKindToStepIdentityPrefix[key] ?? '';
+        lines.push(`        ${renderTsKey(key)}: ${renderTsStringLiteral(value)},`);
+    }
+    lines.push('    },');
+    lines.push('} as const;');
+    lines.push('');
+    lines.push('export default MAPPINGS;');
+    lines.push('');
+    return lines.join('\n');
+}
+// IMPURE: Script entrypoint (config + filesystem I/O + console + process exit code).
+function main() {
+    try {
+        const config = getConfig();
+        const inPath = config.getSchemaPath('Genesis.json');
+        const outConstantsPath = config.getArtifactsPath('constants.ts');
+        const outMappingsPath = config.getArtifactsPath('mappings.ts');
+        if (!fs.existsSync(inPath)) {
+            throw new Error(`Genesis schema not found at ${inPath}. Run extractSchemasFromResourceTypeShells first.`);
+        }
+        const raw = fs.readFileSync(inPath, 'utf8');
+        const doc = JSON.parse(raw);
+        const { CONSTANTS, MAPPINGS, DIAGNOSTICS } = extractGeneratedConstantsAndMappings(doc);
+        if (DIAGNOSTICS.missingStepKindIdentityPrefixes.length) {
+            const rows = DIAGNOSTICS.missingStepKindIdentityPrefixes
+                .map(({ stepKind, identityName }) => `${stepKind} -> ${identityName}`)
+                .join(', ');
+            throw new Error(`Missing IdentityNameToIdentityPrefix entries required for StepKindToStepIdentityPrefix: ${rows}`);
+        }
+        const constantsTs = renderConstantsTs(CONSTANTS);
+        const mappingsTs = renderMappingsTs(MAPPINGS);
+        fs.mkdirSync(path.dirname(outConstantsPath), { recursive: true });
+        fs.writeFileSync(outConstantsPath, constantsTs, 'utf8');
+        fs.writeFileSync(outMappingsPath, mappingsTs, 'utf8');
+        console.log(`Wrote constants to ${outConstantsPath}`);
+        console.log(`Wrote mappings to ${outMappingsPath}`);
+    }
+    catch (error) {
+        console.error(`Error generating constants/mappings: ${error?.message ?? error}`);
+        process.exitCode = 1;
+    }
+}
+main();

package/dist/scripts/generateDependencies.js

@@ -88,7 +88,7 @@ function main() {
     try {
         const config = getConfig();
         const inPath = config.getSchemaPath("Genesis.json");
-        const outPath = config.getDependencyMapPath();
+        const outPath = config.getArtifactsPath("dependencyMap.json");
         if (!fs.existsSync(inPath)) {
             throw new Error(`Genesis schema not found at ${inPath}. Run extractSchemasFromResourceTypeShells first.`);
         }

package/dist/scripts/generateStandaloneType.js

@@ -9,7 +9,8 @@ import { getConfig } from "./_lib/config.js";
 // PURE: Generate the content of a standalone Resource type definition file for a given schema name.
 function generateStandaloneTypeLogic(name) {
     const header = "// Auto-generated strict composite type. Do not edit.\n";
-    const ts = `import type { ShellMaterializedBase, ${name} as NucleusSchema } from "../types.js";\n` +
+    const nucleusTypeName = name.endsWith("Json") ? name : `${name}Json`;
+    const ts = `import type { ShellMaterializedBaseJson as ShellMaterializedBase, ${nucleusTypeName} as NucleusSchema } from "../types.js";\n` +
         `export type Resource_${name} = ShellMaterializedBase & { nucleus: NucleusSchema };\n`;
     return header + ts;
 }

package/dist/scripts/generateTerminals.js

@@ -37,8 +37,8 @@ function computeTerminalsInKeyOrder(dependencyMap) {
 function main() {
     try {
         const config = getConfig();
-        const inPath = config.getDependencyMapPath();
-        const outPath = path.join(path.dirname(inPath), "terminals.json");
+        const inPath = config.getArtifactsPath("dependencyMap.json");
+        const outPath = config.getArtifactsPath("terminals.json");
         if (!fs.existsSync(inPath)) {
             throw new Error(`Dependency map not found at ${inPath}. Run generateDependencies first.`);
         }

package/dist/scripts/generateTypes.js

@@ -227,6 +227,178 @@ function removeDuplicateUnionEntries(ts) {
 function escapeRegExpLiteral(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+// PURE: Rename exported top-level generated declarations to canonical `*Json` names.
+// This makes editor hover/inference prefer `FooJson` because the underlying declared
+// symbol is `FooJson` (not `Foo` with a re-export alias).
+function applyReplacementsOutsideStringsAndComments(text, replaceCodeSegment) {
+    const len = text.length;
+    let out = '';
+    let i = 0;
+    let codeStart = 0;
+    const flushCode = (end) => {
+        if (end > codeStart)
+            out += replaceCodeSegment(text.slice(codeStart, end));
+        codeStart = end;
+    };
+    const startsWith = (s) => text.startsWith(s, i);
+    while (i < len) {
+        // Line comment
+        if (startsWith('//')) {
+            flushCode(i);
+            const start = i;
+            i += 2;
+            while (i < len && text[i] !== '\n')
+                i++;
+            if (i < len && text[i] === '\n')
+                i++;
+            out += text.slice(start, i);
+            codeStart = i;
+            continue;
+        }
+        // Block comment
+        if (startsWith('/*')) {
+            flushCode(i);
+            const start = i;
+            i += 2;
+            while (i < len && !text.startsWith('*/', i))
+                i++;
+            if (i < len)
+                i += 2;
+            out += text.slice(start, i);
+            codeStart = i;
+            continue;
+        }
+        const ch = text[i];
+        // Single-quoted string
+        if (ch === "'") {
+            flushCode(i);
+            const start = i;
+            i++;
+            while (i < len) {
+                const c = text[i];
+                if (c === '\\') {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                if (c === "'")
+                    break;
+            }
+            out += text.slice(start, i);
+            codeStart = i;
+            continue;
+        }
+        // Double-quoted string
+        if (ch === '"') {
+            flushCode(i);
+            const start = i;
+            i++;
+            while (i < len) {
+                const c = text[i];
+                if (c === '\\') {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                if (c === '"')
+                    break;
+            }
+            out += text.slice(start, i);
+            codeStart = i;
+            continue;
+        }
+        // Template literal (backticks). We conservatively treat the whole template as a string.
+        // The generated .d.ts uses these primarily for template-literal *value* types like `TYPE-${string}`
+        // and we do not want to rewrite their raw text.
+        if (ch === '`') {
+            flushCode(i);
+            const start = i;
+            i++;
+            while (i < len) {
+                const c = text[i];
+                if (c === '\\') {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                if (c === '`')
+                    break;
+            }
+            out += text.slice(start, i);
+            codeStart = i;
+            continue;
+        }
+        i++;
+    }
+    flushCode(len);
+    return out;
+}
+function renameExportedTopLevelTypesToJson(tsText) {
+    // Collect exported type/interface names.
+    const exportedDeclRegex = /^export\s+(?:type|interface)\s+([A-Za-z_][A-Za-z0-9_]*)\b/gm;
+    const exportedNames = new Set();
+    for (let m = exportedDeclRegex.exec(tsText); m; m = exportedDeclRegex.exec(tsText)) {
+        exportedNames.add(m[1]);
+    }
+    const renamePairs = Array.from(exportedNames)
+        .filter((name) => !name.endsWith('Json'))
+        .map((name) => ({ from: name, to: `${name}Json` }));
+    if (!renamePairs.length)
+        return tsText;
+    // Replace longer names first to reduce any accidental partial-match risk.
+    renamePairs.sort((a, b) => b.from.length - a.from.length);
+    const replaceCode = (code) => {
+        let out = code;
+        for (const { from, to } of renamePairs) {
+            const re = new RegExp(`\\b${escapeRegExpLiteral(from)}\\b`, 'g');
+            out = out.replace(re, to);
+        }
+        return out;
+    };
+    return applyReplacementsOutsideStringsAndComments(tsText, replaceCode);
+}
+// PURE: Derive the TS value type for JobStepSocket from Genesis.json.
+// We prefer to match the schema shape:
+//   JobStepSocket.additionalProperties.oneOf = [#ResourcePotential, #Resource]
+// so the emitted TS becomes:
+//   Record<ResourceRoleIdentity, Resource | ResourcePotential>
+function deriveJobStepSocketValueType(parsedSchema) {
+    // NOTE: The generator reads from `src/generated/schemas/Genesis.json`, where `$defs.*`
+    // entries are plain JSON-Schema objects.
+    // The source-of-truth `src/Genesis.json` uses a wrapper shape:
+    //   $defs.X = { identity, name, description, nucleusSchema: { ...actual schema... } }
+    // Support both.
+    const defs = parsedSchema?.$defs ?? parsedSchema?.nucleusSchema?.$defs;
+    const def = defs?.JobStepSocket;
+    const schemaNode = def?.nucleusSchema ?? def;
+    const additionalProperties = schemaNode?.additionalProperties;
+    if (!additionalProperties || typeof additionalProperties !== 'object' || Array.isArray(additionalProperties)) {
+        return 'Resource';
+    }
+    const union = additionalProperties.oneOf ??
+        additionalProperties.anyOf;
+    if (!Array.isArray(union) || union.length === 0) {
+        return 'Resource';
+    }
+    const names = [];
+    for (const item of union) {
+        const ref = item && typeof item === 'object' ? item.$ref : undefined;
+        if (typeof ref !== 'string')
+            continue;
+        // Accept both internal anchor refs like "#Resource" and JSON Pointer refs like "#/$defs/Resource".
+        const m = /^#(?:\/(?:\$defs|definitions)\/)?([A-Za-z_][A-Za-z0-9_]*)$/.exec(ref);
+        if (m)
+            names.push(m[1]);
+    }
+    const unique = Array.from(new Set(names));
+    if (!unique.length)
+        return 'Resource';
+    // Preserve an intentional ordering when we recognize the canonical pair.
+    if (unique.includes('Resource') && unique.includes('ResourcePotential')) {
+        return 'Resource | ResourcePotential';
+    }
+    return unique.join(' | ');
+}
 // PURE: Fix a known json-schema-to-typescript edge case where a JSON-like recursive value union
 // accidentally includes a direct self-reference (`| JsonData`) instead of the intended array case (`| JsonData[]`).
 function fixJsonDataSelfReference(ts) {
@@ -306,19 +478,25 @@ function postProcessEmittedTypes(ts, parsedSchema) {
     const resourceRoleKeyType = 'ResourceRoleIdentity';
     const jobStepKeyType = 'JobStepIdentity';
     const strategyThreadKeyType = 'StrategyThreadIdentity';
-    ts = ts.replace(/export interface RoleMap\s*{[^}]*}/g, `export type RoleMap = Record<${resourceRoleKeyType}, ResourceRoleValue>;`);
+    ts = ts.replace(/export interface RoleDict\s*{[^}]*}/g, `export type RoleDict = Record<${resourceRoleKeyType}, ResourceRoleValue>;`);
     // Normalize StrategyState & related socket maps to identity-keyed Records.
     // These are emitted as `[k: string]` by json-schema-to-typescript but are identity-keyed in practice.
-    // Per schema: JobStepSocket: Record<ResourceRoleIdentity, Resource>
+    // Per schema: JobStepSocket: Record<ResourceRoleIdentity, Resource | ResourcePotential>
     //            StrategyState: Record<JobStepIdentity, JobStepSocket>
-    const jobStepSocketValueType = 'Resource';
+    const jobStepSocketValueType = deriveJobStepSocketValueType(parsedSchema);
     ts = ts.replace(/export interface JobStepSocket\s*\{\s*\[k:\s*string\]:\s*[^;]+;\s*\}/g, `export type JobStepSocket = Record<${resourceRoleKeyType}, ${jobStepSocketValueType}>;`);
+    // If the upstream generator (or earlier passes) already emitted a Record-based alias,
+    // force its value type to match the schema-derived union.
+    ts = ts.replace(/export\s+type\s+JobStepSocket\s*=\s*Record<\s*ResourceRoleIdentity\s*,\s*[^>]+>\s*;/g, `export type JobStepSocket = Record<${resourceRoleKeyType}, ${jobStepSocketValueType}>;`);
     ts = ts.replace(/export interface StrategyState\s*\{\s*\[k:\s*string\]:\s*JobStepSocket;\s*\}/g, `export type StrategyState = Record<${jobStepKeyType}, JobStepSocket>;`);
     ts = ts.replace(/(strategyStateUpdate\??:\s*)\{\s*\[k:\s*string\]:\s*JobStepSocket;\s*\};/g, `$1Record<${jobStepKeyType}, JobStepSocket>;`);
-    // Ensure key constraints for strategyThreadMap are preserved as template-literal identity keys.
+    // Ensure key constraints for strategyThreadDict are preserved as template-literal identity keys.
     // json-schema-to-typescript emits `[k: string]: StepArray;`, but we want keys to be `StrategyThreadIdentity`.
-    ts = ts.replace(/export interface StrategyThreadMap\s*\{\s*\[k:\s*string\]:\s*StepArray;\s*\}/g, `export type StrategyThreadMap = Record<${strategyThreadKeyType}, StepArray>;`);
+    ts = ts.replace(/export interface StrategyThreadDict\s*\{\s*\[k:\s*string\]:\s*StepArray;\s*\}/g, `export type StrategyThreadDict = Record<${strategyThreadKeyType}, StepArray>;`);
     ts = fixJsonDataSelfReference(ts);
+    // IMPORTANT: do this last so earlier post-processing regexes can target
+    // the generator's original names (without `Json` suffixes).
+    ts = renameExportedTopLevelTypesToJson(ts);
     return ts;
 }
 // PURE: Add banner + formatting/guards to build the final .d.ts content.

package/dist/scripts/wrapResourceTypesWithResourceShells.js

@@ -22,8 +22,10 @@ function generateResourceShellLogic(genesis) {
             resourceRoleHandle: 'ROLE-Genesis',
             jobStepHandle: 'JOB_STEP-Genesis'
         },
-        kind: 'materialized',
+        resourceShellKind: 'materialized',
+        version: 1,
         timestamp: genesisTimestamp,
+        path: 'https://schemas.toolproof.com/v1/Genesis.json',
         nucleus: {}
     };
     defKeys.forEach((defName) => {
@@ -33,10 +35,12 @@ function generateResourceShellLogic(genesis) {
             resourceTypeHandle: 'TYPE-ResourceType',
             creationContext: {
                 resourceRoleHandle: 'ROLE-Genesis',
-                jobStepHandle: `JOB_STEP-${defName}`
+                jobStepHandle: 'JOB_STEP-Genesis'
             },
-            kind: 'materialized',
+            resourceShellKind: 'materialized',
+            version: 1,
             timestamp: genesisTimestamp,
+            path: `https://schemas.toolproof.com/v1/Genesis.json#/$defs/${defName}`,
             nucleus: defValue
         };
     });