@weave-kit/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WeaveKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @weave-kit/engine
+
+Metadata-driven headless backend engine. Author objects in `schema.json` — get PostgreSQL tables, a governed REST API with field/row-level RBAC, an immutable audit log, an MCP tool surface for AI agents, and object-level TypeScript types. Built with TypeScript + Node 24 (Fastify + PostgreSQL).
+
+The engine renders no UI and ships no business logic: it compiles your metadata into a database schema, a typed API, and agent tools.
+
+```
+objects/leads/schema.json   →   PostgreSQL tables + indexes + RLS
+                                REST API (CRUD + RBAC)
+                                MCP tools (agent interface + guardrails)
+                                Audit log
+                                TypeScript types
+```
+
+## Quick start
+
+```sh
+npm i create-weavekit-app && npx create-weavekit-app my-app --type=agent
+cd my-app
+cp .env.example .env      # set DATABASE_URL
+weave migrate             # state-diff migration: schema.json → PG tables (+ metadata cache)
+weave dev                 # http://localhost:3000 — hot reload
+weave types               # object-level TS types → generated/types.ts
+```
+
+**Existing database?** Reverse-model it instead of authoring from scratch:
+
+```sh
+weave introspect          # live tables → objects/<table>/schema.json (read-only, alter:false)
+weave schema:map          # schema field ↔ PostgreSQL column mapping + drift
+```
+
+**Connect an agent** (MCP is enabled by default at `/mcp`):
+
+```sh
+weave mcp:config          # ready-to-paste config for Claude Code / Cursor / VS Code / Claude Desktop
+```
+
+Programmatic assembly:
+
+```ts
+import { createEngine } from '@weave-kit/engine';
+
+const engine = await createEngine({
+  databaseUrl: process.env.DATABASE_URL,
+  schemaDir: '.', // project root containing objects/
+  auth: { source: { 'sk-admin': { id: 'admin', roles: ['admin'] } } },
+});
+await engine.app.listen({ port: 3000 });
+```
+
+## Metadata
+
+- **Objects** live in `objects/<name>/schema.json` (one directory per object; the directory name must equal the object name).
+- **`weavekit.config.ts`** is the single wiring point — `satisfies EngineConfig` default export (`schemaDir`, `auth`, `adapters`, `subsystems`).
+- `schema.json` is versioned in Git and is the source of truth; the engine syncs it to PostgreSQL and a metadata cache.
+
+## CLI
+
+| Command | Description |
+| --- | --- |
+| `weave introspect` | Reverse-model an existing Postgres DB into `objects/*/schema.json` |
+| `weave schema:map [object] [--drift]` | Report the schema field ↔ PostgreSQL column mapping |
+| `weave migrate [--dry-run]` | State-diff migration + metadata cache + auto-commit |
+| `weave dev [--port]` | Run with hot reload |
+| `weave build` | Bundle the server entry (esbuild) |
+| `weave test` | Proxy the project test suite |
+| `weave types [--outdir]` | Compile `schema.json` into object-level TS types |
+| `weave object:create <name>` | Scaffold `objects/<name>/schema.json` + `server.js` hooks |
+| `weave field:add <object>` | Add a validated field to a schema |
+| `weave module:add` / `module:remove <name>` | Enable/disable a subsystem (audit/script) |
+| `weave mcp:config [--host]` | Print MCP client config for this project's `/mcp` endpoint |
+| `weave pages:migrate` | Migrate legacy flat custom pages to directories |
+| `weave connect` | Reverse-tunnel a local engine to a governance endpoint |
+
+## Object-level types
+
+```sh
+weave types   # → generated/types.ts
+```
+
+```ts
+import type { Lead } from './generated/types';
+import { createClient } from '@weave-kit/client';
+
+const leads = createClient({ baseUrl, apiKey }).objects<Lead>('lead');
+const { rows } = await leads.find({ filter: { status: 'open' } });
+```
+
+## What's implemented
+
+MVP milestones **M1–M12** are complete:
+
+- metadata core (schema validation, relation graph, formula fields, i18n)
+- state-diff PostgreSQL migration (existing tables read-only unless `alter: true`, additive-only DDL)
+- RBAC (row + field level: all/own/team) enforced in the data-access layer
+- generic REST object CRUD with unified errors
+- MCP streamable HTTP endpoint (`/mcp`) with per-identity tool surface + guardrails
+- Git-backed metadata (`syncSchema` / `autoCommit`)
+- `weave` CLI (the full command set above, including DB introspection and the schema map)
+- object-level type generation
+- audit subsystem (immutable event log; optional)
+- script subsystem (`*.server.js` sandboxed lifecycle hooks; optional)
+- SSE event stream, open contract (custom tools + guardrail policies + audit replay)
+
+Planned (not yet implemented): GraphQL, workflow subsystem.
+
+See `AGENTS.md` for the architecture memory and internal invariants; user docs live in [`docs/`](docs/01-getting-started.md).

