apcore-js 0.7.1 → 0.9.0

package/dist/utils/error-propagation.js

@@ -0,0 +1,35 @@
+/**
+ * Error propagation (Algorithm A11).
+ */
+import { ModuleError, ModuleExecuteError } from '../errors.js';
+/**
+ * Wrap a raw error into a standardized ModuleError (Algorithm A11).
+ *
+ * If the error is already a ModuleError, enriches it with trace context.
+ * Otherwise wraps it as a ModuleExecuteError.
+ *
+ * @param error - The raw error.
+ * @param moduleId - Module ID where the error occurred.
+ * @param context - Current execution context.
+ * @returns A ModuleError with traceId, moduleId, and callChain attached.
+ */
+export function propagateError(error, moduleId, context) {
+    if (error instanceof ModuleError) {
+        // Already a ModuleError -- enrich with context if missing
+        if (error.traceId === undefined) {
+            error.traceId = context.traceId;
+        }
+        if (!('module_id' in error.details)) {
+            error.details['module_id'] = moduleId;
+        }
+        if (!('call_chain' in error.details)) {
+            error.details['call_chain'] = [...context.callChain];
+        }
+        return error;
+    }
+    // Wrap raw error as ModuleExecuteError
+    const wrapped = new ModuleExecuteError(moduleId, `Module '${moduleId}' raised ${error.constructor.name}: ${error.message}`, { cause: error });
+    wrapped.details['call_chain'] = [...context.callChain];
+    return wrapped;
+}
+//# sourceMappingURL=error-propagation.js.map

package/dist/utils/error-propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-propagation.js","sourceRoot":"","sources":["../../src/utils/error-propagation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY,EAAE,QAAgB,EAAE,OAAgB;IAC7E,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,0DAA0D;QAC1D,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,KAA6B,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC3D,CAAC;QACD,IAAI,CAAC,CAAC,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC;QACxC,CAAC;QACD,IAAI,CAAC,CAAC,YAAY,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACrC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,uCAAuC;IACvC,MAAM,OAAO,GAAG,IAAI,kBAAkB,CACpC,QAAQ,EACR,WAAW,QAAQ,YAAY,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,EACzE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACF,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACvD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/index.d.ts

