@toolproof-npm/shared 0.1.76 → 0.1.77

package/dist/_lib/types.d.ts

@@ -0,0 +1,19 @@
+import type { ExecutionIdentityJson, ResourceIdentityJson, ResourceJson, ResourceRoleIdentityJson, ResourceRoleValueJson, ResourceTypeIdentityJson } from '@toolproof-npm/schema';
+import { CONSTANTS } from '../constants.js';
+export type BucketConst = typeof CONSTANTS.STORAGE.BUCKETS.tp_resources;
+export type CollectionConst = keyof typeof CONSTANTS.STORAGE.COLLECTIONS;
+export type TerminalConst = keyof typeof CONSTANTS.TERMINALS;
+export type StepConst = keyof typeof CONSTANTS.STEPS;
+export type Role = {
+    identity: ResourceRoleIdentityJson;
+} & ResourceRoleValueJson;
+export type ResourceMap = Record<ResourceTypeIdentityJson, ResourceJson[]>;
+export type PartialResourceMeta = {
+    identity: ResourceIdentityJson;
+    resourceTypeRef: ResourceTypeIdentityJson;
+    creationContext: {
+        resourceRoleRef: ResourceRoleIdentityJson;
+        executionRef: ExecutionIdentityJson;
+    };
+    timestamp?: string;
+};

package/dist/_lib/types.js

@@ -0,0 +1 @@
+export {};

package/dist/_lib/utils/resourceCreation.d.ts

@@ -0,0 +1,112 @@
+import type { ResourceTypeIdentityJson, ResourceJson, ResourcePotentialOutputJson, JsonDataJson } from '@toolproof-npm/schema';
+/**
+ * Generates SHA-256 hash of content
+ * @param content The content to hash
+ * @returns The SHA-256 hash as hex string
+ */
+export declare function generateContentHash(content: string): string;
+/**
+ * Generates a content-addressed path for a resource
+ * @param resourceTypeRef The resource type reference
+ * @param content The content to hash
+ * @returns The path in format: {resourceTypeRef}/{contentHash}
+ */
+export declare function generateContentAddressedPath(resourceTypeRef: ResourceTypeIdentityJson, content: string): string;
+/**
+ * Options for creating a materialized resource from a potential-output
+ * Provide either 'path' OR 'content' (which generates a hash-based path)
+ */
+export type CreateMaterializedResourceOptions = Pick<ResourceJson, 'extractedData'> & {
+    /** Explicit path (if provided, content is ignored) */
+    path?: string;
+    /** Content to hash for generating path (used if path not provided) */
+    content?: string;
+    /** Optional timestamp (defaults to current ISO timestamp) */
+    timestamp?: string;
+};
+/**
+ * Options for creating a materialized resource from scratch
+ * Provide either 'path' OR 'content' (which generates a hash-based path)
+ * Omits 'kind' (always set to 'materialized') and makes 'timestamp' optional
+ */
+export type CreateMaterializedResourceFromScratchOptions = Omit<ResourceJson, 'kind' | 'timestamp' | 'path'> & {
+    /** Explicit path (if provided, content is ignored) */
+    path?: string;
+    /** Content to hash for generating path (used if path not provided) */
+    content?: string;
+    /** Optional timestamp (defaults to current ISO timestamp) */
+    timestamp?: string;
+};
+/**
+ * Creates a materialized resource from a potential-output resource.
+ * Handles timestamp generation, extractedData normalization, path generation, and structural conversion.
+ *
+ * @param potentialOutput The potential-output resource to materialize
+ * @param options Configuration for the materialized resource
+ * @returns A fully materialized ResourceJson
+ *
+ * @example
+ * ```typescript
+ * // With explicit path
+ * const materialized = createMaterializedResource(potentialOutput, {
+ *   path: 'TYPE-Natural/abc123...',
+ *   extractedData: { identity: 42 },
+ *   timestamp: '2025-01-03T12:00:00.000Z'
+ * });
+ *
+ * // With content (generates hash-based path)
+ * const materialized = createMaterializedResource(potentialOutput, {
+ *   content: '{"identity": 42}',
+ *   extractedData: { identity: 42 }
+ * });
+ * ```
+ */
+export declare function createMaterializedResource(potentialOutput: ResourcePotentialOutputJson, options: CreateMaterializedResourceOptions): ResourceJson;
+/**
+ * Normalizes extractedData to ensure consistent structure with an identity field.
+ * Handles various input formats:
+ * - Primitives (numbers, strings): wrapped in { identity: value }
+ * - Objects with identity: preserved
+ * - Objects without identity: identity extracted from first suitable field
+ *
+ * @param data The raw extracted data
+ * @returns Normalized extractedData with identity field
+ */
+export declare function normalizeExtractedData(data: JsonDataJson): JsonDataJson;
+/**
+ * Creates a materialized resource from scratch (for manual resource creation).
+ * Handles timestamp generation, extractedData normalization, path generation, and structural validation.
+ * Use this when creating resources manually without a potential-output template.
+ *
+ * @param options All required fields for creating a materialized resource
+ * @returns A fully materialized ResourceJson
+ *
+ * @example
+ * ```typescript
+ * // With explicit path
+ * const materialized = createMaterializedResourceFromScratch({
+ *   identity: 'RESOURCE-abc123',
+ *   resourceTypeRef: 'TYPE-Natural',
+ *   creationContext: {
+ *     resourceRoleRef: 'ROLE-Manual',
+ *     executionRef: 'EXECUTION-Genesis'
+ *   },
+ *   path: 'TYPE-Natural/def456...',
+ *   extractedData: { identity: 42 },
+ *   timestamp: '2025-01-03T12:00:00.000Z'
+ * });
+ *
+ * // With content (generates hash-based path)
+ * const materialized = createMaterializedResourceFromScratch({
+ *   identity: 'RESOURCE-abc123',
+ *   resourceTypeRef: 'TYPE-Natural',
+ *   creationContext: {
+ *     resourceRoleRef: 'ROLE-Manual',
+ *     executionRef: 'EXECUTION-Genesis'
+ *   },
+ *   content: '{"identity": 42}',
+ *   extractedData: { identity: 42 }
+ * });
+ * ```
+ */
+export declare function createMaterializedResourceFromScratch(options: CreateMaterializedResourceFromScratchOptions): ResourceJson;

