@agilesyndrome/cf-genai-base 5.0.1 → 6.0.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+## 5.0.3
+
+This release intentionally removes legacy compatibility paths. Applications
+must migrate to the single v5 contract; no aliases or fallback behavior are
+retained.
+
+### Consolidation
+
+- `cf-genai-llm`, `cf-genai-messaging`, and `cf-genai-cli` are no longer
+  runtime dependencies. LLM and messaging now ship from
+  `@agilesyndrome/cf-genai-base/features/llm` and `/features/messaging`; the
+  `cf-genai` executable ships from base.
+- Messaging storage is now base migration `0007_messaging.sql`. Vendor and
+  apply the base migrations, then remove separately vendored messaging schema
+  migrations when they are redundant for a new installation.
+- Messaging tables and the built-in resource manifest are tenant-scoped by
+  default. Remove application-owned messaging resource declarations; existing
+  installations must add and backfill `tenant_id` before adopting the base
+  migration contract.
+- The changelog filename is now `CHANGELOG.md`.
+- Core operational code is divided into owned segments: `circuits/`,
+  `healthchecks/`, `events/`, `jobs/`, `database/`, and `security/`. Request
+  identity now lives under `auth/identity/`. Internal modules use these narrow
+  boundaries instead of the broad core barrel.
+- Built-in features now use folder entrypoints. LLM code is divided into
+  client, configuration, schema, error, and manifest modules under
+  `features/llm/`; messaging code is divided into model, resource, store, job,
+  and manifest modules under `features/messaging/`.
+
+### Required application changes
+
+- Replace imports of removed flat source modules with package segment exports:
+  `core/circuits.js` becomes `/core/circuits`, `core/events.js` becomes
+  `/core/events`, `core/jobs.js` becomes `/core/jobs`, `core/d1.js` becomes
+  `/core/database`, `core/security.js` becomes `/core/security`, and
+  `core/identity.js` becomes `/auth/identity`. The old source files and their
+  compatibility facades do not exist in v5.
+- Replace direct source imports of `src/features/llm.js` and
+  `src/features/messaging.js` with their folder `index.js` files. Package
+  consumers continue to use `/features/llm` and `/features/messaging`; those
+  package paths now resolve to the folder entrypoints.
+
+- Move every feature registration into `defineApp({ features: [...] })`.
+  Remove `createWorker.features` and `createWorker.featureOptions`. Configure a
+  built-in with `defineFeature("llm", options)` or
+  `defineFeature("messaging", options)`; put external feature objects such as
+  auth directly in the same application feature array.
+- Remove `createWorker.auth` and `createWorker.repositories`. Register auth as
+  an application feature and repositories through `defineApp({ repositories })`.
+- Replace `createFeature` imports with `createLLMFeature` or
+  `createMessagingFeature`. `createMessagingFeature` is no longer an alias.
+- LLM clients expose only `generate`, `generateJob`, `generateMulti`, `review`,
+  `reviewMulti`, and `listModels`. Remove the `*WithSchema` method aliases.
+- Use the fixed LLM signatures `(prompt, schema, options)`,
+  `(jobId, prompt, schema, options)`, and
+  `(originalText, prompts, schema, options)`. Object-wrapped requests and
+  schema-inside-options overloads are removed.
+- Configure LLM credentials only with `apiToken` or `LLM_API_TOKEN`. Remove
+  `apiKey`, `LLM_API_KEY`, and `OPENAI_API_KEY`. Use `featureName`; the old
+  client `feature` option is removed.
+- Messaging participants must be `{ type, key, name, metadata? }` objects.
+  Remove string participants and the `participantType`, `participantKey`,
+  `displayName`, `id`, `senderType`, `senderKey`, `senderName`, `recipients`,
+  and `kind` input aliases. Reply generators must return a message object, not
+  a string.
+- Messaging stores now accept only a scoped data reader:
+  `createMessagingStore(env.data.tenant)`. Remove raw D1 bindings, table
+  prefixes, and authorization callbacks from store construction.
+- Feature manifests now accept only `name`, `displayName`, `packageName`,
+  `version`, `healthchecks`, and `circuitBreakers` in their canonical casing.
+  Remove nested manifests, `id` names, snake-case manifest properties,
+  `healthChecks`, `circuit_breakers`, and circuit `dependencies`.
+- Configure both an exact HTTPS `OIDC_DISCOVERY_URL` and `OIDC_ISSUER`. The
+  issuer-to-discovery fallback and automatic well-known URL construction are
+  removed.
+- Use only the CLI forms `healthchecks ...`, `circuit-breakers ...`, and
+  `--env production`. Colon commands, singular domains, `circuit`, `update`
+  action aliases, `rename`, and `prod` are removed. `cf-genai upgrade` accepts
+  only `base` or `auth`; it no longer treats `llm` and `messaging` as aliases.
+  Top-level `backup` and `restore` aliases are removed; use `d1 backup` and
+  `d1 restore`.
+- Read request IDs from the `X-Request-ID` response header. The browser client
+  no longer falls back to a `request_id` JSON field.
+
+## 5.0.0
+
+- Replace `@agilesyndrome/cf-genai-base/authorization` imports with `/auth`.
+- Replace direct `src/core.js` imports with `src/core/index.js` or the package `/core` entrypoint.
+- Replace direct `src/data.js` imports with `src/data/index.js` or the package `/data` entrypoint.
+- Replace direct `src/api/router.js` imports with `src/api/contracts.js` for route definitions and dispatch.
+- Update internal imports to the canonical folder modules; the old facade files are removed.
+- Update package consumers and lockfiles to version `5.0.0`.
+- Replace server-rendered admin HTML and custom elements with the React UI entrypoint; apps own the shell and theme around base's admin components.
+- Apply `migrations/0006_jobs.sql`; features now use generic durable job helpers and `GET /api/jobs` instead of inventing job tables and status endpoints.
+- Configure an `EVENT_HUB` Durable Object and export `EventHub` from `@agilesyndrome/cf-genai-base/event-hub` to enable authenticated live job events over WebSockets.
+- Dispatch long-running work through a Cloudflare Workflow with `dispatchJob`; execute its durable lifecycle with `executeJob` instead of relying on request-lifetime background work.
+- Remove the lowercase `admin_token` environment alias; use `ADMIN_TOKEN` only.

