@cleocode/cant 2026.5.133 → 2026.5.134

package/README.md

@@ -19,9 +19,15 @@ pnpm add @cleocode/cant
 
 The package ships pre-built napi binaries via `optionalDependencies` for
 `x86_64-unknown-linux-gnu`. On other platforms `@cleocode/cant` falls back to
-graceful errors at runtime — the TypeScript surface still loads but
+typed errors at runtime — the TypeScript surface still loads but
 parser/validator/executor calls require a native binding present.
 
+**`cant-core` is the single source of truth (SSoT) for all CANT parsing.**
+There is no JS-regex fallback parser in the routine code path. If the native
+addon is absent, `parseCANTMessage` throws a typed error unless the
+`CLEO_CANT_ALLOW_JS_FALLBACK=1` env-var is explicitly set (degraded mode,
+not for production use).
+
 ## Public API
 
 ```ts
@@ -144,9 +150,19 @@ Requires a Rust toolchain. Produces `napi/cant.linux-x64-gnu.node`.
 Other platform triples are added via the workspace release pipeline,
 not locally.
 
+## Crate track
+
+| Crate | Status | Purpose |
+|-------|--------|---------|
+| `crates/cant-core` | Active — SSoT | Parser, validator, 42 static-analysis rules, pipeline executor |
+| `crates/cant-napi` | Active | napi-rs cdylib binding wrapping cant-core + cant-runtime |
+| `crates/cant-runtime` | Active | Deterministic pipeline execution engine (Path B) |
+| `crates/cant-router` | Retired from napi surface (E8 T11432) | Model-tier classifier — preserved in workspace but NOT linked into the published binary |
+| `crates/cant-lsp` | Shelved from default build (E8 T11434) | Language Server Protocol for `.cant` files — kept in workspace, build with `cargo build -p cant-lsp` |
+
 ## Related
 
-- [`crates/cant-core`](../../crates/cant-core) — Rust source of truth (parser, validator, executor)
+- [`crates/cant-core`](../../crates/cant-core) — Rust SSoT (parser, validator, pipeline executor)
 - [`crates/cant-napi`](../../crates/cant-napi) — napi-rs bindings (cdylib)
 - [`packages/cleo/templates/cleoos-hub/pi-extensions/cant-bridge.ts`](../cleo/templates/cleoos-hub/pi-extensions/cant-bridge.ts) — Pi-interactive runtime (Path A)
 - [`.cleo/adrs/ADR-035-pi-v2-v3-harness.md`](../../.cleo/adrs/ADR-035-pi-v2-v3-harness.md) — architecture decisions for the CANT execution model

package/dist/native-loader.d.ts

@@ -270,8 +270,10 @@ export type SeedPersonaId = (typeof SEED_PERSONA_IDS)[number];
  * Files that cannot be parsed (unreadable, missing `agent <id>:` block) are
  * silently skipped.
  *
- * This function is intentionally pure-TS and does NOT require the native addon.
- * It is safe to call in environments where `cant-napi` is absent (CI, test, etc.).
+ * When the native addon is available, agent identity fields are extracted via
+ * `cant_extract_agent_profiles` (cant-core, E8-AC2 / T11430). When the addon
+ * is absent the loader falls back to a minimal regex extractor so basic
+ * identity resolution still works in environments without the binary.
  *
  * @param agentsRoot - Optional override for the `packages/agents/` root. When
  *   omitted the path is resolved automatically relative to this file. Tests

package/dist/native-loader.js

@@ -309,22 +309,6 @@ function resolveAgentsPackageRoot() {
     ];
     return candidates.find((p) => (0, node_fs_1.existsSync)(p)) ?? null;
 }
-/**
- * Extract the `role:` value from a raw `.cant` file body.
- *
- * Looks for a line matching `  role: <value>` within the `agent <id>:` block
- * using a simple regex — intentionally avoids full CANT parsing to remove the
- * native-addon dependency from this path (the addon may not be present in all
- * environments where the loader runs).
- *
- * @param content - Raw `.cant` file text.
- * @returns Extracted role string, or `null` when no `role:` line is found.
- * @internal
- */
-function extractRoleFromCant(content) {
-    const match = /^\s{2}role:\s*(\S+)/m.exec(content);
-    return match ? (match[1] ?? null) : null;
-}
 /**
  * Map a raw role string from a `.cant` file to a {@link PeerKind}.
  *
@@ -347,61 +331,22 @@ function roleToPeerKind(rawRole) {
     }
 }
 /**
- * Extract the `description:` value from a raw `.cant` file body.
- *
- * Handles single-line descriptions (`description: "..."`) and multiline
- * block-scalar descriptions (`description: |`). Returns the first line of
- * the block-scalar body for multiline values. Returns empty string when no
- * `description:` field is found.
- *
- * @param content - Raw `.cant` file text.
- * @internal
- */
-function extractDescriptionFromCant(content) {
-    // Single-line: `  description: "some text"` or `  description: some text`
-    const singleLine = /^\s{2}description:\s+"([^"]+)"/m.exec(content);
-    if (singleLine)
-        return singleLine[1] ?? '';
-    const singleLineUnquoted = /^\s{2}description:\s+(.+)/m.exec(content);
-    if (singleLineUnquoted) {
-        const raw = singleLineUnquoted[1] ?? '';
-        // Exclude multiline indicator '|'
-        if (raw.trim() !== '|')
-            return raw.trim();
-    }
-    // Multiline block scalar: grab first non-empty line after `description: |`
-    const blockScalar = /^\s{2}description:\s+\|\s*\n((?:\s+\S[^\n]*\n?)+)/m.exec(content);
-    if (blockScalar) {
-        const bodyLines = (blockScalar[1] ?? '').split('\n');
-        for (const line of bodyLines) {
-            const trimmed = line.trim();
-            if (trimmed.length > 0)
-                return trimmed;
-        }
-    }
-    return '';
-}
-/**
- * Extract the agent business id from a raw `.cant` file body.
+ * Parse a single `.cant` file into a {@link PeerIdentity} via the canonical
+ * `cant_extract_agent_profiles` napi path (E8-AC2, T11430).
  *
- * Looks for the `agent <id>:` declaration line. Returns `null` when not found.
+ * When the native addon is available, agent id, role, and description are
+ * extracted by the Rust cant-core parser — eliminating the previous
+ * regex-based `extractRoleFromCant` / `extractAgentIdFromCant` /
+ * `extractDescriptionFromCant` helpers which are now retired.
  *
- * @param content - Raw `.cant` file text.
- * @internal
- */
-function extractAgentIdFromCant(content) {
-    const match = /^agent\s+([a-z][a-z0-9-]*):/m.exec(content);
-    return match ? (match[1] ?? null) : null;
-}
-/**
- * Parse a single `.cant` file at `cantFile` into a {@link PeerIdentity}.
- *
- * Returns `null` when the file cannot be parsed (missing `agent <id>:` block
- * or unreadable file). The caller is responsible for logging / skipping nulls.
+ * Falls back to a minimal regex extractor ONLY when the native addon is
+ * absent AND `fallbackId` is provided (i.e. the universal-base path where
+ * the filename is the canonical id). Returns `null` when the file is
+ * unreadable or no agent id can be determined.
  *
  * @param cantFile - Absolute path to the `.cant` file.
- * @param fallbackId - Id to use when the `agent <id>:` block is absent (e.g.,
- *   when loading the universal base by a known filename).
+ * @param fallbackId - Id to use when no `agent <id>:` block can be parsed
+ *   (e.g. when loading the universal base by a known filename).
  * @internal
  */
 function parseCantFileToIdentity(cantFile, fallbackId) {
@@ -412,18 +357,77 @@ function parseCantFileToIdentity(cantFile, fallbackId) {
     catch {
         return null;
     }
-    const agentId = extractAgentIdFromCant(content) ?? fallbackId ?? null;
+    // Primary path: route through the cant-core napi bridge.
+    // The native `cantExtractAgentProfiles` returns loose objects whose shape
+    // mirrors the Rust AgentProfile extractor. Common observed fields:
+    //   - `name`         — agent business id (kebab-case)
+    //   - `agentId`      — alternative agent id field (if present)
+    //   - `role`         — role string (may also live inside `propertiesJson`)
+    //   - `description`  — agent description (may also live inside `propertiesJson`)
+    //   - `propertiesJson` — JSON-serialized top-level properties blob
+    if (isNativeAvailable()) {
+        try {
+            const raw = cantExtractAgentProfilesNative(content);
+            if (Array.isArray(raw) && raw.length > 0) {
+                const entry = raw[0];
+                // Resolve agent id: prefer explicit agentId, fall back to name, then fallbackId.
+                const agentId = (typeof entry['agentId'] === 'string' ? entry['agentId'] : undefined) ??
+                    (typeof entry['name'] === 'string' ? entry['name'] : undefined) ??
+                    fallbackId ??
+                    null;
+                if (!agentId)
+                    return null;
+                // Resolve role: try direct field, then propertiesJson.
+                let rawRole = typeof entry['role'] === 'string' ? entry['role'] : null;
+                if (!rawRole && typeof entry['propertiesJson'] === 'string') {
+                    try {
+                        const props = JSON.parse(entry['propertiesJson']);
+                        rawRole = typeof props['role'] === 'string' ? props['role'] : null;
+                    }
+                    catch {
+                        // ignore malformed JSON
+                    }
+                }
+                const peerKind = roleToPeerKind(rawRole);
+                // Resolve description: try direct field, then propertiesJson.
+                let description = typeof entry['description'] === 'string' ? entry['description'] : '';
+                if (!description && typeof entry['propertiesJson'] === 'string') {
+                    try {
+                        const props = JSON.parse(entry['propertiesJson']);
+                        description = typeof props['description'] === 'string' ? props['description'] : '';
+                    }
+                    catch {
+                        // ignore malformed JSON
+                    }
+                }
+                return {
+                    peerId: agentId,
+                    peerKind,
+                    cantFile,
+                    displayName: agentId,
+                    description,
+                };
+            }
+        }
+        catch {
+            // Fall through to regex fallback below.
+        }
+    }
+    // Degraded regex fallback — only used when the native addon is absent.
+    // Extracts the minimum fields needed to produce a usable PeerIdentity.
+    const agentIdMatch = /^agent\s+([a-z][a-z0-9-]*):/m.exec(content);
+    const agentId = (agentIdMatch !== null ? agentIdMatch[1] : undefined) ?? fallbackId ?? null;
     if (!agentId)
         return null;
-    const rawRole = extractRoleFromCant(content);
+    const roleMatch = /^\s{2}role:\s*(\S+)/m.exec(content);
+    const rawRole = roleMatch ? (roleMatch[1] ?? null) : null;
     const peerKind = roleToPeerKind(rawRole);
-    const description = extractDescriptionFromCant(content);
     return {
         peerId: agentId,
         peerKind,
         cantFile,
         displayName: agentId,
-        description,
+        description: '',
     };
 }
 /**
@@ -438,8 +442,10 @@ function parseCantFileToIdentity(cantFile, fallbackId) {
  * Files that cannot be parsed (unreadable, missing `agent <id>:` block) are
  * silently skipped.
  *
- * This function is intentionally pure-TS and does NOT require the native addon.
- * It is safe to call in environments where `cant-napi` is absent (CI, test, etc.).
+ * When the native addon is available, agent identity fields are extracted via
+ * `cant_extract_agent_profiles` (cant-core, E8-AC2 / T11430). When the addon
+ * is absent the loader falls back to a minimal regex extractor so basic
+ * identity resolution still works in environments without the binary.
  *
  * @param agentsRoot - Optional override for the `packages/agents/` root. When
  *   omitted the path is resolved automatically relative to this file. Tests

package/dist/parse.d.ts

@@ -1,10 +1,11 @@
 import type { ParsedCANTMessage } from './types';
 export type { ParsedCANTMessage };
 /**
- * Initialize the CANT parser
+ * Initialize the CANT parser.
  *
- * With napi-rs native addons, this is a no-op (native modules load synchronously).
- * Kept for backward compatibility with code that previously called this for WASM init.
+ * With napi-rs native addons this is a no-op — native modules load
+ * synchronously. Kept for backward compatibility with code that
+ * previously called this for WASM init.
  *
  * @example
  * ```typescript