package/dist/adapters/auth/index.d.ts

@@ -0,0 +1,14 @@
+import type { Locale } from '../../core/index.js';
+import type { RbacSubject } from '../../core/index.js';
+import { type AuthConfig, type Authenticator } from './source.js';
+export type { Authenticator, AuthConfig, AuthResolver, AuthSource } from './source.js';
+export { createAuth } from './source.js';
+/**
+ * Resolve the Authorization header into a subject, or throw a 401-family
+ * {@link SchemaError}. Missing header → `auth.missingKey`; present but
+ * unresolvable → `auth.invalidKey`. The REST layer maps both to 401.
+ */
+export declare function authenticate(authenticator: Authenticator, header: string | undefined, locale: Locale): Promise<RbacSubject>;
+/** build the default authenticator from an auth source (static map or custom resolver) */
+export declare function buildAuthenticator(config: AuthConfig): Authenticator;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,CAKtB;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAEpE"}

package/dist/adapters/auth/index.js

@@ -0,0 +1,21 @@
+import { SchemaError } from '../../core/index.js';
+import { createAuth } from './source.js';
+export { createAuth } from './source.js';
+/**
+ * Resolve the Authorization header into a subject, or throw a 401-family
+ * {@link SchemaError}. Missing header → `auth.missingKey`; present but
+ * unresolvable → `auth.invalidKey`. The REST layer maps both to 401.
+ */
+export async function authenticate(authenticator, header, locale) {
+    const subject = await authenticator.resolve(header);
+    if (subject !== null)
+        return subject;
+    if (header === undefined)
+        throw new SchemaError('auth.missingKey', {}, locale);
+    throw new SchemaError('auth.invalidKey', {}, locale);
+}
+/** build the default authenticator from an auth source (static map or custom resolver) */
+export function buildAuthenticator(config) {
+    return createAuth(config);
+}
+//# sourceMappingURL=index.js.map

package/dist/adapters/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAuC,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,aAA4B,EAC5B,MAA0B,EAC1B,MAAc;IAEd,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAC/E,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/adapters/auth/source.d.ts

@@ -0,0 +1,24 @@
+import type { RbacSubject } from '../../core/index.js';
+/** resolves an Authorization header into an authenticated identity (null = unauthenticated) */
+export interface Authenticator {
+    resolve(header: string | undefined): RbacSubject | null | Promise<RbacSubject | null>;
+}
+/**
+ * Custom auth resolver: given the raw Authorization header (including the
+ * `Bearer ` prefix), return the authenticated subject. Async resolvers may load
+ * the user from the customer's own database / verify a JWT. Returning null
+ * means unauthenticated (401).
+ */
+export type AuthResolver = (header: string | undefined) => RbacSubject | null | Promise<RbacSubject | null>;
+/**
+ * The authentication source: either a static key map or a resolver function.
+ * `source` is required whenever `auth` is configured (fail fast otherwise).
+ */
+export type AuthSource = Record<string, RbacSubject> | AuthResolver;
+/** authentication config — the single source of truth is `source` */
+export interface AuthConfig {
+    source: AuthSource;
+}
+/** default authenticator: static map (unchanged behavior) or custom resolver */
+export declare function createAuth(config: AuthConfig): Authenticator;
+//# sourceMappingURL=source.d.ts.map

package/dist/adapters/auth/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACvF;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAE5G;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,YAAY,CAAC;AAEpE,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAc5D"}

package/dist/adapters/auth/source.js

@@ -0,0 +1,19 @@
+/** default authenticator: static map (unchanged behavior) or custom resolver */
+export function createAuth(config) {
+    const source = config.source;
+    if (typeof source === 'function') {
+        return { resolve: (header) => source(header) };
+    }
+    const keys = source;
+    return {
+        resolve(header) {
+            if (header === undefined)
+                return null;
+            const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+            if (match === null)
+                return null;
+            return keys[match[1]] ?? null;
+        },
+    };
+}
+//# sourceMappingURL=source.js.map

