@resourcexjs/core 2.14.1 → 2.16.0

package/dist/index.d.ts

@@ -72,18 +72,21 @@ interface RXI {
 	readonly path?: string;
 	/** Resource name */
 	readonly name: string;
-	/** Tag (version or label). Defaults to "latest" if not specified. */
+	/** Tag (mutable pointer). Defaults to "latest" if not specified. */
 	readonly tag: string;
+	/** Content digest (immutable hash, e.g., "sha256:abc123"). */
+	readonly digest?: string;
 }
 /**
 * Format RXI to locator string.
 *
-* Docker-style format: [registry/][path/]name[:tag]
+* Docker-style format: [registry/][path/]name[:tag][@digest]
 *
 * Examples:
 * - { name: "hello", tag: "latest" } → "hello" (omit :latest)
 * - { name: "hello", tag: "1.0.0" } → "hello:1.0.0"
-* - { registry: "localhost:3098", name: "hello", tag: "1.0.0" } → "localhost:3098/hello:1.0.0"
+* - { name: "hello", tag: "latest", digest: "sha256:abc" } → "hello@sha256:abc"
+* - { name: "hello", tag: "beta", digest: "sha256:abc" } → "hello:beta@sha256:abc"
 *
 * @param rxi - Resource identifier
 * @returns Locator string
@@ -113,9 +116,11 @@ interface RXMDefinition {
 }
 /**
 * RXM Archive — packaging metadata.
-* Placeholder for future fields (digest, size, md5, etc.)
 */
-type RXMArchive = {};
+interface RXMArchive {
+	/** Deterministic content digest computed from file-level digests. Format: sha256:<hex> */
+	readonly digest?: string;
+}
 /**
 * File entry with metadata.
 */