package/dist/_lib/utils/resourceCreation.js

@@ -0,0 +1,146 @@
+import { createHash } from 'crypto';
+/**
+ * Generates SHA-256 hash of content
+ * @param content The content to hash
+ * @returns The SHA-256 hash as hex string
+ */
+export function generateContentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Generates a content-addressed path for a resource
+ * @param resourceTypeRef The resource type reference
+ * @param content The content to hash
+ * @returns The path in format: {resourceTypeRef}/{contentHash}
+ */
+export function generateContentAddressedPath(resourceTypeRef, content) {
+    const contentHash = generateContentHash(content);
+    return `${resourceTypeRef}/${contentHash}`;
+}
+/**
+ * Creates a materialized resource from a potential-output resource.
+ * Handles timestamp generation, extractedData normalization, path generation, and structural conversion.
+ *
+ * @param potentialOutput The potential-output resource to materialize
+ * @param options Configuration for the materialized resource
+ * @returns A fully materialized ResourceJson
+ *
+ * @example
+ * ```typescript
+ * // With explicit path
+ * const materialized = createMaterializedResource(potentialOutput, {
+ *   path: 'TYPE-Natural/abc123...',
+ *   extractedData: { identity: 42 },
+ *   timestamp: '2025-01-03T12:00:00.000Z'
+ * });
+ *
+ * // With content (generates hash-based path)
+ * const materialized = createMaterializedResource(potentialOutput, {
+ *   content: '{"identity": 42}',
+ *   extractedData: { identity: 42 }
+ * });
+ * ```
+ */
+export function createMaterializedResource(potentialOutput, options) {
+    const { path, content, extractedData, timestamp } = options;
+    // Determine path: use explicit path or generate from content
+    const finalPath = path ?? (content ? generateContentAddressedPath(potentialOutput.resourceTypeRef, content) : '');
+    if (!finalPath) {
+        throw new Error('Either path or content must be provided');
+    }
+    // Normalize extractedData to ensure it has an identity field
+    const normalizedExtractedData = normalizeExtractedData(extractedData);
+    return {
+        identity: potentialOutput.identity,
+        resourceTypeRef: potentialOutput.resourceTypeRef,
+        creationContext: potentialOutput.creationContext,
+        kind: 'materialized',
+        path: finalPath,
+        timestamp: timestamp ?? new Date().toISOString(),
+        extractedData: normalizedExtractedData,
+    };
+}
+/**
+ * Normalizes extractedData to ensure consistent structure with an identity field.
+ * Handles various input formats:
+ * - Primitives (numbers, strings): wrapped in { identity: value }
+ * - Objects with identity: preserved
+ * - Objects without identity: identity extracted from first suitable field
+ *
+ * @param data The raw extracted data
+ * @returns Normalized extractedData with identity field
+ */
+export function normalizeExtractedData(data) {
+    // If data is a primitive, wrap it
+    if (typeof data !== 'object' || data === null) {
+        return { identity: data };
+    }
+    // If data is an object
+    const dataObj = data;
+    // If it already has an identity field, preserve everything
+    if ('identity' in dataObj) {
+        return data;
+    }
+    // Otherwise, try to extract an identity value from common patterns
+    // This handles cases where the data might have a value field or similar
+    const identityValue = dataObj.value ?? dataObj.id ?? dataObj.result ?? 0;
+    return {
+        identity: identityValue,
+        ...dataObj,
+    };
+}
+/**
+ * Creates a materialized resource from scratch (for manual resource creation).
+ * Handles timestamp generation, extractedData normalization, path generation, and structural validation.
+ * Use this when creating resources manually without a potential-output template.
+ *
+ * @param options All required fields for creating a materialized resource
+ * @returns A fully materialized ResourceJson
+ *
+ * @example
+ * ```typescript
+ * // With explicit path
+ * const materialized = createMaterializedResourceFromScratch({
+ *   identity: 'RESOURCE-abc123',
+ *   resourceTypeRef: 'TYPE-Natural',
+ *   creationContext: {
+ *     resourceRoleRef: 'ROLE-Manual',
+ *     executionRef: 'EXECUTION-Genesis'
+ *   },
+ *   path: 'TYPE-Natural/def456...',
+ *   extractedData: { identity: 42 },
+ *   timestamp: '2025-01-03T12:00:00.000Z'
+ * });
+ *
+ * // With content (generates hash-based path)
+ * const materialized = createMaterializedResourceFromScratch({
+ *   identity: 'RESOURCE-abc123',
+ *   resourceTypeRef: 'TYPE-Natural',
+ *   creationContext: {
+ *     resourceRoleRef: 'ROLE-Manual',
+ *     executionRef: 'EXECUTION-Genesis'
+ *   },
+ *   content: '{"identity": 42}',
+ *   extractedData: { identity: 42 }
+ * });
+ * ```
+ */
+export function createMaterializedResourceFromScratch(options) {
+    const { identity, resourceTypeRef, creationContext, path, content, extractedData, timestamp } = options;
+    // Determine path: use explicit path or generate from content
+    const finalPath = path ?? (content ? generateContentAddressedPath(resourceTypeRef, content) : '');
+    if (!finalPath) {
+        throw new Error('Either path or content must be provided');
+    }
+    // Normalize extractedData to ensure it has an identity field
+    const normalizedExtractedData = normalizeExtractedData(extractedData);
+    return {
+        identity,
+        resourceTypeRef,
+        creationContext,
+        kind: 'materialized',
+        path: finalPath,
+        timestamp: timestamp ?? new Date().toISOString(),
+        extractedData: normalizedExtractedData,
+    };
+}