package/dist/adapters/auth/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../../src/adapters/auth/source.ts"],"names":[],"mappings":"AA0BA,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,MAAkB;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;IACjD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC;IACpB,OAAO;QACL,OAAO,CAAC,MAA0B;YAChC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACtC,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACtD,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC;YAChC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,IAAI,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/events/index.d.ts

@@ -0,0 +1,41 @@
+import type { FastifyInstance } from 'fastify';
+import type { Locale, ObjectRegistry } from '../../core/index.js';
+import type { EventBus } from '../../core/provider/event/index.js';
+import type { SlidingWindow } from '../../core/limiter/index.js';
+import type { Authenticator } from '../auth/index.js';
+/**
+ * Live event endpoint (M12, framework-agnostic push channel):
+ *   GET {prefix}/events  (SSE over `Authorization: Bearer`)
+ *
+ * Every connection is bound to the authenticated subject and filtered before
+ * delivery (a push must never leak a record the identity cannot read, nor an
+ * audit event it may not see):
+ *   - record.* events   → object must be readable (mirrors MCP list_objects)
+ *   - audit.event       → own actorId only, unless the subject holds an admin role
+ *   - schema.changed    → broadcast (cache-invalidation nudge, no payload)
+ *
+ * Reconnect: the client sends `Last-Event-ID: <seq>`; buffered events are
+ * replayed from the ring buffer. When the requested window is unrecoverable
+ * (process restart / overflow) a `schema.changed` nudge is sent instead, so the
+ * client refetches metadata/permissions via REST.
+ */
+export interface EventsDeps {
+    registry: ObjectRegistry;
+    authenticator: Authenticator;
+    locale: Locale;
+    bus: EventBus;
+    /** roles allowed to see every actor's audit events (mirrors adapters.rest.adminRoles) */
+    adminRoles?: string[];
+}
+export interface EventsOptions {
+    /** URL prefix; defaults to `/api` */
+    prefix?: string;
+    /** keep-alive ping interval in ms; defaults to 30s */
+    heartbeatMs?: number;
+    /** per-agent-key sliding-window limiter; disabled when absent */
+    rateLimiter?: SlidingWindow;
+    /** CORS origin allowed on the SSE response (mirrors adapters.rest.cors.origin) */
+    corsOrigin?: string | string[] | boolean;
+}
+export declare function registerEventsRoutes(app: FastifyInstance, deps: EventsDeps, options?: EventsOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/events/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAe,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAGV,QAAQ,EAET,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,QAAQ,CAAC;IACd,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;CAC1C;AAmBD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CAuD9G"}

package/dist/adapters/events/index.js

@@ -0,0 +1,70 @@
+import { EVENT_TYPES, listObjectDescriptors } from '../../core/index.js';
+import { authenticateRequest, checkRateLimit } from '../rest/common.js';
+import { createSseStream } from './stream.js';
+function passesFilter(event, subject, readable, isAdmin) {
+    switch (event.type) {
+        case EVENT_TYPES.RECORD_CREATED:
+        case EVENT_TYPES.RECORD_UPDATED:
+        case EVENT_TYPES.RECORD_DELETED: {
+            const payload = event.payload;
+            return readable.has(payload.object);
+        }
+        case EVENT_TYPES.AUDIT_EVENT: {
+            const payload = event.payload;
+            return isAdmin || payload.event.actorId === subject.id;
+        }
+        default:
+            return true; // schema.changed — broadcast
+    }
+}
+export function registerEventsRoutes(app, deps, options = {}) {
+    const prefix = options.prefix ?? '/api';
+    const { registry, authenticator, locale, bus } = deps;
+    const adminRoles = new Set(deps.adminRoles ?? []);
+    // Active SSE streams. On app close they are ended so `server.close()` (inside
+    // Fastify `app.close()`) is not left waiting on the long-lived connections —
+    // otherwise hot reload (`weave dev`) hangs while a frontend keeps `/api/events`
+    // open. Clients reconnect with `Last-Event-ID` to replay the gap.
+    const streams = new Set();
+    app.addHook('onClose', async () => {
+        for (const stream of streams)
+            stream.close();
+        streams.clear();
+    });
+    app.get(`${prefix}/events`, async (request, reply) => {
+        checkRateLimit(options.rateLimiter, request, locale);
+        const subject = await authenticateRequest(authenticator, request, locale);
+        const readable = new Set(listObjectDescriptors(registry, subject.roles).map((o) => o.name));
+        const isAdmin = subject.roles.some((r) => adminRoles.has(r));
+        reply.hijack();
+        let unsubscribe = () => { };
+        const stream = createSseStream(reply, {
+            heartbeatMs: options.heartbeatMs,
+            onClose: () => {
+                unsubscribe();
+                streams.delete(stream);
+            },
+            corsOrigin: options.corsOrigin,
+        });
+        streams.add(stream);
+        const deliver = (event) => {
+            if (passesFilter(event, subject, readable, isAdmin))
+                stream.write(event);
+        };
+        const rawLast = request.headers['last-event-id'];
+        const afterSeq = rawLast === undefined ? -1 : Number.parseInt(String(Array.isArray(rawLast) ? rawLast[0] : rawLast), 10);
+        const replayAfter = Number.isNaN(afterSeq) ? -1 : afterSeq;
+        if (replayAfter >= 0) {
+            const result = bus.replay(replayAfter, deliver);
+            if (result === 'gap') {
+                // restart / ring overflow: continuity lost — tell the client to refetch
+                stream.writeRaw(EVENT_TYPES.SCHEMA_CHANGED, {
+                    type: EVENT_TYPES.SCHEMA_CHANGED,
+                    payload: { kind: 'schema', replayGap: true },
+                });
+            }
+        }
+        unsubscribe = bus.subscribe(deliver);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/adapters/events/index.js.map

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

package/dist/adapters/events/stream.d.ts

@@ -0,0 +1,29 @@
+import type { FastifyReply } from 'fastify';
+import type { EngineEvent } from '../../core/provider/event/index.js';
+/**
+ * SSE stream over a hijacked fastify reply. Writes `id`/`event`/`data` blocks,
+ * sends a keep-alive `: ping` comment on an interval, and tears down cleanly on
+ * client disconnect (the raw socket 'close' event).
+ */
+export interface SseStreamOptions {
+    /** keep-alive ping interval; defaults to 30s */
+    heartbeatMs?: number;
+    /** fired when the underlying connection closes */
+    onClose?: () => void;
+    /**
+     * CORS origin to allow (mirrors `adapters.rest.cors.origin`). The SSE response
+     * is hijacked, which bypasses the @fastify/cors onSend hook — so the header is
+     * written here for cross-origin frontends (real-time via `client.subscribe`).
+     * `true` reflects the request origin; a string[] echoes it when allowed.
+     */
+    corsOrigin?: string | string[] | boolean;
+}
+export interface SseStream {
+    /** write one bus event as an SSE block (carries its `seq` as the event id) */
+    write(event: EngineEvent): void;
+    /** write a raw named SSE event without a seq id (e.g. the replay-gap nudge) */
+    writeRaw(eventName: string, data: unknown): void;
+    close(): void;
+}
+export declare function createSseStream(reply: FastifyReply, options?: SseStreamOptions): SseStream;
+//# sourceMappingURL=stream.d.ts.map

package/dist/adapters/events/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/adapters/events/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAEtE;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAUD,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CAuD9F"}

package/dist/adapters/events/stream.js

@@ -0,0 +1,67 @@
+/** resolve the Access-Control-Allow-Origin value for a request (cors origin semantics) */
+function allowOrigin(cors, requestOrigin) {
+    if (cors === undefined || cors === false)
+        return undefined;
+    if (cors === true)
+        return requestOrigin;
+    if (typeof cors === 'string')
+        return cors;
+    return requestOrigin !== undefined && cors.includes(requestOrigin) ? requestOrigin : undefined;
+}
+export function createSseStream(reply, options = {}) {
+    const raw = reply.raw;
+    let closed = false;
+    const heartbeatMs = options.heartbeatMs ?? 30_000;
+    const headers = {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+        'x-accel-buffering': 'no',
+    };
+    const origin = allowOrigin(options.corsOrigin, reply.request.headers.origin);
+    if (origin !== undefined)
+        headers['access-control-allow-origin'] = origin;
+    raw.writeHead(200, headers);
+    raw.flushHeaders();
+    raw.setTimeout(0);
+    const heartbeat = setInterval(() => {
+        if (!closed)
+            raw.write(': ping\n\n');
+    }, heartbeatMs);
+    heartbeat.unref?.();
+    raw.on('close', () => {
+        closed = true;
+        clearInterval(heartbeat);
+        options.onClose?.();
+    });
+    return {
+        write(event) {
+            if (closed)
+                return;
+            const data = JSON.stringify({
+                seq: event.seq,
+                ts: event.ts.toISOString(),
+                type: event.type,
+                payload: event.payload,
+            });
+            raw.write(`id: ${event.seq}\nevent: ${event.type}\ndata: ${data}\n\n`);
+        },
+        writeRaw(eventName, data) {
+            if (closed)
+                return;
+            raw.write(`event: ${eventName}\ndata: ${JSON.stringify(data)}\n\n`);
+        },
+        close() {
+            if (!closed) {
+                closed = true;
+                clearInterval(heartbeat);
+                raw.end();
+            }
+            // end the underlying socket too — the SSE response advertises
+            // keep-alive, so a bare end() would leave the connection open and
+            // `server.close()` (via app.close()) would keep waiting on it
+            raw.socket?.destroy();
+        },
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/adapters/events/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/adapters/events/stream.ts"],"names":[],"mappings":"AA+BA,0FAA0F;AAC1F,SAAS,WAAW,CAAC,IAA6C,EAAE,aAAiC;IACnG,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC3D,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,aAAa,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAmB,EAAE,UAA4B,EAAE;IACjF,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,MAAM,CAAC;IAElD,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,mBAAmB;QACnC,eAAe,EAAE,UAAU;QAC3B,UAAU,EAAE,YAAY;QACxB,mBAAmB,EAAE,IAAI;KAC1B,CAAC;IACF,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,6BAA6B,CAAC,GAAG,MAAM,CAAC;IAC1E,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC5B,GAAG,CAAC,YAAY,EAAE,CAAC;IACnB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAElB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,IAAI,CAAC,MAAM;YAAE,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC,EAAE,WAAW,CAAC,CAAC;IAChB,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;IAEpB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,aAAa,CAAC,SAAS,CAAC,CAAC;QACzB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,CAAC,KAAkB;YACtB,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;gBAC1B,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE;gBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YACH,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,IAAI,WAAW,IAAI,MAAM,CAAC,CAAC;QACzE,CAAC;QACD,QAAQ,CAAC,SAAiB,EAAE,IAAa;YACvC,IAAI,MAAM;gBAAE,OAAO;YACnB,GAAG,CAAC,KAAK,CAAC,UAAU,SAAS,WAAW,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtE,CAAC;QACD,KAAK;YACH,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,GAAG,IAAI,CAAC;gBACd,aAAa,CAAC,SAAS,CAAC,CAAC;gBACzB,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;YACD,8DAA8D;YAC9D,kEAAkE;YAClE,8DAA8D;YAC9D,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/mcp/generate.d.ts

@@ -0,0 +1,21 @@
+import type { ObjectDefinition, RbacSubject, FieldDefinition, ToolDefinition } from '../../core/index.js';
+import { READ_SCOPES } from '../../core/index.js';
+import type { ToolExecutor } from '../../runtime/tools/index.js';
+import type { JsonSchema, McpEngine, McpToolSpec } from './types.js';
+/** JSON Schema for a single field *value* (enum → literal set, relation → pk) */
+export declare function fieldValueSchema(field: FieldDefinition, defs: Map<string, ObjectDefinition>): JsonSchema;
+export interface CompiledTool {
+    spec: McpToolSpec;
+    objectName: string | undefined;
+}
+/**
+ * Compile the full tool surface for a subject: CRUD tools for every object the
+ * subject can touch (per RBAC) plus the always-on introspection tools plus the
+ * subject-visible custom tools (M10b, roles-filtered by the executor).
+ */
+export declare function compileToolsFor(engine: McpEngine, subject: RbacSubject, custom?: {
+    defs: ToolDefinition[];
+    executor: ToolExecutor;
+}): CompiledTool[];
+export { READ_SCOPES };
+//# sourceMappingURL=generate.d.ts.map

package/dist/adapters/mcp/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/generate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAkB,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1H,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAGjE,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAiB,WAAW,EAAmB,MAAM,YAAY,CAAC;AAsBrG,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,UAAU,CAqCxG;AA4CD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AA4JD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAC1D,YAAY,EAAE,CAyChB;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}