@@ -242,7 +247,7 @@ interface TypeDetectionResult {
 	readonly type: string;
 	/** Detected resource name */
 	readonly name: string;
-	/** Tag/version (defaults to "latest" if not provided) */
+	/** Tag (defaults to "latest" if not provided) */
 	readonly tag?: string;
 	/** Description extracted from content */
 	readonly description?: string;
@@ -293,6 +298,17 @@ interface TypeDetector {
 */
 declare function generateDefinition(result: TypeDetectionResult): RXD;
 /**
+* PrototypeDetector - Detects prototype resources from prototype.json.
+*
+* Pattern:
+* - Required: prototype.json file
+* - Optional: *.feature files (referenced via @filename)
+*/
+declare class PrototypeDetector implements TypeDetector {
+	readonly name = "prototype";
+	detect(files: Record<string, Buffer>, source: string): TypeDetectionResult | null;
+}
+/**
 * ResourceJsonDetector - Detects resources with an explicit resource.json.
 *
 * Highest-priority detector. When resource.json exists,
@@ -330,7 +346,8 @@ declare class SkillDetector implements TypeDetector {
 * Detection order:
 * 1. ResourceJsonDetector (explicit resource.json always wins)
 * 2. SkillDetector (SKILL.md pattern)
-* 3. Custom detectors (registered in order)
+* 3. PrototypeDetector (prototype.json pattern)
+* 4. Custom detectors (registered in order)
 */
 declare class TypeDetectorChain {
 	private readonly detectors;
@@ -415,21 +432,6 @@ interface SourceLoader {
 	* @throws ResourceXError if loading fails
 	*/
 	load(source: string): Promise<RXS>;
-	/**
-	* Check if cached content for this source is still fresh.
-	*
-	* Each loader implements its own strategy:
-	* - FolderSourceLoader: compare file mtime against cachedAt
-	* - GitHubSourceLoader: not implemented (always stale)
-	*
-	* Loaders that don't implement this are treated as always stale,
-	* causing a full reload on every ingest.
-	*
-	* @param source - Source path or identifier
-	* @param cachedAt - When the resource was last cached
-	* @returns true if cache is still fresh, false if stale
-	*/
-	isFresh?(source: string, cachedAt: Date): Promise<boolean>;
 }
 /**
 * Default ResourceLoader implementation for loading resources from folders.
@@ -446,8 +448,8 @@ interface SourceLoader {
 * {
 *   "name": "resource-name",      // required
 *   "type": "text",               // required
-*   "version": "1.0.0",           // required
-*   "domain": "localhost",        // optional, defaults to "localhost"
+*   "tag": "1.0.0",              // optional, defaults to "latest"
+*   "registry": "localhost",      // optional
 *   "path": "optional/path"       // optional
 * }
 * ```
@@ -473,15 +475,6 @@ declare class FolderSourceLoader implements SourceLoader {
 	canLoad(source: string): Promise<boolean>;
 	load(source: string): Promise<RXS>;
 	/**
-	* Check if cached content is still fresh by comparing file mtimes.
-	* Returns true only if no file in the directory has been modified since cachedAt.
-	*/
-	isFresh(source: string, cachedAt: Date): Promise<boolean>;
-	/**
-	* Get the most recent mtime across all files in a folder (recursive).
-	*/
-	private getMaxMtime;
-	/**
 	* Recursively read all files in a folder.
 	*/
 	private readFolderFiles;
@@ -584,17 +577,6 @@ declare class SourceLoaderChain {
 	* @throws ResourceXError if no loader matches
 	*/
 	load(source: string): Promise<RXS>;
-	/**
-	* Check if cached content for a source is still fresh.
-	*
-	* Delegates to the matching loader's isFresh method.
-	* Returns false if the loader doesn't implement isFresh (always reload).
-	*
-	* @param source - Source path or identifier
-	* @param cachedAt - When the resource was last cached
-	* @returns true if cache is still fresh
-	*/
-	isFresh(source: string, cachedAt: Date): Promise<boolean>;
 }
 /**
 * Configuration for resolveSource.
@@ -684,6 +666,7 @@ interface StoredRXM {
 	readonly license?: string;
 	readonly keywords?: string[];
 	readonly repository?: string;
+	readonly digest?: string;
 	readonly files: Record<string, string>;
 	readonly createdAt?: Date;
 	readonly updatedAt?: Date;
@@ -778,19 +761,6 @@ interface ProviderStores {
 	rxmStore: RXMStore;
 }
 /**
-* Resource loader interface for loading from directories/archives.
-*/
-interface ResourceLoader2 {
-	/**
-	* Check if this loader can handle the given source.
-	*/
-	canLoad(source: string): boolean | Promise<boolean>;
-	/**
-	* Load resource from source.
-	*/
-	load(source: string): Promise<unknown>;
-}
-/**
 * Platform-specific defaults resolved from environment variables and config files.
 */
 interface ProviderDefaults {
@@ -823,11 +793,6 @@ interface ResourceXProvider {
 	*/
 	createStores(config: ProviderConfig): ProviderStores;
 	/**
-	* Create resource loader (optional).
-	* Not all platforms support loading from filesystem.
-	*/
-	createLoader?(config: ProviderConfig): ResourceLoader2;
-	/**
 	* Create source loader for auto-detection pipeline (optional).
 	*/
 	createSourceLoader?(config: ProviderConfig): SourceLoader;
@@ -915,8 +880,9 @@ interface Registry {
 	get(rxi: RXI): Promise<RXR>;
 	/**
 	* Store resource.
+	* @returns The stored manifest (with computed digest).
 	*/
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	/**
 	* Check if resource exists.
 	*/
@@ -936,7 +902,7 @@ declare class CASRegistry implements Registry {
 	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
 	private resolveTag;
 	get(rxi: RXI): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -994,7 +960,7 @@ declare class LinkedRegistry implements Registry {
 	* Put is not typically used for LinkedRegistry.
 	* Use link() instead to create symlinks.
 	*/
-	put(_rxr: RXR): Promise<void>;
+	put(_rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -1030,7 +996,7 @@ declare abstract class RegistryMiddleware implements Registry {
 	protected readonly inner: Registry;
 	constructor(inner: Registry);
 	get(rxi: RXI): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
+	put(rxr: RXR): Promise<RXM>;
 	has(rxi: RXI): Promise<boolean>;
 	remove(rxi: RXI): Promise<void>;
 	list(options?: SearchOptions): Promise<RXI[]>;
@@ -1129,7 +1095,7 @@ interface ResolveContext {
 		path?: string
 		name: string
 		type: string
-		version: string
+		tag: string
 	};
 	/**
 	* Extracted files from archive.
@@ -1265,6 +1231,14 @@ declare const jsonType: BundledType;
 */
 declare const binaryType: BundledType;
 /**
+* Skill content (SKILL.md + optional references)
+*/
+declare const skillType: BundledType;
+/**
+* Prototype instruction set (prototype.json + @filename references)
+*/
+declare const prototypeType: BundledType;
+/**
 * All built-in types as an array.
 */
 declare const builtinTypes: BundledType[];
@@ -1337,4 +1311,4 @@ declare class TypeHandlerChain {
 	*/
 	clear(): void;
 }
-export { wrap, withDomainValidation, textType, resource, resolveSource, parse, manifest, locate, loadResource, jsonType, isValidDigest, generateDefinition, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, TypeDetectorChain, TypeDetector, TypeDetectionResult, StoredRXM, SourceLoaderChain, SourceLoader, SkillDetector, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResourceJsonDetector, ResolvedResource, ResolveSourceConfig, ResolveContext, RegistryMiddleware, RegistryError, RegistryEntry, Registry, RXS, RXR, RXMStore, RXMSource, RXMSearchOptions, RXMDefinition, RXMArchive, RXM, RXL, RXI, RXD, RXAStore, RXA, ProviderStores, ProviderDefaults, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, GitHubSourceLoader, FolderSourceLoader, FolderLoader, FileTree, FileEntry, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };
+export { wrap, withDomainValidation, textType, skillType, resource, resolveSource, prototypeType, parse, manifest, locate, loadResource, jsonType, isValidDigest, generateDefinition, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, TypeDetectorChain, TypeDetector, TypeDetectionResult, StoredRXM, SourceLoaderChain, SourceLoader, SkillDetector, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResourceJsonDetector, ResolvedResource, ResolveSourceConfig, ResolveContext, RegistryMiddleware, RegistryError, RegistryEntry, Registry, RXS, RXR, RXMStore, RXMSource, RXMSearchOptions, RXMDefinition, RXMArchive, RXM, RXL, RXI, RXD, RXAStore, RXA, ProviderStores, ProviderDefaults, ProviderConfig, PrototypeDetector, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, GitHubSourceLoader, FolderSourceLoader, FolderLoader, FileTree, FileEntry, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };

package/dist/index.js

@@ -14597,7 +14597,6 @@ var RXDSchema = exports_external.object({
   name: exports_external.string().min(1).max(128),
   type: exports_external.string().min(1).max(64),
   tag: exports_external.string().max(64).optional(),
-  version: exports_external.string().max(64).optional(),
   registry: exports_external.string().max(256).optional(),
   path: exports_external.string().max(256).optional(),
   description: exports_external.string().max(1024).optional(),
@@ -14619,7 +14618,7 @@ function define(input) {
   const rxd = Object.assign(Object.create(null), {
     name: validated.name,
     type: validated.type,
-    tag: validated.tag ?? validated.version ?? undefined,
+    tag: validated.tag ?? undefined,
     registry: validated.registry,
     path: validated.path,
     description: validated.description,
@@ -14659,6 +14658,9 @@ function format(rxi) {
   if (rxi.tag && rxi.tag !== "latest") {
     result += `:${rxi.tag}`;
   }
+  if (rxi.digest) {
+    result += `@${rxi.digest}`;
+  }
   return result;
 }
 // src/model/locate.ts
@@ -14737,15 +14739,25 @@ function parse5(locator) {
     throw new LocatorError("Locator must be a non-empty string", locator);
   }
   validateLocatorSecurity(locator);
-  if (locator.includes("@")) {
-    throw new LocatorError("Invalid locator format. Use name:tag instead of name@version", locator);
+  let digest;
+  let locatorWithoutDigest = locator;
+  const atIndex = locator.indexOf("@");
+  if (atIndex !== -1) {
+    if (atIndex === 0) {
+      throw new LocatorError("Invalid locator format. Name is required before @", locator);
+    }
+    digest = locator.substring(atIndex + 1);
+    locatorWithoutDigest = locator.substring(0, atIndex);
+    if (!digest || digest.includes("@")) {
+      throw new LocatorError("Invalid digest format after @", locator);
+    }
   }
-  const lastSlashIndex = locator.lastIndexOf("/");
+  const lastSlashIndex = locatorWithoutDigest.lastIndexOf("/");
   let beforeSlash = "";
-  let afterSlash = locator;
+  let afterSlash = locatorWithoutDigest;
   if (lastSlashIndex !== -1) {
-    beforeSlash = locator.substring(0, lastSlashIndex);
-    afterSlash = locator.substring(lastSlashIndex + 1);
+    beforeSlash = locatorWithoutDigest.substring(0, lastSlashIndex);
+    afterSlash = locatorWithoutDigest.substring(lastSlashIndex + 1);
   }
   const colonIndex = afterSlash.lastIndexOf(":");
   let name;
@@ -14768,7 +14780,8 @@ function parse5(locator) {
       registry: undefined,
       path: undefined,
       name,
-      tag
+      tag,
+      digest
     };
   }
   const parts = beforeSlash.split("/");
@@ -14779,14 +14792,16 @@ function parse5(locator) {
       registry: registry2,
       path,
       name,
-      tag
+      tag,
+      digest
     };
   }
   return {
     registry: undefined,
     path: beforeSlash,
     name,
-    tag
+    tag,
+    digest
   };
 }
 // src/model/resource.ts
@@ -14844,6 +14859,23 @@ function generateDefinition(result) {
     input.repository = result.repository;
   return define(input);
 }
+// src/detector/PrototypeDetector.ts
+import { basename } from "node:path";
+
+class PrototypeDetector {
+  name = "prototype";
+  detect(files, source) {
+    if (!files["prototype.json"]) {
+      return null;
+    }
+    const name = basename(source);
+    return {
+      type: "prototype",
+      name,
+      description: `Prototype instruction set: ${name}`
+    };
+  }
+}
 // src/detector/ResourceJsonDetector.ts
 class ResourceJsonDetector {
   name = "resource-json";
@@ -14864,7 +14896,7 @@ class ResourceJsonDetector {
     return {
       type: json2.type,
       name: json2.name,
-      tag: json2.tag ?? json2.version ?? undefined,
+      tag: json2.tag,
       description: json2.description,
       registry: json2.registry,
       path: json2.path,
@@ -14877,7 +14909,7 @@ class ResourceJsonDetector {
   }
 }
 // src/detector/SkillDetector.ts
-import { basename } from "node:path";
+import { basename as basename2 } from "node:path";
 
 class SkillDetector {
   name = "skill";
@@ -14885,7 +14917,7 @@ class SkillDetector {
     if (!files["SKILL.md"]) {
       return null;
     }
-    const name = basename(source);
+    const name = basename2(source);
     const content = files["SKILL.md"].toString("utf-8");
     const description = this.extractDescription(content);
     return {
@@ -14914,6 +14946,7 @@ class TypeDetectorChain {
     const chain = new TypeDetectorChain;
     chain.detectors.push(new ResourceJsonDetector);
     chain.detectors.push(new SkillDetector);
+    chain.detectors.push(new PrototypeDetector);
     return chain;
   }
   register(detector) {
@@ -15008,31 +15041,6 @@ class FolderSourceLoader {
     const files = await this.readFolderFiles(source);
     return { source, files };
   }
-  async isFresh(source, cachedAt) {
-    try {
-      const maxMtime = await this.getMaxMtime(source);
-      return maxMtime <= cachedAt;
-    } catch {
-      return false;
-    }
-  }
-  async getMaxMtime(folderPath) {
-    let max = new Date(0);
-    const entries = await readdir2(folderPath, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join2(folderPath, entry.name);
-      if (entry.isFile()) {
-        const stats = await stat2(fullPath);
-        if (stats.mtime > max)
-          max = stats.mtime;
-      } else if (entry.isDirectory()) {
-        const subMax = await this.getMaxMtime(fullPath);
-        if (subMax > max)
-          max = subMax;
-      }
-    }
-    return max;
-  }
   async readFolderFiles(folderPath, basePath = folderPath) {
     const files = {};
     const entries = await readdir2(folderPath, { withFileTypes: true });
@@ -15154,17 +15162,6 @@ class SourceLoaderChain {
     }
     throw new ResourceXError(`Cannot load source: ${source}`);
   }
-  async isFresh(source, cachedAt) {
-    for (const loader of this.loaders) {
-      if (await loader.canLoad(source)) {
-        if (loader.isFresh) {
-          return loader.isFresh(source, cachedAt);
-        }
-        return false;
-      }
-    }
-    return false;
-  }
 }
 
 // src/loader/resolveSource.ts
@@ -15278,6 +15275,22 @@ function withRegistryValidation(registry2, trustedRegistry) {
 }
 var DomainValidation = RegistryValidation;
 var withDomainValidation = withRegistryValidation;
+// src/registry/store/digest.ts
+import { createHash } from "node:crypto";
+function computeDigest(data) {
+  const hash2 = createHash("sha256").update(data).digest("hex");
+  return `sha256:${hash2}`;
+}
+function computeArchiveDigest(files) {
+  const entries = Object.keys(files).sort().map((name) => `${name}:${files[name]}`).join(`
+`);
+  const hash2 = createHash("sha256").update(entries).digest("hex");
+  return `sha256:${hash2}`;
+}
+function isValidDigest(digest) {
+  return /^sha256:[a-f0-9]{64}$/.test(digest);
+}
+
 // src/registry/registries/CASRegistry.ts
 class CASRegistry {
   rxaStore;
@@ -15320,7 +15333,9 @@ class CASRegistry {
         keywords: storedRxm.keywords,
         repository: storedRxm.repository
       },
-      archive: {},
+      archive: {
+        digest: storedRxm.digest ?? computeArchiveDigest(storedRxm.files)
+      },
       source: {}
     };
     const rxa = await archive(files);
@@ -15330,9 +15345,10 @@ class CASRegistry {
     const files = await extract(rxr.archive);
     const fileDigests = {};
     for (const [filename, content] of Object.entries(files)) {
-      const digest = await this.rxaStore.put(content);
-      fileDigests[filename] = digest;
+      const digest2 = await this.rxaStore.put(content);
+      fileDigests[filename] = digest2;
     }
+    const digest = computeArchiveDigest(fileDigests);
     const storedRxm = {
       registry: rxr.manifest.definition.registry,
       path: rxr.manifest.definition.path,
@@ -15344,12 +15360,18 @@ class CASRegistry {
       license: rxr.manifest.definition.license,
       keywords: rxr.manifest.definition.keywords,
       repository: rxr.manifest.definition.repository,
+      digest,
       files: fileDigests,
       createdAt: new Date,
       updatedAt: new Date
     };
     await this.rxmStore.put(storedRxm);
     await this.rxmStore.setLatest(rxr.manifest.definition.name, rxr.manifest.definition.tag, rxr.manifest.definition.registry);
+    return {
+      definition: rxr.manifest.definition,
+      archive: { digest },
+      source: rxr.manifest.source
+    };
   }
   async has(rxi) {
     const tag = await this.resolveTag(rxi.name, rxi.tag ?? "latest", rxi.registry);
@@ -15548,15 +15570,6 @@ class LinkedRegistry {
     }
   }
 }
-// src/registry/store/digest.ts
-import { createHash } from "node:crypto";
-function computeDigest(data) {
-  const hash2 = createHash("sha256").update(data).digest("hex");
-  return `sha256:${hash2}`;
-}
-function isValidDigest(digest) {
-  return /^sha256:[a-f0-9]{64}$/.test(digest);
-}
 // src/registry/store/MemoryRXAStore.ts
 class MemoryRXAStore {
   blobs = new Map;
@@ -15760,7 +15773,47 @@ var skill_type_default = {
     }
   }
 };
-var builtinTypes = [textType, jsonType, binaryType, skillType];
+var prototypeType = {
+  name: "prototype",
+  description: "Instruction set for materializing roles and organizations",
+  code: `// @resolver: prototype_type_default
+var prototype_type_default = {
+  async resolve(ctx) {
+    var protoFile = ctx.files["prototype.json"];
+    if (!protoFile) throw new Error("Prototype resource must contain a prototype.json file");
+    var decoder = new TextDecoder();
+    var instructions = JSON.parse(decoder.decode(protoFile));
+    if (!Array.isArray(instructions)) {
+      throw new Error("prototype.json must be a JSON array of instructions");
+    }
+    var resolved = instructions.map(function(instr) {
+      var resolvedArgs = {};
+      var keys = Object.keys(instr.args || {});
+      for (var i = 0; i < keys.length; i++) {
+        var key = keys[i];
+        var value = instr.args[key];
+        if (typeof value === "string" && value.startsWith("@")) {
+          var filename = value.slice(1);
+          var file = ctx.files[filename];
+          if (!file) throw new Error("Referenced file not found: " + filename);
+          resolvedArgs[key] = decoder.decode(file);
+        } else {
+          resolvedArgs[key] = value;
+        }
+      }
+      return { op: instr.op, args: resolvedArgs };
+    });
+    return { id: ctx.manifest.name, instructions: resolved };
+  }
+};`
+};
+var builtinTypes = [
+  textType,
+  jsonType,
+  binaryType,
+  skillType,
+  prototypeType
+];
 // src/type/bundler.ts
 import { readFile as readFile3 } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
@@ -15863,8 +15916,10 @@ export {
   wrap,
   withDomainValidation,
   textType,
+  skillType,
   resource,
   resolveSource,
+  prototypeType,
   parse5 as parse,
   manifest,
   locate,
@@ -15890,6 +15945,7 @@ export {
   ResourceJsonDetector,
   RegistryMiddleware,
   RegistryError,
+  PrototypeDetector,
   MemoryRXMStore,
   MemoryRXAStore,
   ManifestError,
@@ -15904,4 +15960,4 @@ export {
   CASRegistry
 };
 
-//# debugId=B122DF8CA052DA8364756E2164756E21
+//# debugId=0BF8A796080AFBD664756E2164756E21