package/CLI.md

@@ -5,10 +5,6 @@ provides safe operational commands for Cloudflare Worker repositories using
 Wrangler and D1. The refresh command surface contains only local and staging
 targets.
 
-Projects that previously installed `@agilesyndrome/cf-genai-cli` should remove
-that dependency. Installing `@agilesyndrome/cf-genai-base` now installs the
-same `cf-genai` executable.
-
 Automation can import the command runner from
 `@agilesyndrome/cf-genai-base/cli`. The migrated helper modules remain
 available through subpaths such as `@agilesyndrome/cf-genai-base/cli/d1` and
@@ -23,14 +19,14 @@ cf-genai lint data-access
 cf-genai test
 cf-genai ci
 cf-genai dev
+cf-genai storybook
 cf-genai upgrade base latest
 cf-genai upgrade auth latest
-cf-genai upgrade llm 5.0.0
-cf-genai upgrade messaging latest
 cf-genai release --confirm
 cf-genai release --first --confirm
 cf-genai release --add-trust --confirm
 cf-genai release --dry-run
+cf-genai release --pre --confirm
 cf-genai release --version 4.1 --confirm
 cf-genai release-status
 cf-genai release-status --wait 3 --json
@@ -87,17 +83,17 @@ clean checkout on `main`, fetches and compares `origin/main`, pushes and
 verifies the release commit before creating the tag, and only then pushes the
 tag that triggers npm publishing. The release tag publishes the package through GitHub Actions with provenance. `config check` runs a Wrangler deploy dry-run. Production refresh remains intentionally unavailable; backups and restores are available with explicit file paths.
 
-`upgrade PACKAGE VERSION` upgrades the first-party `base`, `auth`, `llm`, or
-`messaging` package with npm and vendors package migrations not already represented in the repository's
+`upgrade PACKAGE VERSION` upgrades the first-party `base` or `auth` package
+with npm and vendors package migrations not already represented in the repository's
 `migrations/` directory. The generated files are ordinary committed Wrangler
 migrations, so the same schema change is applied consistently to local,
 staging, and production D1 databases. Review and commit the package files,
 `package.json`, `package-lock.json`, and generated migrations together.
 Operational status can be read directly from the current site directory through Wrangler (no CLI login prompt):
-  cf-genai healthcheck:list --env local
-  cf-genai healthcheck:list --env staging
-  cf-genai circuit-breaker:list --env prod
-  cf-genai circuit-breaker:set llm:openai-models on --env staging
+  cf-genai healthchecks list --env local
+  cf-genai healthchecks list --env staging
+  cf-genai circuit-breakers list --env production
+  cf-genai circuit-breakers set llm:openai-models on --env staging
 The standardized admin surface mirrors cf-genai-base and uses Wrangler authentication from the current machine:
   cf-genai admin status --env staging
   cf-genai admin features --env staging
@@ -118,4 +114,4 @@ The standardized admin surface mirrors cf-genai-base and uses Wrangler authentic
 Back up and restore a complete D1 database with explicit files:
   cf-genai d1 backup production --output ./backup.sql --confirm-production
   cf-genai d1 restore staging --file ./backup.sql --yes
