keri-ts 0.4.0 → 0.6.0

package/README.md

@@ -1,85 +1,22 @@
 # keri-ts
 
-KERI TypeScript runtime package with the `tufa` CLI.
+KERI TypeScript protocol/runtime library.
 
 ## Install
 
 ```bash
 # As a dependency
 npm install keri-ts
-
-# Global CLI install
-npm install -g keri-ts
-```
-
-## CLI quick start
-
-`tufa version` and `tufa annotate` are the fastest way to verify your setup.
-
-```bash
-# Version
-tufa version
-tufa --version
-
-# Annotate CESR from file
-tufa annotate --in ./mystream.cesr
-
-# Annotate from stdin
-cat ./mystream.cesr | tufa annotate
-```
-
-## Benchmark CESR parser
-
-Benchmark any CESR stream from file or stdin:
-
-```bash
-# Benchmark a stream file
-tufa benchmark cesr --in ./mystream.cesr
-
-# Benchmark from stdin with explicit chunk simulation
-cat ./mystream.cesr | tufa benchmark cesr --chunk-size 256 --iterations 25 --warmup 5
-```
-
-- `--in <path>`: input file path (defaults to stdin)
-- `--iterations <count>`: measured benchmark runs (default `50`)
-- `--warmup <count>`: warmup runs before measurement (default `5`)
-- `--chunk-size <bytes>`: chunk size for streaming simulation (`0` = full
-  stream)
-- `--framed`: benchmark parser in framed mode
-- `--compat`: benchmark parser with compat attachment dispatch mode
-- `--allow-errors`: continue benchmark even when parse errors are emitted
-- `--json`: print one JSON result line
-
-## Annotate options
-
-```bash
-tufa annotate --in <path> --out <path> --pretty
-tufa annotate --qb2 --in <binary.qb2> --out <annotation.txt>
 ```
 