package/dist/_lib/utils/utils.d.ts

@@ -0,0 +1,24 @@
+import type { ResourceIdentityJson, ResourceTypeIdentityJson, ResourceJson, ResourceMissingJson, JobJson, ResourcePotentialOutputJson, StrategyStateJson, CreationContextJson } from '@toolproof-npm/schema';
+import type { ResourceMap } from '../types.js';
+export declare function extractResourcesByType(resourceMap: ResourceMap, resourceTypeRef: ResourceTypeIdentityJson): Record<ResourceIdentityJson, ResourceJson>;
+export declare function extractJobMap(resourceMap: ResourceMap): Map<`JOB-${string}`, JobJson>;
+export type ResolveResult = {
+    status: 'materialized';
+    entry: ResourceJson;
+    path: CreationContextJson[];
+} | {
+    status: 'missing';
+    entry: ResourceMissingJson;
+    path: CreationContextJson[];
+} | {
+    status: 'blocked-output';
+    entry: ResourcePotentialOutputJson;
+    path: CreationContextJson[];
+} | {
+    status: 'unresolved';
+    reason: 'missing-entry' | 'cycle' | 'depth-exceeded';
+    path: CreationContextJson[];
+};
+export declare function resolveResourceChain(strategyState: StrategyStateJson, start: CreationContextJson, opts?: {
+    maxDepth?: number;
+}): ResolveResult;