-`release` creates the version commit and tag; the tag-triggered workflow publishes to npm. `release-status` verifies a clean, pushed workspace, the remote release tag, successful GitHub Actions runs for that tag, npm publication, and whether the declared `cf-genai-base` version is current. An older base version is shown in yellow with an upgrade command. `--wait` is one total timeout in minutes shared by GitHub Actions and npm polling; the default is five minutes. Use `release --version MAJOR.MINOR` to explicitly jump to a version such as `5.0`; the CLI assigns patch `0`, accepts an equal prepared manifest version when its tag and npm version do not exist, rejects older versions, and refuses any version already present on npm or GitHub. This is useful for synchronizing packages onto a common release line.
+`release` creates the version commit and tag; the tag-triggered workflow publishes to npm. Use `release --pre --confirm` for a prerelease build: each run creates a new monotonic version such as `<version>-pre.0`, `<version>-pre.1`, and an immutable release tag. `release-status` verifies a clean, pushed workspace, the remote release tag, successful GitHub Actions runs for that tag, npm publication, and whether the declared `cf-genai-base` version is current. An older base version is shown in yellow with an upgrade command. `--wait` is one total timeout in minutes shared by GitHub Actions and npm polling; the default is five minutes. Use `release --version MAJOR.MINOR` to explicitly jump to a version such as `5.0`; the CLI assigns patch `0`, accepts an equal prepared manifest version when its tag and npm version do not exist, rejects older versions, and refuses any version already present on npm or GitHub. This is useful for synchronizing packages onto a common release line.

package/CONTRACT.md

@@ -4,20 +4,35 @@ Every site built from this foundation follows the same edge contract.
 
 ## API, UI, and repositories
 
-`defineRoute({ method, path, auth, scope, csrf, handler })` defines a route
-contract. Applications pass contracts through `createWorker({ apiRoutes })`;
-base enforces authentication, administrator status, same-origin mutation
-rules, and scope checks before invoking the handler. `@agilesyndrome/cf-genai-base/api`
-also exposes `apiFetch` and `apiJson` for browser clients.
-
-`createRepositories(env, definitions)` creates named application or feature
+`AppDomain` owns route contracts alongside a concept's model, views, data
+resources, and repositories. Applications register domains through
+`defineApp({ domains })`; base gives every domain route to Hono and enforces
+authentication, administrator status, same-origin mutation rules, custom
+policies, and scope checks before invoking the handler. `defineRoute` remains
+the low-level contract helper used by the domain dispatcher.
+
+`defineApp` snapshots and freezes its manifest arrays. TypeScript consumers
+retain the concrete domain and feature registration types, and built-in
+`defineFeature` options are selected from the feature name.
+
+The `/api` browser client returns `JsonValue | Response`: empty, `null`, or
+non-JSON success bodies preserve the original unread `Response`. Callers that
+need a narrower JSON result pass a `validateJson` type guard, which both checks
+the untrusted payload and infers the result type. `ApiError` exposes only the
+safe server message, HTTP `status`, and `X-Request-ID` as `requestId`.
+
+Core security helpers expose typed same-origin inputs, bounded JSON-object
+reading results, status-bearing request errors, and secure response helpers;
+JSON parsing remains runtime-validated and request bodies are read from clones.
+
+`createRepositories(env, definitions)` creates named application or domain
 repositories over the request-scoped data reader. Definitions may declare
 relations to other repositories. Repositories must not expose raw D1 or accept
 unvalidated table, column, or SQL fragments from callers.
 
 ## Worker entrypoint
 
-`createWorker({ fetch, features?, middleware?, auth?, authorize?, scheduled?, security? })` owns the Worker lifecycle and reserved admin boundary. Features run in declaration order and may call `next()` or return a response. A feature may also declare `{ routes: [{ match, handle }] }`; matching handlers receive `{ request, env, ctx, state, next }` and run before the site handler. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
+`createWorker({ fetch, app, middleware?, authorize?, scheduled?, security? })` owns the Worker lifecycle and reserved admin boundary. An application requests built-ins with `defineApp({ name, features: [defineFeature("llm", options), defineFeature("messaging", options)] })`; base resolves only those registrations and ignores every unrequested built-in. External feature objects are registered in the same `app.features` array. Business APIs, views, data resources, and repositories are composed through `AppDomain` instances registered in `app.domains` or `feature.domains`. Duplicate and unknown features fail during Worker construction. Feature middleware runs in declaration order and may call `next()` or return a response; feature endpoints must be domains so Hono remains the only route matcher. The site router owns pages that are not supplied by a domain. `scheduled`
 is optional and must use `ctx.waitUntil` for background work.
 
 ## Routes