-- `--in <path>`: input file path (defaults to stdin)
-- `--out <path>`: output file path (defaults to stdout)
-- `--qb2`: parse input as qb2 binary
-- `--pretty`: pretty-print annotation output
-- `--colored`: colorize annotation output on stdout only (ignored with `--out`)
-
-Optional color overrides:
-
-- File: `$HOME/.tufa/annot-color.yaml` or `$HOME/.tufa/annot-color.yml`
-- Keys: `counter`, `group`, `body`, `signature`, `said`, `opaque`, `comment`
-- Values: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`,
-  or bright variants (`brightBlack` ... `brightWhite`)
+## Library surfaces
 
-## Package entrypoints
+- default import: browser-safe core/types surface
+- `keri-ts/runtime`: explicit non-browser-safe runtime surface
+- `keri-ts/db`: explicit LMDB-backed storage surface
 
-```bash
-# CLI help
-npx tufa --help
-
-# From source in this repo
-deno task tufa --help
-deno task tufa version
-```
+Only those three entrypoints are supported public surfaces. Runnable CLI/server
+ownership lives in the separate `tufa` package.
 
 ## License
 

package/esm/cesr/src/adapters/async-iterable.js

@@ -1,4 +1,12 @@
 import { createParser } from "../core/parser-engine.js";
+/**
+ * Adapt an async byte stream into parsed CESR frames.
+ *
+ * Boundary contract:
+ * - chunks are fed in arrival order into one parser instance
+ * - emitted parser error events are rethrown as stream errors
+ * - yielded values are the historical `CesrMessage` frame payloads only
+ */
 export async function* toAsyncFrames(source, options = {}) {
     const parser = createParser(options);
     for await (const chunk of source) {

package/esm/cesr/src/adapters/effection.js

@@ -1,5 +1,11 @@
 import { action } from "effection";
 import { toAsyncFrames } from "./async-iterable.js";
+/**
+ * Bridge the async-iterable parser adapter into an Effection operation.
+ *
+ * This stays intentionally thin so parser semantics continue to live in
+ * `toAsyncFrames()` rather than forking behavior in an Effection-only path.
+ */
 export function* toEffectionFrames(source, options = {}) {
     const frames = yield* action((resolve) => {
         resolve(toAsyncFrames(source, options));

package/esm/cesr/src/annotate/annotator.js

@@ -25,12 +25,24 @@ function parsedFramesOrThrow(frames) {
     }
     return parsedFrames;
 }
+/**
+ * Parse input and return one annotation structure per emitted frame.
+ *
+ * Use this when callers want to inspect annotation lines programmatically
+ * instead of flattening the whole stream to one rendered string.
+ */
 export function annotateFrames(input, options) {
     const opts = resolveOptions(options);
     const bytes = typeof input === "string" ? b(input) : input;
     const frames = parsedFramesOrThrow(parseBytes(bytes));
     return renderAnnotatedFrames(frames, opts);
 }
+/**
+ * Render one CESR stream into maintainer-oriented annotated text.
+ *
+ * Wrapper-aware rendering is attempted first so opaque wrapper payloads can be
+ * preserved faithfully before falling back to frame-by-frame annotation.
+ */
 export function annotate(input, options) {
     const opts = resolveOptions(options);
     const bytes = typeof input === "string" ? b(input) : input;

package/esm/cesr/src/annotate/comments.js

@@ -1,5 +1,5 @@
 import { resolveCounterCodeNameTable } from "../tables/counter-version-registry.js";
-import { COUNTER_CODE_NAMES_V1, COUNTER_CODE_NAMES_V2, } from "../tables/counter.tables.generated.js";
+import { COUNTER_CODE_NAMES_V1, COUNTER_CODE_NAMES_V2 } from "../tables/counter.tables.generated.js";
 import { MATTER_CODE_NAMES } from "../tables/matter.tables.generated.js";
 const NATIVE_FIELD_LABELS = Object.freeze({
     v: "version string",
@@ -17,6 +17,7 @@ const NATIVE_FIELD_LABELS = Object.freeze({
     c: "traits/config",
     a: "anchors/data",
 });
+/** Resolve a human-readable counter name against either known counter table. */
 export function counterCodeName(code) {
     const v2 = COUNTER_CODE_NAMES_V2[code];
     if (v2)
@@ -26,13 +27,16 @@ export function counterCodeName(code) {
         return v1;
     return "Counter";
 }
+/** Resolve a counter name against the registry selected for one protocol version. */
 export function counterCodeNameForVersion(code, version) {
     const table = resolveCounterCodeNameTable(version);
     return table[code] ?? "Counter";
 }
+/** Resolve a human-readable matter name from the generated matter code table. */
 export function matterCodeName(code) {
     return MATTER_CODE_NAMES[code] ?? "Matter";
 }
+/** Expand well-known native field labels for annotation comments when available. */
 export function nativeLabelName(label) {
     if (!label)
         return null;

package/esm/cesr/src/annotate/denot.js

@@ -1,4 +1,10 @@
 const TEXT_ENCODER = new TextEncoder();
+/**
+ * Strip annotation comments/whitespace and rebuild the raw CESR text stream.
+ *
+ * This is the inverse of maintainer-facing annotation output, not a general
+ * parser: comment lines and inline `# ...` commentary are discarded.
+ */
 export function denot(annotated) {
     const tokens = [];
     for (const line of annotated.split(/\r?\n/)) {

package/esm/cesr/src/annotate/render.js

@@ -1,5 +1,5 @@
 import { b64ToInt, intToB64 } from "../core/bytes.js";
-import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError, } from "../core/errors.js";
+import { DeserializeError, GroupSizeError, ShortageError, UnknownCodeError } from "../core/errors.js";
 import { parseBytes } from "../core/parser-engine.js";
 import { sniff } from "../parser/cold-start.js";
 import { parseAttachmentDispatchCompat } from "../parser/group-dispatch.js";
@@ -8,7 +8,7 @@ import { Indexer } from "../primitives/indexer.js";
 import { Matter, parseMatter } from "../primitives/matter.js";
 import { isCounterGroupLike, isPrimitiveTuple } from "../primitives/primitive.js";
 import { UnknownPrimitive } from "../primitives/unknown.js";
-import { counterCodeName, counterCodeNameForVersion, matterCodeName, nativeLabelName, } from "./comments.js";
+import { counterCodeName, counterCodeNameForVersion, matterCodeName, nativeLabelName } from "./comments.js";
 const TEXT_DECODER = new TextDecoder();
 const OPAQUE_TOKEN_COMMENT = "opaque token";
 const OPAQUE_WRAPPER_PAYLOAD_COMMENT = "opaque wrapper payload";
@@ -59,6 +59,7 @@ function emitLine(lines, value, comment, indent, options) {
     }
     lines.push(`${pad}${value} # ${comment}`);
 }
