@bcts/envelope-pattern 1.0.0-alpha.17 → 1.0.0-alpha.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcts/envelope-pattern",
-  "version": "1.0.0-alpha.17",
+  "version": "1.0.0-alpha.18",
   "type": "module",
   "description": "Pattern matching for Gordian Envelope structures",
   "license": "BSD-2-Clause-Patent",
@@ -66,10 +66,10 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@bcts/dcbor": "^1.0.0-alpha.17",
-    "@bcts/dcbor-parse": "^1.0.0-alpha.17",
-    "@bcts/dcbor-pattern": "^1.0.0-alpha.17",
-    "@bcts/envelope": "^1.0.0-alpha.17",
-    "@bcts/known-values": "^1.0.0-alpha.17"
+    "@bcts/dcbor": "^1.0.0-alpha.18",
+    "@bcts/dcbor-parse": "^1.0.0-alpha.18",
+    "@bcts/dcbor-pattern": "^1.0.0-alpha.18",
+    "@bcts/envelope": "^1.0.0-alpha.18",
+    "@bcts/known-values": "^1.0.0-alpha.18"
   }
 }

package/src/format.ts

@@ -156,18 +156,37 @@ export function envelopeSummary(env: Envelope): string {
 
   let summary: string;
   switch (c.type) {
-    case "node":
-      summary = `NODE ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+    case "node": {
+      const subjectSummary = env.subject().summary(Number.MAX_SAFE_INTEGER);
+      const assertions = env.assertions();
+      if (assertions.length > 0) {
+        const assertionSummaries = assertions.map((a) => {
+          const ac = a.case();
+          if (ac.type === "assertion") {
+            const pred = ac.assertion.predicate().summary(Number.MAX_SAFE_INTEGER);
+            const obj = ac.assertion.object().summary(Number.MAX_SAFE_INTEGER);
+            return `${pred}: ${obj}`;
+          }
+          return a.summary(Number.MAX_SAFE_INTEGER);
+        });
+        summary = `NODE ${subjectSummary} [ ${assertionSummaries.join(", ")} ]`;
+      } else {
+        summary = `NODE ${subjectSummary}`;
+      }
       break;
+    }
     case "leaf":
       summary = `LEAF ${env.summary(Number.MAX_SAFE_INTEGER)}`;
       break;
     case "wrapped":
       summary = `WRAPPED ${env.summary(Number.MAX_SAFE_INTEGER)}`;
       break;
-    case "assertion":
-      summary = `ASSERTION ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+    case "assertion": {
+      const pred = c.assertion.predicate().summary(Number.MAX_SAFE_INTEGER);
+      const obj = c.assertion.object().summary(Number.MAX_SAFE_INTEGER);
+      summary = `ASSERTION ${pred}: ${obj}`;
       break;
+    }
     case "elided":
       summary = "ELIDED";
       break;

package/src/parse/index.ts

@@ -8,6 +8,7 @@
  */
 
 import { parse as parseDcborPattern } from "@bcts/dcbor-pattern";
+import { parseDcborItemPartial } from "@bcts/dcbor-parse";
 import { Lexer } from "./token";
 import {
   type Result,
@@ -37,10 +38,17 @@ import {
   byteString,
   anyDate,
   date,
+  dateRange,
+  dateEarliest,
+  dateLatest,
+  dateRegex,
   anyKnownValue,
   knownValue,
   anyArray,
   anyTag,
+  anyCbor,
+  cborValue,
+  cborPattern,
   nullPattern,
   // Structure pattern constructors
   leaf,
@@ -79,7 +87,6 @@ import {
   ByteStringPattern,
   KnownValuePattern,
   ArrayPattern,
-  TaggedPattern,
   DigestPattern,
   NodePattern,
   AssertionsPattern,
@@ -87,7 +94,6 @@ import {
   leafByteString,
   leafKnownValue,
   leafArray,
-  leafTag,
   structureDigest,
   structureNode,
   structureAssertions,
@@ -469,6 +475,7 @@ function parsePrimary(lexer: Lexer): Result<Pattern> {
     case "Comma":
     case "Ellipsis":
     case "Range":
+    case "Identifier":
       return err(unexpectedToken(token, span));
   }
 }
@@ -685,7 +692,50 @@ function parseTag(lexer: Lexer): Result<Pattern> {
  * Parse date content from date'...' pattern.
  */
 function parseDateContent(content: string, span: Span): Result<Pattern> {
-  // Try to parse as ISO date
+  // Check for regex syntax: /pattern/
+  if (content.startsWith("/") && content.endsWith("/")) {
+    const regexStr = content.slice(1, -1);
+    try {
+      return ok(dateRegex(new RegExp(regexStr)));
+    } catch {
+      return err(invalidRegex(span));
+    }
+  }
+
+  // Check for range syntax: date1...date2, date1..., ...date2
+  const rangeIdx = content.indexOf("...");
+  if (rangeIdx !== -1) {
+    const left = content.slice(0, rangeIdx).trim();
+    const right = content.slice(rangeIdx + 3).trim();
+
+    if (left.length === 0 && right.length > 0) {
+      // ...date2 → latest
+      const parsed = Date.parse(right);
+      if (isNaN(parsed)) return err({ type: "InvalidDateFormat", span });
+      return ok(dateLatest(CborDate.fromDatetime(new Date(parsed))));
+    }
+    if (left.length > 0 && right.length === 0) {
+      // date1... → earliest
+      const parsed = Date.parse(left);
+      if (isNaN(parsed)) return err({ type: "InvalidDateFormat", span });
+      return ok(dateEarliest(CborDate.fromDatetime(new Date(parsed))));
+    }
+    if (left.length > 0 && right.length > 0) {
+      // date1...date2 → range
+      const parsedStart = Date.parse(left);
+      const parsedEnd = Date.parse(right);
+      if (isNaN(parsedStart) || isNaN(parsedEnd)) return err({ type: "InvalidDateFormat", span });
+      return ok(
+        dateRange(
+          CborDate.fromDatetime(new Date(parsedStart)),
+          CborDate.fromDatetime(new Date(parsedEnd)),
+        ),
+      );
+    }
+    return err({ type: "InvalidDateFormat", span });
+  }
+
+  // Simple exact date
   const parsed = Date.parse(content);
   if (isNaN(parsed)) {
     return err({ type: "InvalidDateFormat", span });
@@ -713,17 +763,64 @@ function parseKnownValueContent(content: string): Result<Pattern> {
 
 /**
  * Parse CBOR pattern.
+ *
+ * Matches Rust parse_cbor: tries dcbor-pattern regex first (/keyword/),
+ * then CBOR diagnostic notation via parseDcborItemPartial, then falls
+ * back to parseOr for envelope pattern expressions.
  */
 function parseCbor(lexer: Lexer): Result<Pattern> {
   // Check for optional content in parentheses
   const next = lexer.peekToken();
   if (next?.token.type !== "ParenOpen") {
-    return ok(patternLeaf(leafTag(TaggedPattern.any()))); // cbor matches any CBOR
+    return ok(anyCbor()); // cbor matches any CBOR value
   }
 
   lexer.next(); // consume (
 
-  // Parse inner content - this is a dcbor-pattern expression
+  // Check for dcbor-pattern regex syntax: cbor(/keyword/)
+  // Use peek() (character-level, non-destructive) instead of peekToken()
+  // to avoid the lexer advancing past the CBOR content.
+  if (lexer.peek() === "/") {
+    const regexTokenResult = lexer.next(); // tokenize /pattern/
+    if (regexTokenResult?.token.type === "Regex") {
+      const regexToken = regexTokenResult.token;
+      if (!regexToken.value.ok) return err(regexToken.value.error);
+      const keyword = regexToken.value.value;
+
+      // Parse the keyword as a dcbor-pattern expression
+      const dcborResult = parseDcborPattern(keyword);
+      if (!dcborResult.ok) {
+        return err(unexpectedToken(regexToken, regexTokenResult.span));
+      }
+
+      const close = lexer.next();
+      if (close?.token.type !== "ParenClose") {
+        return err({ type: "ExpectedCloseParen", span: lexer.span() });
+      }
+
+      return ok(cborPattern(dcborResult.value));
+    }
+  }
+
+  // Try to parse inner content as CBOR diagnostic notation
+  // (matching Rust utils::parse_cbor_inner which calls parse_dcbor_item_partial)
+  const remaining = lexer.remainder();
+  const cborResult = parseDcborItemPartial(remaining);
+  if (cborResult.ok) {
+    const [cborData, consumed] = cborResult.value;
+    lexer.bump(consumed);
+    // Skip whitespace before closing paren
+    while (lexer.peek() === " " || lexer.peek() === "\t" || lexer.peek() === "\n") {
+      lexer.bump(1);
+    }
+    const close = lexer.next();
+    if (close?.token.type !== "ParenClose") {
+      return err({ type: "ExpectedCloseParen", span: lexer.span() });
+    }
+    return ok(cborValue(cborData));
+  }
+
+  // Fallback: try parsing as a regular pattern expression
   const inner = parseOr(lexer);
   if (!inner.ok) return inner;
 
@@ -746,6 +843,24 @@ function parseNode(lexer: Lexer): Result<Pattern> {
   }
 
   lexer.next(); // consume (
+
+  // Check for assertion count range: node({n,m}), node({n}), node({n,})
+  const afterParen = lexer.peekToken();
+  if (afterParen?.token.type === "Range") {
+    lexer.next(); // consume Range token
+    const rangeToken = afterParen.token;
+    if (!rangeToken.value.ok) return err(rangeToken.value.error);
+    const quantifier = rangeToken.value.value;
+    const interval = quantifier.interval();
+
+    const close = lexer.next();
+    if (close?.token.type !== "ParenClose") {
+      return err({ type: "ExpectedCloseParen", span: lexer.span() });
+    }
+
+    return ok(patternStructure(structureNode(NodePattern.fromInterval(interval))));
+  }
+
   const inner = parseOr(lexer);
   if (!inner.ok) return inner;
 
@@ -847,6 +962,24 @@ function parseDigest(lexer: Lexer): Result<Pattern> {
     return ok(digestPrefix(digestToken.token.value.value));
   }
 
+  // Accept raw hex string identifiers: digest(a1b2c3)
+  if (digestToken.token.type === "Identifier") {
+    const hexStr = digestToken.token.value;
+    // Validate hex string: must be even length and all hex digits
+    if (hexStr.length === 0 || hexStr.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hexStr)) {
+      return err({ type: "InvalidHexString", span: digestToken.span });
+    }
+    const bytes = new Uint8Array(hexStr.length / 2);
+    for (let i = 0; i < hexStr.length; i += 2) {
+      bytes[i / 2] = Number.parseInt(hexStr.slice(i, i + 2), 16);
+    }
+    const close = lexer.next();
+    if (close?.token.type !== "ParenClose") {
+      return err({ type: "ExpectedCloseParen", span: lexer.span() });
+    }
+    return ok(digestPrefix(bytes));
+  }
+
   return err(unexpectedToken(digestToken.token, digestToken.span));
 }
 

package/src/parse/token.ts

@@ -99,7 +99,8 @@ export type Token =
   | { readonly type: "DatePattern"; readonly value: Result<string> }
   | { readonly type: "Range"; readonly value: Result<Quantifier> }
   | { readonly type: "SingleQuotedPattern"; readonly value: Result<string> }
-  | { readonly type: "SingleQuotedRegex"; readonly value: Result<string> };
+  | { readonly type: "SingleQuotedRegex"; readonly value: Result<string> }
+  | { readonly type: "Identifier"; readonly value: string };
 
 /**
  * Keyword to token type mapping.
@@ -875,8 +876,8 @@ export class Lexer {
         return { token: keyword, span: this.span() };
       }
 
-      // Unknown identifier - treat as error
-      return undefined;
+      // Unknown identifier - return as Identifier token
+      return { token: { type: "Identifier", value: ident }, span: this.span() };
     }
 
     // Unknown character

package/src/pattern/index.ts

@@ -19,6 +19,7 @@ import {
 
 import type { Path } from "../format";
 import type { Instr } from "./vm";
+import { compile, run } from "./vm";
 
 // Re-export sub-modules
 export * from "./leaf";
@@ -104,6 +105,7 @@ import {
   registerNodePatternFactory,
   registerObscuredPatternFactory,
   registerWrappedPatternFactory,
+  registerWrappedPatternDispatch,
 } from "./structure";
 
 // Import meta patterns
@@ -176,13 +178,57 @@ export function patternMeta(meta: MetaPattern): Pattern {
 // Pattern Matcher Implementation
 // ============================================================================
 
+/**
+ * Check if a pattern requires the VM for execution.
+ * Patterns containing Group (repeat), Traverse, or Search require compilation.
+ */
+function patternNeedsVM(pattern: Pattern): boolean {
+  switch (pattern.type) {
+    case "Leaf":
+    case "Structure":
+      return false;
+    case "Meta":
+      return metaPatternNeedsVM(pattern.pattern);
+  }
+}
+
+function metaPatternNeedsVM(pattern: MetaPattern): boolean {
+  switch (pattern.type) {
+    case "Any":
+      return false;
+    case "And":
+      return pattern.pattern.patterns().some(patternNeedsVM);
+    case "Or":
+      return pattern.pattern.patterns().some(patternNeedsVM);
+    case "Not":
+      return patternNeedsVM(pattern.pattern.pattern());
+    case "Capture":
+      return patternNeedsVM(pattern.pattern.pattern());
+    case "Search":
+    case "Traverse":
+      return true;
+    case "Group": {
+      // Group with exactly(1) is simple pass-through, doesn't need VM
+      const q = pattern.pattern.quantifier();
+      if (q.min() === 1 && q.max() === 1) {
+        return patternNeedsVM(pattern.pattern.pattern());
+      }
+      return true;
+    }
+  }
+}
+
 /**
  * Gets paths with captures for a pattern.
+ * Routes through the VM for complex patterns that require compilation.
  */
 export function patternPathsWithCaptures(
   pattern: Pattern,
   haystack: Envelope,
 ): [Path[], Map<string, Path[]>] {
+  if (patternNeedsVM(pattern)) {
+    return patternPathsWithCapturesViaVM(pattern, haystack);
+  }
   switch (pattern.type) {
     case "Leaf":
       return leafPatternPathsWithCaptures(pattern.pattern, haystack);
@@ -193,6 +239,31 @@ export function patternPathsWithCaptures(
   }
 }
 
+/**
+ * Execute a pattern through the VM, merging results.
+ */
+function patternPathsWithCapturesViaVM(
+  pattern: Pattern,
+  haystack: Envelope,
+): [Path[], Map<string, Path[]>] {
+  const prog = compile(pattern);
+  const results = run(prog, haystack);
+
+  const allPaths: Path[] = [];
+  const mergedCaptures = new Map<string, Path[]>();
+
+  for (const [path, captures] of results) {
+    allPaths.push(path);
+    for (const [name, paths] of captures) {
+      const existing = mergedCaptures.get(name) ?? [];
+      existing.push(...paths);
+      mergedCaptures.set(name, existing);
+    }
+  }
+
+  return [allPaths, mergedCaptures];
+}
+
 /**
  * Gets paths for a pattern.
  */
@@ -347,6 +418,27 @@ export function dateRange(earliest: CborDate, latest: CborDate): Pattern {
   return patternLeaf(leafDate(DatePattern.range(earliest, latest)));
 }
 
+/**
+ * Creates a new Pattern that matches Date values on or after the specified date.
+ */
+export function dateEarliest(d: CborDate): Pattern {
+  return patternLeaf(leafDate(DatePattern.earliest(d)));
+}
+
+/**
+ * Creates a new Pattern that matches Date values on or before the specified date.
+ */
+export function dateLatest(d: CborDate): Pattern {
+  return patternLeaf(leafDate(DatePattern.latest(d)));
+}
+
+/**
+ * Creates a new Pattern that matches Date values whose ISO-8601 string matches the regex.
+ */
+export function dateRegex(pattern: RegExp): Pattern {
+  return patternLeaf(leafDate(DatePattern.regex(pattern)));
+}
+
 /**
  * Creates a new Pattern that matches any number value.
  */
@@ -700,6 +792,11 @@ function registerAllFactories(): void {
   registerNodePatternFactory((p) => patternStructure(structureNode(p)));
   registerObscuredPatternFactory((p) => patternStructure(structureObscured(p)));
   registerWrappedPatternFactory((p) => patternStructure(structureWrapped(p)));
+  registerWrappedPatternDispatch({
+    pathsWithCaptures: patternPathsWithCaptures,
+    compile: patternCompile,
+    toString: patternToString,
+  });
 
   // Meta pattern factories
   registerAnyPatternFactory((p) => patternMeta(metaAny(p)));
@@ -719,6 +816,17 @@ registerAllFactories();
 import { registerVMPatternFunctions } from "./vm";
 registerVMPatternFunctions(patternPathsWithCaptures, patternMatches, patternPaths);
 
-// Register pattern match function for meta patterns
-import { registerPatternMatchFn } from "./matcher";
+// Register pattern dispatch functions for meta patterns
+import { registerPatternMatchFn, registerPatternDispatchFns } from "./matcher";
 registerPatternMatchFn(patternMatches);
+registerPatternDispatchFns({
+  pathsWithCaptures: patternPathsWithCaptures,
+  paths: patternPaths,
+  compile: patternCompile,
+  isComplex: patternIsComplex,
+  toString: patternToString,
+});
+
+// Register traverse dispatch functions to resolve circular dependencies
+import { registerTraverseDispatchFunctions } from "./meta/traverse-pattern";
+registerTraverseDispatchFunctions(patternPathsWithCaptures, patternCompile, patternIsComplex);

package/src/pattern/leaf/array-pattern.ts

@@ -98,7 +98,7 @@ export class ArrayPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // Try to extract CBOR from the envelope
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor === undefined) {
       return [[], new Map<string, Path[]>()];
     }

package/src/pattern/leaf/bool-pattern.ts

@@ -72,7 +72,7 @@ export class BoolPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborBoolPatternPaths(this._inner, cbor);

package/src/pattern/leaf/byte-string-pattern.ts

@@ -82,7 +82,7 @@ export class ByteStringPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborByteStringPatternPaths(this._inner, cbor);

package/src/pattern/leaf/cbor-pattern.ts

@@ -156,7 +156,7 @@ export class CBORPattern implements Matcher {
   }
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
-    const envCase = haystack.case();
+    const envCase = haystack.subject().case();
 
     // Special case for KnownValue envelope
     if (envCase.type === "knownValue") {
@@ -206,7 +206,7 @@ export class CBORPattern implements Matcher {
     }
 
     // Standard case for CBOR leaf
-    const leafCbor = haystack.asLeaf();
+    const leafCbor = haystack.subject().asLeaf();
     if (leafCbor === undefined) {
       return [[], new Map<string, Path[]>()];
     }

package/src/pattern/leaf/date-pattern.ts

@@ -114,7 +114,7 @@ export class DatePattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborDatePatternPaths(this._inner, cbor);

package/src/pattern/leaf/index.ts

@@ -141,8 +141,7 @@ export function leafPatternPathsWithCaptures(
 ): [Path[], Map<string, Path[]>] {
   switch (pattern.type) {
     case "Cbor":
-      // CBOR patterns from dcbor-pattern need special handling
-      return [[], new Map<string, Path[]>()];
+      return pattern.pattern.pathsWithCaptures(haystack);
     case "Number":
       return pattern.pattern.pathsWithCaptures(haystack);
     case "Text":

package/src/pattern/leaf/known-value-pattern.ts

@@ -90,8 +90,9 @@ export class KnownValuePattern implements Matcher {
   }
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
-    // Check if the envelope is a known value via case()
-    const envCase = haystack.case();
+    // Check if the envelope subject is a known value via case()
+    const subject = haystack.subject();
+    const envCase = subject.case();
 
     if (envCase.type === "knownValue") {
       // Get the KnownValue and create CBOR for pattern matching
@@ -102,7 +103,7 @@ export class KnownValuePattern implements Matcher {
     }
 
     // Also try matching as a leaf (for tagged CBOR containing known values)
-    const leafCbor = haystack.asLeaf();
+    const leafCbor = subject.asLeaf();
     if (leafCbor !== undefined) {
       if (knownValuePatternMatches(this._inner, leafCbor)) {
         return [[[haystack]], new Map<string, Path[]>()];

package/src/pattern/leaf/map-pattern.ts

@@ -67,7 +67,7 @@ export class MapPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // Try to extract CBOR from the envelope
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor === undefined) {
       return [[], new Map<string, Path[]>()];
     }

package/src/pattern/leaf/null-pattern.ts

@@ -58,7 +58,7 @@ export class NullPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborNullPatternPaths(this._inner, cbor);

package/src/pattern/leaf/number-pattern.ts

@@ -136,7 +136,7 @@ export class NumberPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborNumberPatternPaths(this._inner, cbor);

package/src/pattern/leaf/text-pattern.ts

@@ -80,7 +80,7 @@ export class TextPattern implements Matcher {
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
     // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
-    const cbor = haystack.asLeaf();
+    const cbor = haystack.subject().asLeaf();
     if (cbor !== undefined) {
       // Delegate to dcbor-pattern for CBOR matching
       const dcborPaths = dcborTextPatternPaths(this._inner, cbor);