@toolproof-core/lib 1.0.34 → 1.0.37

package/dist/utils/strategyExtraction.js

@@ -0,0 +1,88 @@
+import { CONSTANTS } from '../lookups/lookups.js';
+export function getInputRoleSpecEntriesFromTool(tool) {
+    return Object.entries(tool.roleSpec.inputRoleValueByName);
+}
+export function getOutputRoleSpecEntriesFromTool(tool) {
+    return Object.entries(tool.roleSpec.outputRoleValueByName);
+}
+export function getInputRoleNamesFromTool(tool) {
+    return getInputRoleSpecEntriesFromTool(tool).map(([roleName]) => roleName);
+}
+export function getOutputRoleNamesFromTool(tool) {
+    return getOutputRoleSpecEntriesFromTool(tool).map(([roleName]) => roleName);
+}
+export function extractResourceTypeHandleFromRoleValue(roleValue) {
+    const typeRef = roleValue.typeRef;
+    if ('resourceTypeHandle' in typeRef) {
+        return typeRef.resourceTypeHandle;
+    }
+    return null;
+}
+export function extractToolStepsFromStrategy(strategy) {
+    const toolSteps = [];
+    const visitStep = (step) => {
+        switch (step.stepKind) {
+            case 'tool': {
+                toolSteps.push(step);
+                return;
+            }
+            case 'branch': {
+                for (const conditional of step.cases) {
+                    toolSteps.push(conditional.when, conditional.what);
+                }
+                return;
+            }
+            case 'while':
+            case 'for': {
+                toolSteps.push(step.case.when, step.case.what);
+                return;
+            }
+            default: {
+                const _exhaustive = step;
+                return _exhaustive;
+            }
+        }
+    };
+    for (const threadSteps of strategy.stepsByThreadIndex) {
+        for (const step of threadSteps) {
+            visitStep(step);
+        }
+    }
+    return toolSteps;
+}
+export function extractToolsFromStrategy(strategy, toolMap) {
+    const toolSteps = extractToolStepsFromStrategy(strategy);
+    const toolHandles = new Set();
+    const tools = [];
+    for (const toolStep of toolSteps) {
+        toolHandles.add(toolStep.toolHandle);
+    }
+    for (const toolHandle of toolHandles) {
+        const tool = toolMap.get(toolHandle);
+        if (!tool) {
+            throw new Error(`Tool with handle '${toolHandle}' not found in toolMap.`);
+        }
+        tools.push(tool);
+    }
+    return tools;
+}
+function extractRoleSpecByDirectionFromTool(tool) {
+    return {
+        inputRoleValueByName: new Map(getInputRoleSpecEntriesFromTool(tool)),
+        outputRoleValueByName: new Map(getOutputRoleSpecEntriesFromTool(tool)),
+    };
+}
+export function extractRoleSpecByDirectionByToolHandleFromStrategy(strategy, toolMap) {
+    const roleSpecByDirectionByToolHandle = new Map();
+    for (const tool of extractToolsFromStrategy(strategy, toolMap)) {
+        roleSpecByDirectionByToolHandle.set(tool.handle, extractRoleSpecByDirectionFromTool(tool));
+    }
+    return roleSpecByDirectionByToolHandle;
+}
+export function extractSingleBranchableOutputResourceTypeHandle(tool) {
+    const outputRoleSpecEntries = getOutputRoleSpecEntriesFromTool(tool).filter(([roleName]) => roleName !== CONSTANTS.Cosmos.ErrorOutputRoleName);
+    if (!outputRoleSpecEntries[0] || outputRoleSpecEntries.length !== 1) {
+        throw new Error(`Tool ${tool.handle} must have exactly one branchable output resource type to be branchable/loopable`);
+    }
+    return extractResourceTypeHandleFromRoleValue(outputRoleSpecEntries[0][1]);
+}

package/dist/utils/strategyStateResolution.d.ts