@@ -16,13 +17,24 @@ export type { ParsedCANTMessage };
  */
 export declare function initCantParser(): Promise<void>;
 /**
- * Parse a CANT message
+ * Parse a CANT message via the canonical cant-core napi-rs path.
  *
- * If the native addon is available, uses the Rust cant-core parser via napi-rs.
- * Falls back to a basic JavaScript implementation if the native addon is not loaded.
+ * The native addon (Rust `cant-core`) is the single source of truth for
+ * CANT message parsing (E8-AC2: one canonical path). The previous
+ * JS regex fallback is intentionally NOT a routine code path — if the
+ * native addon is unavailable the function throws a typed error so
+ * callers know they are running in a degraded environment and cannot
+ * silently produce wrong results.
  *
- * @param content - The CANT message content to parse
- * @returns ParsedCANTMessage with directive, addresses, task_refs, tags
+ * In test environments where the binary is not present, mock
+ * `isNativeAvailable` or use the `CLEO_CANT_ALLOW_JS_FALLBACK=1`
+ * environment variable to enable the clearly-marked degraded-mode
+ * branch (emits a console.warn and returns a best-effort parse).
+ *
+ * @param content - The CANT message content to parse.
+ * @returns ParsedCANTMessage with directive, addresses, task_refs, tags.
+ * @throws {Error} When the native addon is unavailable and
+ *   `CLEO_CANT_ALLOW_JS_FALLBACK` is not set.
  *
  * @example
  * ```typescript

package/dist/parse.js

@@ -4,10 +4,11 @@ exports.initCantParser = initCantParser;
 exports.parseCANTMessage = parseCANTMessage;
 const native_loader_1 = require("./native-loader");
 /**
- * Initialize the CANT parser
+ * Initialize the CANT parser.
  *
- * With napi-rs native addons, this is a no-op (native modules load synchronously).
- * Kept for backward compatibility with code that previously called this for WASM init.
+ * With napi-rs native addons this is a no-op — native modules load
+ * synchronously. Kept for backward compatibility with code that
+ * previously called this for WASM init.
  *
  * @example
  * ```typescript
@@ -22,13 +23,24 @@ async function initCantParser() {
     // Kept for backward compatibility.
 }
 /**
- * Parse a CANT message
+ * Parse a CANT message via the canonical cant-core napi-rs path.
  *
- * If the native addon is available, uses the Rust cant-core parser via napi-rs.
- * Falls back to a basic JavaScript implementation if the native addon is not loaded.
+ * The native addon (Rust `cant-core`) is the single source of truth for
+ * CANT message parsing (E8-AC2: one canonical path). The previous
+ * JS regex fallback is intentionally NOT a routine code path — if the
+ * native addon is unavailable the function throws a typed error so
+ * callers know they are running in a degraded environment and cannot
+ * silently produce wrong results.
  *
- * @param content - The CANT message content to parse
- * @returns ParsedCANTMessage with directive, addresses, task_refs, tags
+ * In test environments where the binary is not present, mock
+ * `isNativeAvailable` or use the `CLEO_CANT_ALLOW_JS_FALLBACK=1`
+ * environment variable to enable the clearly-marked degraded-mode
+ * branch (emits a console.warn and returns a best-effort parse).
+ *
+ * @param content - The CANT message content to parse.
+ * @returns ParsedCANTMessage with directive, addresses, task_refs, tags.
+ * @throws {Error} When the native addon is unavailable and
+ *   `CLEO_CANT_ALLOW_JS_FALLBACK` is not set.
  *
  * @example
  * ```typescript
@@ -40,37 +52,47 @@ async function initCantParser() {
  * ```
  */
 function parseCANTMessage(content) {
-    // If native addon is available, use it
+    // Canonical path: use the Rust cant-core parser via napi-rs.
     if ((0, native_loader_1.isNativeAvailable)()) {
-        try {
-            const nativeResult = (0, native_loader_1.cantParseNative)(content);
-            return {
-                directive: nativeResult.directive ?? undefined,
-                directive_type: (nativeResult.directiveType?.toLowerCase() ??
-                    'informational'),
-                addresses: nativeResult.addresses ?? [],
-                task_refs: nativeResult.taskRefs ?? [],
-                tags: nativeResult.tags ?? [],
-                header_raw: nativeResult.headerRaw ?? '',
-                body: nativeResult.body ?? '',
-            };
-        }
-        catch (error) {
-            console.warn('Native parsing failed, falling back to JS:', error);
-        }
+        const nativeResult = (0, native_loader_1.cantParseNative)(content);
+        return {
+            directive: nativeResult.directive ?? undefined,
+            directive_type: (nativeResult.directiveType?.toLowerCase() ??
+                'informational'),
+            addresses: nativeResult.addresses ?? [],
+            task_refs: nativeResult.taskRefs ?? [],
+            tags: nativeResult.tags ?? [],
+            header_raw: nativeResult.headerRaw ?? '',
+            body: nativeResult.body ?? '',
+        };
+    }
+    // ── DEGRADED MODE ────────────────────────────────────────────────────────
+    // The native addon is NOT available. This is an explicit degraded-mode
+    // branch guarded by an environment variable so it is never activated
+    // silently in production (E8-AC2). Callers that need a best-effort parse
+    // in environments without the binary (CI matrix, edge runtimes) must
+    // set CLEO_CANT_ALLOW_JS_FALLBACK=1 explicitly.
+    if (process.env.CLEO_CANT_ALLOW_JS_FALLBACK !== '1') {
+        throw new Error('cant-core native addon not available. Build it with: cargo build --release -p cant-napi\n' +
+            'Or set CLEO_CANT_ALLOW_JS_FALLBACK=1 to enable the degraded JS fallback parser.');
     }
-    // Fallback: basic JS implementation (header/body split)
+    // Degraded JS fallback — header/body split with basic regex.
+    // Only reached when CLEO_CANT_ALLOW_JS_FALLBACK=1.
+    console.warn('[cant] DEGRADED MODE: cant-core native addon unavailable; using JS regex parser. ' +
+        'Results may differ from the canonical Rust parser. ' +
+        'Build cant-napi to restore full fidelity.');
     const lines = content.split('\n');
-    const header = lines[0] || '';
+    const header = lines[0] ?? '';
     const body = lines.slice(1).join('\n');
-    // Basic regex extraction (not as robust as WASM parser)
     const directiveMatch = header.match(/^\/([a-z][a-z0-9-]*)/);
-    const addresses = [...header.matchAll(/@([a-zA-Z][a-zA-Z0-9_-]*)/g)].map((m) => m[1]);
-    const taskRefs = [...content.matchAll(/T(\d+)/g)].map((m) => `T${m[1]}`);
-    const tags = [...content.matchAll(/#([a-zA-Z][a-zA-Z0-9_-]*)/g)].map((m) => m[1]);
+    const addresses = [...header.matchAll(/@([a-zA-Z][a-zA-Z0-9_-]*)/g)].map((m) => m[1] ?? '');
+    const taskRefs = [...content.matchAll(/T(\d+)/g)].map((m) => `T${m[1] ?? ''}`);
+    const tags = [...content.matchAll(/#([a-zA-Z][a-zA-Z0-9_-]*)/g)].map((m) => m[1] ?? '');
     return {
         directive: directiveMatch ? directiveMatch[1] : undefined,
-        directive_type: directiveMatch ? classifyDirective(directiveMatch[1]) : 'informational',
+        directive_type: directiveMatch
+            ? _classifyDirectiveFallback(directiveMatch[1] ?? '')
+            : 'informational',
         addresses,
         task_refs: taskRefs,
         tags,
@@ -79,12 +101,13 @@ function parseCANTMessage(content) {
     };
 }
 /**
- * Classify a directive verb into its type
+ * Classify a directive verb into its type.
  *
+ * @internal Used only by the degraded JS fallback parser.
  * @param verb - The directive verb (e.g., 'done', 'action', 'info')
  * @returns 'actionable', 'routing', or 'informational'
  */
-function classifyDirective(verb) {
+function _classifyDirectiveFallback(verb) {
     const actionable = ['claim', 'done', 'blocked', 'approve', 'decision', 'checkin'];
     const routing = ['action', 'review', 'proposal'];
     if (actionable.includes(verb))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cleocode/cant",
-  "version": "2026.5.133",
-  "description": "CANT protocol parser and runtime for CLEO — wraps cant-core via napi-rs",
+  "version": "2026.5.134",
+  "description": "CANT DSL — cant-core (SSoT) parser, validator, and pipeline executor via napi-rs; agent identity, message parsing, and migration utilities",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -9,9 +9,9 @@
     "napi/"
   ],
   "dependencies": {
-    "@cleocode/contracts": "2026.5.133",
-    "@cleocode/core": "2026.5.133",
-    "@cleocode/lafs": "2026.5.133"
+    "@cleocode/contracts": "2026.5.134",
+    "@cleocode/core": "2026.5.134",
+    "@cleocode/lafs": "2026.5.134"
   },
   "devDependencies": {
     "typescript": "^6.0.2",