+/** Parse counters with a bounded v1/v2 fallback for annotation-only rendering paths. */
 function parseCounterCompat(input, version, domain) {
     try {
         return parseCounter(input, version, domain);
@@ -73,6 +74,7 @@ function parseCounterCompat(input, version, domain) {
         return parseCounter(input, alternate, domain);
     }
 }
+/** Decode a wrapped genus-version selector into the active protocol version context. */
 function decodeVersionCounter(counter) {
     const triplet = counter.qb64.length >= 3
         ? counter.qb64.slice(-3)
@@ -84,6 +86,7 @@ function decodeVersionCounter(counter) {
         minor: minorRaw,
     };
 }
+/** Render hydrated group entries recursively using semantic primitive comments. */
 function renderGroupItems(lines, items, version, indent, options) {
     for (const item of items) {
         if (isPrimitiveTuple(item)) {
@@ -117,6 +120,7 @@ function renderGroupItems(lines, items, version, indent, options) {
         emitLine(lines, String(item), OPAQUE_TOKEN_COMMENT, indent, options);
     }
 }
+/** Render one raw attachment-group span, including nested wrapper groups when present. */
 function renderAttachmentGroupRaw(lines, raw, version, indent, options) {
     const domain = asDomain(raw);
     if (domain !== "txt" && domain !== "bny") {
@@ -170,6 +174,7 @@ function renderAttachmentGroupRaw(lines, raw, version, indent, options) {
     renderGroupItems(lines, parsed.group.items, version, indent + options.indent, options);
     return parsed.consumed;
 }
+/** Render a native CESR body-group payload using hydrated native field projections when available. */
 function renderNativeBody(lines, frame, options, version) {
     const raw = frame.body.raw;
     const domain = asDomain(raw);
@@ -211,6 +216,7 @@ function renderNativeBody(lines, frame, options, version) {
         offset += matterSize;
     }
 }
+/** Render non-native or opaque message bodies as one annotated body line. */
 function renderMessageBody(lines, frame, options) {
     const rawBody = TEXT_DECODER.decode(frame.body.raw);
     const isOpaqueCesrBody = frame.body.kind === "CESR"
@@ -240,11 +246,15 @@ function renderMessageBody(lines, frame, options) {
     ].filter(Boolean).join(" ");
     emitLine(lines, body, info, 0, options);
 }
+/** Render one parsed frame and all of its attachment groups into annotation lines. */
 function renderFrame(frame, index, options) {
     const lines = [];
     const version = frame.body.gvrsn ?? frame.body.pvrsn;
     const domain = asDomain(frame.body.raw);
-    if (domain === "txt" || domain === "bny") {
+    if (frame.body.kind === "CESR" && frame.body.ked === null) {
+        renderMessageBody(lines, frame, options);
+    }
+    else if (domain === "txt" || domain === "bny") {
         renderNativeBody(lines, frame, options, version);
     }
     else {
@@ -255,6 +265,7 @@ function renderFrame(frame, index, options) {
     }
     return { index, frame, lines };
 }
+/** Parse and render a nested frame chunk inside wrapper-aware annotation flows. */
 function renderFrameChunk(lines, input, indent, options) {
     const parsed = parseBytes(input);
     const frames = [];
@@ -271,6 +282,7 @@ function renderFrameChunk(lines, input, indent, options) {
         }
     }
 }
+/** Walk a stream that may begin with wrapper/version selectors before ordinary frames. */
 function renderWrapperAwareStream(lines, input, inheritedVersion, indent, options) {
     let offset = 0;
     let activeVersion = inheritedVersion;

package/esm/cesr/src/core/bytes.js

@@ -1,4 +1,6 @@
+/** Shared UTF-8 encoder used by CESR and DB byte helpers. */
 export const encoder = new TextEncoder();
+/** Shared UTF-8 decoder used by CESR and DB byte helpers. */
 export const decoder = new TextDecoder();
 const B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 /**
@@ -17,6 +19,7 @@ export function concatBytes(...chunks) {
     }
     return out;
 }
+/** Encode a non-negative integer into CESR's URL-safe base64 sextet text. */
 export function intToB64(value, length = 1) {
     if (value < 0) {
         throw new Error(`value must be >= 0, got ${value}`);
@@ -32,6 +35,7 @@ export function intToB64(value, length = 1) {
     }
     return out.padStart(length, "A");
 }
+/** Decode CESR URL-safe base64 sextet text into a non-negative integer. */
 export function b64ToInt(text) {
     let out = 0;
     for (const ch of text) {
@@ -43,10 +47,12 @@ export function b64ToInt(text) {
     }
     return out;
 }
+/** Encode raw bytes to unpadded URL-safe base64 text. */
 export function encodeB64(data) {
     const str = btoa(String.fromCharCode(...data));
     return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
+/** Decode unpadded URL-safe base64 text into raw bytes. */
 export function decodeB64(text) {
     const padded = text + "===".slice((text.length + 3) % 4);
     const raw = atob(padded.replace(/-/g, "+").replace(/_/g, "/"));
@@ -63,11 +69,13 @@ export function decodeB64(text) {
 export function sceil(value) {
     return Math.ceil(value);
 }
+/** Convert a CESR code string to the exact leading qb2 bytes that carry it. */
 export function codeB64ToB2(text) {
     const n = sceil((text.length * 3) / 4);
     const full = text + "A".repeat((4 - (text.length % 4)) % 4);
     return decodeB64(full).slice(0, n);
 }
+/** Convert leading qb2 bytes into the requested number of CESR sextets. */
 export function codeB2ToB64(bytes, sextets) {
     const n = sceil((sextets * 3) / 4);
     if (n > bytes.length) {
@@ -75,6 +83,7 @@ export function codeB2ToB64(bytes, sextets) {
     }
     return encodeB64(bytes.slice(0, n)).slice(0, sextets);
 }
+/** Re-slice the first `sextets` worth of qb2 bytes for parser/code probing. */
 export function nabSextets(bytes, sextets) {
     return codeB64ToB2(codeB2ToB64(bytes, sextets));
 }

package/esm/cesr/src/core/errors.js

@@ -56,6 +56,9 @@ export class GroupSizeError extends ParserError {
 /** Qualified input could not be deserialized into a valid CESR payload. */
 export class DeserializeError extends ParserError {
 }
+/** A CESR payload could not be serialized into a valid protocol representation. */
+export class SerializeError extends ParserError {
+}
 /** Failure while constructing syntax artifacts from token bytes. */
 export class SyntaxParseError extends ParserError {
     constructor(message, cause, offset, context) {

package/esm/cesr/src/core/parser-engine.js

@@ -6,7 +6,7 @@ import { DeferredFrameLifecycle } from "./parser-deferred-frames.js";
 import { FrameParser } from "./parser-frame-parser.js";
 import { createFrameBoundaryPolicy } from "./parser-policy.js";
 import { ParserStreamState } from "./parser-stream-state.js";
-import { composeRecoveryDiagnosticObserver, } from "./recovery-diagnostics.js";
+import { composeRecoveryDiagnosticObserver } from "./recovery-diagnostics.js";
 /**
  * Streaming CESR parser for message-domain and CESR-native body-group streams.
  * Handles chunk boundaries, pending frames, and attachment continuation.

package/esm/cesr/src/core/parser-frame-parser.js

@@ -3,7 +3,7 @@ import { sniff } from "../parser/cold-start.js";
 import { parseCounter } from "../primitives/counter.js";
 import { parseIlker } from "../primitives/ilker.js";
 import { isLabelerCode, parseLabeler } from "../primitives/labeler.js";
-import { interpretMapperBodySyntax, parseMapperBodySyntax, } from "../primitives/mapper.js";
+import { interpretMapperBodySyntax, parseMapperBodySyntax } from "../primitives/mapper.js";
 import { parseMatter } from "../primitives/matter.js";
 import { parseVerser } from "../primitives/verser.js";
 import { reapSerder } from "../serder/serdery.js";
@@ -242,14 +242,15 @@ export class FrameParser {
             };
         }
         catch (_error) {
+            const raw = matter.raw;
             return {
                 frame: {
                     body: {
-                        raw: matter.raw,
+                        raw,
                         ked: null,
                         proto: Protocols.keri,
                         kind: Kinds.cesr,
-                        size: matter.raw.length,
+                        size: raw.length,
                         pvrsn: version,
                         gvrsn: version,
                         ilk: null,
@@ -274,23 +275,26 @@ export class FrameParser {
         const syntax = this.parseNativeBodySyntax(raw, cold, version);
         const metadata = this.interpretNativeMetadataSyntax(syntax.metadata, version);
         const fields = this.interpretNativeFieldSyntax(syntax.fields);
+        // KERIpy parity rule: once the frame parser has classified a top-level
+        // FixBodyGroup/MapBodyGroup as a native message body, the result must be a
+        // real Serder or a parse error. Arbitrary native map/list corpora still
+        // belong to lower-level CESR-native surfaces such as Mapper/Aggor.
+        const { serder } = reapSerder(raw);
+        if (serder.proto !== metadata.proto
+            || serder.pvrsn.major !== metadata.pvrsn.major
+            || serder.pvrsn.minor !== metadata.pvrsn.minor
+            || (metadata.ilk !== null && serder.ilk !== metadata.ilk)
+            || (metadata.said !== null && serder.said !== metadata.said)) {
+            throw new SemanticInterpretationError("Native body syntax pre-read disagreed with Serder hydration");
+        }
+        serder.native = {
+            bodyCode,
+            fields,
+        };
+        const body = serder;
         return {
             frame: {
-                body: {
-                    raw,
-                    ked: null,
-                    proto: metadata.proto,
-                    kind: Kinds.cesr,
-                    size: raw.length,
-                    pvrsn: metadata.pvrsn,
-                    gvrsn: metadata.gvrsn,
-                    ilk: metadata.ilk,
-                    said: metadata.said,
-                    native: {
-                        bodyCode,
-                        fields,
-                    },
-                },
+                body,
                 attachments: [],
             },
             consumed: offset + total,

package/esm/cesr/src/core/vocabulary.js

@@ -0,0 +1,47 @@
+/** KERI security tiers for deterministic secret derivation. */
+export const Tiers = Object.freeze({
+    low: "low",
+    med: "med",
+    high: "high",
+});
+/** Return true when the value is one of the supported KERI security tiers. */
+export function isTier(value) {
+    return Object.values(Tiers).includes(value);
+}
+/** KERI/ACDC message ilks mirrored from KERIpy's `kering.Ilks`. */
+export const Ilks = Object.freeze({
+    icp: "icp",
+    rot: "rot",
+    ixn: "ixn",
+    dip: "dip",
+    drt: "drt",
+    rct: "rct",
+    qry: "qry",
+    rpy: "rpy",
+    xip: "xip",
+    exn: "exn",
+    pro: "pro",
+    bar: "bar",
+    vcp: "vcp",
+    vrt: "vrt",
+    iss: "iss",
+    rev: "rev",
+    bis: "bis",
+    brv: "brv",
+    rip: "rip",
+    bup: "bup",
+    upd: "upd",
+    acm: "acm",
+    act: "act",
+    acg: "acg",
+    ace: "ace",
+    sch: "sch",
+    att: "att",
+    agg: "agg",
+    edg: "edg",
+    rul: "rul",
+});
+/** Return true when the value is one of the known KERI/ACDC ilks. */
+export function isIlk(value) {
+    return Object.values(Ilks).includes(value);
+}

package/esm/cesr/src/index.js

@@ -13,6 +13,7 @@ export * from "./core/parser-engine.js";
 export * from "./core/parser-policy.js";
 export * from "./core/recovery-diagnostics.js";
 export * from "./core/types.js";
+export * from "./core/vocabulary.js";
 export * from "./parser/cold-start.js";
 export * from "./parser/group-dispatch.js";
 export * from "./primitives/aggor.js";
@@ -27,7 +28,9 @@ export * from "./primitives/dater.js";
 export * from "./primitives/decimer.js";
 export * from "./primitives/decrypter.js";
 export * from "./primitives/diger.js";
+export * from "./primitives/disclosure.js";
 export * from "./primitives/encrypter.js";
+export * from "./primitives/hydrate.js";
 export * from "./primitives/ilker.js";
 export * from "./primitives/indexer.js";
 export * from "./primitives/labeler.js";
@@ -46,6 +49,8 @@ export * from "./primitives/sealer.js";
 export * from "./primitives/seqner.js";
 export * from "./primitives/siger.js";
 export * from "./primitives/signer.js";
+export * from "./primitives/streamer.js";
+export * from "./primitives/structing.js";
 export * from "./primitives/structor.js";
 export * from "./primitives/tagger.js";
 export * from "./primitives/texter.js";

package/esm/cesr/src/parser/attachment-parser.js

@@ -1,4 +1,8 @@
 import { parseAttachmentDispatchCompat } from "./group-dispatch.js";
+/**
+ * Historical attachment-group entrypoint preserved as a thin wrapper around the
+ * newer dispatch-policy parser.
+ */
 export function parseAttachmentGroup(input, version, domain, options = {}) {
     return parseAttachmentDispatchCompat(input, version, domain, options);
 }

package/esm/cesr/src/parser/cold-start.js

@@ -1,4 +1,10 @@
 import { ColdStartError, ShortageError } from "../core/errors.js";
+/**
+ * Classify the next unread stream bytes into CESR cold-start domains.
+ *
+ * This mirrors KERIpy's tritet probe: message-domain encodings, text CESR,
+ * binary CESR, or annotation separators all begin with distinct leading bits.
+ */
 export function sniff(ims) {
     if (ims.length === 0) {
         throw new ShortageError(1, 0);

package/esm/cesr/src/parser/group-dispatch.js

@@ -1,12 +1,12 @@
 import { b, b64ToInt, intToB64 } from "../core/bytes.js";
 import { GroupSizeError, ShortageError, UnknownCodeError } from "../core/errors.js";
-import { composeRecoveryDiagnosticObserver, } from "../core/recovery-diagnostics.js";
+import { composeRecoveryDiagnosticObserver } from "../core/recovery-diagnostics.js";
 import { CounterGroup, parseCounter } from "../primitives/counter.js";
 import { parseIndexer } from "../primitives/indexer.js";
 import { parseMatter } from "../primitives/matter.js";
 import { UnknownPrimitive } from "../primitives/unknown.js";
 import { CtrDexV1, CtrDexV2 } from "../tables/counter-codex.js";
-import { resolveVersionedRegistryValue, } from "../tables/counter-version-registry.js";
+import { resolveVersionedRegistryValue } from "../tables/counter-version-registry.js";
 import { createAttachmentVersionFallbackPolicy, } from "./attachment-fallback-policy.js";
 export { createAttachmentVersionFallbackPolicy } from "./attachment-fallback-policy.js";
 function tupleItem(items) {