llmtxt 2026.4.5 → 2026.4.7

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.4.7] — 2026-04-17
+
+### Fixed
+- **Bundler compatibility for `onnxruntime-node`**: dynamic import in `embeddings.ts` now uses a runtime-constructed specifier + `/* @vite-ignore */` + `/* webpackIgnore: true */` hints. esbuild, webpack, vite, and rollup no longer try to inline the `.node` native addon. Verified with esbuild 0.28 bundle of `llmtxt` + `llmtxt/embeddings` — exit 0, no `--external` flag needed for the onnxruntime path.
+
+### Changed
+- `better-sqlite3`, `drizzle-orm`, `postgres` moved from `optionalDependencies` to `peerDependencies` + `peerDependenciesMeta.optional: true`. pnpm no longer auto-installs them — consumers must opt in per topology. Matches treatment of `onnxruntime-node` and `@vlcn.io/crsqlite`.
+- README adds install matrix + esbuild/webpack/vite externalize list.
+
 ## [2026.4.5] - 2026-04-16
 
 This release ships the full Round 1+2+3 multi-agent foundation: CRDT/Yrs, signed Ed25519 identity, append-only event log, real-time presence/leases/diff-subscriptions (W1+W2), BFT consensus, agent scratchpad, A2A envelope routing (W3), a self-hosted observability stack (Grafana / Loki / Tempo / Prometheus / OTel collector / GlitchTip on Railway), OpenAPI schema generation with forge-ts integration, local semantic embeddings via pgvector + ONNX, four reference agents plus a `/demo` page, and a fully portable SDK offering `LocalBackend`, `RemoteBackend`, and `llmtxt` CLI — including a complete CLEO integration example. Also upgrades drizzle-orm/kit to `1.0.0-beta.21` and zod to `^4`.

package/README.md

@@ -1,16 +1,219 @@
 # llmtxt
 
