llmtxt 2026.4.4 → 2026.4.5

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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`.
+
+### Added — Portable SDK / LocalBackend (T317)
+
+**T332: RemoteBackend** (`llmtxt/remote`) — thin HTTP/WS client implementing the
+full `Backend` interface. REST for CRUD, SSE for `subscribeStream`, WebSocket for
+`subscribeSection`. Drop-in replacement for `LocalBackend` for remote deployments.
+
+**T333: Backend contract test suite** — 25-test parameterised harness that
+validates any `Backend` implementation against the full interface contract.
+Covers documents, versions, lifecycle transitions, events, leases, scratchpad,
+A2A, identity, and nonces.
+
+**T334: Fastify LocalBackend plugin** (`apps/backend/src/plugins/local-backend-plugin.ts`)
+— Fastify plugin that decorates the app with `fastify.localBackend`. New routes
+can use the portable SDK without touching the existing Drizzle/Postgres layer.
+
+**T335 + T336: `llmtxt` CLI binary** — `packages/llmtxt/src/cli/llmtxt.ts`
+compiled to `dist/cli/llmtxt.js` and listed in `package.json bin`. Commands:
+`init` (SQLite + Ed25519 keypair), `create-doc`, `push-version`, `pull`, `watch`,
+`search`, `keys generate|list|revoke`, `sync`. Defaults to `LocalBackend`; use
+`--remote <url>` for `RemoteBackend`.
+
+**T337: `llmtxt sync`** — pulls remote events/documents not in local, pushes
+local documents/events not in remote. State vector exchange for CRDT sections.
+
+**T338: CLEO integration example** (`apps/examples/cleo-integration/index.ts`)
+— runnable end-to-end example showing 4 patterns: task attachment docs, BFT
+decision records, A2A coordination, real-time presence.
+
+**T339: Docs** (`apps/docs/content/docs/embed/cleo-pm.mdx`) — documentation
+page covering all 4 CLEO + LLMtxt integration patterns with working snippets.
+
+**T340: Subpath exports** — `llmtxt/local`, `llmtxt/remote`, `llmtxt/cli` added
+to `package.json` exports map with `types` + `import` entries.
+
+**Build**: `build` script now copies `src/local/migrations` into `dist/local/migrations`
+so the CLI and embedded consumers find migrations at runtime.
+
+### Fixed
+
+- **Migration idempotency** (7df5795): W2 leases (`20260416021212_natural_shiva`) and W3 BFT/A2A inbox (`20260416030000_w3_bft_a2a_inbox`) Postgres migrations are now fully idempotent — all `CREATE TABLE` / `CREATE INDEX` / `ADD CONSTRAINT` statements use `IF NOT EXISTS` guards and a redundant `ALTER TABLE` that caused Railway crash-loops on retry is removed.
+
+## [2026.4.4] - 2026-04-15
+
+### Changed — SDK-First Refactor (T111)
+
+All 22 violations from `docs/SSOT-AUDIT.md` resolved. `crates/llmtxt-core` is now the canonical Single Source of Truth (SSoT) for all portable primitives. `packages/llmtxt` is a thin WASM wrapper + TypeScript types. `apps/backend` imports only from the SDK — no more direct `node:crypto`, no more pure-TS re-implementations.
+
+**Rust primitives added to `crates/llmtxt-core`** (WASM-exported via `packages/llmtxt`):
+- `crypto::sign_webhook_payload` (HMAC-SHA256 for webhook signing) — replaces backend `createHmac`
+- `normalize::l2_normalize` (L2 vector normalization) — replaces backend inline TS
+- `slugify::slugify` — replaces backend inline TS
+- `rbac` module (ROLE_PERMISSIONS matrix lookups) — replaces backend matrix + types
+- `validation` module (`detect_format`, `contains_binary_content`, `find_overlong_line`) — replaces pure-TS re-implementations
+- `graph` module (mentions, tags, directives, graph build + top rankings) — replaces pure-TS `graph.ts`
+- `similarity` module (n-grams, jaccard, text/content similarity, min-hash, rank_by_similarity) — replaces pure-TS `similarity.ts`
+- `disclosure` module with submodules (markdown/code/json/text parsers, search, jsonpath, generateOverview) — replaces pure-TS `disclosure.ts` (729 LoC → ~100 LoC wrapper)
+- `tfidf` module (FNV1a hashing + TF-IDF batch embed) — replaces backend `LocalEmbeddingProvider`
+
+**TypeScript types/constants now exported from `packages/llmtxt`**:
+- `DocumentEventType`, `DocumentEvent`, `AuditAction`
+- `Permission`, `DocumentRole`, `OrgRole`, `ROLE_PERMISSIONS`
+- `CONTENT_LIMITS`, `API_VERSION_REGISTRY`, `CURRENT_API_VERSION`, `LATEST_API_VERSION`, `ApiVersionInfo`
+- `VALID_LINK_TYPES`
+- `COLLECTION_EXPORT_SEPARATOR`, `API_KEY_PREFIX`, `API_KEY_LENGTH`, `API_KEY_DISPLAY_LENGTH`
+- `STATE_CHANGING_METHODS` (deduplicated from audit + csrf middleware)
+
+### Deferred
+T112 (NAPI-RS native bindings) deferred 2026-04-15 pending production benchmark evidence. WASM is the sole Rust→JS binding for `llmtxt` until benchmarks justify native.
+
+### Testing
+- Cargo tests: 122 → 278 (+156 new Rust tests for migrated primitives)
+- Backend tests: 67/67 throughout — zero regression
+- Byte-identity tests: every migrated primitive verified Rust output == previous TypeScript output for ≥3 vectors
+
 ## [2026.4.3] - 2026-04-13
 
 ### Added
@@ -119,7 +197,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **cache**: generic LRU cache with configurable TTL, max size, and hit/miss statistics
 - **signed-url**: HMAC-SHA256 signed URL generation and verification -- conversation-scoped, time-limited, with timing-safe comparison
 
-[Unreleased]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.0...HEAD
+[Unreleased]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.5...HEAD
+[2026.4.5]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.4...core-v2026.4.5
+[2026.4.4]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.3...core-v2026.4.4
+[2026.4.3]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.2...core-v2026.4.3
+[2026.4.2]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.1...core-v2026.4.2
+[2026.4.1]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.0...core-v2026.4.1
 [2026.4.0]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.4.0
 [2026.3.1]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.3.1
 [2026.3.0]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.3.0

package/README.md

@@ -67,6 +67,46 @@ 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
+
+```bash
+# Initialise local storage + identity keypair
+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
+llmtxt sync --remote https://api.llmtxt.my --api-key $KEY
+```
+
 ## What Ships
 
 - Compression, hashing, base62, token estimation (Rust WASM)

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

@@ -0,0 +1,13 @@
+/**
+ * Backend contract test suite.
+ *
+ * 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).
+ *
+ * Pattern: each `describe` block receives a `BackendFactory` and runs
+ * identical assertions regardless of which implementation is under test.
+ */
+export {};
+//# sourceMappingURL=backend-contract.test.d.ts.map

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

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

package/dist/__tests__/backend-contract.test.js

@@ -0,0 +1,356 @@
+/**
+ * Backend contract test suite.
+ *
+ * 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).
+ *
+ * Pattern: each `describe` block receives a `BackendFactory` and runs
+ * identical assertions regardless of which implementation is under test.
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { LocalBackend } from '../local/local-backend.js';
+/**
+ * Make a temp dir for each test backend instance so tests are isolated.
+ */
+function makeTempDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'llmtxt-contract-'));
+}
+// ── Contract suite factory ────────────────────────────────────────
+function runContractSuite(label, factory) {
+    describe(`${label} — Backend contract`, () => {
+        let backend;
+        let cleanup;
+        before(async () => {
+            ({ backend, cleanup } = factory());
+            await backend.open();
+        });
+        after(async () => {
+            await backend.close();
+            await cleanup();
+        });
+        // ── Document CRUD ────────────────────────────────────────────
+        describe('createDocument / getDocument', () => {
+            it('creates a document and retrieves it by id', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Contract Test Doc',
+                    createdBy: 'test-agent',
+                });
+                assert.ok(doc.id, 'document id must be truthy');
+                assert.equal(doc.title, 'Contract Test Doc');
+                assert.equal(doc.createdBy, 'test-agent');
+                assert.equal(doc.state, 'DRAFT');
+                assert.equal(doc.versionCount, 0);
+                const fetched = await backend.getDocument(doc.id);
+                assert.ok(fetched, 'getDocument must return the document');
+                assert.equal(fetched.id, doc.id);
+                assert.equal(fetched.title, doc.title);
+            });
+            it('getDocument returns null for unknown id', async () => {
+                const result = await backend.getDocument('nonexistent-id-xyz');
+                assert.equal(result, null, 'must return null for missing document');
+            });
+            it('generates a unique slug from the title', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Slug Test Document',
+                    createdBy: 'agent',
+                });
+                assert.ok(doc.slug, 'slug must be set');
+                assert.match(doc.slug, /^[a-z0-9-]+$/, 'slug must be url-safe');
+            });
+            it('accepts an explicit slug', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Explicit Slug Doc',
+                    createdBy: 'agent',
+                    slug: 'my-explicit-slug',
+                });
+                assert.equal(doc.slug, 'my-explicit-slug');
+            });
+            it('getDocumentBySlug retrieves a document', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Slug Lookup Test',
+                    createdBy: 'agent',
+                    slug: 'slug-lookup-unique',
+                });
+                const found = await backend.getDocumentBySlug('slug-lookup-unique');
+                assert.ok(found);
+                assert.equal(found.id, doc.id);
+            });
+            it('getDocumentBySlug returns null for unknown slug', async () => {
+                const result = await backend.getDocumentBySlug('does-not-exist');
+                assert.equal(result, null);
+            });
+        });
+        describe('listDocuments', () => {
+            it('returns documents with pagination', async () => {
+                const result = await backend.listDocuments({ limit: 100 });
+                assert.ok(Array.isArray(result.items));
+                assert.ok(result.items.length >= 1, 'at least one document from prior tests');
+            });
+        });
+        describe('deleteDocument', () => {
+            it('deletes an existing document and returns true', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Delete Me',
+                    createdBy: 'agent',
+                });
+                const deleted = await backend.deleteDocument(doc.id);
+                assert.equal(deleted, true);
+                const fetched = await backend.getDocument(doc.id);
+                assert.equal(fetched, null, 'must not exist after deletion');
+            });
+            it('returns false for nonexistent document', async () => {
+                const result = await backend.deleteDocument('never-existed');
+                assert.equal(result, false);
+            });
+        });
+        // ── Versions ─────────────────────────────────────────────────
+        describe('publishVersion / getVersion / listVersions', () => {
+            it('publishes and retrieves a version', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Version Test Doc',
+                    createdBy: 'agent',
+                });
+                const version = await backend.publishVersion({
+                    documentId: doc.id,
+                    content: '# Hello\n\nThis is version 1.',
+                    patchText: '',
+                    createdBy: 'agent',
+                    changelog: 'Initial version',
+                });
+                assert.equal(version.versionNumber, 1);
+                assert.equal(version.createdBy, 'agent');
+                assert.equal(version.changelog, 'Initial version');
+                assert.ok(version.contentHash, 'contentHash must be set');
+                const fetched = await backend.getVersion(doc.id, 1);
+                assert.ok(fetched);
+                assert.equal(fetched.versionNumber, 1);
+                assert.equal(fetched.contentHash, version.contentHash);
+            });
+            it('increments versionCount on the document', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Version Count Test',
+                    createdBy: 'agent',
+                });
+                await backend.publishVersion({
+                    documentId: doc.id,
+                    content: 'v1',
+                    patchText: '',
+                    createdBy: 'agent',
+                    changelog: 'v1',
+                });
+                await backend.publishVersion({
+                    documentId: doc.id,
+                    content: 'v2',
+                    patchText: '',
+                    createdBy: 'agent',
+                    changelog: 'v2',
+                });
+                const updated = await backend.getDocument(doc.id);
+                assert.ok(updated);
+                assert.equal(updated.versionCount, 2);
+            });
+            it('getVersion returns null for unknown version', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Version Null Test',
+                    createdBy: 'agent',
+                });
+                const result = await backend.getVersion(doc.id, 999);
+                assert.equal(result, null);
+            });
+            it('listVersions returns all versions in order', async () => {
+                const doc = await backend.createDocument({
+                    title: 'List Versions Test',
+                    createdBy: 'agent',
+                });
+                await backend.publishVersion({ documentId: doc.id, content: 'v1', patchText: '', createdBy: 'agent', changelog: 'v1' });
+                await backend.publishVersion({ documentId: doc.id, content: 'v2', patchText: '', createdBy: 'agent', changelog: 'v2' });
+                const versions = await backend.listVersions(doc.id);
+                assert.equal(versions.length, 2);
+                assert.equal(versions[0].versionNumber, 1);
+                assert.equal(versions[1].versionNumber, 2);
+            });
+        });
+        describe('transitionVersion', () => {
+            it('transitions DRAFT → REVIEW', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Lifecycle Transition Test',
+                    createdBy: 'agent',
+                });
+                const result = await backend.transitionVersion({
+                    documentId: doc.id,
+                    to: 'REVIEW',
+                    changedBy: 'agent',
+                });
+                assert.equal(result.success, true);
+                assert.ok(result.document);
+                assert.equal(result.document.state, 'REVIEW');
+            });
+            it('rejects invalid transitions', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Invalid Transition Test',
+                    createdBy: 'agent',
+                });
+                // DRAFT → ARCHIVED is not a valid direct transition
+                const result = await backend.transitionVersion({
+                    documentId: doc.id,
+                    to: 'ARCHIVED',
+                    changedBy: 'agent',
+                });
+                assert.equal(result.success, false);
+                assert.ok(result.error, 'error message must be provided');
+            });
+        });
+        // ── Events ───────────────────────────────────────────────────
+        describe('appendEvent / queryEvents', () => {
+            it('appends and queries events', async () => {
+                const doc = await backend.createDocument({
+                    title: 'Event Test Doc',
+                    createdBy: 'agent',
+                });
+                const event = await backend.appendEvent({
+                    documentId: doc.id,
+                    type: 'test.event',
+                    agentId: 'agent',
+                    payload: { foo: 'bar' },
+                });
+                assert.ok(event.id);
+                assert.equal(event.documentId, doc.id);
+                assert.equal(event.type, 'test.event');
+                assert.deepEqual(event.payload, { foo: 'bar' });
+                const result = await backend.queryEvents({ documentId: doc.id });
+                assert.ok(result.items.length >= 1);
+                assert.equal(result.items[0].type, 'test.event');
+            });
+        });
+        // ── Leases ───────────────────────────────────────────────────
+        describe('acquireLease / renewLease / releaseLease / getLease', () => {
+            it('acquires, checks, and releases a lease', async () => {
+                const resource = `test-resource-${Date.now()}`;
+                const lease = await backend.acquireLease({
+                    resource,
+                    holder: 'agent-1',
+                    ttlMs: 5000,
+                });
+                assert.ok(lease, 'lease must be acquired');
+                assert.equal(lease.resource, resource);
+                assert.equal(lease.holder, 'agent-1');
+                const fetched = await backend.getLease(resource);
+                assert.ok(fetched);
+                assert.equal(fetched.holder, 'agent-1');
+                const released = await backend.releaseLease(resource, 'agent-1');
+                assert.equal(released, true);
+                const afterRelease = await backend.getLease(resource);
+                assert.equal(afterRelease, null);
+            });
+            it('blocks second agent from acquiring held lease', async () => {
+                const resource = `contested-${Date.now()}`;
+                await backend.acquireLease({ resource, holder: 'agent-1', ttlMs: 5000 });
+                const second = await backend.acquireLease({ resource, holder: 'agent-2', ttlMs: 5000 });
+                assert.equal(second, null, 'second agent must not acquire a held lease');
+                await backend.releaseLease(resource, 'agent-1');
+            });
+            it('allows same holder to re-acquire (idempotent)', async () => {
+                const resource = `reacquire-${Date.now()}`;
+                const first = await backend.acquireLease({ resource, holder: 'agent-1', ttlMs: 5000 });
+                const second = await backend.acquireLease({ resource, holder: 'agent-1', ttlMs: 5000 });
+                assert.ok(first);
+                assert.ok(second, 'same holder re-acquire must succeed');
+                await backend.releaseLease(resource, 'agent-1');
+            });
+        });
+        // ── Scratchpad ───────────────────────────────────────────────
+        describe('sendScratchpad / pollScratchpad / deleteScratchpadMessage', () => {
+            it('sends and polls a scratchpad message', async () => {
+                const msg = await backend.sendScratchpad({
+                    toAgentId: 'rx-agent',
+                    fromAgentId: 'tx-agent',
+                    payload: { task: 'do the thing' },
+                });
+                assert.ok(msg.id);
+                assert.equal(msg.toAgentId, 'rx-agent');
+                assert.deepEqual(msg.payload, { task: 'do the thing' });
+                const polled = await backend.pollScratchpad('rx-agent');
+                const found = polled.find((m) => m.id === msg.id);
+                assert.ok(found, 'message must be pollable');
+                const deleted = await backend.deleteScratchpadMessage(msg.id, 'rx-agent');
+                assert.equal(deleted, true);
+                const afterDelete = await backend.pollScratchpad('rx-agent');
+                const stillThere = afterDelete.find((m) => m.id === msg.id);
+                assert.equal(stillThere, undefined, 'message must not appear after deletion');
+            });
+        });
+        // ── A2A ──────────────────────────────────────────────────────
+        describe('sendA2AMessage / pollA2AInbox / deleteA2AMessage', () => {
+            it('delivers and polls an A2A message', async () => {
+                const sent = await backend.sendA2AMessage({
+                    toAgentId: 'target-agent',
+                    envelopeJson: JSON.stringify({ op: 'ping', from: 'sender' }),
+                });
+                assert.equal(sent.success, true);
+                assert.ok(sent.message);
+                assert.equal(sent.message.toAgentId, 'target-agent');
+                const inbox = await backend.pollA2AInbox('target-agent');
+                const found = inbox.find((m) => m.id === sent.message.id);
+                assert.ok(found);
+                const deleted = await backend.deleteA2AMessage(sent.message.id, 'target-agent');
+                assert.equal(deleted, true);
+            });
+        });
+        // ── Identity ─────────────────────────────────────────────────
+        describe('registerAgentPubkey / lookupAgentPubkey / revokeAgentPubkey', () => {
+            it('registers, looks up, and revokes a pubkey', async () => {
+                const agentId = `agent-${Date.now()}`;
+                const pubkeyHex = 'a'.repeat(64); // fake but syntactically valid
+                const record = await backend.registerAgentPubkey(agentId, pubkeyHex, 'Test Key');
+                assert.equal(record.agentId, agentId);
+                assert.equal(record.pubkeyHex, pubkeyHex);
+                const fetched = await backend.lookupAgentPubkey(agentId);
+                assert.ok(fetched);
+                assert.equal(fetched.agentId, agentId);
+                const revoked = await backend.revokeAgentPubkey(agentId, pubkeyHex);
+                assert.equal(revoked, true);
+            });
+            it('registerAgentPubkey is idempotent', async () => {
+                const agentId = `idem-agent-${Date.now()}`;
+                const pubkeyHex = 'b'.repeat(64);
+                await backend.registerAgentPubkey(agentId, pubkeyHex);
+                const second = await backend.registerAgentPubkey(agentId, pubkeyHex);
+                assert.equal(second.agentId, agentId, 'idempotent: no error on second call');
+            });
+            it('lookupAgentPubkey returns null for unregistered agent', async () => {
+                const result = await backend.lookupAgentPubkey('never-registered');
+                assert.equal(result, null);
+            });
+        });
+        describe('recordSignatureNonce / hasNonceBeenUsed', () => {
+            it('records and checks nonces', async () => {
+                const agentId = `nonce-agent-${Date.now()}`;
+                const nonce = `nonce-${Date.now()}`;
+                const first = await backend.recordSignatureNonce(agentId, nonce);
+                assert.equal(first, true, 'first recording must succeed');
+                const second = await backend.recordSignatureNonce(agentId, nonce);
+                assert.equal(second, false, 'duplicate nonce must be rejected');
+                const used = await backend.hasNonceBeenUsed(agentId, nonce);
+                assert.equal(used, true);
+            });
+        });
+    });
+}
+// ── Run contract suite against LocalBackend ───────────────────────
+runContractSuite('LocalBackend', () => {
+    const dir = makeTempDir();
+    const backend = new LocalBackend({ storagePath: dir });
+    return {
+        backend,
+        cleanup: async () => {
+            fs.rmSync(dir, { recursive: true, force: true });
+        },
+    };
+});
+//# sourceMappingURL=backend-contract.test.js.map

package/dist/__tests__/backend-contract.test.js.map

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

package/dist/awareness.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Awareness SDK module — T257.
+ *
+ * Implements the setLocalAwarenessState / onAwarenessChange / getAwarenessStates
+ * surface over a raw WebSocket connection.
+ *
+ * The y-protocols/awareness library is used for encoding/decoding awareness
+ * update messages (CRDT-aware awareness protocol). Since direct yjs imports are
+ * banned by the SSoT lint rule, this module relies on the re-exported
+ * primitives from the llmtxt SDK (which wraps the WASM core).
+ *
+ * Awareness message framing on the wire:
+ *   Byte 0 = 0x03 (MSG_AWARENESS_RELAY, matching ws-crdt.ts constant)
+ *   Bytes 1..N = raw y-protocols awareness update bytes
+ */
+/**
+ * Presence state for a single agent.
+ */
+export interface AwarenessState {
+    agentId: string;
+    section: string;
+    cursorOffset?: number;
+    lastSeen: number;
+}
+/**
+ * Events emitted when awareness state changes.
+ */
+export type AwarenessEventType = 'JOIN' | 'LEAVE' | 'MOVE';
+export interface AwarenessEvent {
+    type: AwarenessEventType;
+    clientId: number;
+    state: AwarenessState | null;
+}
+/**
+ * Unsubscribe function returned by onAwarenessChange.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Set the local agent's awareness state on a WebSocket connection.
+ * Encodes the state and sends it to the server (which relays to peers).
+ *
+ * @param conn   Active WebSocket connection.
+ * @param state  The awareness state to broadcast.
+ */
+export declare function setLocalAwarenessState(conn: WebSocket | {
+    send(data: Uint8Array | Buffer): void;
+}, state: AwarenessState): void;
+/**
+ * Subscribe to awareness state changes on a WebSocket connection.
+ * The callback is invoked with the full current state map whenever
+ * a peer's awareness changes.
+ *
+ * @param conn  Active WebSocket connection.
+ * @param fn    Callback invoked with updated Map<clientId, AwarenessState>.
+ * @returns     Unsubscribe function.
+ */
+export declare function onAwarenessChange(conn: WebSocket | {
+    on?(event: string, handler: (data: Buffer | Uint8Array) => void): void;
+    addEventListener?(type: string, handler: (event: {
+        data: unknown;
+    }) => void): void;
+}, fn: (states: Map<number, AwarenessState>) => void): Unsubscribe;
+/**
+ * Get the current awareness states for all known clients on a connection.
+ *
+ * @param conn  Active WebSocket connection.
+ * @returns     Map<clientId, AwarenessState>.
+ */
+export declare function getAwarenessStates(conn: WebSocket | object): Map<number, AwarenessState>;
+//# sourceMappingURL=awareness.d.ts.map

package/dist/awareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../src/awareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAgJrC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG;IAAE,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CA0B/H;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,GAAG;IAAE,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAA;CAAE,EAChL,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,IAAI,GAChD,WAAW,CA6Eb;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAExF"}