@@ -28,18 +43,19 @@ is optional and must use `ctx.waitUntil` for background work.
 - `/admin` and `/admin/*` are browser admin routes; `/api/admin` and `/api/admin/*` are admin API routes.
 - Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN`. Missing token means all admin routes return 401.
 - `AUTH_STRATEGY=oauth` delegates identity establishment to the configured auth provider and uses `authorize` for admin policy.
-- `scopes` registers an application scope manifest. `scopeRoutes` associates route prefixes or match functions with required scopes.
-- Base protects `/admin` and `/api/admin`; browser pages are React applications that consume the JSON admin APIs. Import `AdminShell` and the platform catalogs from `@agilesyndrome/cf-genai-base/ui` and apply the application's theme around them.
-- Base provides `/api/admin/users`, `/api/admin/scopes`, `/api/admin/groups`, `/api/admin/status`, `/api/admin/features`, `/api/admin/healthchecks`, `/api/admin/circuit-breakers`, and `/api/admin/users/:id/scopes|groups` for platform administrators when the authorization and core migrations are installed. It also provides short-lived `/api/admin/users/:id/impersonate` and `/api/admin/impersonate/clear` controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. `GET /api/admin/features` returns the installed runtime feature manifests, package names and versions, per-feature health rollups, healthchecks, and circuit breakers. React platform components consume these JSON APIs. Feature manifests may provide `name`, `displayName`, `packageName`, and `version`.
+- Domain route `scopes` register the application scope manifest and enforce access at the exact Hono route. Use `scopeMode: "any"` when any declared scope is sufficient; the default requires all declared scopes.
+- Base protects `/admin` and `/api/admin`; browser pages are React applications that consume the JSON admin APIs. `AdminDashboard` is the complete single-route administration UI; it includes all platform catalogs and owns internal list/detail navigation. `AdminShell` and the individual components remain available for custom routed interfaces.
+- Base provides list/detail APIs for users, groups, tenants, features, healthchecks, and circuit breakers, plus relationship replacement for user scopes, groups, and tenants. Built-in admin domains declare delegated `users:*`, `groups:*`, `tenants:*`, `operations:*`, `subscriptions:*`, and `impersonation:start` capabilities; platform administrators satisfy all route capabilities. It also provides short-lived impersonation controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. React platform components consume these JSON APIs.
 - Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
 - `createWorker` supplies request-scoped `data`, `user`, `authUser`, `userId`, `context`, `event`, and audited D1 access to route handlers. `Event(who, what, where, when, details)` creates normalized events; installed features may consume them through `eventHandler`.
-- `migrations/0006_jobs.sql` adds generic durable jobs and job events. Features create and update jobs with the exported lifecycle helpers; `GET /api/jobs`, `GET /api/jobs/:id`, and `GET /api/jobs/:id/events` expose only the authenticated owner's records. `GET /api/events` is an optional authenticated WebSocket stream backed by the configured `EVENT_HUB` Durable Object.
+- `migrations/0006_jobs.sql` adds generic durable jobs and job events. Features create and update jobs with the exported lifecycle helpers; `GET /api/jobs`, `GET /api/jobs/:id`, and `GET /api/jobs/:id/events` expose only the authenticated owner's records, while `POST /api/jobs/:id/cancel` cancels an owned queued/running job. Administrators may request `GET /api/jobs?all=true`. `GET /api/events` is an optional authenticated WebSocket stream backed by the configured `EVENT_HUB` Durable Object.
 
 ## Environment and bindings
 
 Required OIDC secrets for the standard auth plugin:
 
+- `OIDC_DISCOVERY_URL`
 - `OIDC_ISSUER`
 - `OIDC_CLIENT_ID`
 - `OIDC_CLIENT_SECRET`
@@ -56,7 +72,8 @@ Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
 The package includes ordered migrations. Each site must apply
 `migrations/0001_authorization.sql` before enabling the generic user/scope APIs,
 `migrations/0004_tenants.sql` for tenant membership and subscriptions, and
-`migrations/0006_jobs.sql` before creating or reading durable jobs.
+`migrations/0006_jobs.sql` before creating or reading durable jobs. Apps that
+request messaging also apply `migrations/0007_messaging.sql`.
 The tenant migration seeds the `Easley Family` tenant and `VIP` subscription,
 and migrates existing authorization users into that tenant.
 
@@ -72,8 +89,8 @@ must remain in the application router rather than in the shared auth package.
 
 ## Scoped data contract
 
-`createWorker` accepts `dataResources`, and features may expose the same
-manifest through `feature.dataResources`. Each resource must declare a safe
+Domains expose persistence manifests through `domain.dataResources` and
+`domain.repositories`; apps and features register those domains. Each resource must declare a safe
 name, table, explicit columns, and one scope: `user`, `tenant`, `public`, or
 `system`. Public resources are read-only and predicate on the worker's
 `publicTenantId`, including for authenticated users.

package/README.md

@@ -10,6 +10,18 @@ The base owns the shared security boundary as well as Worker lifecycle concerns.
 Use D1 bindings for durable application data and R2 bindings for binary assets;
 do not put either into module-level state.
 
+The Worker transport is built on [Hono](https://hono.dev/): middleware ordering,
+HTTP method/path matching, and admin/API dispatch all use Hono's runtime. Existing
+feature middleware keeps the package's compatibility signature while new integrations
+can use Hono middleware directly. For Worker-rendered documents, import
+`createSsrRenderer`, `SiteDocument`, or `renderSiteDocument` from
+`@agilesyndrome/cf-genai-base/ui/ssr`; the interactive admin components remain
+React-based and are intentionally separate from Hono JSX SSR.
+
+The site document contract owns safe metadata, canonical URLs, Open Graph
+fields, theme color, stylesheets, scripts, and body data attributes. A site
+supplies its own children, theme CSS, navigation, and content components.
+
 Base also provides provider-neutral authorization helpers and browser components
 through `@agilesyndrome/cf-genai-base/auth` and
 `@agilesyndrome/cf-genai-base/ui`. Applications declare their scope manifest,
@@ -18,24 +30,66 @@ API. The UI components are themeable with CSS custom properties and do not
 contain application-specific components.
 
 ```js