+[![v2026.4.7](https://img.shields.io/badge/version-2026.4.7-blue)](https://www.npmjs.com/package/llmtxt)
+
 Primitives and SDK for LLM agent content workflows.
 
 `llmtxt` wraps the Rust `llmtxt-core` crate through WASM so TypeScript
 consumers use the same single-source-of-truth logic as native Rust consumers.
 
+**v2026.4.7** (patch): bundler-friendly dynamic import of `onnxruntime-node`; `drizzle-orm` / `better-sqlite3` / `postgres` moved from `optionalDependencies` to optional `peerDependencies` so consumers no longer auto-install them. Docs add the required externalize list for esbuild / webpack / vite / rollup.
+
+**v2026.4.6**: Loro CRDT (replaces Yrs — binary-incompatible), AgentSession lifecycle, document export/import (4 formats), binary blob attachments, `createBackend()` topology factory, cr-sqlite changeset sync, P2P mesh, and new CLI commands.
+
 ## Install
 
 ```bash
 npm install llmtxt
 ```
 
+All database/embedding drivers are **optional peer dependencies** — install only the ones your topology needs:
+
+| Topology / feature | Extra install |
+|---|---|
+| `standalone` (local SQLite) | `pnpm add better-sqlite3 drizzle-orm` |
+| `hub-spoke` (Postgres hub) | `pnpm add postgres drizzle-orm` |
+| `mesh` + cr-sqlite CRR | `pnpm add @vlcn.io/crsqlite` |
+| Semantic embeddings | `pnpm add onnxruntime-node` |
+| RemoteBackend-only consumer (no local DB) | nothing extra |
+
+## Bundling with esbuild / webpack / vite / rollup
+
+`llmtxt` keeps optional peer deps opaque to static bundler analysis where possible, but deep imports inside `LocalBackend` (drizzle-orm) and native addons (onnxruntime-node) must be marked **external** by consumers who bundle. Minimum external list:
+
+```js
+// esbuild
+esbuild.build({
+  bundle: true,
+  platform: 'node',
+  external: [
+    'onnxruntime-node',          // native .node addon
+    'better-sqlite3',            // native .node addon
+    '@vlcn.io/crsqlite',         // native extension + ESM-only
+    'drizzle-orm',               // transitively pulls mssql, @opentelemetry/api
+    'drizzle-orm/*',             // subpath imports
+    'postgres',
+    'mssql',
+    '@opentelemetry/api',
+  ],
+});
+```
+
+Same list works as `externals` in webpack/rollup and `build.rollupOptions.external` in vite. If your deployment does NOT use LocalBackend (e.g. RemoteBackend only), you may also externalize `llmtxt/local`.
+
+## Topology Factory
+
+The entry point for all deployments. Returns a `Backend` configured for the chosen topology.
+
+```ts
+import { createBackend } from 'llmtxt';
+
+// Standalone — local SQLite, no network
+const backend = await createBackend({ topology: 'standalone', storagePath: './.llmtxt' });
+
+// Hub-spoke — ephemeral worker pointing at shared hub
+const backend2 = await createBackend({
+  topology: 'hub-spoke',
+  hubUrl: 'https://api.llmtxt.my',
+  apiKey: process.env.LLMTXT_API_KEY,
+});
+
+// Mesh — P2P, no server required
+const backend3 = await createBackend({
+  topology: 'mesh',
+  storagePath: './.llmtxt',
+});
+```
+
+Note: `createBackend` is `async` (returns `Promise<Backend>`). Always `await` it.
+
+See [docs.llmtxt.my/architecture/topology](https://docs.llmtxt.my/architecture/topology) and [docs/specs/ARCH-T429-hub-spoke-topology.md](../../docs/specs/ARCH-T429-hub-spoke-topology.md).
+
+## AgentSession Lifecycle
+
+Gives every agent an explicit, auditable lifecycle with crash recovery and signed contribution receipts.
+
+```ts
+import { AgentSession } from 'llmtxt/sdk';
+import type { ContributionReceipt } from 'llmtxt/sdk';
+
+const session = new AgentSession({ backend, agentId: 'agent-1' });
+await session.open();   // registers presence, allocates temp .db for LocalBackend sessions
+
+// contribute() returns T (whatever fn returns); receipt is from close()
+const doc = await session.contribute(async (b) => {
+  const created = await b.createDocument({ title: 'Spec', createdBy: 'agent-1' });
+  await b.publishVersion({
+    documentId: created.id,
+    content: '# Spec',
+    patchText: '',
+    createdBy: 'agent-1',
+    changelog: 'Initial',
+  });
+  return created;
+});
+
+const contributionReceipt: ContributionReceipt = await session.close();
+// Releases leases, drains inbox, deletes temp .db, emits signed ContributionReceipt
+```
+
+`ContributionReceipt` fields: `sessionId`, `agentId`, `documentIds`, `eventCount`, `sessionDurationMs`, `openedAt`, `closedAt`, `signature` (Ed25519 when RemoteBackend).
+
+See [docs.llmtxt.my/multi-agent/session-lifecycle](https://docs.llmtxt.my/multi-agent/session-lifecycle) and [docs/specs/ARCH-T426-ephemeral-agent-lifecycle.md](../../docs/specs/ARCH-T426-ephemeral-agent-lifecycle.md).
+
+## Document Export / Import
+
+```ts
+// Export a document to disk
+const result = await backend.exportDocument({
+  slug: 'my-spec',
+  format: 'markdown',   // 'markdown' | 'json' | 'txt' | 'llmtxt'
+  outputPath: './exports/my-spec.md',
+  sign: true,           // Ed25519-sign the export manifest
+});
+// result: { filePath, slug, version, fileHash, byteCount, exportedAt, signatureHex }
+
+// Export all documents
+const allResult = await backend.exportAll({ format: 'json', outputDir: './exports/' });
+
+// Import from file — creates doc or appends new version if slug exists
+const imported = await backend.importDocument({
+  filePath: './exports/my-spec.md',
+  importedBy: 'agent-1',
+  onConflict: 'new_version',  // 'new_version' | 'create'
+});
+```
+
+Formats: `markdown` (YAML frontmatter + body), `json` (structured), `txt` (body only), `llmtxt` (round-trippable with chain reference). Output is deterministic: same document state always produces identical file bytes.
+
+See [docs.llmtxt.my/sdk/export-import](https://docs.llmtxt.my/sdk/export-import) and [docs/specs/ARCH-T427-document-export-ssot.md](../../docs/specs/ARCH-T427-document-export-ssot.md).
+
+## Binary Blob Attachments
+
+```ts
+import * as fs from 'node:fs';
+
+// Attach a binary file to a document
+const attachment = await backend.attachBlob({
+  docSlug: 'my-spec',
+  name: 'diagram.png',
+  data: fs.readFileSync('./diagram.png'),
+  contentType: 'image/png',
+  uploadedBy: 'agent-1',
+});
+
+// Read back — hash verified on every read when includeData=true
+const blob = await backend.getBlob('my-spec', 'diagram.png', { includeData: true });
+
+// List attachments (metadata only, no bytes)
+const blobs = await backend.listBlobs('my-spec');
+
+// Remove
+await backend.detachBlob('my-spec', 'diagram.png', 'agent-1');
+```
+
+Blobs are content-addressed (SHA-256). Hash verification is mandatory on read — corrupt bytes are never returned. Max default size: 100 MB. Conflict resolution: Last Write Wins per attachment name.
+
+See [docs.llmtxt.my/sdk/blob-attachments](https://docs.llmtxt.my/sdk/blob-attachments) and [docs/specs/ARCH-T428-binary-blob-attachments.md](../../docs/specs/ARCH-T428-binary-blob-attachments.md).
+
+## cr-sqlite LocalBackend (Changeset Sync)
+
+Install the optional peer dependency to enable changeset-based sync between LocalBackend instances:
+
+```bash
+npm install @vlcn.io/crsqlite
+```
+
+```ts
+import { createBackend } from 'llmtxt';
+
+const backend = await createBackend({
+  topology: 'standalone',
+  storagePath: './.llmtxt',
+  crsqlite: true,   // requires @vlcn.io/crsqlite peer dep
+});
+
+// Exchange changesets with another agent
+const changes = await backend.getChangesSince({ version: lastSyncVersion });
+await otherBackend.applyChanges({ changes });
+```
+
+Single-tenant only (one agent per `.db`). Loro CRDT state in the `crdt_state` column is merged at the application level (not via cr-sqlite row merge). See [docs/specs/P2-cr-sqlite.md](../../docs/specs/P2-cr-sqlite.md).
+
+## P2P Mesh
+
+```ts
+import { createBackend } from 'llmtxt';
+
+const backend = await createBackend({
+  topology: 'mesh',
+  storagePath: './.llmtxt',
+  peers: ['unix:/tmp/agent-b.sock', 'http://192.168.1.5:7642'],
+});
+await backend.open();
+// Sync engine starts; Ed25519 mutual handshake required for each peer connection
+```
+
+See [docs.llmtxt.my/mesh](https://docs.llmtxt.my/mesh) and [docs/specs/P3-p2p-mesh.md](../../docs/specs/P3-p2p-mesh.md).
+
+## Loro CRDT (replaces Yrs)
+
+v2026.4.6 replaced `yrs` with `loro` 1.0 in `crates/llmtxt-core`. The six WASM function names are unchanged (`crdt_new_doc`, `crdt_encode_state_as_update`, `crdt_apply_update`, `crdt_merge_updates`, `crdt_state_vector`, `crdt_diff_update`) but their binary format is incompatible with previous versions.
+
+**Wire protocol change**: 1-byte message prefix `0x01`/`0x02`/`0x03`/`0x04` replaces the y-sync `0x00`/`0x01`/`0x02`/`0x03` framing. Legacy Yjs clients will be rejected.
+
+**Migration**: No data migration path. Drop all `section_crdt_states` and `section_crdt_updates` rows on deploy. See [docs/specs/P1-loro-migration.md](../../docs/specs/P1-loro-migration.md).
+
 ## Primitives
 
 ```ts
@@ -27,16 +230,9 @@ const hash = hashContent(text);
 
 const patch = createPatch('hello\n', 'hello world\n');
 const rebuilt = applyPatch('hello\n', patch);
-```
-
-## Multi-Way Diff and Cherry-Pick Merge
 
-```ts
-import { multiWayDiff, cherryPickMerge } from 'llmtxt';
-
-// Compare multiple agent versions against a base using LCS alignment
+// LCS-aligned multi-way diff across agent versions
 const diff = multiWayDiff(base, JSON.stringify([v2Content, v3Content, v4Content]));
-// Returns MultiDiffResult: { sections, totalVersions, baseTokenCount }
 
 // Selectively merge sections from different versions
 const merged = cherryPickMerge(
@@ -47,80 +243,72 @@ const merged = cherryPickMerge(
     { section: 'API Reference', fromVersion: 2 },
   ])
 );
-// Returns CherryPickResult: { content, provenance, stats }
-```
-
-## SDK (Collaborative Documents)
-
-```ts
-import {
-  isValidTransition, evaluateApprovals, planRetrieval,
-  reconstructVersion, attributeVersion, buildContributorSummary,
-} from 'llmtxt/sdk';
 ```
 
-### Subpath Exports
+## Subpath Exports
 
 ```ts
+import { AgentSession } from 'llmtxt/sdk';
+import { createBackend } from 'llmtxt/topology';
+import { LocalBackend } from 'llmtxt/local';
+import { RemoteBackend } from 'llmtxt/remote';
 import { generateOverview, getSection } from 'llmtxt/disclosure';
 import { textSimilarity, rankBySimilarity } from 'llmtxt/similarity';
 import { buildGraph } from 'llmtxt/graph';
 ```
 
-## LocalBackend (Embedded, Zero-Network)
-
-```ts
-import { LocalBackend } from 'llmtxt/local';
-
-const backend = new LocalBackend({ storagePath: './.llmtxt' });
-await backend.open();
-
-const doc = await backend.createDocument({ title: 'My Spec', createdBy: 'agent-1' });
-await backend.publishVersion({ documentId: doc.id, content: '# Spec', patchText: '', createdBy: 'agent-1', changelog: 'Initial' });
-await backend.close();
-```
-
-## RemoteBackend (HTTP/WS Client)
-
-```ts
-import { RemoteBackend } from 'llmtxt/remote';
-
-const backend = new RemoteBackend({ baseUrl: 'https://api.llmtxt.my', apiKey: process.env.LLMTXT_API_KEY });
-await backend.open();
-// Same calls as LocalBackend — same Backend interface.
-await backend.close();
-```
-
-## CLI
+## CLI Reference
 
 ```bash
-# Initialise local storage + identity keypair
+# Core
 llmtxt init
-
-# Create a document
 llmtxt create-doc "My Specification"
-
-# Push a version from stdin
-cat spec.md | llmtxt push-version my-specification "First draft"
-
-# Sync local ↔ remote
+cat spec.md | llmtxt push-version my-spec "First draft"
 llmtxt sync --remote https://api.llmtxt.my --api-key $KEY
+
+# Export / Import
+llmtxt export <slug> --format md --output ./specs/
+llmtxt export <slug> --format json --output ./exports/ --sign
+llmtxt export-all --format md --output ./docs/
+llmtxt import ./specs/my-doc.md
+
+# Binary blob attachments
+llmtxt attach <slug> ./diagram.png --name diagram.png
+llmtxt blobs <slug>
+llmtxt detach <slug> diagram.png
+
+# Agent session lifecycle
+llmtxt session start <agentId>
+llmtxt session end <sessionId>
+
+# P2P mesh
+llmtxt mesh start
+llmtxt mesh stop
+llmtxt mesh status
+llmtxt mesh peers
+llmtxt mesh sync
 ```
 
 ## What Ships
 
 - Compression, hashing, base62, token estimation (Rust WASM)
-- Signed URL generation and verification
+- Signed URL generation and verification (HMAC-SHA256, Ed25519)
 - Unified diff patch creation, application, version reconstruction
+- Loro CRDT via WASM (crdt_new_doc, crdt_apply_update, crdt_merge_updates, crdt_diff_update)
 - Multi-way diff across up to 5 agent versions (LCS-aligned, WASM)
 - Cherry-pick merge: selectively assemble sections from multiple versions (WASM)
 - Progressive disclosure: overview, section extraction, content search
 - Collaborative document lifecycle (DRAFT, REVIEW, LOCKED, ARCHIVED)
+- AgentSession: open / contribute / close with signed ContributionReceipt
+- Document export (4 formats, deterministic, signed) and import
+- Binary blob attachments (content-addressed SHA-256, hash-verify-on-read)
+- Topology factory: standalone / hub-spoke / mesh via `createBackend()`
+- cr-sqlite changeset sync (optional peer dep `@vlcn.io/crsqlite`)
+- P2P mesh sync engine (Ed25519 mutual handshake, Unix socket + HTTP transports)
 - Version stack management with attribution tracking
 - Consensus/approval evaluation with stale review handling
 - Token-budget-aware retrieval planning
 - Storage content reference abstractions (inline vs object-store)
-- Attachment client helpers for upload, fetch, reshare, versioning
 
 ## Release Model
 

package/dist/__tests__/a2a.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * a2a.test.ts — T419: A2A over Mesh tests
+ *
+ * 5 tests covering:
+ *  1. Direct send: signed message delivered to directly-connected peer.
+ *  2. SECURITY: unsigned/invalid-sig message is rejected before delivery.
+ *  3. Relay path: message forwarded via connected peer when target not direct.
+ *  4. Queue: message queued locally when no relay path found.
+ *  5. Payload size limit: payload >1 MB is rejected at send.
+ *
+ * Spec: P3-p2p-mesh.md §7, §10
+ */
+export {};
+//# sourceMappingURL=a2a.test.d.ts.map

package/dist/__tests__/a2a.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/a2a.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/__tests__/a2a.test.js

@@ -0,0 +1,217 @@
+/**
+ * a2a.test.ts — T419: A2A over Mesh tests
+ *
+ * 5 tests covering:
+ *  1. Direct send: signed message delivered to directly-connected peer.
+ *  2. SECURITY: unsigned/invalid-sig message is rejected before delivery.
+ *  3. Relay path: message forwarded via connected peer when target not direct.
+ *  4. Queue: message queued locally when no relay path found.
+ *  5. Payload size limit: payload >1 MB is rejected at send.
+ *
+ * Spec: P3-p2p-mesh.md §7, §10
+ */
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { AgentIdentity } from '../identity.js';
+import { MeshMessenger } from '../mesh/a2a.js';
+// ── Helpers ───────────────────────────────────────────────────────
+const MSG_TYPE_A2A = 0x10;
+function buildA2AFrame(envelope) {
+    const json = JSON.stringify(envelope);
+    const jsonBytes = new TextEncoder().encode(json);
+    const out = new Uint8Array(1 + jsonBytes.length);
+    out[0] = MSG_TYPE_A2A;
+    out.set(jsonBytes, 1);
+    return out;
+}
+function mockTransport(opts) {
+    const sent = [];
+    let listener;
+    return {
+        type: 'mock-a2a',
+        sent,
+        simulateInbound(peerId, data) {
+            listener?.(peerId, data);
+        },
+        async listen(cb) {
+            listener = cb;
+        },
+        async sendChangeset(peerId, _address, data) {
+            if (opts?.failForPeer && peerId === opts.failForPeer) {
+                throw new Error(`[mock] peer ${peerId} unreachable`);
+            }
+            sent.push({ peerId, data });
+            await opts?.onSend?.(peerId, data);
+        },
+        async close() {
+            // no-op
+        },
+    };
+}
+function mockDiscovery(peers) {
+    return {
+        async discover() {
+            return peers;
+        },
+        markInactive(_id) { },
+    };
+}
+async function makeIdentity() {
+    const seed = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(seed);
+    return AgentIdentity.fromSeed(seed);
+}
+// ── Tests ─────────────────────────────────────────────────────────
+describe('MeshMessenger', () => {
+    let senderIdentity;
+    let recipientIdentity;
+    before(async () => {
+        senderIdentity = await makeIdentity();
+        recipientIdentity = await makeIdentity();
+    });
+    it('test-1: direct send — signed message delivered to directly-connected peer', async () => {
+        const transport = mockTransport();
+        const peers = [
+            {
+                agentId: recipientIdentity.pubkeyHex,
+                address: 'unix:/tmp/recv.sock',
+                pubkeyBase64: Buffer.from(recipientIdentity.pk).toString('base64'),
+            },
+        ];
+        const discovery = mockDiscovery(peers);
+        const received = [];
+        const messenger = new MeshMessenger({
+            identity: senderIdentity,
+            transport,
+            discovery,
+            onMessage: (env) => received.push(env),
+        });
+        await messenger.start();
+        await messenger.send(recipientIdentity.pubkeyHex, { action: 'ping' });
+        await messenger.stop();
+        assert.equal(transport.sent.length, 1, 'one send call expected');
+        const frame = transport.sent[0];
+        assert.equal(frame.peerId, recipientIdentity.pubkeyHex);
+        assert.equal(frame.data[0], MSG_TYPE_A2A);
+        // Decode envelope.
+        const json = new TextDecoder().decode(frame.data.slice(1));
+        const env = JSON.parse(json);
+        assert.equal(env.type, 'a2a');
+        assert.equal(env.from, senderIdentity.pubkeyHex);
+        assert.equal(env.to, recipientIdentity.pubkeyHex);
+        assert.ok(typeof env.sig === 'string' && env.sig.length > 0, 'message must be signed');
+        assert.deepEqual(env.payload, { action: 'ping' });
+    });
+    it('test-2: SECURITY — unsigned/invalid-sig inbound message is rejected', async () => {
+        const transport = mockTransport();
+        const discovery = mockDiscovery([]);
+        const received = [];
+        const rejections = [];
+        const messenger = new MeshMessenger({
+            identity: recipientIdentity,
+            transport,
+            discovery,
+            onMessage: (env) => received.push(env),
+        });
+        messenger.on('security-rejection', (r) => rejections.push(r));
+        await messenger.start();
+        // Build a message with an invalid signature.
+        const badEnvelope = {
+            type: 'a2a',
+            from: senderIdentity.pubkeyHex,
+            to: recipientIdentity.pubkeyHex,
+            payload: { action: 'malicious' },
+            sig: Buffer.from('invalid-sig-bytes-xxxx').toString('base64'),
+            sentAt: new Date().toISOString(),
+        };
+        const frame = buildA2AFrame(badEnvelope);
+        transport.simulateInbound('attacker', frame);
+        // Allow async verification to complete.
+        await new Promise((r) => setTimeout(r, 100));
+        await messenger.stop();
+        assert.equal(received.length, 0, 'message with invalid sig MUST NOT be delivered');
+        assert.ok(rejections.length >= 1, 'security-rejection event must be emitted');
+    });
+    it('test-3: relay path — message forwarded through connected peer', async () => {
+        // senderIdentity → relay agent → recipientIdentity
+        const relayAgentId = 'relay-agent-hex-pubkey';
+        const transport = mockTransport();
+        // Only relay is directly connected; recipient is NOT in peer list.
+        const peers = [
+            {
+                agentId: relayAgentId,
+                address: 'unix:/tmp/relay.sock',
+                pubkeyBase64: Buffer.alloc(32, 0x44).toString('base64'),
+            },
+        ];
+        const discovery = mockDiscovery(peers);
+        const messenger = new MeshMessenger({
+            identity: senderIdentity,
+            transport,
+            discovery,
+        });
+        await messenger.start();
+        // Should relay since recipient not directly connected.
+        await messenger.send(recipientIdentity.pubkeyHex, { action: 'routed-task' });
+        await messenger.stop();
+        // Message should have been sent to relay agent.
+        const relaySends = transport.sent.filter((s) => s.peerId === relayAgentId);
+        assert.ok(relaySends.length >= 1, 'message must be forwarded to relay peer');
+        // Verify the relay frame contains the inner envelope.
+        const relayFrame = relaySends[0];
+        assert.equal(relayFrame.data[0], MSG_TYPE_A2A);
+        const json = new TextDecoder().decode(relayFrame.data.slice(1));
+        const parsed = JSON.parse(json);
+        // The relay wraps in a relay frame.
+        assert.equal(parsed.type, 'relay', 'relay frame type must be "relay"');
+        assert.ok(parsed.inner, 'relay frame must contain inner envelope');
+        assert.equal(parsed.inner.to, recipientIdentity.pubkeyHex);
+    });
+    it('test-4: no-path — message queued locally when no relay found', async () => {
+        const transport = mockTransport();
+        // No peers at all — no direct or relay path.
+        const discovery = mockDiscovery([]);
+        const queued = [];
+        const messenger = new MeshMessenger({
+            identity: senderIdentity,
+            transport,
+            discovery,
+        });
+        messenger.on('queued', (e) => queued.push(e));
+        await messenger.start();
+        await messenger.send(recipientIdentity.pubkeyHex, { action: 'offline-task' });
+        await messenger.stop();
+        assert.equal(transport.sent.length, 0, 'nothing must be sent when no path exists');
+        const status = messenger.getQueueStatus();
+        const totalQueued = Object.values(status).reduce((a, b) => a + b, 0);
+        assert.ok(totalQueued >= 1, 'message must be queued locally');
+        assert.ok(queued.length >= 1, 'queued event must be emitted');
+    });
+    it('test-5: payload >1 MB is rejected at send', async () => {
+        const transport = mockTransport();
+        const peers = [
+            {
+                agentId: recipientIdentity.pubkeyHex,
+                address: 'unix:/tmp/recv.sock',
+                pubkeyBase64: Buffer.from(recipientIdentity.pk).toString('base64'),
+            },
+        ];
+        const discovery = mockDiscovery(peers);
+        const messenger = new MeshMessenger({
+            identity: senderIdentity,
+            transport,
+            discovery,
+        });
+        await messenger.start();
+        // Build a payload just over 1 MB.
+        const bigString = 'x'.repeat(1024 * 1024 + 1);
+        await assert.rejects(() => messenger.send(recipientIdentity.pubkeyHex, { data: bigString }), (err) => {
+            assert.ok(err instanceof Error, 'must throw an Error');
+            assert.ok(err.message.includes('1 MB'), `error message must mention 1 MB limit, got: ${err.message}`);
+            return true;
+        }, 'send must reject payloads over 1 MB');
+        assert.equal(transport.sent.length, 0, 'oversized payload must not be sent');
+        await messenger.stop();
+    });
+});
+//# sourceMappingURL=a2a.test.js.map

package/dist/__tests__/a2a.test.js.map

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

package/dist/__tests__/backend-contract.test.d.ts

@@ -1,13 +1,24 @@
 /**
- * Backend contract test suite.
+ * Backend contract test suite — parametrized over LocalBackend and PostgresBackend.
  *
- * Runs the same set of behavioural assertions against any Backend
- * implementation. Currently validates LocalBackend; RemoteBackend is
- * validated against a mock HTTP server when one is available (skipped
- * in CI without a running server).
+ * Runs the same set of behavioural assertions against any Backend implementation.
+ * Each describe block receives a BackendFactory and runs identical assertions
+ * regardless of which backend is under test.
  *
- * Pattern: each `describe` block receives a `BackendFactory` and runs
- * identical assertions regardless of which implementation is under test.
+ * Backends:
+ *  - LocalBackend (SQLite, temp dir) — always runs.
+ *  - PostgresBackend (Postgres via DATABASE_URL_PG env) — skipped with WARN if
+ *    DATABASE_URL_PG is not set. Never fails the suite when absent.
+ *
+ * Output format:
+ *   [LocalBackend] documents.create …
+ *   [PostgresBackend] documents.create …  (or SKIPPED if no PG)
+ *
+ * Multi-agent semantic tests (added in T361):
+ *   - Lease contention: agent-1 acquires, agent-2 blocked, release, agent-2 acquires.
+ *   - A2A round-trip: send + pollInbox + markRead (deleteA2AMessage).
+ *   - Scratchpad round-trip: send + poll + delete.
+ *   - Identity: register + lookup + revoke + nonce replay prevention.
  */
 export {};
 //# sourceMappingURL=backend-contract.test.d.ts.map

package/dist/__tests__/backend-contract.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend-contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/backend-contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}
+{"version":3,"file":"backend-contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/backend-contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}