@segmentstream/app 0.0.0-stage → 0.38.1

package/README.md

@@ -1,3 +1,1237 @@
-# Temporary Holding Version
+# @segmentstream/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Releases up to the scope change were published as `@segmentstream-cloud/app`; versions continue
+from them, with the same exports and API.
+
+The ontology client uses camelCase entities, records and actions, including
+`createdAt`, `assignedOwnerId`, and `actions.changeStatus(...)`. It translates
+queries and declared action inputs to snake_case REST and decodes records back to
+camelCase. The catalog is read lazily and cached by ontology hash so nested
+relationships and select identifiers convert while JSON property contents,
+provider payloads and opaque action results remain unchanged.
+
+Sign-in, users, permissions, the ontology client and warehouse data access for
+SegmentStream workspace apps built with Next.js (App Router, version 16.4.1 or later) and
+React 19. Compatibility deployments sign in with an email code, or a sign-in link the first time,
+through Neon Auth (Managed
+Better Auth) on the workspace's Neon project; the workspace's ontology decides who may
+use the app and what they may do. The SDK wraps `@neon/auth`, so the app never
+configures Neon Auth itself.
+
+## Declared browser methods
+
+Workspace browser authentication is declared in `ontology/index.ts`:
+
+```ts
+signIn: {
+  policy: "invited",
+  browser: { methods: ["segmentstream"], primary: "segmentstream", autoRedirect: true, local: { port: 3000 } },
+}
+```
+
+New starters use this declaration. Existing workspaces that omit `browser` retain
+Neon email authentication and optional configured SegmentStream login.
+
+This first release allows additive adoption only. A first-ever deployment may
+start with SegmentStream alone. An existing email workspace adopts
+`methods: ["email", "segmentstream"], primary: "email", autoRedirect: false`.
+Deployment rejects removing any currently serving browser method before migration;
+email-to-SegmentStream-only cutover and dual-to-email rollback are unavailable.
+A source rollback must retain the explicit declaration and its serving methods.
+Full method removal requires a later staged-activation release; linking accounts
+does not make method removal safe in this release.
+
+Email possession never merges established users. `useIdentityLink()` confirms an
+existing Neon workspace login before explicitly connecting a SegmentStream account;
+that account may use a different email. `useEmailIdentityLink()` verifies and
+explicitly attaches a Neon identity only when its email matches the canonical
+workspace user email. A missing/different workspace email requires administrator
+recovery. The SegmentStream account email is not a replacement for that profile.
+Reverse linking preserves identity but does not enable method removal or an
+email-only rollback in this release.
+
+Start a deliberate Neon-to-SegmentStream connection with
+`useBrowserSignIn().connectAccountUrl` (`GET /api/segmentstream/connect`), not the
+ordinary `segmentstreamSignInUrl`. Connect requires an existing active Neon
+workspace login. Its protected flow captures that user and sends fresh Neon proof
+with `intent: "link"` during callback exchange, bypassing new-user enrollment even
+under open admission. Switching the email workspace account aborts the connection.
+
+`useIdentityLink()` reads the pending request's expiry and trusted SegmentStream
+identity (`id`, optional `email`/`name`) together with the current workspace user's
+`id`, optional `email`/`name`. Render both before a deliberate confirmation POST to
+`confirmationUrl`; opening the page never links identities. Expired requests and
+account changes fail closed. The ontology rechecks the exact verified Neon proof;
+client-provided user IDs are never identity proof. The starter's `/sign-in/link`
+page demonstrates this review, including different-email forward linking.
+
+Deployment checks the side-effect-free
+`@segmentstream/app/browser-auth-capability` export before accepting a
+browser declaration. `app dev` also checks the installed app SDK from `app/`
+before evaluating ontology source or making an authenticated request; install
+capable app dependencies even when starting only the local ontology service. Its named `browserAuthCapability` value is a protocol
+capability, not an SDK release version. Missing/unsupported capability fails the
+build instead of allowing an older SDK to ignore the declaration.
+
+Deployment derives `SEGMENTSTREAM_BROWSER_AUTH` from the manifest. Do not author a
+second policy in app configuration. `useBrowserSignIn()` exposes enabled methods,
+safe destinations, recovery error codes, and an account-switch URL; the workspace
+supplies its own text and controls. Sole-method automatic login applies only to
+normal GET page navigation. Error/recovery pages, APIs, prefetch and non-GET
+requests never restart authentication automatically.
+
+During deployment, Cloud may admit the immediately preceding production browser revision for
+up to 30 seconds after confirmed promotion when its authentication, origin and relevant ontology
+contracts remain compatible. Revision admission is checked on each protected request. The SDK
+accepts a different configuration digest only when Cloud explicitly admits that exact live digest.
+Disabled clients, removed methods and changed security policy never gain this overlap.
+
+A page pinned to a revision that cannot continue receives `409 deployment_refresh_required`,
+`retryable: false`, and an `x-segmentstream-error` response header. Server calls throw
+`SegmentStreamApiError` with the same code. The workspace supplies its recovery wording and
+refresh controls. The SDK never reloads these pages or replays a POST in response to this signal. Revision
+status and configuration network failures retain `browser_auth_revision_unavailable` and
+`browser_auth_configuration_unavailable`; authentication and session errors retain their own codes.
+
+SegmentStream accounts and Cloud access are separate. An app-only member needs no
+Cloud organization membership; app signup and invitations do not grant organization
+creation. SegmentStream-only launch requires explicitly confirmed open WorkOS account
+registration. Closed-registration invitation handoff is not implemented. An emailed
+app link preserves its safe destination but may require interactive WorkOS login,
+registration, verification, consent, or account recovery; it is not a universal
+signed-out one-click login. Compatibility and dual deployments keep their Neon
+email-link behavior and workspace-owned templates/reply routing.
+
+For local development install app and ontology dependencies, supply an isolated
+local ontology database, and keep the ontology dev service on loopback port 3100.
+Run these from the workspace root in separate terminals:
+
+```sh
+segmentstream app dev -- npm --prefix ontology run dev
+segmentstream app dev -- npm --prefix app run dev
+```
+
+`app dev` currently supports SegmentStream-only local source. It rejects dual-method
+and email-only declarations before authentication, client registration, or launching
+a dev process. Those workspaces keep their existing independently configured local
+email workflow until isolated local Neon bindings are supported. Do not copy
+production Neon credentials or silently change the deployed browser policy to use
+this command. Deployed dual-method authentication remains supported.
+
+The CLI evaluates the local ontology, registers an exact temporary loopback client
+for its declared `local.port`, and passes matching configuration to each process.
+Restart after changing the declaration or after the 24-hour client deadline. It
+does not create a database or persist authentication configuration. The app must
+listen on its declared port; this starter uses 3000. Cloud checks `app_auth:manage`
+for client registration. Local activity does not count as production migration.
+
+## Install
+
+```sh
+npm install @segmentstream/app
+```
+
+## Deploying workspace source
+
+Main pushes deploy the workspace by default. To accumulate source updates for an explicit
+release, commit `.segmentstream/deployment.json` with
+`{ "schemaVersion": 1, "trigger": "manual" }`. Pushes still store and index source;
+`segmentstream deploy` explicitly deploys current main with the existing authorization and
+idempotency checks. Removing the file or selecting `"push"` restores automatic deployment.
+This repository setting is read by Cloud, not by the app SDK, and adds no scheduler.
+
+For an existing hourly release process, the optional `productionWindow` setting
+in the same file restricts explicit production admission to configured UTC minutes.
+Outside that window, create and retry return `deployment_window_closed` with the
+next opening time; no attempt starts. This adds no scheduler or preview restriction.
+
+## Set up
+
+The proxy and server-client setup is shared. The auth-route/sign-in form example
+below is for enabled email compatibility. Declared SegmentStream browser methods
+use workspace-owned `useBrowserSignIn()` UI and `segmentstream.handlers()` at
+`/api/segmentstream/[...path]`; the starter supplies those routes and recovery pages.
+
+**`src/segmentstream.ts`** configures the app once. Pass the type of the app's
+ontology to type `segmentstream.ontology`; the ontology is imported as a type only:
+
+```ts
+import { createSegmentStreamApp } from "@segmentstream/app";
+
+import type ontology from "../../ontology";
+import link from "../segmentstream.json"; // { "workspaceId": "…", "organizationId": "…" }
+
+export const segmentstream = createSegmentStreamApp<typeof ontology>(link);
+```
+
+**`src/proxy.ts`** keeps every page and API route signed in:
+
+```ts
+import { segmentstream } from "./segmentstream";
+
+export const proxy = segmentstream.proxy({
+  // Optional: paths anyone may open. `/webhooks` also covers `/webhooks/stripe`.
+  publicPaths: ["/webhooks"],
+});
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+Static assets, `/api/auth`, `/sign-in` and `/api/health` are always open.
+
+**`src/app/api/auth/[...path]/route.ts`** serves the Neon Auth API that sign-in and
+sessions use:
+
+```ts
+import { segmentstream } from "@/segmentstream";
+
+export const { GET, POST, PUT, DELETE, PATCH } = segmentstream.authHandlers();
+```
+
+The route completes emailed sign-in links (`/api/auth/magic-link/verify`) itself: it
+verifies the token through Neon Auth without a callback, sets the session cookies on
+the app's domain and redirects to the link's `callbackURL` path. An expired, used or
+unknown link redirects to `/sign-in?error=sign_in_link_invalid`, where `<SignIn />` (or
+`useSignIn().linkInvalid`) offers a new one.
+
+**`src/app/sign-in/page.tsx`** renders the sign-in form, and the root layout imports
+its stylesheet once. Apps with their own design system render their own form on
+[`useSignIn()`](#your-own-sign-in-form) instead and skip the stylesheet:
+
+```tsx
+import { SignIn } from "@segmentstream/app/ui";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export default async function SignInPage({ searchParams }: { searchParams: SearchParams }) {
+  const { returnTo, error } = await searchParams;
+
+  return (
+    <SignIn
+      returnTo={typeof returnTo === "string" ? returnTo : undefined}
+      error={typeof error === "string" ? error : undefined}
+    />
+  );
+}
+```
+
+```tsx
+// src/app/layout.tsx
+import "@segmentstream/app/ui/styles.css";
+```
+
+## Publish page descriptions for ontology agents
+
+Page discovery is optional. Wrap the app's Next.js configuration:
+
+```ts
+import { withPageCatalog } from "@segmentstream/app/navigation/next";
+
+export default withPageCatalog({});
+```
+
+Keep existing Next plugins and configuration inside the wrapper. Object and async
+function configurations are supported, and an existing
+`compiler.runAfterProductionCompile` hook still runs. The route adapter supports
+stable Next.js 16.x App Router builds.
+
+Add `page.navigation.json` beside an ordinary page, using canonical ontology names:
+
+```json
+{
+  "title": "Invoices",
+  "entities": ["invoice"],
+  "description": "Search invoices and open one from the results."
+}
+```
+
+The SDK derives the route from the page file, including route groups, dynamic and
+catch-all segments, `pageExtensions`, `basePath`, and `trailingSlash`. Optional
+`parameters` and `query` maps describe existing UI behavior. Parameter hints must
+name actual path parameters. Pages may name multiple entities or no entities.
+Page components, data loading, and frontend links do not change.
+
+`segmentstream deploy` prepares the catalog from the immutable app source and its
+evaluated ontology before the app and ontology builds. It verifies the final Next
+route inventory after the app's configured build command. The ontology service
+publishes the resulting metadata through its read-only `navigation` MCP tool.
+Sidecars without `withPageCatalog` fail preparation. Missing, invalid, shadowed,
+or unrepresentable annotated routes fail rather than publishing guessed links.
+
+For a standalone build, supply the evaluated ontology JSON (`hash` and an
+`entities` array with canonical `name` fields) and immutable source identity:
+
+```sh
+npx --no-install segmentstream-page-catalog generate --project-dir . --ontology ../evaluated-ontology.json --source-hash "$SOURCE_HASH"
+npm run build
+npx --no-install segmentstream-page-catalog verify --project-dir .
+```
+
+The Node-only `@segmentstream/app/navigation/build` entry point exports
+`generatePageCatalog({ files, routing?, ontology, sourceHash })` for pure in-memory
+generation, `preparePageCatalog({ projectDir, ontology, sourceHash })` for resolved
+Next configuration and artifact preparation, and
+`verifyPageCatalogBuild({ projectDir })` for final build checks. File-map keys are
+app-root relative, such as `src/app/invoices/page.tsx`; values are source strings.
+Preparation also reports annotated and unannotated page coverage.
+
+Ignore `.segmentstream/navigation/` in Git. Its atomically replaced
+`page-catalog.json` is the deployment artifact; `build-context.json` and
+`compiled.json` are disposable build inputs/evidence and are not runtime settings.
+Failed generation or verification removes previous output. Custom build commands
+must retain the compiler hook and run final verification; a prepared catalog
+alone does not prove the app was built.
+
+An intercepted annotation has no independent URL and must describe its ordinary
+destination or containing page. A parallel annotation requires an ordinary
+direct-load page at the same URL. Unannotated variants do not prevent adoption.
+Redirects, `beforeFiles` rewrites, and `afterFiles` rewrites preceding a dynamic
+page fail validation when they may intercept an advertised route. Dynamic routes are
+compared by complete path shape, including optional and catch-all segments. Custom
+regular expressions remain conservative when static prefixes cannot prove them
+disjoint. Runtime proxy/redirect behavior remains the workspace's responsibility.
+
+## Read the signed-in user
+
+```tsx
+import { segmentstream } from "@/segmentstream";
+
+export default async function Page() {
+  const user = await segmentstream.requireUser();
+
+  return (
+    <p>
+      {user.name ?? user.email}: {user.roles.join(", ")}
+    </p>
+  );
+}
+```
+
+- `requireUser()` returns `{ id, email?, name?, roles, permissions, scopes?, kind?,
+active?, authUserId?, organizationId, workspaceId }`. `id` is the person's ontology `user`
+  record. Roles and permissions come from the ontology's `GET /api/ontology/me`,
+  cached per session for a minute; `requireUser({ fresh: true })` asks again and
+  caches the new answer. Signed out, it redirects to `/sign-in`. For a
+  person the app has not invited (`403 not_invited`), it redirects to
+  `/sign-in?error=not_invited`, where `<SignIn />` asks them to request an invitation
+  or use another email.
+- `getUser()` returns the same, or `null` when signed out, and takes `{ fresh }`; it throws
+  `SegmentStreamApiError` with `code: "not_invited"` for people without an invitation.
+- `can("lead:changeStatus")` is `true` when the user's permissions cover the
+  permission. Roles may hold wildcards: `lead:*`, `*:read`, `*:*`. `isAllowed` and
+  `grants` apply the same rule to any list of permissions.
+- `scopes`, present only when a held permission covers some records only (a
+  [scoped permission](../../docs/ontology.md#scoped-permissions),
+  ontology 0.40.0 and later), lists them as `{ permission, where }`. `permission` is
+  spelled as in `permissions`, which still holds it, so `can()` is `true`; `where` is
+  the condition in the wire form of a query, the user as `{ "$me": [] }` and a path
+  from them as `{ "$me": ["staff_member", "division"] }`. It is informational, for
+  what the app shows: the ontology service enforces the scope on every read and write.
+- The cached roles decide what the app shows. Every `segmentstream.ontology` request is
+  checked by the ontology service with the member's current roles, so it never needs
+  `fresh`. Pass `can(permission, { fresh: true })` where code outside the ontology, such
+  as a warehouse query or a job start, is gated on a permission that a role change must
+  take away at once.
+- `signOut()` ends the session, clears its cookies and redirects to `/sign-in` (or
+  `{ redirectTo }`). Call it from a Server Function or Route Handler.
+
+Use them in Server Components, Route Handlers and Server Functions. Always check the
+user in Server Functions and Route Handlers too; do not rely on the proxy alone.
+
+## Client components
+
+`@segmentstream/app/ui` holds React client components with plain, neutral CSS
+(no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
+`:root` set colours, radius and font.
+
+| Export                                 | Does                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `<SignIn />`                           | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
+| `useSignIn()`                          | The same sign-in without markup, for the app's own form                         |
+| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                |
+| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise       |
+| `<UserMenu />`                         | Name, email, roles and sign-out                                                 |
+| `<AgentConnect />`                     | The agent connect page: the pairing, an Approve button and the result           |
+| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
+| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
+| `useSession()`, `signOut()`            | The selected browser session; sign-out from the browser                         |
+
+For an OIDC or channel session, `signOut()` revokes the selected grant before clearing browser
+state and navigating. It rejects on revocation failure, keeping the session available for retry.
+
+`<Can>` only hides controls: the ontology service checks every read and action. A
+Server Component may wrap server-rendered children in `<Can>`:
+
+```tsx
+<Can permission="lead:changeStatus" fallback={lead.status}>
+  <ChangeStatusForm lead={lead.id} />
+</Can>
+```
+
+### Your own sign-in form
+
+This email controller applies only when `email` is enabled. For declared
+SegmentStream login use `useBrowserSignIn()` and supply workspace-owned text.
+
+`useSignIn({ returnTo, error })` holds everything `<SignIn />` does, without markup: the
+sign-in check, the steps, the 30-second resend hold, the six-digit check, error sentences
+and their codes, the return to `returnTo` after sign-in and the `not_invited` and
+`sign_in_link_invalid` states. Both options default to the page's query parameters.
+
+`submitEmail()` first asks the ontology's `POST /api/ontology/sign-in/check` whether the
+address may sign in. A member who has signed in with Neon Auth before gets a six-digit
+code (`step: "code"`). A first sign-in gets a sign-in link instead (`step: "link"`),
+because Neon Auth sends codes only to existing accounts and the link creates the
+account. An address the ontology refuses gets `errorCode: "not_invited"`, and nothing
+is sent. Without an ontology that answers the check (none, or one deployed with
+`@segmentstream/ontology` before 0.4), every address gets a code. The workspace starter renders it with
+Tailwind CSS and shadcn/ui in `src/components/sign-in-form.tsx`; `<SignIn />` stays for
+apps without Tailwind.
+
+```tsx
+"use client";
+
+import { useSignIn } from "@segmentstream/app/ui";
+
+export function SignInForm() {
+  const signIn = useSignIn();
+
+  if (signIn.step === "email") {
+    return (
+      <form
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault();
+          void signIn.submitEmail();
+        }}
+      >
+        <input
+          type="email"
+          value={signIn.email}
+          onChange={(event) => signIn.setEmail(event.target.value)}
+        />
+        {signIn.error !== null && <p role="alert">{signIn.error}</p>}
+        <button disabled={signIn.pending !== null}>Continue</button>
+      </form>
+    );
+  }
+
+  if (signIn.step === "link") {
+    return (
+      <p>
+        We sent a sign-in link to {signIn.email}. Open it to sign in.
+        <button type="button" onClick={() => void signIn.resend()} disabled={signIn.resendIn > 0}>
+          Resend link
+        </button>
+      </p>
+    );
+  }
+
+  return (
+    <form
+      noValidate
+      onSubmit={(event) => {
+        event.preventDefault();
+        void signIn.submitCode();
+      }}
+    >
+      <input
+        inputMode="numeric"
+        autoComplete="one-time-code"
+        value={signIn.code}
+        onChange={(event) => signIn.setCode(event.target.value)}
+      />
+      {signIn.error !== null && <p role="alert">{signIn.error}</p>}
+      <button disabled={signIn.pending !== null}>Sign in</button>
+      <button type="button" onClick={() => void signIn.resend()} disabled={signIn.resendIn > 0}>
+        Resend code
+      </button>
+    </form>
+  );
+}
+```
+
+| Field                                  | Means                                                                                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `step`                                 | `email`, then `code` once a code is sent, or `link` once a sign-in link is sent       |
+| `email`, `setEmail`, `code`, `setCode` | The field values; `submitEmail()` trims the address                                   |
+| `pending`                              | `send`, `verify`, `resend` or `sign-out` while a call runs; disable the form          |
+| `error`, `notice`                      | A sentence for the person, and a confirmation such as a resent code                   |
+| `errorCode`, `noticeCode`              | Why the call failed (`not_invited`, `code_invalid`, …) and what was resent, to reword |
+| `resendIn`                             | Seconds until `resend()` may be offered; 0 when it may                                |
+| `submitEmail()`, `submitCode(value?)`  | Check, then send a code or link; verify `value` or `code`. A wrong code clears `code` |
+| `resend()`, `changeEmail()`            | Another code, or link, to the same address; back to the email step                    |
+| `signedIn`, `destination`              | A session already exists: offer a link to `destination`                               |
+| `notInvited`, `sessionEmail`           | The person is signed in as `sessionEmail` without an invitation                       |
+| `switchAccount()`                      | Signs out and returns to the email step                                               |
+| `linkInvalid`                          | An emailed sign-in link was expired or used: say so on the email step                 |
+
+The calls take values, not form events: call `submitEmail()` and `submitCode()` from the
+form's submit handler after `event.preventDefault()`. A second `submitCode()` while one
+runs is ignored, so the last digit and the Enter key may both submit.
+
+## Telegram Mini App sign-in
+
+The Mini App is the same app on any page. Enable it explicitly in both SDKs:
+
+```ts
+// App SDK configuration
+createSegmentStreamApp({ ...link, channels: { telegram: true } });
+
+// Ontology service configuration (the connection used by chat.telegram)
+createOntologyService(ontology, {
+  ...config,
+  channels: { telegram: { connection: "chat_bot", miniApp: {} } },
+});
+```
+
+Without these opt-ins, exchange and Telegram framing stay disabled. Providers default to invited:
+paired members can sign in. Workspace apps may explicitly open `signIn.channels.telegram` for new
+accounts and choose their restricted member grants, `onNewUser` action, notice/reply content and
+lower limits. The exchange uses A1's shared admission, limits and onboarding; browser values cannot
+change them. Members without email are managed by member ID.
+
+Mount `<TelegramSignIn />` in a client layout on any page, or call `useTelegramSignIn()` and render
+its `{status, error}` codes with app-owned copy. `<SignIn />` automatically exchanges when the app
+opts in and Telegram launch data is present; `renderTelegram` optionally renders its status. No
+dedicated Mini App route is provided. In a top-level WebView, an unauthenticated deep link redirects
+to `/sign-in?returnTo=…`; HTTP redirects inherit Telegram's URL fragment, and the SDK reads
+`tgWebAppData` there. Raw assertions never enter redirect queries, logs or persistent storage.
+For Telegram Web, an unauthenticated iframe navigation instead receives an inert exchange shell
+at the original protected URL. It renders no workspace content and makes one exchange, then checks
+that the browser retained the session cookie before reloading the deep link. This requires the app's
+explicit Telegram opt-in and is limited to iframe GET navigations. Decision pages remain unframeable.
+Missing launch data stays idle; a refusal or failed discovery stops without reloading or falling back
+to another provider. The shell has no UI copy; its `data-channel-sign-in` and
+`data-channel-sign-in-error` attributes expose status and machine codes for inspection.
+If the same launch returns to the shell after its one allowed reload, it stops with `launch_loop`;
+reopen the Mini App with fresh launch data to retry.
+Safari and other browsers without usable CHIPS cannot persist an iframe session; the regular
+sign-in redirect remains DENY inside an iframe, so use a top-level Mini App launch.
+Browsers without Fetch Metadata headers fall back to that DENY sign-in redirect.
+
+A failed launch otherwise stays on the blank shell. To explain it in the app's own words, name a
+public page with `channelLaunchFailurePath`:
+
+```ts
+export const proxy = segmentstream.proxy({
+  publicPaths: ["/telegram-unavailable"],
+  channelLaunchFailurePath: "/telegram-unavailable",
+});
+```
+
+After any failure except missing launch data, the shell replaces the frame with that page and
+passes `error`, the machine code (`session_unavailable` when the browser did not keep the session
+cookie, `launch_loop`, `not_paired`, `access_refused` and the other exchange codes), and
+`returnTo`, the launched path and query. Telegram's launch data stays in the fragment and never
+reaches the page. Telegram Web frames the page, and anyone can open it with any query: show only
+copy chosen for known codes, and accept `returnTo` only as a local path, for example to open it in
+a new browser tab, where regular sign-in works. The path must be a plain page covered by
+`publicPaths`, never a decision page or an `/api`, `/mcp`, `/.well-known` or `/_next` route; the
+proxy refuses other values.
+Apps using Telegram's Web App script can also supply fresh data from `Telegram.WebApp.initData`:
+
+```tsx
+"use client";
+import { TelegramSignIn } from "@segmentstream/app/ui";
+
+export function ChannelSession() {
+  return <TelegramSignIn />;
+}
+```
+
+The hook posts each fresh assertion once. A single timer renews at the discovered session's
+`expires_at`, without polling. Supply `initData={() => freshRawInitData}` for a custom integration;
+if Telegram still supplies an expired assertion, reopen the Mini App. The app owns refusal text.
+
+A valid channel session takes precedence over regular OIDC and Neon sessions on server, proxy and
+browser. Stale channel cookies fall through to regular sign-in. `requireUser`, ontology transport,
+`useSession`, `useUser`, permissions and logout use that selection. JavaScript receives session
+metadata, never the opaque token. `getAccessToken()` remains the legacy SegmentStream credential
+API, and legacy SegmentStream-mode `can()` keeps its previous behavior. Routes live outside
+`/api/auth/*`.
+
+Session discovery, configuration and proxy verification/refresh outages remain `unavailable`; they never
+select another provider's user or start an assertion exchange. Retry session discovery or reload
+after recovery. Malformed channel/OIDC identity responses also stop authentication; OIDC discovery
+retains upstream failures instead of reporting a signed-out session. Only confirmed absence or
+refusal is treated as signed out.
+
+Browser discovery probes Neon only when the app configures it. Telegram sign-in also works in
+legacy SegmentStream apps without Neon or OIDC. A separate `SEGMENTSTREAM_ONTOLOGY_URL` uses its
+HTTP(S) origin consistently for channel discovery and protected-page validation.
+Public proxy paths and OAuth metadata discovery bypass cookie verification in every authentication
+mode. Unsupported metadata returns 404 without starting sign-in.
+
+Sessions last one hour absolutely, without refresh tokens. HTTPS cookies are HttpOnly, Secure,
+SameSite=None and Partitioned. Logout revokes the grant and clears the cookie. Renewal, unpairing
+and pairing displacement revoke only that identity's grants; blocking/deactivation revoke all of
+that member's sessions. Writes, exchange and logout require the app's Origin. Framing by Telegram
+Web is enabled only with app opt-in; sign-in, consent and pairing pages always remain DENY.
+
+Before release, manually check Telegram iOS, Android, Desktop and Web: deep-link launch/fragment retention,
+exchange, reload, expiry/fresh data, partitioned-cookie persistence, logout/reopen, mixed sessions
+and revoked/blocked/deactivated members. These checks need a deployed HTTPS app and are separate
+from local fixtures. CI runs the HTTPS iframe suite when Chrome is installed; opt in locally with
+`CHROME_BIN=/usr/bin/google-chrome pnpm --filter @segmentstream/app test --maxWorkers=1 tests/telegram-launch.browser.test.ts`.
+It uses Chrome and OpenSSL installed on the host and a temporary self-signed certificate.
+
+## The ontology
+
+`segmentstream.ontology.<entity>` calls the app's ontology service at `/api/ontology`
+with the signed-in user's selected workspace session, so the service applies their permissions.
+Records, action inputs and action results are typed from the ontology:
+
+```ts
+const { items, nextCursor } = await segmentstream.ontology.lead.find({
+  where: { status: { in: ["new", "contacted"] } },
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+  include: ["owner"],
+  limit: 20,
+});
+const lead = await segmentstream.ontology.lead.get(id);
+const history = await segmentstream.ontology.lead.history(id, { limit: 50 });
+const page = await segmentstream.ontology.lead.query({ where: { email: { startsWith: "ada" } } });
+
+const input = { lead: id, status: "contacted" } as const;
+const check = await segmentstream.ontology.lead.actions.changeStatus(input, {
+  validateOnly: true,
+});
+const { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
+```
+
+- `find` sends the query as URL parameters, `query` as a JSON body; both return
+  `{ items, nextCursor }`. Pass `nextCursor` as `after` for the next page.
+- `include` adds related records under their relationship names: list the names,
+  `["owner", "tags"]`, or pass `{ owner: true, tags: true }`.
+- `select: ["email", "status"]` returns only those base fields, plus `id` and
+  any requested `include` relationships. An empty list returns ids only. Selected
+  pages carry `projected: true`; the typed client marks unselected fields optional.
+  Filtering and cursor ordering may use unselected fields. Omit `select` to receive
+  complete records. `get` and action reads always return complete records.
+- `actions.<name>(input, { validateOnly })` posts `{ input, options }` and returns
+  `{ result, validation, edits }`. Generated actions are there too
+  (`actions.create`, `update`, `delete`), and `action(name, input)` runs any action by
+  name, such as `upsert_by_email`.
+- `segmentstream.ontology.user` reads members and services. Each record has `roles`, the
+  role names assigned to it without `member`, spelled as `requireUser().roles` spells
+  them; filter on them with `where: { roles: { has: "sales" } }` or
+  `{ roles: { hasAny: ["sales", "support"] } }`. Its generated actions change them:
+  `actions.invite({ email, name?, roles? })`, `grantRoles({ id, roles })`,
+  `revokeRoles({ id, roles })` or `revokeRoles({ id, all: true })`, `deactivate({ id })`
+  and `reactivate({ id })`. Each needs its explicit `user:<verb>` permission, which
+  `*:*` does not cover, writes history and returns the updated record. List `User` (or
+  `User.actions(…)`) in the ontology's `entities` to type `segmentstream.ontology.user`.
+- Failures throw `SegmentStreamApiError` with the service's `code` (`forbidden`,
+  `not_found`, `invalid_input`, `action_rejected`, `conflict`, `not_invited`), `status`,
+  `detail`, `requestId` and, for invalid input, `issues`.
+- The types are read from the ontology SDK's `Ontology`, entity and action types
+  structurally, so the app needs neither the ontology SDK nor Effect at runtime.
+  Without a type argument, any entity name is accepted and records are untyped.
+
+### Upload files
+
+In a Neon Auth app, import the browser client from `@segmentstream/app/storage`
+and send its metadata requests to the app's own ontology path:
+
+```ts
+import { createBlobStorageClient } from "@segmentstream/app/storage";
+
+const files = createBlobStorageClient({
+  fetch: (path, init) => fetch(`/api/ontology${path}`, { ...init, credentials: "same-origin" }),
+});
+
+// In the file picker: keep this UUID for retries of this file's upload.
+const uploadKey = crypto.randomUUID();
+const uploaded = await files.uploadForAction(
+  { entity: "document", property: "content", action: "create" },
+  selectedFile,
+  { idempotencyKey: uploadKey },
+);
+```
+
+The browser attaches the member's HttpOnly Neon session cookie automatically. The
+ontology checks the target action's permission before issuing a transfer grant;
+missing permission answers `403`. File bytes go directly to storage without member
+credentials. Import the `/storage` entry point in browser code; the package root
+loads the server-side app integration. No token handling or `segmentstream.fetch`
+call is needed.
+
+Send `uploaded.ticket` and `uploaded.options` as JSON to a workspace Server Function
+or Route Handler. As the same signed-in member, server code calls:
+
+```ts
+await segmentstream.ontology.document.actions.create(
+  { title: "Contract", content: { uploadId: uploaded.ticket.uploadId } },
+  uploaded.options,
+);
+```
+
+Upload completion alone does not change a record. Keep the upload result and retry
+the action with the same input and options if its response is lost; do not restart
+an upload after its ticket has been consumed. The helper supplies `createIntent`
+for a new record; use `recordId` in the target when changing an existing record.
+The deployed blob property, target action and workspace quota must permit the file.
+The returned `uploaded.upload` contains the session ID, state and expiry. An optional
+`onSession(session)` callback records that ID as soon as the server creates it, even
+if a later transfer fails. `onProgress` reports byte transfer, not record creation.
+
+Recover your current open sessions with `await files.list()`: it returns `pending`,
+`max` and `uploads`, including filename, target action, expiry and `awaitingAction`.
+A `ready` session with `awaitingAction: true` has uploaded bytes and still needs its
+saving action. Use `files.status(id)` to inspect its ticket. When you abandon that
+action, including after a permanent rejection, call `await files.cancel(id)` to
+release the slot. Keep the session when you intend to retry; do not cancel merely
+because an action returned an error or its response was lost. Saved records cannot
+be canceled through this API. Discovery requires an upgraded, redeployed ontology;
+the existing status and cancel endpoints also work with earlier SDK deployments.
+
+`SegmentStreamApiError.limit` preserves structured platform refusals: `storage_quota`
+has `usedBytes`, `requestedBytes` and `quotaBytes`; `pending_uploads` has `pending`,
+`max` and, when supplied, the open upload IDs, filenames and `expiresAt` values;
+`member_attachments` has `live` and `max`. Workspace code supplies the user-facing
+explanation from these fields.
+See the complete [browser upload and Server Function example](../../docs/app-data.md#upload-an-ontology-file)
+for authentication, retries, cancellation, and local development.
+
+### Download files
+
+Server Components and Route Handlers request blob download grants through the same
+member-authenticated client, including under Neon Auth:
+
+```ts
+const grant = await segmentstream.ontology.document.files.download(id, "content", {
+  inline: false,
+});
+// grant: { url, method: "GET", headers, expiresAt }
+```
+
+The ontology checks current `document:read` permission and record scopes. The
+property name is typed to blob properties; options also accept `revisionId` and
+`signal`. Missing permission throws `SegmentStreamApiError` with status `403`;
+an inaccessible record or revision answers `404`. The helper never reads file bytes.
+
+Use a Route Handler to obtain a fresh grant and redirect the browser to its signed
+GET URL with `Cache-Control: private, no-store`. The browser downloads directly
+from storage, including files over 2 MiB. Keep the app route as the durable link,
+since grants expire. See the complete
+[Route Handler example](../../docs/app-data.md#download-an-ontology-file).
+
+Normal app downloads need no custom transport or token handling, and do not use
+`segmentstream.fetch` or the workspace machine credential. Browser uploads use
+the separate [storage client](#upload-files).
+
+## Agent connect page
+
+The workspace agent answers a chat account it does not know, such as a Telegram user,
+with a link to `/agent/connect?code=<code>`. A signed-in member approves there, and the
+ontology links the account to them: the agent then acts as that member, with their
+current roles, for that account's messages. The proxy signs the page in like any other
+and forbids other sites to frame it.
+
+```tsx
+// src/app/agent/connect/page.tsx, without Tailwind
+import { SegmentStreamApiError, type AgentPairing } from "@segmentstream/app";
+import { AgentConnect } from "@segmentstream/app/ui";
+import { segmentstream } from "@/segmentstream";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export default async function ConnectPage({ searchParams }: { searchParams: SearchParams }) {
+  const user = await segmentstream.requireUser();
+  const { code, connected } = await searchParams;
+  let pairing: AgentPairing | null = null;
+
+  if (typeof code === "string" && typeof connected !== "string") {
+    try {
+      pairing = await segmentstream.agent.pairing(code);
+    } catch (error) {
+      // A used or expired code shows "This link has expired"; anything else is an error.
+      if (
+        !(error instanceof SegmentStreamApiError) ||
+        !["not_found", "expired"].includes(error.code)
+      ) {
+        throw error;
+      }
+    }
+  }
+
+  return (
+    <AgentConnect
+      code={typeof code === "string" ? code : undefined}
+      pairing={pairing}
+      connected={typeof connected === "string" ? connected : undefined}
+      member={user.email ?? undefined}
+    />
+  );
+}
+```
+
+```ts
+// src/app/api/agent/connect/route.ts
+import { segmentstream } from "@/segmentstream";
+
+export const { POST } = segmentstream.agent.connectHandler();
+```
+
+`segmentstream.agent` holds:
+
+| Call                   | Does                                                                                   |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| `pairing(code)`        | `{ provider, display, expiresAt }`; throws `not_found` or `expired`                    |
+| `approvePairing(code)` | Links the account to the signed-in member; returns the `AgentIdentity`                 |
+| `identities()`         | The member's own: `{ id, provider, externalId, display, createdAt, revokedAt }`        |
+| `revokeIdentity(id)`   | Revokes one of them at once                                                            |
+| `connectHandler()`     | `{ POST }` for the page's form: same-origin only; `303` on success; throws on conflict |
+
+The handler sends the browser back to `/agent/connect?connected=<provider>`, or to
+`/agent/connect?expired=1` when the code was used or is older than ten minutes. An account already
+connected to another member throws `SegmentStreamApiError` with status `409` and
+`code === "identity_in_use"` through the app's existing error mechanism. The app owns conflict copy.
+Same-member pairing is idempotent, and replacing your own previous account on a provider is supported. Other
+refusals, such as `forbidden` for a member the ontology does not admit, throw
+`SegmentStreamApiError`. All calls are server-only and run as the signed-in member;
+the ontology decides every one. The workspace starter renders the page with Tailwind CSS
+and shadcn/ui; apps made from an earlier starter add `src/app/agent/connect/page.tsx`
+and `src/app/api/agent/connect/route.ts` from it.
+
+## Query the warehouse
+
+```tsx
+import { sql } from "@segmentstream/app";
+import { segmentstream } from "@/segmentstream";
+
+type Revenue = { order_date: string; total_revenue: number };
+
+export default async function Page() {
+  await segmentstream.requireUser();
+
+  const { rows } = await segmentstream.warehouse.query<Revenue>(
+    `SELECT order_date, total_revenue
+     FROM gold.revenue_summary
+     WHERE order_date >= @from
+     ORDER BY order_date`,
+    { params: { from: sql.date("2026-09-01") } },
+  );
+
+  return <pre>{JSON.stringify(rows, null, 2)}</pre>;
+}
+```
+
+- Warehouse calls authenticate with the workspace app credential,
+  `SEGMENTSTREAM_APP_CREDENTIAL`, which SegmentStream sets on deploy and the SDK reads
+  on every call. Without it they use the legacy sign-in's session token. The
+  credential belongs to the app, so check the user before querying for them.
+- Queries are read-only GoogleSQL over the workspace warehouse. `dataset.table` resolves
+  to the workspace's project. Anything other than a single `SELECT` is rejected.
+- Pass values as named `@parameters` in `params`; never build SQL from user input.
+  Strings, booleans, `bigint`, safe integers (`INT64`), other numbers (`FLOAT64`), `Date`
+  (`TIMESTAMP`) and arrays of these are typed automatically. Use `sql.date()`,
+  `sql.datetime()`, `sql.timestamp()`, `sql.numeric()`, `sql.bignumeric()`, `sql.int64()`
+  and `sql.array(type, values)` for anything else.
+- `query()` waits for running queries (`timeoutMs`, default 60 s) and follows result
+  pages up to `maxRows` (default 10,000); `truncated` reports whether more rows exist.
+  `maximumBytesBilled` lowers the per-query byte ceiling; `warehouse.dryRun()` returns the
+  estimated bytes and result columns without running the query.
+- Long queries keep running in the warehouse for up to an hour after `query()` stops
+  waiting. It then throws `query_timeout` with a `queryId`. Resume the query from a later
+  request, for example a Route Handler your page polls, with `warehouse.result(queryId)`.
+  Don't hold one request open for minutes.
+- Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
+  timestamps as ISO strings, records and arrays as JSON strings.
+
+One authorization model covers the ontology: every `segmentstream.ontology` call, metric queries
+included, runs as the signed-in user through the ontology service, which checks their
+permissions. `segmentstream.ontology.<entity>.queryMetrics(request)` posts to
+`/api/ontology/<entity>/query_metrics` and needs read permission on the entities it reaches.
+`segmentstream.warehouse` uses the workspace app credential and reaches the whole workspace
+warehouse. The job helpers below use it for explicitly opted-in jobs. `segmentstream.fetch(path)` still requires the legacy
+platform session. Metric queries through the service need the workspace's ontology deployed with
+`@segmentstream/ontology` 0.13.0 or later.
+
+The next release names analytics as the ontology does: a request for metrics grouped by
+dimensions is a metric query, `queryMetrics`, which takes `metrics` and `orderBy[].metric`. Its
+types are `MetricQuery`, `EntityMetricQuery`, `MetricQueryResult`, `MetricQueryField`,
+`MetricQueryFilter`, `MetricQueryFilterOperator` and `MetricQueryGranularity`, and the client
+reads an ontology's `metrics`. Earlier releases named these calls and types differently; the
+sections below use the current names. Code that uses the earlier names keeps compiling and
+working as deprecated aliases, which the release notes list, and the client also reads the
+metrics of an ontology built by an earlier ontology SDK. The client posts to
+`/api/ontology/query_metrics` and `/api/ontology/<entity>/query_metrics`. An ontology service
+deployed with an ontology SDK before manifest version 14 serves metric queries only at their
+earlier routes, with the earlier names, and answers 404 at these: the client then posts the
+query there, and once that route answers, sends the service's later queries there directly.
+
+Since 0.10.0, dimensions, filters and `orderBy` accept relationship paths, typed from the
+ontology's relationships:
+
+```ts
+const { rows, execution } = await segmentstream.ontology.order.queryMetrics({
+  dimensions: ["customer.segment"],
+  metrics: ["orders"],
+  dateRange: { from: "2026-09-01", to: "2026-09-30" },
+});
+```
+
+- A path is `<relationship>.<property>`, through one or two to-one relationships. Paths into
+  a stored target include `id`; json and blob properties are left out. A thunk target types
+  its paths as `` `customer.${string}` ``. Each segment converts to snake_case on the wire,
+  and rows come back keyed by the camelCase path. These names are relative to the entity and
+  convert as record fields do: `line_2` reads as `line2`.
+- `execution.warnings` reports keys that matched more than one related row; totals are
+  unaffected. Warnings are absent when the query produced none. Stored replicas are eventually
+  consistent; current responses do not report `execution.sources` or a destination freshness watermark.
+- 0.10.0 requires the platform release that joins stored targets through replication.
+- See [relationship paths](../../docs/ontology-metrics.md#relationship-paths).
+
+Since 0.10.0, `segmentstream.ontology.queryMetrics(request)` asks for numbers about the whole
+model: metrics of several entities, warehouse-backed or stored, grouped by properties they all
+reach. Look at or change records through `find` and actions; count, sum or compare through
+`queryMetrics`.
+
+```ts
+const { fields, rows, execution } = await segmentstream.ontology.queryMetrics({
+  metrics: ["acmeSales.revenue", "acmeStock.onHand"],
+  dimensions: ["acmeProduct.assortmentStatus"],
+  filters: [
+    {
+      dimension: "acmeSales.orderDate",
+      operator: "between",
+      values: ["2026-09-01", "2026-09-30"],
+    },
+    { dimension: "acmeSales.currency", operator: "equals", value: "RUB" },
+  ],
+  orderBy: [{ metric: "acmeSales.revenue", direction: "desc" }],
+});
+```
+
+- Names are `entity.metric` and `entity.property`, each segment in camelCase, typed from the
+  ontology. An `_` before a digit stays, so an entity's declared name converts back:
+  `sales_2025.revenue`. This differs from the per-entity call and records, which drop it. Fields
+  and rows are keyed by these names.
+- When an entity reaches a property's entity in more than one way, write a route from it:
+  `acmeSales.returnedProduct.brand`. Its column is still keyed by the property's own name,
+  `acmeProduct.brand`.
+- It posts to the ontology service's `/api/ontology/query_metrics` as the signed-in user, who
+  needs read permission on every entity the request reaches. Previews and local development
+  answer `aggregate_unavailable`.
+- Date bounds are `between` filters, inclusive, or `inPeriod` filters. Each partitioned entity
+  needs one on its own partition property. Currency metrics need their entity filtered to one
+  currency, the same for every entity.
+- A metric field's `filters` lists the filters applied to it, and `execution.warnings` names
+  each filter that did not reach a metric's entity. `additive: false` marks a metric whose
+  rows don't add up to a total.
+- Failures throw `SegmentStreamApiError` with the service's `code`: `invalid_request`,
+  `invalid_aggregate_query`, `forbidden`, `rate_limited` (30 metric queries a minute per user),
+  `aggregate_unavailable`, `aggregate_upstream_unavailable`, `ontology_version_mismatch` or
+  `aggregate_scope_mismatch`. The codes keep their earlier wording. See
+  [errors](../../docs/ontology-metrics.md#errors).
+
+Since 0.13.0, both metric queries take more conditions, buckets and a timezone:
+
+```ts
+const { rows, execution } = await segmentstream.ontology.queryMetrics({
+  metrics: ["acmeSales.wonOrders"],
+  dimensions: ["acmeSales.orderDate"],
+  granularity: "week",
+  granularityOf: "acmeSales.orderDate",
+  filters: [
+    { dimension: "acmeSales.orderDate", operator: "inPeriod", value: "last 4 weeks" },
+    { dimension: "acmeProduct.brand", operator: "notIn", values: ["Unknown", "Test"] },
+  ],
+  timezone: "Europe/Moscow",
+});
+```
+
+- Filter operators are `equals`, `in`, `notEquals`, `notIn`, `isNull`, `isNotNull`, `gt`,
+  `gte`, `lt`, `lte`, `contains`, `startsWith` and `endsWith`; the model-level call adds
+  `between` and `inPeriod`. `notEquals` and `notIn` also match nulls and rows whose
+  relationship found no target. Text operators are case-sensitive and take no wildcards.
+- `inPeriod` takes a period relative to today, typed as `RelativePeriod`: `today`,
+  `yesterday`, `this month`, `last quarter`, `this year to date`, `last 7 days`,
+  `last 4 weeks`. `execution.periods` gives the dates each one resolved to and the timezone
+  that decided today. Only `between` and `inPeriod` bound a partitioned entity.
+- `granularity` is `hour`, `day`, `week`, `month`, `quarter` or `year`; `hour` needs a
+  timestamp dimension.
+- `timezone`, an IANA name or `UTC`, replaces the entities' timezones for timestamp buckets,
+  date bounds on timestamps and the today of `inPeriod`.
+- A balance metric's field carries `balanceOver`, the date dimension its rows snapshot.
+  Group by that dimension or filter it to one day. `balanceOver` and each period's
+  `dimension` come back camelCase per segment, like field names.
+- The per-entity call takes the new operators, granularities and `timezone`, but neither
+  `between` nor `inPeriod`: `dateRange` stays its partition bound.
+- These requests need app SDK 0.13.0 and the workspace's ontology deployed with
+  `@segmentstream/ontology` 0.17.0 or later, whose service accepts them; earlier
+  versions refuse them. See [Upgrading to 0.13](#upgrading-to-013).
+
+Since 0.14.0, the model-level call also takes model metrics, which the ontology declares in
+`defineOntology({ metrics })` over metrics of several entities, by their bare names beside
+`entity.metric` names:
+
+```ts
+const { fields, rows } = await segmentstream.ontology.queryMetrics({
+  metrics: ["planAttainment", "acmeSales.ordered"],
+  dimensions: ["acmeSales.orderDate"],
+  granularity: "month",
+  granularityOf: "acmeSales.orderDate",
+  filters: [{ dimension: "acmeSales.orderDate", operator: "inPeriod", value: "this year to date" }],
+  orderBy: [{ metric: "planAttainment", direction: "desc" }],
+});
+// fields[1]: { name: "planAttainment", label: "Plan attainment", unit: "ratio", additive: false,
+//   filters: [...], inputs: ["acmeSales.ordered", "acmePlans.plannedUnits"] }
+```
+
+- A model metric is requested by the camelCase name the ontology declares, typed from
+  `typeof ontology`. The platform names it in snake_case, `plan_attainment`; its field and row
+  key are the camelCase form, `planAttainment`, as for entity metrics.
+- Its field carries `inputs`, the entity metrics it reads, as `entity.metric` in camelCase per
+  segment, like other names. They are computed whether or not you request them; request one to
+  get its column too.
+- Its `filters` lists the filters that applied to every input. A filter on a property the
+  model metric aligns applies to each entity through its own property; a filter that reaches
+  some of its entities and not others is refused with `invalid_aggregate_query`.
+- A group one of its entities has no rows for, or a zero denominator, gives `null`.
+- The caller needs read permission on every entity it reads.
+- These requests need the workspace's ontology deployed with `@segmentstream/ontology`
+  0.23.0 or later, which declares and serves model metrics; earlier versions refuse them.
+  Requests that name none work as before, and their fields carry no `inputs`. See
+  [request model metrics](../../docs/ontology-metrics.md#request-model-metrics).
+
+## Start a pipeline job
+
+With app SDK 0.15.0 and pipeline SDK 0.1.0a65 or later, opt in a job and deploy it:
+
+```python
+s.job("land_watch", assets=[land_checks], allow_app_runs=True)
+```
+
+In server code, check the user's role or permissions before calling on their behalf. The
+credential is the app's, so ask with `{ fresh: true }` when a revoked role must stop the run at
+once:
+
+```ts
+const user = await segmentstream.requireUser({ fresh: true });
+if (!user.roles.includes("operator")) {
+  throw new Error("An operator role is required.");
+}
+
+const run = await segmentstream.jobs.run("land_watch");
+// From a later authorized request, for example a Route Handler the page polls:
+const current = await segmentstream.jobs.getRun(run.id);
+const recent = await segmentstream.jobs.listRuns("land_watch");
+```
+
+The helpers use the workspace app credential, read on every call, or fall back to the
+legacy member session. Credential access defaults to denied unless the current deployed
+job sets `allow_app_runs=True`. It stays within the workspace and permits submission and
+status/history reads; run logs, activity and cancellation require platform membership.
+Removing the flag revokes app access to that job's runs.
+
+`run()` returns immediately with a run ID and status. It generates a UUID idempotency key
+unless passed `{ idempotencyKey }`; reuse an explicit key when retrying one button action.
+Separate calls with new keys can run concurrently. Partitioned jobs accept
+`{ partitionRange: { startDate, endDate } }`. All helpers accept an optional `signal`.
+Poll `getRun()` until status is `succeeded`, `failed` or `cancelled`, and tolerate future
+status values. Protect both submission and status routes with your app's authorization.
+See [app data access](../../docs/app-data.md#start-a-pipeline-job-from-the-app) for a Route Handler.
+
+## How requests are handled
+
+- Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
+  return to the page after sign-in.
+- API routes, `fetch` calls, non-GET requests and Next.js data requests receive
+  `401 {"error":"unauthenticated"}` instead of a redirect.
+- Static assets, `/api/auth/*`, `/sign-in`, `/api/health` and your `publicPaths` never
+  require a session.
+
+## Environment
+
+App previews are selected by the platform with `SEGMENTSTREAM_DEPLOYMENT_TARGET=preview`,
+`SEGMENTSTREAM_PREVIEW_EXPIRES_AT` (an ISO timestamp), and the existing
+`SEGMENTSTREAM_ONTOLOGY_DEPLOYMENT_ID`. Omitting the target preserves production behavior.
+Compatibility previews receive an isolated Neon Auth URL and cookie secret.
+Declared browser methods use exact deployment-bound clients and revision checks;
+production/sibling credentials and retired revisions are refused. Neither mode
+falls back to the legacy broker. The preview has its own ontology service and
+expiring machine credential.
+
+`segmentstream.deployment` is a serializable `DeploymentObservation`: `target`, optional
+`deploymentId`, preview `expiresAt`, and `capabilities` (`warehouseRead`, `pipelineRuns`,
+`connections`, `agents`, `workflows`). A preview enables `warehouseRead` and `workflows` in this profile;
+its isolated ontology CRUD and file operations remain available under normal user permissions.
+Workflows support manual starts, action/change triggers and inbound webhooks. Scheduled cron
+triggers remain disabled. Trusted workspace workflow code can make external network requests
+and cause real side effects; managed connections, agents and pipeline runs remain unavailable.
+Pass this observation to your UI to present your own preview indicator and unavailable actions.
+The SDK supplies codes and values; the workspace supplies human-language text.
+
+Preview pipeline methods, agent operations and their Route Handlers are refused before external
+requests. Every server helper, proxy and auth handler checks the deadline, including cached
+sessions and clients captured before expiry. `DeploymentAdmissionError` exposes stable `code`
+and `status` values, including `preview_expired` (410), `preview_capability_unavailable` (403)
+and `preview_configuration_invalid` (503). These SDK observations and guards do not authorize
+the machine credential: the platform independently enforces its deployment and capability scope.
+
+| Variable                               | Purpose                                                                                                     |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `NEON_AUTH_BASE_URL`                   | Email provider URL when email is enabled; environment selection applies only without a browser declaration. |
+| `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET` | 32 or more characters; signs the session cache cookie. Required with Neon Auth.                             |
+| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries and opted-in pipeline jobs.                              |
+| `SEGMENTSTREAM_ONTOLOGY_URL`           | Optional: the ontology service when it does not run beside the app.                                         |
+| `SEGMENTSTREAM_URL`                    | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`.                                        |
+
+SegmentStream derives browser policy, revision/client bindings and enabled provider
+configuration on deploy. Explicit methods take precedence over leftover environment
+variables; missing required bindings fail closed.
+
+## Local development
+
+App SDK checks and builds copy the browser-safe channel protocol from
+`packages/ontology-sdk/src/channel-session.ts` into an ignored source module. The
+packed app includes that module and does not require the ontology npm package at
+runtime. Change the canonical ontology source when updating the wire contract.
+
+For SegmentStream-only local development use `app dev` above and supply an isolated
+local ontology database. The following applies only to an independently configured
+email compatibility environment. Use that isolated local Neon Auth URL and a local
+cookie secret in `app/.env.local`; never copy production credentials. Configure its
+trusted origins for `http://localhost:3000`:
+
+```sh
+NEON_AUTH_BASE_URL=https://ep-….neonauth.….aws.neon.tech/ontology/auth
+SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET=<openssl rand -base64 32>
+SEGMENTSTREAM_ONTOLOGY_URL=http://localhost:3100
+```
+
+With `SEGMENTSTREAM_ONTOLOGY_URL`, server-side ontology calls go there and the proxy
+forwards the browser's `/api/ontology/*` requests to it. Point it at a local
+`npm --prefix ontology run dev` backed by the isolated development database.
+
+## Security
+
+Declared SegmentStream browser login keeps an opaque workspace session in an
+HttpOnly cookie. Ontology admission checks current membership/roles and the parent
+provider grant; revision and session revocation meet the sixty-second bound.
+The following JWT/cache details describe email compatibility only.
+
+- Email sessions are Neon Auth's: `HttpOnly`, `Secure`, `SameSite=Lax` cookies on the app's
+  own domain, set through the app's `/api/auth` route. The session cache cookie is
+  signed with `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET`.
+- Signing in proves an email address and grants nothing. The ontology links the
+  person to an invited member, and their roles decide what they may read and do. The
+  ontology service verifies the user's JWT (EdDSA, 15 minutes) and checks activity,
+  roles and permissions on every request. `can()` and `<Can>` read roles cached for up
+  to a minute and decide what the app shows; gate code outside the ontology with
+  `can(permission, { fresh: true })` when a revoked role must stop it at once.
+- The session JWT and the app credential stay on the server, except that the browser
+  components fetch the JWT from the app's own `/api/auth/token` to read
+  `/api/ontology/me`.
+- Warehouse queries run with the workspace's own identity; the app never holds
+  warehouse credentials.
+
+## Legacy compatibility without Neon Auth
+
+This section applies only without a browser declaration or OIDC binding. Declared
+SegmentStream-only authentication never invokes this broker fallback.
+Without `NEON_AUTH_BASE_URL`, the legacy path retains the earlier behavior, so existing apps keep
+working: members of the workspace's organization sign in with their SegmentStream
+account through `/api/segmentstream/[...path]/route.ts`
+(`export const { GET, POST } = segmentstream.handlers();`), the proxy redirects to
+SegmentStream, and `fetch` acts as the member; warehouse queries prefer the workspace app credential. In that mode
+`roles` and `permissions` are empty, `can()` is `false`, `authHandlers()` answers
+`404 neon_auth_not_configured`, and `segmentstream.ontology` sends the member's app
+token, which the ontology service accepts while workspaces move to Neon Auth. Keep the
+protocol route for supported existing consumers; this release does not retire the broker.
+
+## Upgrading from 0.2
+
+Add the auth route, the sign-in page and the stylesheet import; keep the legacy route.
+`AppUser` gained `roles` and `permissions`. Under Neon Auth, people sign in again with
+an email code, and the ontology must have invited them.
+
+## Upgrading to 0.4
+
+`useSignIn().step` may now be `link`: render it, or a form written for 0.3 shows the code
+step after a link was sent. The `<SignIn />` button reads "Continue". Deploy the
+ontology with `@segmentstream/ontology` 0.4 or later to answer the sign-in check;
+until then every address gets a code, as in 0.3. `errorCode` and `noticeCode` let an
+app word messages in its own language without matching the English sentences.
+
+## License
+
+Apache-2.0
+
+## Upgrading to 0.5
+
+Replace segmentstream.semantic with typed metric queries of warehouse-backed entities. See [ontology metrics](../../docs/ontology-metrics.md). Warehouse-backed clients now also expose read-only `find`, `query` and `get`, with opaque record IDs; actions and stored history remain unavailable. See [warehouse record reads](../../docs/ontology-record-reads.md).
+
+## Upgrading to 0.10
+
+- Per-entity metric queries accept relationship paths. Their responses may carry
+  `execution.warnings`; historical responses also carried `execution.sources`.
+- The model-level metric query is new, and its name is reserved: no entity is named after it.
+- The per-entity metric query now runs as the signed-in user through the ontology service, like
+  record reads, and no longer uses `SEGMENTSTREAM_APP_CREDENTIAL`. The user needs read
+  permission on the entities it reaches.
+- Server code without a signed-in user, such as a scheduled Route Handler, can no longer
+  query metrics with the workspace credential. Use `segmentstream.warehouse` there, or call the
+  ontology service with an API key.
+- Deploy the workspace's ontology with `@segmentstream/ontology` 0.13.0 or later. It
+  serves the per-entity and model-level metric query routes; earlier versions don't.
+
+## Upgrading to 0.13
+
+- The model-level filter type, now `MetricQueryFilter`, is a union: a filter with `value` or
+  `values`, or an `inPeriod` filter whose `value` is a `RelativePeriod`. An interface cannot
+  extend a union, so `interface X extends MetricQueryFilter` does not compile; write
+  `type X = MetricQueryFilter & { … }` instead. Reading `filter.values` still compiles: it is
+  always `undefined` on an `inPeriod` filter.
+- The new operators, `inPeriod`, granularities and `timezone` need the workspace's ontology
+  deployed with `@segmentstream/ontology` 0.17.0 or later. Requests that use none of
+  them work as before.
+
+## Request timing
+
+Wrap app Route Handlers to add `Server-Timing: app;dur=…`, `x-request-id` and safe
+structured `app.request` runtime logs:
+
+```ts
+import { withRequestTiming } from "@segmentstream/app";
+
+export const GET = withRequestTiming(async (request: Request) => {
+  return Response.json({ ok: true });
+});
+```
+
+The wrapper passes handler arguments through and preserves response headers and
+streaming bodies. It logs duration, method, HTTP status and a generated request ID,
+excluding URLs, cookies, bodies and error details. Errors propagate unchanged.
+Next.js redirects and `notFound()` log their HTTP status and propagate unchanged;
+other Next.js control-flow exceptions log `status: null` because Next owns their eventual response.
+Those exceptions cannot receive timing headers here;
+return an explicit response when the wrapper needs to decorate its headers.
+Read these logs with `segmentstream logs --service app` (deployment permission required).
+Duration ends when the handler returns response headers; it excludes later stream
+work and browser rendering. It is opt-in for Route Handlers, not a page renderer
+or a web vitals collector. A Next.js proxy cannot time the downstream page render.
+
+Ontology SDK 0.31.2 adds request timing for ontology calls automatically. Timings
+are available in hosted logs; retained diagnostics are tracked in issue #520.
+
+## Upgrading to 0.14
+
+- The model-level metric query accepts model metrics by their bare names, typed from an ontology
+  that declares them. Ontologies without them type the same names as before.
+- The field type, now `MetricQueryField`, gains `inputs`, which only fields of model metrics
+  carry.
+
+### Replication lifecycle and freshness
+
+Cloud publishes a generation's views after its baseline, backfill and replay preparation finish
+and Pub/Sub accepts its fixed initialization prefix. Later writes do not postpone that boundary
+or make published views unavailable. Pub/Sub acceptance does not prove BigQuery visibility;
+the native BigQuery subscription handles delivery and retries. Replication status reports
+`captured` and `accepted`, and metric query responses carry no destination freshness watermark.
+Initial copies and replay remain unavailable until acceptance and view publication finish.