-import { createWorker, healthResponse } from "@agilesyndrome/cf-genai-base";
+import { createWorker, defineApp, defineFeature } from "@agilesyndrome/cf-genai-base";
 
 export default createWorker({
-  features: [auth],
+  app: defineApp({
+    name: "cookbook",
+    features: [
+      auth,
+      defineFeature("llm", { apiToken: (env) => env.LLM_API_TOKEN }),
+      defineFeature("messaging", { displayName: "Cookbook chat" }),
+    ],
+  }),
   fetch: async (request, env) => {
-    if (new URL(request.url).pathname === "/health") return healthResponse(env);
     return router(request, env);
   },
 });
 ```
 
-Features expose `middleware(request, env, ctx, next, state)` and may short-circuit reserved routes, attach request state, or call `next()`.
+Built-in features are inert unless an application registers them in
+`app.features`. Feature-specific APIs use explicit subpaths:
+
+```js
+import { createLLM } from "@agilesyndrome/cf-genai-base/features/llm";
+import { createMessagingStore } from "@agilesyndrome/cf-genai-base/features/messaging";
+```
+
+The LLM feature provides OpenAI-compatible generation, typed JSON repair,
+review, model healthchecks, circuit breakers, and durable job integration. The
+`/features/llm` entrypoint exports its complete TypeScript contract, including
+`LLMEnvironment`, client and request options, provider configuration, JSON
+Schema inputs and `InferJSONSchema`, token usage, generation/review inputs,
+job options, loggers, and callbacks. Pass a literal schema with `as const` (or
+`satisfies JSONSchemaInput`) to preserve the generated value type.
+The messaging feature provides conversations, participants, messages, scoped and
+tenant-isolated stores, and durable reply jobs. Construct the store with the
+request-scoped reader, for example `createMessagingStore(env.data.tenant)`. Apply
+`migrations/0007_messaging.sql` when messaging is requested.
+
+Features expose `middleware(request, env, ctx, next, state)` and may
+short-circuit routes, attach request state, or call `next()`.
 
 Base protects `/admin` and `/api/admin`; the React UI package owns the browser
-pages. Import `AdminShell` and the platform catalogs from
+pages. For a complete single-route UI, import `AdminDashboard` from
+`@agilesyndrome/cf-genai-base/ui` and mount `<AdminDashboard />`, or use
+`mountAdminDashboards` for declarative roots. It includes
+users and access assignments, tenants, user groups, scopes, subscriptions,
+jobs, features, health checks, and circuit breakers with internal list/detail
+navigation. Use `enabledSections` to hide an unavailable optional domain and
+`applicationSections` to add site-owned panels. Import `AdminShell` and the platform catalogs from
 `@agilesyndrome/cf-genai-base/ui`. Sites provide their own application links and
 theme while the base components consume the shared JSON admin APIs.
 
+```jsx
+import { AdminDashboard } from "@agilesyndrome/cf-genai-base/ui";
+import "@agilesyndrome/cf-genai-base/ui/styles.css";
+
+export function AdminPage() {
+  return <AdminDashboard />;
+}
+```
+
 ## Command-line tools
 
 Install base in a project (or globally) and use the bundled executable:
@@ -48,21 +102,23 @@ cf-genai check
 cf-genai test
 cf-genai ci
 cf-genai dev
+cf-genai storybook
 cf-genai upgrade base latest
 cf-genai release --confirm
 cf-genai release-status --wait 3
 ```
 
-Projects upgrading from the standalone package should remove
-`@agilesyndrome/cf-genai-cli`; their existing base dependency now supplies the
-same `cf-genai` executable.
-
-The CLI includes all commands formerly published by
-`@agilesyndrome/cf-genai-cli`: project checks and releases, scoped-data linting,
-package upgrades with migration vendoring, D1 refresh/backup/restore/migration,
-site status, and user, tenant, healthcheck, circuit-breaker, and platform admin
+The CLI includes project checks and releases, scoped-data linting, package
+upgrades with migration vendoring, D1 refresh/backup/restore/migration, site
+status, and user, tenant, healthcheck, circuit-breaker, and platform admin
 operations.
 