package/dist/_lib/utils/utils.js

@@ -0,0 +1,58 @@
+export function extractResourcesByType(resourceMap, resourceTypeRef) {
+    const resources = resourceMap[resourceTypeRef] ?? [];
+    const result = {};
+    for (const resource of resources) {
+        result[resource.identity] = resource;
+    }
+    return result;
+}
+export function extractJobMap(resourceMap) {
+    const resourceJobMap = extractResourcesByType(resourceMap, 'TYPE-Job');
+    const jobMap = new Map();
+    Object.values(resourceJobMap).forEach((resource) => {
+        if (resource.extractedData?.identity) {
+            jobMap.set(resource.extractedData.identity, resource.extractedData); // ATTENTION: why do we need type assertion here?
+        }
+    });
+    return jobMap;
+}
+export function resolveResourceChain(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.executionRef}::${current.resourceRoleRef}`;
+        if (visited.has(visitKey)) {
+            return { status: 'unresolved', reason: 'cycle', path };
+        }
+        visited.add(visitKey);
+        const bucket = strategyState[current.executionRef];
+        if (!bucket)
+            return { status: 'unresolved', reason: 'missing-entry', path };
+        const entry = bucket[current.resourceRoleRef];
+        if (!entry)
+            return { status: 'unresolved', reason: 'missing-entry', path };
+        if (entry.kind === 'materialized') {
+            return { status: 'materialized', entry: entry, path };
+        }
+        if (entry.kind === 'missing') {
+            return { status: 'missing', entry: entry, path };
+        }
+        if (entry.kind === 'potential-output') {
+            return { status: 'blocked-output', entry: entry, path };
+        }
+        // potential-input: follow ref backwards
+        if (entry.kind === 'potential-input') {
+            const rpi = entry.creationContext;
+            if (!rpi)
+                return { status: 'unresolved', reason: 'missing-entry', path };
+            current = rpi;
+            continue;
+        }
+        // Unknown case
+        return { status: 'unresolved', reason: 'missing-entry', path };
+    }
+    return { status: 'unresolved', reason: 'depth-exceeded', path };
+}

package/dist/firebaseAdminHelpers.d.ts

@@ -1,5 +1,5 @@
 import type { ResourceTypeIdentityJson } from '@toolproof-npm/schema';
-import type { StepConst, ResourceMap, TerminalConst } from './types.d.ts';
+import type { StepConst, ResourceMap, TerminalConst } from './_lib/types.js';
 export declare function getNewIdentity(identifiable: TerminalConst | StepConst): string;
 export declare function listResources(// ATTENTION: must clean up
 resourceTypeRefs: ResourceTypeIdentityJson[]): Promise<ResourceMap>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export * as CONSTANTS from './constants.js';
-export * as TYPES from './types.js';
-export * as UTILS from './utils.js';
+export * as TYPES from './_lib/types.js';
+export * as UTILS from './_lib/utils/utils.js';
 export * from './firebaseAdminHelpers.js';
 export * from './firebaseAdminInit.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export * as CONSTANTS from './constants.js';
-export * as TYPES from './types.js';
-export * as UTILS from './utils.js';
+export * as TYPES from './_lib/types.js';
+export * as UTILS from './_lib/utils/utils.js';
 export * from './firebaseAdminHelpers.js';
 export * from './firebaseAdminInit.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolproof-npm/shared",
-  "version": "0.1.76",
+  "version": "0.1.77",
   "description": "Core library utilities for ToolProof",
   "keywords": [
     "toolproof",