@@ -0,0 +1,17 @@
+import type { MutableInputResource, MutableExternalInputPotential, MutableStrategyState, MutableToolStepKey, MutableToolStepRoleAddress } from './mutableStrategyOverlay.js';
+export type ResolveResult<TKey extends string = MutableToolStepKey> = {
+    status: 'inputResource';
+    entry: MutableInputResource;
+    path: MutableToolStepRoleAddress<TKey>[];
+} | {
+    status: 'externalInputPotential';
+    entry: MutableExternalInputPotential;
+    path: MutableToolStepRoleAddress<TKey>[];
+} | {
+    status: 'unresolved';
+    reason: 'not-found' | 'cycle' | 'depth-exceeded';
+    path: MutableToolStepRoleAddress<TKey>[];
+};
+export declare function resolveStrategyStateChain<TKey extends string, TStrategyState extends MutableStrategyState<TKey>>(strategyState: TStrategyState, start: MutableToolStepRoleAddress<TKey>, opts?: {
+    maxDepth?: number;
+}): ResolveResult<TKey>;

package/dist/utils/strategyStateResolution.js

@@ -0,0 +1,27 @@
+import { getStrategyStateInputEntry } from './mutableStrategyOverlay.js';
+export function resolveStrategyStateChain(strategyState, start, opts) {
+    const maxDepth = opts?.maxDepth ?? 50;
+    const visited = new Set();
+    const path = [];
+    let current = start;
+    for (let depth = 0; depth <= maxDepth; depth++) {
+        path.push(current);
+        const visitKey = `${current.toolStepKey}::${current.roleName}`;
+        if (visited.has(visitKey)) {
+            return { status: 'unresolved', reason: 'cycle', path };
+        }
+        visited.add(visitKey);
+        const entry = getStrategyStateInputEntry(strategyState, current);
+        if (!entry) {
+            return { status: 'unresolved', reason: 'not-found', path };
+        }
+        if (entry.strategyStateInputKind === 'inputResource') {
+            return { status: 'inputResource', entry, path };
+        }
+        if (entry.strategyStateInputKind === 'externalInputPotential') {
+            return { status: 'externalInputPotential', entry, path };
+        }
+        current = entry.toolStepRoleAddress;
+    }
+    return { status: 'unresolved', reason: 'depth-exceeded', path };
+}

package/dist/utils/strategyThreading.d.ts

@@ -0,0 +1,2 @@
+import type { MutableStrategy, MutableStep, MutableStrategyState, MutableToolStepKey } from './mutableStrategyOverlay.js';
+export declare function toExecutionMutableStrategy<TKey extends string = MutableToolStepKey, TStep extends MutableStep<TKey> = MutableStep<TKey>, TState extends MutableStrategyState<TKey> = MutableStrategyState<TKey>>(mutableStrategy: MutableStrategy<TKey, TStep, TState>): MutableStrategy<TKey, TStep, TState>;

package/dist/utils/strategyThreading.js

@@ -0,0 +1,10 @@
+import { getIndependentThreads } from './stepParallelization.js';
+import { getAuthoringSteps as getAuthoringThreadSteps } from './mutableStrategyOverlay.js';
+export function toExecutionMutableStrategy(mutableStrategy) {
+    const authoringSteps = getAuthoringThreadSteps(mutableStrategy);
+    const stepsByThreadIndex = getIndependentThreads(authoringSteps, mutableStrategy.strategyState);
+    return {
+        ...mutableStrategy,
+        stepsByThreadIndex: stepsByThreadIndex,
+    };
+}

package/dist/utils/toolStepPaths.d.ts

@@ -0,0 +1,2 @@
+import type { ToolStepPath, ToolStepPathSpec } from '@toolproof-core/genesis';
+export declare function toToolStepPath(spec: ToolStepPathSpec): ToolStepPath;

package/dist/utils/toolStepPaths.js