+In this repository, `npm install` activates the checked-in Git hooks. Each
+commit runs `cf-genai ci`, the same full verification command used by GitHub
+Actions. Verification includes typechecking, source whitespace/unsafe-type
+checks, compilation, unit tests, the example integration suite, export checks,
+and package assembly.
+
 ```sh
 cf-genai status --env staging
 cf-genai d1 refresh local
@@ -92,15 +148,17 @@ Cloudflare configuration is incomplete.
 ## Core operational services
 
 The package is organized by responsibility: `runtime` composes Workers,
-`core` owns request/event/security/D1 primitives, `auth` owns authorization
-data access, `api` owns route contracts and the browser client, `admin` owns
-platform administration, and `ui` owns shared browser components. Each
-responsibility has a canonical folder entrypoint; import from `core`, `auth`,
-`data`, `api`, `admin`, or `ui` as appropriate.
+`core` owns operational primitives, `auth` owns identity and authorization,
+`api` owns route contracts and the browser client, `admin` owns platform
+administration, and `ui` owns shared browser components. Core services have
+focused package entrypoints: `/core/circuits`, `/core/healthchecks`,
+`/core/events`, `/core/jobs`, `/core/database`, and `/core/security`; request
+identity is `/auth/identity`. Prefer these narrow imports when an app needs one
+concern. The root package remains the application-composition surface.
 
 Apply `migrations/0002_core.sql` and `migrations/0006_jobs.sql` after the authorization migration. The package exports `registerHealthcheck`, `updateHealthcheck`, `registerCircuitBreaker`, `setCircuitBreaker`, `evaluateCircuitBreaker`, and generic job lifecycle helpers from `/cf-genai-base`. Healthchecks use `red`, `yellow` (unknown/transient), or `green`; breakers use `off`, `tripped`, or `on`, with `any` or `all` healthcheck evaluation. Automated evaluation may only move `on` to `tripped`, or self-healing `tripped` to `on`; admin API writes are the human control plane for the `off` state.
 
-Admin APIs are `GET /api/admin/healthchecks`, `PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`, and `GET /api/admin/features`. React platform components consume these JSON responses. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers (including the feature roll-up breaker). Feature manifests may expose `healthchecks` and `circuitBreakers`; add `displayName`, `packageName`, and `version` to make the installation identity explicit. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.
+Admin APIs are `GET /api/admin/healthchecks`, `GET|PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`, and `GET /api/admin/features`. Reads require `operations:read`; mutations require `operations:manage`, while platform administrators bypass capability checks. React platform components provide both catalog and detail views. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog records with the requesting actor.
 
 
 ## User administration
@@ -116,11 +174,11 @@ Use the selected D1 target (local by default) to inspect and update users:
     cf-genai user get someone.com --target staging
     cf-genai user update someone.com --roles admin --target production
 
-`user:get` also reports scopes, groups, and tenant memberships. The shared admin user page displays each user’s tenant memberships and lets an administrator attach or detach tenants. The admin API exposes `GET|POST /api/admin/tenants`, `GET|PUT /api/admin/tenants/:id`, and `GET|PUT /api/admin/users/:id/tenants`. Production commands should be run through the repository credentials wrapper and reviewed as an administrative change.
+`user:get` also reports scopes, groups, and tenant memberships. The shared admin UI provides list and detail views and atomically replaces a user’s complete access assignment through `PUT /api/admin/users/:id/access`; individual relationship endpoints remain available. The admin API also exposes `GET /api/admin/users/:id`, `GET|POST /api/admin/tenants`, and `GET|PUT|PATCH|DELETE /api/admin/tenants/:id`. The default tenant cannot be deleted, and other tenants must first have no users, subscriptions, or messaging conversations. Tenant deletion also requires an `X-Confirm-Delete` header equal to the tenant ID. Production commands should be run through the repository credentials wrapper and reviewed as an administrative change.
 
 ## Scoped data access
 
-Features may register D1 resources with `dataResources` and receive the
+Domains may register D1 resources with `dataResources` and receive the
 scoped reader on the request state as `state.data`. Resources declare `user`,
 `tenant`, `public`, or `system` scope, their physical table, and an explicit column
 allowlist. Use `state.data.tenant`, `state.data.public`, `state.data.user`, or
@@ -128,7 +186,8 @@ allowlist. Use `state.data.tenant`, `state.data.public`, `state.data.user`, or
 the reader applies ownership predicates, supports bounded native pagination via
 page with limit/offset, count, and safe bulk updateWhere/deleteWhere
 operations, and never accepts raw SQL. Resources can explicitly restrict
-their operations to read, create, update, and delete.
+their operations to read, create, update, and delete, require capabilities per
+operation with `operationScopes`, and protect columns with `columnScopes`.
 
 Anonymous tenant reads require both publicTenantId on createWorker and a
 resource-level publicRead declaration. Use publicRead true only when the
@@ -138,8 +197,10 @@ system access. A `public` resource is read-only and always predicates on the
 worker's `publicTenantId`, including authenticated users; use it for shared
 catalog data such as GTA's `gta-public` tenant.
 
-Applications may pass subscriptionManifest to createWorker to register their
-own subscription IDs and entitlement values. Base exposes
+Applications register `new AuthSubscriptionsDomain(manifest)` in
+`defineApp({ domains })` to own their subscription IDs and entitlement values.
+That domain exposes catalog/detail APIs at `/api/admin/subscriptions` and tenant
+assignment at `/api/admin/tenants/:id/subscriptions`. Base also exposes
 requireSubscription and requireEntitlement but does not know any
 product-specific subscription such as VIP. Authenticated users can inspect
 their validated active tenant at GET /api/tenant.
@@ -149,6 +210,12 @@ POST /api/admin/users/:id/impersonate and clear it with
 POST /api/admin/impersonate/clear. Impersonation affects scoped data context
 only and does not grant the target user administrator permissions.
 
+The messaging store derives user senders from the scoped reader context and
+limits conversations to their creator, participants, and system actors.
+Creator-only operations manage participants, titles, messages, and deletion.
+Trusted host adapters without an actor context remain responsible for their
+own authorization.
+
 For example, a tenant-owned resource registers its `tenant_id` column with
 base, while feature code calls `state.data.tenant.list("recipes")` without
 passing a tenant ID. The active tenant must be a validated membership. A
@@ -185,9 +252,9 @@ are the shared identity, request, security, and feature-gating contracts.
 The layered web surface is React-first: `/api` exports route contracts, scoped
 repositories, the browser `apiFetch`/`apiJson` client, and job/event endpoints;
 `/ui` exports React admin primitives, live event hooks, and durable job
-notifications. Repositories are registered with
-`createWorker({ repositories })`, can be supplied by applications or features,
-and may declare links to other repositories while remaining behind the scoped
-data reader. `GET /api/jobs` and `GET /api/jobs/:id` expose an authenticated
+notifications. Repositories are registered by `AppDomain` instances in
+`defineApp({ domains })` or `feature.domains`; they may declare links to other
+repositories while remaining behind the scoped data reader. `GET /api/jobs`
+and `GET /api/jobs/:id` expose an authenticated
 user's durable job records. `GET /api/events` upgrades to the authenticated live
 event stream when the optional `EVENT_HUB` Durable Object binding is configured.

package/bin/cf-genai.js

@@ -1,11 +1,27 @@
 #!/usr/bin/env node
 
-import { main } from "../src/cli/cli.js";
-
-try {
-  const result = await main(process.argv.slice(2));
-  if (result?.ok === false) process.exitCode = 1;
-} catch (error) {
-  console.error(`Error: ${error.message}`);
-  process.exitCode = 1;
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Keep this JavaScript launcher as the npm bin compatibility boundary. Published
+// packages load compiled TypeScript output; source checkouts run the TypeScript
+// entrypoint through the development dependency installed by npm ci/install.
+const builtEntrypoint = new URL("../dist/cli/cli.js", import.meta.url);
+const sourceEntrypoint = new URL("../src/cli/cli.ts", import.meta.url);
+
+if (!existsSync(builtEntrypoint)) {
+  const sourceRunner = new URL("../scripts/run-cli.mjs", import.meta.url);
+  const result = spawnSync(process.execPath, ["--import", "tsx", fileURLToPath(sourceRunner), ...process.argv.slice(2)], { stdio: "inherit" });
+  process.exitCode = result.status ?? 1;
+} else {
+  const { main } = await import(builtEntrypoint.href);
+
+  try {
+    const result = await main(process.argv.slice(2));
+    if (result?.ok === false) process.exitCode = 1;
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  }
 }

package/dist/admin/auth.d.ts

@@ -0,0 +1,12 @@
+import type { AdminBindings, AdminIdentity, AdminRequestState, AdminUserProvider } from "./types.js";
+export declare function authenticateAdminRequest<Env extends AdminBindings, User extends AdminIdentity, State extends AdminRequestState<User>>(request: Request, env: Env, url: URL, state: State, provider?: AdminUserProvider<Env, User> | null): Promise<Response | null>;
+export declare function requireSameOriginMutation(request: Request, url: URL): Response | null;
+export declare function actorFor(user: AdminIdentity): string;
+export declare function isPlatformAdministrator(state: AdminRequestState): boolean;
+export declare function isAdminPath(pathname: string): boolean;
+export declare function administratorRequired(url: URL): Response;
+export declare function authenticationRequired(request: Request): Response;
+export declare function oauthAuthenticationRequired(url: URL): Response;
+export declare function safeReturnTo(value: string): string;
+export declare function prepareAdminState<Env extends AdminBindings, User extends AdminIdentity, State extends AdminRequestState<User>>(env: Env, user: User, state: State): Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/admin/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/admin/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB,wBAAsB,wBAAwB,CAC5C,GAAG,SAAS,aAAa,EACzB,IAAI,SAAS,aAAa,EAC1B,KAAK,SAAS,iBAAiB,CAAC,IAAI,CAAC,EAErC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,QAAQ,CAAC,EAAE,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,GAC7C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAyB1B;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,QAAQ,GAAG,IAAI,CASrF;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAEpD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAEzE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAIxD;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAKjE;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAG9D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AA2BD,wBAAsB,iBAAiB,CACrC,GAAG,SAAS,aAAa,EACzB,IAAI,SAAS,aAAa,EAC1B,KAAK,SAAS,iBAAiB,CAAC,IAAI,CAAC,EACrC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAInD"}

package/dist/admin/auth.js

@@ -0,0 +1,103 @@
+import { ensureUser } from "../auth/index.js";
+import { requestActor } from "../auth/identity/index.js";
+import { jsonError, NO_STORE_HEADERS } from "../api/http.js";
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+export async function authenticateAdminRequest(request, env, url, state, provider) {
+    const strategy = String(env.AUTH_STRATEGY ?? "http_basic").trim().toLowerCase();
+    if (strategy === "http_basic") {
+        const user = basicUser(request, env);
+        if (!user)
+            return authenticationRequired(request);
+        state.user = user;
+        return null;
+    }
+    if (strategy === "oauth") {
+        const user = Object.hasOwn(state, "user")
+            ? state.user
+            : provider
+                ? await provider.getUser(request, env)
+                : null;
+        if (!user)
+            return oauthAuthenticationRequired(url);
+        state.user = user;
+        return null;
+    }
+    return new Response("Unsupported AUTH_STRATEGY", {
+        status: 500,
+        headers: NO_STORE_HEADERS,
+    });
+}
+export function requireSameOriginMutation(request, url) {
+    if (!MUTATING_METHODS.has(request.method) || !url.pathname.startsWith("/api/"))
+        return null;
+    const origin = request.headers.get("Origin");
+    try {
+        if (origin && new URL(origin).origin === url.origin)
+            return null;
+    }
+    catch {
+        // A malformed Origin is untrusted just like a cross-origin value.
+    }
+    return jsonError("A same-origin request is required.", 403);
+}
+export function actorFor(user) {
+    return user.auth_strategy === "http_basic" ? "user:admin" : `user:${user.sub || "unknown"}`;
+}
+export function isPlatformAdministrator(state) {
+    return state.user?.auth_strategy === "http_basic" || Boolean(state.authUser?.is_admin);
+}
+export function isAdminPath(pathname) {
+    return pathname === "/admin" || pathname.startsWith("/admin/") || pathname === "/api/admin" || pathname.startsWith("/api/admin/");
+}
+export function administratorRequired(url) {
+    return url.pathname.startsWith("/api/")
+        ? jsonError("Administrator access is required.", 403)
+        : new Response("Administrator access is required.", { status: 403, headers: NO_STORE_HEADERS });
+}
+export function authenticationRequired(request) {
+    const headers = { ...NO_STORE_HEADERS, "WWW-Authenticate": 'Basic realm="admin", charset="UTF-8"' };
+    return new URL(request.url).pathname.startsWith("/api/")
+        ? Response.json({ error: "Authentication is required." }, { status: 401, headers })
+        : new Response("Authentication is required.", { status: 401, headers });
+}
+export function oauthAuthenticationRequired(url) {
+    if (url.pathname.startsWith("/api/"))
+        return jsonError("Authentication is required.", 401);
+    return Response.redirect(`${url.origin}/auth/login?return_to=${encodeURIComponent(safeReturnTo(url.pathname + url.search))}`, 302);
+}
+export function safeReturnTo(value) {
+    return value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/auth/") ? value : "/";
+}
+function basicUser(request, env) {
+    const token = String(env.ADMIN_TOKEN ?? "");
+    if (!token)
+        return null;
+    const header = request.headers.get("Authorization") ?? "";
+    if (!header.toLowerCase().startsWith("basic "))
+        return null;
+    let decoded;
+    try {
+        decoded = atob(header.slice(6).trim());
+    }
+    catch {
+        return null;
+    }
+    const separator = decoded.indexOf(":");
+    if (separator < 0 || !constantTimeEqual(decoded.slice(0, separator), "admin") || !constantTimeEqual(decoded.slice(separator + 1), token))
+        return null;
+    return { sub: "basic:admin", email: "", name: "admin", roles: ["admin"], auth_strategy: "http_basic" };
+}
+function constantTimeEqual(a, b) {
+    const aa = new TextEncoder().encode(a);
+    const bb = new TextEncoder().encode(b);
+    let difference = aa.length ^ bb.length;
+    for (let index = 0; index < Math.max(aa.length, bb.length); index += 1)
+        difference |= (aa[index] ?? 0) ^ (bb[index] ?? 0);
+    return difference === 0;
+}
+export async function prepareAdminState(env, user, state) {
+    const actor = actorFor(user);
+    state.authUser = user.authUser ?? (await ensureUser(env, user, { who: actor }));
+    state.requestedBy = requestActor(state);
+}
+//# sourceMappingURL=auth.js.map