@@ -1,4 +1,7 @@
-export { matchPattern } from './pattern.js';
+export { matchPattern, calculateSpecificity } from './pattern.js';
+export { normalizeToCanonicalId } from './normalize.js';
+export { guardCallChain, DEFAULT_MAX_CALL_DEPTH, DEFAULT_MAX_MODULE_REPEAT } from './call-chain.js';
+export { propagateError } from './error-propagation.js';
 export declare function deepCopy<T>(obj: T): T;
 /**
  * Generate a random hex string of the given byte length.

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAM5C,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAErC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAYpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAMxD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAErC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAYpD"}

package/dist/utils/index.js

@@ -1,4 +1,7 @@
-export { matchPattern } from './pattern.js';
+export { matchPattern, calculateSpecificity } from './pattern.js';
+export { normalizeToCanonicalId } from './normalize.js';
+export { guardCallChain, DEFAULT_MAX_CALL_DEPTH, DEFAULT_MAX_MODULE_REPEAT } from './call-chain.js';
+export { propagateError } from './error-propagation.js';
 // Lazy-load node:crypto for environments without globalThis.crypto (Node.js < 19)
 let _nodeCrypto;
 try {

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,kFAAkF;AAClF,IAAI,WAAqD,CAAC;AAC1D,IAAI,CAAC;IAAC,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAAC,CAAC;AAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAEtF,MAAM,UAAU,QAAQ,CAAI,GAAM;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,IAAI,WAAW,EAAE,SAAS,CAAC;IACtD,IAAI,CAAC,EAAE,CAAC;QACN,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,yEAAyE;QACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kFAAkF;AAClF,IAAI,WAAqD,CAAC;AAC1D,IAAI,CAAC;IAAC,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAAC,CAAC;AAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAEtF,MAAM,UAAU,QAAQ,CAAI,GAAM;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,IAAI,WAAW,EAAE,SAAS,CAAC;IACtD,IAAI,CAAC,EAAE,CAAC;QACN,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,yEAAyE;QACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/utils/normalize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-language module ID normalization (Algorithm A02).
+ */
+/**
+ * Convert a language-local module ID to Canonical ID format (Algorithm A02).
+ *
+ * Steps:
+ *   1. Split by language-specific separator.
+ *   2. Normalize each segment from PascalCase/camelCase to snake_case.
+ *   3. Join with "." and validate against Canonical ID EBNF.
+ *
+ * @param localId - Language-local format ID (e.g. "executor::validator::DbParams").
+ * @param language - Source language ("python" | "rust" | "go" | "java" | "typescript").
+ * @returns Dot-separated snake_case Canonical ID.
+ * @throws {Error} If language is unsupported or the result is not a valid Canonical ID.
+ */
+export declare function normalizeToCanonicalId(localId: string, language: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkCH;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuBhF"}

package/dist/utils/normalize.js

@@ -0,0 +1,61 @@
+/**
+ * Cross-language module ID normalization (Algorithm A02).
+ */
+const SEPARATORS = {
+    python: '.',
+    rust: '::',
+    go: '.',
+    java: '.',
+    typescript: '.',
+};
+const SUPPORTED_LANGUAGES = new Set(Object.keys(SEPARATORS));
+/**
+ * Regex for splitting PascalCase / camelCase into words.
+ * Handles transitions like: "Http" | "JSON" | "Parser" | "v2".
+ */
+const CASE_BOUNDARY = /(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/g;
+/** Canonical ID format from PROTOCOL_SPEC section 2.7 EBNF grammar. */
+const CANONICAL_ID_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+function toSnakeCase(segment) {
+    if (!segment)
+        return segment;
+    // If already snake_case (all lowercase + underscores), return as-is.
+    if (segment === segment.toLowerCase() && /^[a-z_]\w*$/.test(segment)) {
+        return segment;
+    }
+    // Split at case boundaries, join with underscore, lowercase.
+    const words = segment.split(CASE_BOUNDARY).filter(Boolean);
+    return words.map((w) => w.toLowerCase()).join('_');
+}
+/**
+ * Convert a language-local module ID to Canonical ID format (Algorithm A02).
+ *
+ * Steps:
+ *   1. Split by language-specific separator.
+ *   2. Normalize each segment from PascalCase/camelCase to snake_case.
+ *   3. Join with "." and validate against Canonical ID EBNF.
+ *
+ * @param localId - Language-local format ID (e.g. "executor::validator::DbParams").
+ * @param language - Source language ("python" | "rust" | "go" | "java" | "typescript").
+ * @returns Dot-separated snake_case Canonical ID.
+ * @throws {Error} If language is unsupported or the result is not a valid Canonical ID.
+ */
+export function normalizeToCanonicalId(localId, language) {
+    if (!localId) {
+        throw new Error('localId must be a non-empty string');
+    }
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        const supported = [...SUPPORTED_LANGUAGES].sort().join(', ');
+        throw new Error(`Unsupported language '${language}'. Must be one of: ${supported}`);
+    }
+    const separator = SEPARATORS[language];
+    const segments = localId.split(separator);
+    const normalized = segments.map(toSnakeCase);
+    const canonicalId = normalized.join('.');
+    if (!CANONICAL_ID_RE.test(canonicalId)) {
+        throw new Error(`Normalized ID '${canonicalId}' (from '${localId}', language='${language}') ` +
+            'does not conform to Canonical ID grammar');
+    }
+    return canonicalId;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/utils/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,GAA2B;IACzC,MAAM,EAAE,GAAG;IACX,IAAI,EAAE,IAAI;IACV,EAAE,EAAE,GAAG;IACP,IAAI,EAAE,GAAG;IACT,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;AAE7D;;;GAGG;AACH,MAAM,aAAa,GAAG,kDAAkD,CAAC;AAEzE,uEAAuE;AACvE,MAAM,eAAe,GAAG,uCAAuC,CAAC;AAEhE,SAAS,WAAW,CAAC,OAAe;IAClC,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC;IAE7B,qEAAqE;IACrE,IAAI,OAAO,KAAK,OAAO,CAAC,WAAW,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACrE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,6DAA6D;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,QAAgB;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,CAAC,GAAG,mBAAmB,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,yBAAyB,QAAQ,sBAAsB,SAAS,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEzC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,kBAAkB,WAAW,YAAY,OAAO,gBAAgB,QAAQ,KAAK;YAC7E,0CAA0C,CAC3C,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/utils/pattern.d.ts

@@ -2,4 +2,19 @@
  * Wildcard pattern matching for module IDs (Algorithm A08).
  */
 export declare function matchPattern(pattern: string, moduleId: string): boolean;
+/**
+ * Calculate the specificity score of an ACL pattern (Algorithm A10).
+ *
+ * Higher scores indicate more specific patterns. Scoring per segment:
+ * - "*" (pure wildcard) -> 0
+ * - Segment containing "*" (partial wildcard) -> +1
+ * - Exact segment (no wildcard) -> +2
+ *
+ * @example
+ * calculateSpecificity("*")                       // 0
+ * calculateSpecificity("api.*")                   // 2
+ * calculateSpecificity("api.handler.*")           // 4
+ * calculateSpecificity("api.handler.task_submit") // 6
+ */
+export declare function calculateSpecificity(pattern: string): number;
 //# sourceMappingURL=pattern.d.ts.map

package/dist/utils/pattern.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/utils/pattern.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAyBvE"}
+{"version":3,"file":"pattern.d.ts","sourceRoot":"","sources":["../../src/utils/pattern.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAyBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAc5D"}

package/dist/utils/pattern.js

@@ -28,4 +28,35 @@ export function matchPattern(pattern, moduleId) {
     }
     return true;
 }
+/**
+ * Calculate the specificity score of an ACL pattern (Algorithm A10).
+ *
+ * Higher scores indicate more specific patterns. Scoring per segment:
+ * - "*" (pure wildcard) -> 0
+ * - Segment containing "*" (partial wildcard) -> +1
+ * - Exact segment (no wildcard) -> +2
+ *
+ * @example
+ * calculateSpecificity("*")                       // 0
+ * calculateSpecificity("api.*")                   // 2
+ * calculateSpecificity("api.handler.*")           // 4
+ * calculateSpecificity("api.handler.task_submit") // 6
+ */
+export function calculateSpecificity(pattern) {
+    if (pattern === '*')
+        return 0;
+    let score = 0;
+    for (const segment of pattern.split('.')) {
+        if (segment === '*') {
+            // +0
+        }
+        else if (segment.includes('*')) {
+            score += 1;
+        }
+        else {
+            score += 2;
+        }
+    }
+    return score;
+}
 //# sourceMappingURL=pattern.js.map

package/dist/utils/pattern.js.map

@@ -1 +1 @@
-{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../../src/utils/pattern.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAgB;IAC5D,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,KAAK,QAAQ,CAAC;IAExD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACpD,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7B,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACtE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"pattern.js","sourceRoot":"","sources":["../../src/utils/pattern.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAgB;IAC5D,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,KAAK,QAAQ,CAAC;IAExD,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACpD,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7B,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACtE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,CAAC,CAAC;IAE9B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;YACpB,KAAK;QACP,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;aAAM,CAAC;YACN,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Version negotiation (Algorithm A14).
+ */
+import { ModuleError } from './errors.js';
+import type { ErrorOptions } from './errors.js';
+export declare class VersionIncompatibleError extends ModuleError {
+    static readonly DEFAULT_RETRYABLE: boolean | null;
+    constructor(declared: string, sdk: string, reason: string, options?: ErrorOptions);
+}
+/**
+ * Negotiate the effective version between declared and SDK versions (Algorithm A14).
+ *
+ * Steps:
+ *   1. Parse both versions as semver.
+ *   2. Major mismatch -> error.
+ *   3. Declared minor > SDK minor -> error (SDK too old).
+ *   4. Declared minor < SDK minor by >2 -> deprecation warning.
+ *   5. Same minor -> effective = max(declared, sdk).
+ *
+ * @param declaredVersion - Version declared in configuration or schema.
+ * @param sdkVersion - Maximum version supported by the current SDK.
+ * @returns The effective version string.
+ * @throws {VersionIncompatibleError} When versions are incompatible.
+ * @throws {Error} When a version string is not valid semver.
+ */
+export declare function negotiateVersion(declaredVersion: string, sdkVersion: string): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiEhD,qBAAa,wBAAyB,SAAQ,WAAW;IACvD,gBAAyB,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAS;gBAEvD,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAclF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA4BpF"}

package/dist/version.js

@@ -0,0 +1,104 @@
+/**
+ * Version negotiation (Algorithm A14).
+ */
+import { ModuleError } from './errors.js';
+/** Regex for parsing semver strings (major.minor.patch with optional pre-release). */
+const SEMVER_RE = /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:-(?<pre>[0-9A-Za-z\-]+(?:\.[0-9A-Za-z\-]+)*))?$/;
+/** Deprecation warning threshold. */
+const DEPRECATION_THRESHOLD = 2;
+function parseSemver(version) {
+    const m = SEMVER_RE.exec(version.trim());
+    if (!m || !m.groups) {
+        throw new Error(`Invalid semantic version: '${version}'`);
+    }
+    return {
+        major: parseInt(m.groups['major'], 10),
+        minor: parseInt(m.groups['minor'], 10),
+        patch: parseInt(m.groups['patch'], 10),
+        pre: m.groups['pre'] ?? null,
+    };
+}
+function sortKey(v) {
+    if (v.pre === null) {
+        return [v.major, v.minor, v.patch, 1, []];
+    }
+    const parts = [];
+    for (const ident of v.pre.split('.')) {
+        if (/^\d+$/.test(ident)) {
+            parts.push([0, parseInt(ident, 10), '']);
+        }
+        else {
+            parts.push([1, 0, ident]);
+        }
+    }
+    return [v.major, v.minor, v.patch, 0, parts];
+}
+function compareSortKeys(a, b) {
+    for (let i = 0; i < 4; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    const ap = a[4];
+    const bp = b[4];
+    const len = Math.min(ap.length, bp.length);
+    for (let i = 0; i < len; i++) {
+        if (ap[i][0] !== bp[i][0])
+            return ap[i][0] - bp[i][0];
+        if (ap[i][1] !== bp[i][1])
+            return ap[i][1] - bp[i][1];
+        if (ap[i][2] !== bp[i][2])
+            return ap[i][2] < bp[i][2] ? -1 : 1;
+    }
+    return ap.length - bp.length;
+}
+function semverToString(v) {
+    const base = `${v.major}.${v.minor}.${v.patch}`;
+    return v.pre ? `${base}-${v.pre}` : base;
+}
+export class VersionIncompatibleError extends ModuleError {
+    static DEFAULT_RETRYABLE = false;
+    constructor(declared, sdk, reason, options) {
+        super('VERSION_INCOMPATIBLE', `Version incompatible: declared=${declared}, sdk=${sdk} — ${reason}`, { declaredVersion: declared, sdkVersion: sdk, reason }, options?.cause, options?.traceId, options?.retryable, options?.aiGuidance, options?.userFixable, options?.suggestion);
+        this.name = 'VersionIncompatibleError';
+    }
+}
+/**
+ * Negotiate the effective version between declared and SDK versions (Algorithm A14).
+ *
+ * Steps:
+ *   1. Parse both versions as semver.
+ *   2. Major mismatch -> error.
+ *   3. Declared minor > SDK minor -> error (SDK too old).
+ *   4. Declared minor < SDK minor by >2 -> deprecation warning.
+ *   5. Same minor -> effective = max(declared, sdk).
+ *
+ * @param declaredVersion - Version declared in configuration or schema.
+ * @param sdkVersion - Maximum version supported by the current SDK.
+ * @returns The effective version string.
+ * @throws {VersionIncompatibleError} When versions are incompatible.
+ * @throws {Error} When a version string is not valid semver.
+ */
+export function negotiateVersion(declaredVersion, sdkVersion) {
+    const declared = parseSemver(declaredVersion);
+    const sdk = parseSemver(sdkVersion);
+    // Major version mismatch
+    if (declared.major !== sdk.major) {
+        throw new VersionIncompatibleError(declaredVersion, sdkVersion, 'Major version mismatch');
+    }
+    // Declared minor > SDK minor -> SDK too old
+    if (declared.minor > sdk.minor) {
+        throw new VersionIncompatibleError(declaredVersion, sdkVersion, 'SDK version too low, please upgrade');
+    }
+    // Declared minor < SDK minor
+    if (declared.minor < sdk.minor) {
+        const gap = sdk.minor - declared.minor;
+        if (gap > DEPRECATION_THRESHOLD) {
+            console.warn(`[apcore:version] Declared version ${declaredVersion} is ${gap} minor versions behind SDK ${sdkVersion} — consider upgrading your configuration`);
+        }
+        return declaredVersion; // Backward compatibility mode
+    }
+    // Same minor -> effective = max(declared, sdk)
+    const cmp = compareSortKeys(sortKey(declared), sortKey(sdk));
+    return cmp >= 0 ? semverToString(declared) : semverToString(sdk);
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "type": "git",
     "url": "https://github.com/aipartnerup/apcore-typescript.git"
   },
-  "homepage": "https://github.com/aipartnerup",
+  "homepage": "https://aipartnerup.com",
   "bugs": {
     "url": "https://github.com/aipartnerup/apcore-typescript/issues"
   },
@@ -61,7 +61,7 @@
     "@types/node": "^20.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/uuid": "^9.0.0",
-    "apdev-js": "^0.1.1",
+    "apdev-js": "^0.2.0",
     "vitest": "^2.0.0",
     "@vitest/coverage-v8": "^2.0.0"
   }