@@ -0,0 +1,21 @@
+function getToolStepPathSuffix(spec) {
+    if (spec.toolStepPathSlot === 'self') {
+        return '/self';
+    }
+    if (spec.toolStepPathSlot === 'cases/when' || spec.toolStepPathSlot === 'cases/what') {
+        if (typeof spec.caseIndex !== 'number') {
+            throw new Error('Expected caseIndex for branch tool-step path construction');
+        }
+        return `/cases/${spec.caseIndex}/${spec.toolStepPathSlot === 'cases/when' ? 'when' : 'what'}`;
+    }
+    if (spec.toolStepPathSlot === 'case/when') {
+        return '/case/when';
+    }
+    if (spec.toolStepPathSlot === 'case/what') {
+        return '/case/what';
+    }
+    throw new Error(`Unsupported tool-step path slot '${String(spec.toolStepPathSlot)}'`);
+}
+export function toToolStepPath(spec) {
+    return `/threads/${spec.threadIndex}/steps/${spec.stepIndex}${getToolStepPathSuffix(spec)}`;
+}

package/package.json

@@ -1,43 +1,63 @@
 {
   "name": "@toolproof-core/lib",
-  "version": "1.0.34",
+  "version": "1.0.37",
   "description": "",
   "type": "module",
   "keywords": [],
   "author": "",
   "license": "ISC",
   "exports": {
-    "./artifacts": {
-      "types": "./dist/artifacts/artifacts.d.ts",
-      "import": "./dist/artifacts/artifacts.js"
+    "./lookups": {
+      "types": "./dist/lookups/lookups.d.ts",
+      "import": "./dist/lookups/lookups.js"
     },
     "./types": {
       "types": "./dist/types/types.d.ts",
       "import": "./dist/types/types.js"
     },
-    "./extract-data": {
-      "types": "./dist/utils/extractData.d.ts",
-      "import": "./dist/utils/extractData.js"
+    "./identifier-generation": {
+      "types": "./dist/utils/identifierGeneration.d.ts",
+      "import": "./dist/utils/identifierGeneration.js"
     },
-    "./create-resource": {
-      "types": "./dist/utils/creation/resourceCreation.d.ts",
-      "import": "./dist/utils/creation/resourceCreation.js"
+    "./strategy-assembly": {
+      "types": "./dist/utils/strategyAssembly.d.ts",
+      "import": "./dist/utils/strategyAssembly.js"
     },
-    "./create-step": {
-      "types": "./dist/integrations/firebase/createStep.d.ts",
-      "import": "./dist/integrations/firebase/createStep.js"
+    "./cosmos-data-extraction": {
+      "types": "./dist/utils/cosmosDataExtraction.d.ts",
+      "import": "./dist/utils/cosmosDataExtraction.js"
     },
-    "./create-threaded-strategy": {
-      "types": "./dist/integrations/firebase/createThreadedStrategy.d.ts",
-      "import": "./dist/integrations/firebase/createThreadedStrategy.js"
+    "./strategy-extraction": {
+      "types": "./dist/utils/strategyExtraction.d.ts",
+      "import": "./dist/utils/strategyExtraction.js"
     },
-    "./resolve-resource-chain": {
-      "types": "./dist/utils/resolveResourceChain.d.ts",
-      "import": "./dist/utils/resolveResourceChain.js"
+    "./resource-creation": {
+      "types": "./dist/utils/resourceCreation.d.ts",
+      "import": "./dist/utils/resourceCreation.js"
     },
-    "./bind-input-role-to-resource": {
-      "types": "./dist/utils/bindInputRoleToResource.d.ts",
-      "import": "./dist/utils/bindInputRoleToResource.js"
+    "./step-creation": {
+      "types": "./dist/utils/stepCreation.d.ts",
+      "import": "./dist/utils/stepCreation.js"
+    },
+    "./tool-step-paths": {
+      "types": "./dist/utils/toolStepPaths.d.ts",
+      "import": "./dist/utils/toolStepPaths.js"
+    },
+    "./strategy-state-resolution": {
+      "types": "./dist/utils/strategyStateResolution.d.ts",
+      "import": "./dist/utils/strategyStateResolution.js"
+    },
+    "./mutable-strategy-overlay": {
+      "types": "./dist/utils/mutableStrategyOverlay.d.ts",
+      "import": "./dist/utils/mutableStrategyOverlay.js"
+    },
+    "./strategy-threading": {
+      "types": "./dist/utils/strategyThreading.d.ts",
+      "import": "./dist/utils/strategyThreading.js"
+    },
+    "./strategy-canonicalization": {
+      "types": "./dist/utils/strategyCanonicalization.d.ts",
+      "import": "./dist/utils/strategyCanonicalization.js"
     },
     "./firebase-admin-init": {
       "types": "./dist/integrations/firebase/firebaseAdminInit.d.ts",
@@ -52,7 +72,7 @@
     "@types/node": "^22.0.0"
   },
   "dependencies": {
-    "@toolproof-core/schema": "^1.0.46",
+    "@toolproof-core/genesis": "^1.0.58",
     "firebase-admin": "^13.7.0"
   },
   "scripts": {

package/src/integrations/firebase/firebaseAdminHelpers.ts

@@ -1,203 +1,80 @@
 import type {
-    CreationContext,
     Resource,
-    ResourceProvenance,
-    ResourceTypeId,
-    StepKind,
-} from '@toolproof-core/schema';
+    ResourcePointer,
+    ResourceTypeHandle,
+    TimestampedResource,
+} from '@toolproof-core/genesis';
 import type {
-    IdName,
-    IdStringByIdName,
     ResourcesByType,
 } from '../../types/types.js';
-import { CONSTANTS, MAPPINGS } from '../../artifacts/artifacts.js';
+import { CONSTANTS } from '../../lookups/lookups.js';
 import { dbAdmin, storageAdmin } from './firebaseAdminInit.js';
 
-type StepIdStringByStepKind<K extends StepKind> = string & { readonly __stepKind?: K };
-
-function capitalizeFirst(value: string): string {
-    if (!value) {
-        return value;
-    }
-
-    return value.charAt(0).toUpperCase() + value.slice(1);
-}
-
-export function getNewId<K extends IdName>(idName: K): IdStringByIdName<K> {
-    const prefix = MAPPINGS.IdNameToIdPrefix[idName];
-    const docRef = dbAdmin
-        .collection(CONSTANTS.Persistence.Collections.resources)
-        .doc(idName)
-        .collection(CONSTANTS.Persistence.Collections.members)
-        .doc();
-
-    return (prefix + docRef.id) as IdStringByIdName<K>;
-}
-
-export function getNewStepId<K extends StepKind>(stepKind: K): StepIdStringByStepKind<K> {
-    const idName = `${capitalizeFirst(stepKind)}StepId` as IdName;
-
-    if (!(idName in MAPPINGS.IdNameToIdPrefix)) {
-        throw new Error(`No IdNameToIdPrefix entry for derived step id name: ${idName}`);
-    }
-
-    return getNewId(idName) as StepIdStringByStepKind<K>;
-}
 
 export async function listResources(
-    resourceTypeIds: ResourceTypeId[],
+    resourceTypeHandles: ResourceTypeHandle[],
 ): Promise<ResourcesByType> {
-    const bucketResources = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_resources);
-    const bucketStrategies = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_strategies);
+    const resourcesBucket = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_resources);
+    const strategiesBucket = storageAdmin.bucket(CONSTANTS.Persistence.Buckets.tp_strategies);
+
+    async function fetchTimestampedMetadataUnder(
+        resourceTypeHandle: ResourceTypeHandle,
+    ): Promise<ResourcePointer[]> {
+        const snapshot = await dbAdmin
+            .collection(CONSTANTS.Persistence.Collections.resources)
+            .doc(resourceTypeHandle)
+            .collection(CONSTANTS.Persistence.Collections.members)
+            .get();
+
+        return snapshot.docs.map((doc) => {
+            const data = doc.data() as Partial<TimestampedResource>;
+            if (
+                typeof data.id !== 'string' ||
+                typeof data.resourceTypeHandle !== 'string' ||
+                !data.provenance ||
+                typeof data.provenance !== 'object' ||
+                typeof data.provenance.provenanceKind !== 'string'
+            ) {
+                throw new Error(`Invalid TimestampedResource document for ${resourceTypeHandle}/${doc.id}`);
+            }
 
-    async function fetchFilesUnder(
-        resourceTypeId: ResourceTypeId,
-    ): Promise<Array<{ data: unknown; meta: any; name: string }>> {
-        const bucket = resourceTypeId === CONSTANTS.Cosmos.TYPE_ThreadedStrategy
-            ? bucketStrategies
-            : bucketResources;
-        const prefix = `${resourceTypeId}/`;
-        const [found] = await bucket.getFiles({ prefix });
-        const files = found.filter((file) => {
-            const name = file.name || '';
-            return !!name && !name.endsWith('/');
+            return {
+                id: data.id,
+                resourceTypeHandle: data.resourceTypeHandle,
+                provenance: data.provenance,
+            } as ResourcePointer;
         });
+    }
 
-        if (!files.length) {
-            return [];
+    async function fetchProjection(
+        resourceTypeHandle: ResourceTypeHandle,
+        resourceId: ResourcePointer['id'],
+    ): Promise<unknown> {
+        const bucket = resourceTypeHandle === CONSTANTS.Handles.ResourceTypes.TYPE_Strategy
+            ? strategiesBucket
+            : resourcesBucket;
+        const file = bucket.file(`${resourceTypeHandle}/${resourceId}`);
+        const [exists] = await file.exists();
+        if (!exists) {
+            throw new Error(`Missing projection blob for ${resourceTypeHandle}/${resourceId}`);
         }
 
-        const items = await Promise.all(files.map(async (file) => {
-            try {
-                const [buf] = await file.download();
-                const meta = file.metadata || (await file.getMetadata())[0];
-                const data = JSON.parse(buf.toString('utf8')) as unknown;
-                return { data, meta, name: file.name };
-            } catch {
-                return null as unknown as { data: unknown; meta: any; name: string };
-            }
-        }));
-
-        return items.filter(Boolean) as Array<{ data: unknown; meta: any; name: string }>;
+        const [buf] = await file.download();
+        return JSON.parse(buf.toString('utf8')) as unknown;
     }
 
     const entries = await Promise.all(
-        resourceTypeIds.map(async (resourceTypeId) => {
-            const rows = await fetchFilesUnder(resourceTypeId);
-            const items: Resource[] = rows.map(({ data, meta, name }) => {
-                const flat = meta?.metadata ?? {};
-                const root: any = {};
-
-                for (const [key, valueRaw] of Object.entries(flat)) {
-                    if (typeof valueRaw !== 'string') {
-                        continue;
-                    }
-
-                    const valueString = valueRaw.trim();
-                    let value: any = valueString;
-
-                    if ((valueString.startsWith('{') && valueString.endsWith('}')) || (valueString.startsWith('[') && valueString.endsWith(']'))) {
-                        try {
-                            value = JSON.parse(valueString);
-                        } catch {
-                            value = valueString;
-                        }
-                    }
-
-                    const segments = key.split('.');
-                    let cursor = root;
-
-                    for (const [index, segment] of segments.entries()) {
-                        const arrIdxMatch = segment.match(/^(.*)\[(\d+)\]$/);
-
-                        if (arrIdxMatch) {
-                            const base = arrIdxMatch[1];
-                            const idxStr = arrIdxMatch[2];
-
-                            if (base === undefined || idxStr === undefined) {
-                                continue;
-                            }
-
-                            const idx = parseInt(idxStr, 10);
-
-                            if (!cursor[base] || !Array.isArray(cursor[base])) {
-                                cursor[base] = [];
-                            }
-
-                            while (cursor[base].length <= idx) {
-                                cursor[base].push(undefined);
-                            }
-
-                            if (index === segments.length - 1) {
-                                cursor[base][idx] = value;
-                            } else {
-                                if (!cursor[base][idx]) {
-                                    cursor[base][idx] = {};
-                                }
-                                cursor = cursor[base][idx];
-                            }
-                        } else {
-                            if (index === segments.length - 1) {
-                                cursor[segment] = value;
-                            } else {
-                                if (!cursor[segment] || typeof cursor[segment] !== 'object') {
-                                    cursor[segment] = {};
-                                }
-                                cursor = cursor[segment];
-                            }
-                        }
-                    }
-                }
-
-                const id = root.id;
-                const provenance = root.provenance as ResourceProvenance | undefined;
-                const versionRaw = root.version;
-                const version = typeof versionRaw === 'number'
-                    ? versionRaw
-                    : parseInt(String(versionRaw ?? ''), 10);
-                const resourcePath = root.path;
-                const timestamp = root.timestamp;
-
-                const missing = [
-                    ['id', id],
-                    ['version', Number.isFinite(version) ? String(version) : ''],
-                    ['timestamp', timestamp],
-                    ['path', resourcePath],
-                ].filter(([_, value]) => typeof value !== 'string' || (value as string).length === 0) as Array<[string, string | undefined]>;
-
-                if (missing.length) {
-                    const keys = missing.map(([key]) => key).join(', ');
-                    throw new Error(`Missing required metadata keys [${keys}] for resource file: ${name}`);
-                }
-
-                if (!provenance || typeof provenance !== 'object' || typeof provenance.resourceProvenanceKind !== 'string') {
-                    throw new Error(`Missing required metadata key [provenance] for resource file: ${name}`);
-                }
-
-                if (provenance.resourceProvenanceKind === 'strategy') {
-                    const creationContext = (provenance as { creationContext?: CreationContext }).creationContext;
-                    if (
-                        !creationContext ||
-                        typeof creationContext !== 'object' ||
-                        typeof creationContext.roleName !== 'string' ||
-                        typeof creationContext.toolStepPath !== 'string'
-                    ) {
-                        throw new Error(`Missing required strategy provenance creationContext for resource file: ${name}`);
-                    }
-                }
-
+        resourceTypeHandles.map(async (resourceTypeHandle) => {
+            const pointers = await fetchTimestampedMetadataUnder(resourceTypeHandle);
+            const items: Resource[] = await Promise.all(pointers.map(async (resourcePointer) => {
+                const projection = await fetchProjection(resourceTypeHandle, resourcePointer.id);
                 return {
-                    id,
-                    resourceTypeId,
-                    provenance,
-                    version,
-                    timestamp: timestamp as string,
-                    path: resourcePath as string,
-                    nucleus: data as any,
-                } as unknown as Resource;
-            });
+                    ...resourcePointer,
+                    projection,
+                };
+            }));
 
-            return [resourceTypeId, items] as const;
+            return [resourceTypeHandle, items] as const;
         }),
     );
 

package/src/lookups/lookups.ts

@@ -0,0 +1,35 @@
+import { CONSTANTS as _CONSTANTS, MAPPINGS as _MAPPINGS } from '@toolproof-core/genesis';
+
+export const CONSTANTS = {
+    ..._CONSTANTS,
+    Persistence: {
+        Buckets: {
+            tp_resources: 'tp-resources' as const,
+            tp_strategies: 'tp-strategies' as const,
+        },
+        Collections: {
+            resources: 'resources' as const,
+            members: 'members' as const,
+        },
+    },
+    Engine: {
+        Graphs: {
+            GraphRunStrategy: 'GraphRunStrategy' as const,
+            GraphBuildStrategy: 'GraphBuildStrategy' as const,
+        },
+    },
+    Cosmos: {
+        ErrorOutputRoleName: 'ErrorOutput' as const,
+    }
+} as const;
+
+export const MAPPINGS = {
+    ..._MAPPINGS,
+    IdentifierNameToPrefix: {
+        ..._MAPPINGS.IdentifierNameToPrefix,
+        ToolStepKey: 'TOOL_STEP-',
+        BranchStepKey: 'BRANCH_STEP-',
+        WhileStepKey: 'WHILE_STEP-',
+        ForStepKey: 'FOR_STEP-',
+    },
+} as const;

package/src/types/types.ts

@@ -1,30 +1,33 @@
 import type {
-    StepKind,
     Resource,
-    ResourceTypeId,
-} from '@toolproof-core/schema';
-import { CONSTANTS } from '../artifacts/artifacts.js';
-import { MAPPINGS } from '../artifacts/artifacts.js';
+    ResourceTypeHandle,
+} from '@toolproof-core/genesis/types';
+import { CONSTANTS } from '../lookups/lookups.js';
+import { MAPPINGS } from '../lookups/lookups.js';
 
-export type Bucket = typeof CONSTANTS.Persistence.Buckets.tp_resources;
+export type Bucket = keyof typeof CONSTANTS.Persistence.Buckets;
 
 export type Collection = keyof typeof CONSTANTS.Persistence.Collections;
 
 export type SchemaLike = Record<string, unknown>;
 
-export type ResourcesByType = Record<ResourceTypeId, Resource[]>;
+export type ResourcesByType = Record<ResourceTypeHandle, Resource[]>;
 
-export type IdName = keyof typeof MAPPINGS.IdNameToIdPrefix;
+export type IdentifierName = keyof typeof MAPPINGS.IdentifierNameToPrefix;
 
-export type IdStringByIdName<K extends IdName> = `${(typeof MAPPINGS.IdNameToIdPrefix)[K]}${string}`;
+export type IdentifierStringByName<K extends IdentifierName> = `${(typeof MAPPINGS.IdentifierNameToPrefix)[K]}${string}`;
 
-export type StepIdStringByStepKind<K extends StepKind> = string & { readonly __stepKind?: K };
+export type ItemKey = string;
 
-export interface NucleusBaseSmall<T extends string = string> {
-    id: T;
+export type BaseItem = {
+    itemKey: ItemKey;
 }
 
-export interface NucleusBaseLarge<T extends string = string> extends NucleusBaseSmall<T> {
+export type DocumentedBaseItem = BaseItem & { // ATTENTION: reuse ontology concept
     name: string;
     description: string;
+}
+
+export type Item = DocumentedBaseItem & {
+    label: string;
 }

package/src/utils/cosmosDataExtraction.ts

@@ -0,0 +1,25 @@
+import type { Resource, TimestampedResource } from '@toolproof-core/genesis';
+
+
+export function timestampedResourceToResource(timestampedResource: TimestampedResource): Resource {
+    const { timestamp: _timestamp, ...resource } = timestampedResource;
+    return resource;
+}
+
+export function extractProjectionMapByHandle<TKey extends string, TProjection extends { handle: TKey }>(
+    resources: Resource[] | undefined,
+): Map<TKey, TProjection> {
+    const map = new Map<TKey, TProjection>();
+
+    for (const resource of resources ?? []) {
+        const projection = resource.projection as (TProjection & { handle?: TKey }) | null;
+
+        if (!projection || typeof projection !== 'object' || !projection.handle) {
+            continue;
+        }
+
+        map.set(projection.handle, projection);
+    }
+
+    return map;
+}

package/src/utils/identifierGeneration.ts

@@ -0,0 +1,12 @@
+import type {
+    IdentifierName,
+    IdentifierStringByName,
+} from '../types/types.js';
+import { MAPPINGS } from '../lookups/lookups.js';
+
+export function generateIdentifier<K extends IdentifierName>(identifierName: K): IdentifierStringByName<K> {
+    const prefix = MAPPINGS.IdentifierNameToPrefix[identifierName];
+    
+
+    return (prefix + crypto.randomUUID()) as IdentifierStringByName<K>;
+}