app.api-application-monolith

Managed CompanyOS API Application Monolith

OPA production completion

GET/POST /api/v2/opa/automation-settings exposes current-session policy ancestry and revision-checked updates. Apply additive migration 0073 before deployment. The CompanyOS editor explicitly reports background execution as inactive while delegation and effect-time worker binding remain unqualified. Saved planner placements can be reviewed and added through the existing focus-create lifecycle; the server rechecks saved identity, Work revision, and fresh availability.

Personal Planner generation now loads canonical Work and fresh calendar state, persists a proposal atomically with its command, and returns proposed placements and unscheduled reasons. Generation does not apply calendar changes. Active organization/workspace authority is checked again before committing.

Meeting generation requires an explicit Vercel AI Gateway binding, pinned model, EU provider inference and separately approved global Gateway transit (see Meeting AI through Vercel Gateway). Missing configuration leaves generation unavailable; existing artifacts remain readable. The approval reference is an operator configuration binding, not a substitute for processing review or model evaluation. An explicit saved meeting policy must also enable AI suggestions or editing; missing or disabled policy prevents model invocation. See docs/evidence/opa/production-completion-2026-09-04.md for open release gates.

Durable CompanyOS onboarding preferences

PATCH /api/companyos/onboarding-preferences implements the versioned companyos.onboardingPreferences.complete@1.0.0 command. It accepts only a bounded experience-preference patch, expected tenant-scoped revision, and idempotency key. User and tenant authority always come from the verified session. Migration 0071 stores one document per user and tenant; exact replay, conflicting replay, concurrent revision fencing, cross-user isolation, and cross-tenant isolation are covered by the PGlite repository proof. The existing authenticated shell-preference query returns the validated persisted document so a subsequent page load hydrates the same experience.

OPA meeting provider intake

createCompanyOpaMeetingIntake composes the provider-neutral intake binding with the CompanyOS OPA operation registry, so automatic recorder matches pass through the same session-derived authority and governed opa.recording.source_bind handler as interactive requests. The host factory accepts the real Google or Outlook calendar adapter and Granola or Fireflies recorder adapter without embedding credentials.

Migration 0063 installs the owner-scoped occurrence and immutable review tables; 0065 adds recurring definitions and token-fenced execution leases. When callers do not inject narrower ports, the production composition uses this SQL store for current recorder-binding revisions and mandatory review requests. The deployable worker remains fail-closed until its allowlisted composition supplies selected calendar OAuth/Graph credentials, recorder credentials, and protected configuration resolution. No provider or fixture is selected implicitly.

SupportOS to OPA destination authority

POST /internal/opa/support/destinations/resolve is the only server-to-server bridge that turns a SupportOS opaque profile or booking destination reference into a public CompanyOS URL. It verifies a short-lived AuthOS grant for the companyos-opa-support audience and exact tenant, workspace, case, handoff, and destination binding. The database query independently scopes the stable OPA profile_ref or link_ref, requires a published current profile/link revision, and never returns provider or calendar data. Configure COMPANYOS_OPA_SUPPORT_AUTHOS_GRANT_VERIFY_URL and COMPANYOS_OPA_SUPPORT_AUTHOS_WORKLOAD_TOKEN; APP_WEB_BASE_URL remains the canonical public origin.

CompanyOS Briefings 2.0

Calendar intelligence is recipient-owned. The scheduler reads only selected Google calendars attached to the authenticated user's non-shareable personal context; workspace booking resources are never briefing sources. Missing personal OAuth, selections, or authority fails closed as setup_required with no provider read or delivery. The ledger stores digests, state, composition metadata, and authorized evidence refs only—never notes, graph content, or email bodies. Outbound email has exactly one recipient: the user's verified CompanyOS delivery address. Authenticated preview requests select either morning-recap or meeting-preparation and cannot select a recipient; the server runs only the current user's bounded personal calendar and freshly authorized graph pipeline without persisting event content or rendered bodies.

Migration 0068 deterministically replaces any historical raw or missing briefing provider message identifier with a one-way provider-message:sha256:* reference before installing its provider-evidence constraint. This keeps forward replay compatible with legacy successful deliveries without retaining provider identifiers in the governed ledger.

Scheduled rollout is server-derived and cannot be selected by the browser. It becomes live only after personal calendar setup is ready and at least one delivery cadence is enabled; disabling both cadences or losing setup readiness atomically returns it to off.

Migration 0043 binds every source to the same user's active personal OAuth connection with a composite foreign key and generated owner reference. Production promotion uses the non-automatic, approval-gated db/cutovers/companyos-briefings-v2.sql transaction after the canary, backup, and zero-legacy-read replay; automatic migration must not remove V1 storage before those gates pass. Run bun run companyos:briefings:postgres:test against a disposable PostgreSQL URL for the owner, RLS, occurrence, and cutover proof.

Company Intelligence governed learning persistence

S9 persists the governed-learning lifecycle through the existing migration 0022 canonical records, refs, receipts, and events plus the 0023 transactional outbox. The transaction-scoped repository takes a lifecycle advisory lock, verifies the expected sequence/head, validates a packet-closed history, and delegates canonical append/idempotency. There is no dedicated learning table, index, provider call, export, or live canary. Migration 0027 belongs to S10 API replay and budget state; governed-learning history remains on the canonical 0022/0023 authority. S10 exposes the four authenticated governed-learning routes through this repository and fails closed when LSSM_STUDIO_DATABASE_URL is absent. FORCE RLS remains tenant-scoped; run bun run test:company-intelligence:governed-learning-persistence and the local PostgreSQL proof before changing this boundary.

Company Intelligence Brain persistence

Migration 0026 adds one append-only FORCE-RLS object-version table for the CompanyOS-owned Brain entry, review, edition, gap, remediation, and compiled artifact families. The repository reuses canonical Company Intelligence receipts/events, rejects static/demo fixture sources in production, binds every query to tenant and workspace scope, keeps valid and recorded time distinct, and applies capability/field redaction before projection. Run bun run test:company-intelligence:brain; both managed PostgreSQL 15 proof scripts execute the same corpus under NOSUPERUSER NOBYPASSRLS.

Company Intelligence durable graph and identity

Migration 0025 adds FORCE-RLS query projections and append-only identity candidates, reviewed decisions, aliases and merge/split lineage over the canonical 0022 record/event authority. Canonical content fingerprints bind replay to the complete request. The repository rejects conflicting replay, cross-tenant decisions and label-only auto-linking, and exposes deadline- and edge-bounded traversal that authorizes every recursive branch. Run bun run test:company-intelligence:graph-repository for the exact package corpus. bun run companyos:db:prove-existing-postgres (or the disposable PostgreSQL proof) executes its S6 integration test against PostgreSQL 15 under a constrained NOSUPERUSER NOBYPASSRLS runtime role.

Company Intelligence tenant persistence

Migrations 0022 and 0023 provide the additive app-owned PostgreSQL/Drizzle authority for the canonical G002 Company Intelligence contracts: bitemporal records and normalized references, append-only receipts/events, controlled tombstone purging, and durable job/outbox/DLQ/backfill state. Every table uses FORCE RLS; runtime qualification authenticates as a NOSUPERUSER NOBYPASSRLS role and proves cross-tenant read/write denial.

Run bun run companyos:db:prove-disposable-postgres for the isolated Docker or native-cluster proof. When a PostgreSQL 15 server is already running locally, bun run companyos:db:prove-existing-postgres creates two unique loopback test databases, runs the same S2 migration/recovery/repository/RLS checks, and drops both databases. See docs/company-intelligence-persistence-runbook.md for resumable backfill, corruption checks, forward repair, and purge controls. Use docs/company-intelligence-operations-runbook.md for readiness, safe metrics and budgets, correlation troubleshooting, kill switch recovery, and the executable S12 qualification commands.

Company Intelligence continuous ingestion

S4 reuses the same 0022/0023 authority without adding tables. Upload, webhook, polling, and connector deliveries enter one idempotent durable job path for initial/incremental sync, backfill, resync, cancel, deletion, ACL, and identity changes. Claims use bounded leases, heartbeats, optimistic checkpoints, deterministic retry/backoff, quotas, cancellation, DLQ evidence, and resumable cursors. Duplicate delivery keys create one job and replayed record commits create zero additional effects.

The provider-neutral registry binds direct ingress, Drive, Gmail, Slack, Teams, GitHub, Linear, Jira, Notion, and meeting transcripts to their existing integration/package owners. CI uses caller-supplied canonical deterministic contract fakes; it never substitutes fixtures when credentials are missing. Required credentials resolve outside job payloads through opaque provider session handles. Missing credentials produce not_run plus missing_credentials, a durable redacted receipt/DLQ entry, and zero provider calls.

Source deletion and ACL revocation cancel queued work and append immutable superseding tombstones through the current canonical record closure (source, source version, asset, part, fragment, evidence, and current dependent records). No S5-S9 graph, Brain, retrieval, or public API behavior is implied.

Run bun run test:company-intelligence:ingestion for deterministic connector contracts and bun run companyos:db:prove-disposable-postgres for the complete lease/checkpoint/propagation/RLS qualification.

Company Intelligence structured extraction

S5 adds strict model-output candidate schemas and a pure trusted runtime that alone resolves authorized pre-existing evidence IDs and exact locators into canonical records. Invalid output, invented or cross-tenant evidence, locator drift, instruction-like content, policy override attempts, and model-declared approval produce stable typed rejections with zero canonical effects.

Confidence below 0.75 and high/critical risk require a separately supplied trusted review decision. Redacted deterministic receipts record model, prompt, schema/runtime versions, cost, evidence, dispositions, and correction lineage without raw source/provider content. Migration 0024 adds only a nullable JSONB details column to the existing generic receipt table; the existing canonical record repository remains authoritative. The disposable PostgreSQL proof covers first commit, exact replay, immutable correction history, and tenant denial.

The v2 profile backend is mounted at /api/v2/opa/profile/* for session/RBAC-scoped administration and /api/v2/public/profiles/:handle for the redacted latest-published projection. Mutations require trusted origin and a session-bound CSRF token; admin responses are always no-store. The deployed composition lazily binds the transactional SQL profile repository to LSSM_STUDIO_DATABASE_URL and fails closed when it is absent. The in-memory profile store is available only through explicit test/demo injection.

The public response and admin redaction boundaries omit private topology and provider references. Draft restoration accepts newly created hybrid events but rejects newly invented owned-live events until authoritative provisioning exists. Cache and publish/revoke invalidation remain server-owned. OPA v1 booking contracts are unsupported; promotion remains blocked until G004b binds and verifies the exact v2 runtime and API handlers.

G004b Phase B is implemented locally. Canonical migration 0037 remains absent from default migration discovery and is not production-promotable without a fresh, exact-target opaque activation minted from an independently trusted Ed25519 reset authorization. That authorization digest-binds the 0036 ledger head and exact 0037 digest to ordered external snapshot, schema, restore, runtime build/test, ContractSpec Connect decision/replay, actor, and observed database proof. Application revalidates the target and time window immediately before any migration work and spends the activation once. No external evidence bundle is checked in, so this package does not claim a canary or production activation.

Managed Google Meet booking persistence

Migration 0028 adds protected primary and staged-replacement conference state to the canonical tenant/RLS-scoped booking intent. Published owned-live event types carry their provider-neutral conference mode into both public booking entrypoints. The provider-effect worker confirms a Meet booking only after a verified https://meet.google.com link is encrypted in the same fenced transition; pending, failed, and ambiguous creation stays recoverable by exact known ID. Cancellation clears the link, while rescheduling promotes only the ready encrypted replacement after definitive old-event cancellation.

The canonical opa.profile.public_list@2.0.0 REST identity is GET /api/v2/public/profiles. The Elysia host exposes that route plus GET /api/v2/public/profiles/readiness; handler contract tests freeze those v2 gateway mappings.

Real API monolith for tenant-scoped Managed CompanyOS commands and queries.

Company Intelligence authenticated API

The Elysia host mounts the contract-derived v1 surface at /api/companyos/company-intelligence/v1/*. Every operation requires a tenant-bound user session or service principal, returns private no-store responses with API and correlation headers, and enforces bounded bodies, pagination, timeout, budget, and idempotency semantics. Migration 0027 persists tenant-scoped replay results and minute request budgets with integrity constraints and FORCE RLS, so new handler instances preserve both controls. Production has no fixture fallback.

GET /api/companyos/company-intelligence/v1/surface?surface=<id> resolves the authenticated overview, sources, Brain, graph, assistant, learning, or operations descriptor before browser data reads. The handler accepts exactly one logical surface query parameter and rejects tenant or role input. It returns canonical route, truthful route state, safe-read posture, action availability, and dependency blocks derived from the authenticated actor and server composition; missing PostgreSQL composition is reported as degraded rather than replaced with demo data.

Connections, jobs, uploads, evidence, reviews, graph traversal, Brain reads, replay, health, and the four governed-learning mutations bind canonical PostgreSQL repositories or tables. Structured extraction and grounded answers delegate authorization-aware retrieval to explicitly bound production services without preloading tenant-wide records. Evidence and replay reads, reviewed decisions, graph traversal, and Brain projections use built-in PostgreSQL ACL/workspace authority adapters. Health is degraded until the external extraction and grounding services are bound; those two operations alone fail closed with 503 dependency_unavailable when absent. Run bun run test:company-intelligence:api for parity, auth, isolation, limits, durable idempotency/budgets, degraded behavior, cancellation, and log safety. The disposable PostgreSQL 15 proof covers restart replay, tenant-key isolation, budget continuity, and constrained NOSUPERUSER NOBYPASSRLS denial.

Company Intelligence operational safety

S12 operational controls reuse the canonical append-only PostgreSQL receipt and event authority for dependency health, kill-switch changes, and pre-dispatch audit decisions. Missing switch state fails closed. Ingestion and connector dispatch recheck the durable ingestion and connector_dispatch switches before every provider call; blocked jobs return to retry without consuming an attempt. Run bun run company-intelligence:failure-injection from the repository root to prove database, vector, model, queue, and connector degradation, all six audited switches, recovery within twice the outage duration, safe correlated telemetry, and disposable PostgreSQL cleanup.

ADR-008 reference qualification is fail-closed and never shortens the required 60-minute load plus 8-hour soak. Run bun run company-intelligence:reference-qualification to validate the exact 10-tenant corpus manifest, pull and verify PostgreSQL 16, Qdrant 1.15.0, the locked Qdrant 1.18.0 adapter, and Bun 1.4.0 runner, then launch both phases as one durable background process. Before load begins, a pinned Bun runner applies the tracked database migrations and fails closed unless managed_companyos_ci_records and managed_companyos_ci_jobs both resolve in PostgreSQL and the digest-backed migration ledger matches versions 0022 and 0023. The command records leader-owned environment, schema-preflight, container, image-digest, PID, and log handoff evidence. Docker allocations below 8 CPUs or 16 GiB fail with a concrete blocked packet and launch no qualification; such a packet is not S12-A3 completion.

Google Calendar booking edge

The Elysia host owns protected OAuth start/callback/disconnect routes under /api/companyos/integrations/google-calendar/* and the authenticated /api/cron/google-calendar-maintenance polling/reconciliation route. Runtime configuration is server-only and uses MANAGED_COMPANYOS_GOOGLE_CALENDAR_* CLIENT_ID, CLIENT_SECRET, and exact REDIRECT_URI; tenant/account/calendar topology is enumerated from durable opa_calendar_connections. OAuth tokens and their granted scopes/expiry bind to the ciphertext-only OPA vault. Callback and disconnect persist tenant/account-scoped connection state; disconnect disables the local connection before remote token revocation. Exact-scope drift records reauthorization_required before best-effort revocation of rejected grants. The maintenance cron isolates each tenant, refreshes only near expiry, proves paginated CalendarList owner/busy topology, polls durable free/busy snapshots, and durably schedules daily known-ID reconciliation without broad event listing.

Every request-time free/busy read, freshness refresh, booking event creation, Google Meet creation, cancellation, reschedule, and reconciliation resolves an explicit (tenant, workspace, scheduling resource, write calendar) binding. The booking saga keeps the tenant-scoped write-calendar reference as its stable identity; immediately before every Google call, the trusted adapter resolves it to the current provider calendar identifier. The provider identifier is never accepted from or returned to the anonymous booking browser. One connected Google account may serve multiple workspaces only when each workspace has its own persisted scheduling preference joined to that resource and connection. Missing, foreign, contradictory, or ambiguous bindings fail before snapshot, OAuth vault, protected booking, or Google provider access. Personal mode uses the same contract with its personal workspace authority. Connection-wide maintenance can probe and refresh a connected account, but it does not grant request authority to any workspace. Migration 0033_google_workspace_availability_snapshots.sql partitions opaque snapshots by tenant, workspace, and scheduling resource while retaining legacy maintenance rows in an explicit empty-workspace partition. Malformed timestamps or busy intervals fail closed.

The production integration keeps booking availability free-busy based and uses the separately consented read-only event scope only for bounded daily intelligence. events.list is capped at 40 events per user/run. Raw event titles, descriptions, attendees, locations, bodies, and email content are never persisted; only delivery state and content digests are durable.

The Google and Microsoft readers keep attendee addresses beside the display labels (CalendarIntelligenceMeeting.attendees, contract 2.7.0) under COMPANYOS_CALENDAR_ATTENDEE_ADDRESS_POLICY. Shared pre-meeting briefs use them to propose recipients, so named attendees are no longer missed; the owner still reviews every recipient. They are stripped from the briefing model input and redacted from log lines. The only stored copy is a shared-brief draft's recipient list, which the owner reviews.

Live profiles, booking surfaces, and daily intelligence

Migration 0042 adds evidence-only calendar-intelligence preferences and delivery attempts, canonical owner scopes for the existing OPA profile/calendar tables, and the public published-profile lookup boundary. The core-workspaces (and all) bootstrap profile reconciles the live LSSM and CompanyOS organizations. Hirly and NDconsulting were decommissioned in production on 2026-10-20 (Éléments de preuve^†); no live profile recreates them. Collaborators join through the invitation flow and are never seeded as admins.

After every target workspace has a connected Google Calendar topology, run bun run companyos:booking-surfaces:activate. It publishes shared links for LSSM and CompanyOS plus Théo's personal link (/u/theo). The former Hirly surfaces (/u/hirly, /u/hirly-talent-team-booking) are unpublished. Each surface uses Europe/Paris weekday availability, Google Meet, bounded advance/notice policy, and the workspace-owned scheduling resource. Activation advances the canonical link to the published profile revision and revokes active links from superseded revisions, so a replay cannot expose a dead booking URL. It also reconciles the exact first-party https://www.companyos.run embed origin on all three canonical links so the hosted loader and React canary work immediately. Every additional embedding origin remains an explicit owner-managed allowlist entry.

Canonical owner/admin authority must include the complete owner capability set (COMPANYOS_OWNER_CAPABILITIES, which contains the Meeting Intelligence set) at the organization, workspace-default, and user-workspace layers. Bootstrap provisions that set for new personal and organization contexts. Existing LSSM and CompanyOS grants converge additively with bun run companyos:opa:reconcile-meeting-authority: run it first with COMPANYOS_OPA_MEETING_AUTHORITY_RECONCILE=dry-run (writes nothing, prints the missing capabilities per layer), then with =1 to apply. The owner set is a floor: separately reviewed extras such as builder.* are preserved, and the companyos:db:verify:live bootstrap prerequisite checks containment rather than exact equality. Team grants only receive the Meeting Intelligence set. The owner set includes opa.plan_run.manage, which background planning reproves on both the company workspace and the owner's personal context, so the command also reconciles the canonical owner's personal context. Members get the same self-scoped capability through the frontline_staff template (also the joined-member default; OWNER-DECISIONS-2026-10-19); existing member grants receive it on re-grant or through the joined-template authority repair. Planning counts sessions already added from earlier plans (active planner-sourced focus blocks) as scheduled time, so a re-plan never proposes them again or reports them as moved. The command targets only the canonical owner on the live organizations and increments each changed authority revision so existing sessions fail closed until refreshed. Prefer it over re-running companyos:bootstrap-admin on a live target: bootstrap rewrites grants to the exact set (dropping reviewed extras) and re-enables calendar-intelligence preferences.

Owners can revise an active link's embed allowlist through POST /api/v2/opa/links/:linkRef/embed-origins. The command requires the server-derived opaque scopeRef, same-origin CSRF authority, and the current link revision. It replaces the complete list with unique exact HTTPS origins; passing an empty list returns the link to hosted-only mode without changing its public token.

Protected profile execution uses the exported v3 profile operation version and requires a server-authorized opaque scopeRef. Booking approval is available only through the canonical scoped POST /api/v2/opa/bookings/:bookingRef/approval operation. The former /api/companyos/booking-approvals/:bookingRef/decide host alias is removed because it could not satisfy the v3 owner-scope authority contract.

Production credential recovery requires the exact rotation confirmation and an unused permission-restricted path below /tmp via OPA_ADMIN_PASSWORD_DELIVERY_FILE. The rotation command writes the generated password only to that mode-0600 file and never prints it or stores it in the repository.

The /api/cron/calendar-intelligence route runs every five minutes. It sends a Europe/Paris morning recap once per local day and a preparation email in the five-minute window one hour before each meeting. Model composition is temporarily paused at the host: existing Mistral environment values cannot enable it. The localized deterministic-v2 fallback keeps delivery available without persisting source calendar content. Preview delivery failures return the stable briefing_delivery_unavailable 503 projection; provider response bodies and credentials are never returned to the browser.

The protected admin topology endpoints list every paginated provider CalendarList option, then re-enumerate before atomically materializing the selected owned-write/readable-busy topology and Europe/Paris working hours, buffers, notice, horizon, and approval mode. Tenant identity comes only from the authenticated session; identifiers absent from the current provider response are rejected.

Booking lifecycle recovery uses the exact active original or replacement slot and the persisted saga-owned provider identity. App-owned provider-effect and notification outbox rows are atomically leased with tenant/owner fencing before relay. Notifications use the durable SQS queue when MANAGED_COMPANYOS_BOOKING_QUEUE_URL and the protected delivery service are configured. Serverless deployments without that pair drain the same Postgres outbox directly: recipient material is decrypted only after a token-fenced delivery claim, Resend receives the durable dedupe key as its native idempotency key, and the email management grant stays in the URL fragment until the hosted page exchanges it for HttpOnly cookies. Provider calls are mocked in repository tests; production qualification still requires a reversible live delivery canary.

Smart-meeting preparation

The authenticated GET|POST /api/companyos/opa-os/manual-loop surface composes the existing authorized OPA manual loop for Managed CompanyOS. Session authority owns tenant, workspace, organization, actor, and role scope. The request body contains meeting intent only and strict parsing rejects browser-supplied authority or provider identifiers.

Preparation authorizes before Google work, selects calendar preferences by the session-derived tenant and active workspace, refreshes free/busy through the production calendar bridge, and labels availability as fresh, cached, or unavailable. Readiness distinguishes normal setup states from an explicit runtime outage. It then atomically persists the plan, agenda, booking proposal, immutable command audit, and opa.plan.proposed outbox signal. Exact idempotent replay returns the original redacted receipt; conflicting reuse returns 409. The response remains pending_approval with external effects blocked. No calendar event or Google Meet link is created by this endpoint. Migration 0031_smart_meeting_workspace_calendar.sql preserves legacy tenant-only preferences but requires an authorized workspace binding before they can participate in smart-meeting readiness.

The separate authenticated /api/companyos/smart-meetings lifecycle exposes tenant/workspace-scoped list and status reads plus receipt-scoped approval, cancel, and reschedule mutations. Enterprise admins and founder approvers may mutate the lifecycle; operations managers may prepare and monitor but do not receive external-action approval authority. Approval re-enumerates the active workspace topology, refreshes the selected slot, and links the proposal exactly once to the canonical booking saga. The existing fenced provider-effect worker then owns Google Calendar and optional Google Meet creation; browser and route handlers never call Google directly. Cancellation and rescheduling reuse the same durable leases, deterministic provider identity, reconciliation, and outbox path.

Appliquer 0032_smart_meeting_booking_lifecycle.sql before enabling this lifecycle. It adds nullable forward linkage from the smart-meeting proposal to the canonical booking intent, preserving all existing proposals and enforcing tenant-scoped uniqueness for new links.

Operator qualification is documented in docs/runbooks/opa-smart-meeting.md^†.

Resend purpose ownership and signed status ingress

Auth mail uses AUTH_EMAIL_FROM as CompanyOS Security <security@notifications.companyos.run>; booking mail uses RESEND_BOOKING_FROM as CompanyOS <bookings@notifications.companyos.run>. Both share an explicit, validated RESEND_REPLY_TO, and all three addresses are parsed once before a provider call. Auth callbacks may send directly through the auth-owned provider. Booking code attaches its owned sender only at the protected delivery service and durable outbox claim/dedupe/retry/reconciliation path; it must not call the auth sender.

POST /webhooks/resend/events reads the raw request body and verifies svix-id, svix-timestamp, and svix-signature with RESEND_WEBHOOK_SECRET before parsing. Duplicate svix-id deliveries return a replayed status and do not re-apply the status projection. Production replay and status authority lives in the caller-owned PostgreSQL tables created by migration 0014; a unique event_id plus a transactional monotonic upsert keeps restart and concurrent-instance delivery safe. Stored rows and API results bind only deterministic provider-message:sha256:* references, status, and timestamps—never raw provider message ids, signed payloads, or webhook secrets. Distinct, older events remain recorded but cannot regress the current message status. In-memory storage is test-injected only. This ingress is observational: the booking outbox and protected delivery receipt remain the durable delivery authority. Repository verification never registers a webhook or calls the live Resend API.

Calendar-intelligence email selected through CommunicationOS is admitted to the canonical journal and domain-command outbox before dispatch. The ledger records queued separately from provider acceptance and delivery. The shared worker resolves only the opaque env://COMMUNICATION_OS_CONNECTION_COMPANYOS_CALENDAR_RESEND credential reference, forwards one stable provider idempotency key, and exposes reconciliation_pending if provider acceptance cannot be durably completed. Migration 0069_calendar_intelligence_queued_delivery.sql is required before enabling COMPANYOS_CALENDAR_OMNICHANNEL_ENABLED=1.

api-monolith-elysia-convergence: this app is now verified as a single Elysia host (src/app.ts + api/index.js @vercel/node entry). Former Next.js App Router handlers have been removed from src/app/api; route tests exercise app.handle(Request) directly. The vercel.json deploy flip and external webhook re-registration remain human-gated, but source ownership, tests, and local builds are Elysia-owned. Build the host with bun run build:elysia.

Most proof handlers remain deterministic until their production adapters are explicitly approved. The Managed CompanyOS v2 design-partner routes are an exception: production uses the app-owned Postgres repository and fails closed when its database, migration, tenant kill switch, or evidence relay health is unavailable. Provider strategy remains app-layer and secret-reference-only; bundle/libs/modules remain provider-neutral.

This implementation supports persisted multi-organization authority for the stable canonical slugs. Only lssm and companyos are live; ndconsulting and hirly were decommissioned on 2026-10-20 (Éléments de preuve^†). A verified Better Auth activeOrganizationId is an identity-plane key; an enabled one-to-one binding selects the physical tenant used by FORCE RLS. Production activation still requires the rollout, evidence, and ownership gates in docs/runbooks/managed-companyos.md^†. The former private-pilot configuration remains migration history and rollback input only; it is not forward authorization.

GET /api/companyos/workspaces is a private authority projection. Every success, deny, and degraded response sets Cache-Control: private, no-store; trusted-origin credentialed CORS never makes the response share-cacheable. The route lazily creates one app-owned Postgres authority repository/pool, reuses it for the Elysia host lifecycle, and closes it on host shutdown. It never creates or tears down a pool per request.

Personal, company, team, and workspace authority

Migration 0055_companyos_shell_preferences.sql adds one user-scoped, optimistically versioned shell-preference row and a nullable session preview persona. GET/PATCH /api/companyos/shell-preferences synchronizes context placement across devices. GET/POST /api/companyos/persona-preview authorizes Enterprise Admin by default, stores presentation preview only in the current session, and returns a safe current route or persona home. Context changes and session expiry clear preview; the real session role remains authoritative. Migration 0160 adds a tenant-keyed opa_home_modes map to the same row: GET/POST /api/companyos/opa-os/home-mode (companyos.opaHomeMode.*, workspace.read) reads or sets the OPA OS landing view for the session's own organization (at most 50 organizations remembered); the web app keeps its per-tenant cookie only as a cache for when the API is unavailable.

The additive context family lets an authenticated user operate without a company and switch among one or many companies, teams, and workspaces:

• POST /api/companyos/personal-context/ensure;
• POST /api/companyos/personal-context/disable;
• GET /api/companyos/contexts;
• POST /api/companyos/contexts/set-active.

Migration 0029_personal_context_authority.sql adds the system-owned, non-shareable personal-context manifest, session authority version, one-use nonce digests, and idempotency receipts. Database triggers reject a second member, invitation, or team in a personal organization. Personal ensure creates the existing tenant/binding/grant/workspace topology idempotently; disable revokes binding, grant, public intake, OAuth tokens, and matching active session scope without deleting evidence.

Migration 0030_team_context_authority.sql adds canonical direct-user workspace, team, and team-workspace grants plus workspace authority versions. Existing enabled organization/workspace authority is materialized as explicit direct grants during migration; new workspaces require an explicit grant. The set-active transaction locks the session, consumes the signed five-minute token once, revalidates organization, team, grant, workspace, and projection versions, then updates active organization/team/workspace and emits exactly one context.activeChanged event. Request middleware freshly resolves the selected tuple and intersects organization, team, and workspace capabilities; revoked or stale nested authority fails closed before a protected handler runs.

Only explicitly granted workspaces are listed or accepted at commit time. Opaque contextRef, teamRef, and workspaceRef values cross the public boundary. They are locators, not credentials. Physical tenant identifiers remain server-derived and are never accepted by these routes. Repository-local PGlite proves ensure replay, anti-share enforcement, one-use CAS, stale-token denial, team grant selection, and revocation denial. A real PostgreSQL migration/RLS qualification and live deployment remain separate rollout gates.

Vercel-only Managed CompanyOS production topology

Managed CompanyOS production is cost-capped to the Vercel-hosted web and API monoliths. The API monolith absorbs required background duties through request-time HTTP snapshots and Vercel Cron handlers; it must not require the standalone Bun worker or any browser-held realtime connection for production readiness.

The legacy builds entry in vercel.json makes Vercel ignore the dashboard Build Command. The repository root postinstall therefore dispatches on the Vercel project id and runs this package's build:elysia script during install, before @vercel/node traces api/index.js. That build must bundle src/app.ts to both dist/index.js and api/dist/index.js. The Vercel adapter deliberately loads the generated module through an opaque runtime path and vercel.json explicitly includes only api/dist/index.js; this prevents Node File Trace from re-analyzing the 70+ MB pre-bundled file or packaging the second local-runtime copy.

Implemented route families include retained design-partner-named compatibility adapters. Those adapters preserve NDconsulting history and remain scoped to tenant_ndconsulting_special_ops / workspace_ndconsulting_special_ops; their names do not make pilot identifiers an authorization source.

/api/cron/companyos-snapshot is service-principal gated with the same control-plane.core authorization path as other Vercel crons. User-facing reads remain tenant-session scoped and cross-tenant requests fail closed.

Public profile reads, including 404 responses, use Cache-Control: no-store until a web cache invalidation provider is configured. Publish/revoke signals are durably leased, retried, and emitted by the authenticated profile cache cron.

Runtime surface

• src/app.ts — authoritative Elysia host composition for /api/auth/*, /api/companyos/*, /api/companyos/builder/*, webhooks, crons, schemas, control-plane, billing, and waitlist routes.
• api/index.js — Vercel Node adapter from (req, res) to Web Request to app.handle(request).
• src/handlers/auth-handler.ts — better-auth catch-all with readiness gates, observability, and credentialed CORS.
• src/handlers/companyos/companyos-status-handler.ts — tenant-scoped Managed CompanyOS read routes (health, database, evidence, providers, integrations, replay, workflow, workspace, surface, health/degraded) plus Vercel-only snapshot routes (vercel/snapshot, vercel/replay-evidence, vercel/supervision) and the manual integration sync trigger.
• src/handlers/companyos/companyos-command-handler.ts — verified-session command routes (integrations/setup, workflow/approve).
• src/handlers/companyos-auth-*.ts — invitation, lockout, passkey, sign-out, test-login, and sibling-session revoke routes.
• src/handlers/companyos/*special-ops*.ts — Special Ops and AI Ops Sprint scoped route families.
• src/handlers/companyos/design-partner-readiness-handler.ts — design-partner Special Ops v2 routes for persisted readiness, expert attestation, and founder approval; production derives authority from the verified session and commits through one tenant-scoped Postgres transaction.
• src/handlers/builder/builder-public-handler.ts — public Builder REST surface at /api/companyos/builder/*, distinct from agent/workflow.
• src/handlers/webhooks/* — signed provider ingress (GitHub, Slack, Telegram, WhatsApp Meta/Twilio, Resend, OPA recorders and notetaker bots). Every edge logs through src/observability/webhook-log.ts, a binding over the hashing structured logger: records carry the webhook, the route template (never a route token), a correlation id (a well-formed x-correlation-id, x-request-id or x-vercel-id, else a generated whk_ id) and the W3C traceparent/trace_id from a valid traceparent header. Fields are allowlisted: the tenant is hashed, an id that is not a plain token is digested, and an error keeps only its name, code and a message digest, so raw payloads, headers, secrets and provider error text are never logged.
• src/index.ts — pure command/query functions shared by Elysia handlers and unit tests.

Design-partner readiness API routes

The design-partner readiness routes are the API monolith's sole authenticated runtime authority for the bounded private-pilot slice. When activated, production reads packet versions from Postgres; mutations atomically commit the human decision, durable receipt, audit event, evidence outbox intent, and replay event. The response cannot claim tenant activation or broader production readiness and returns HTTP 503 when database, migration, relay, DLQ, or scheduled-snapshot health is degraded. Migration 0011_design_partner_runtime_authority.sql adds the server-owned tenant enabled kill switch and excludes disabled tenants from scheduled relay enumeration.

The fictive NDconsulting projection remains available only on explicit test/demo surfaces (MANAGED_COMPANYOS_DESIGN_PARTNER_RUNTIME=fixture outside production, or the jointly enabled test-login + test-session-header harness). Production never falls back to this fixture or process-memory receipts.

Canonical fixture IDs:

Routes:

Denied by contract: missing session, cross-tenant access, missing feature entitlement, wrong workspace, unknown packet id, auditor mutation, AI mutation, frontline mutation, operations attestation/approval, expert founder approval, founder expert attestation, enterprise-admin founder approval, and every provider/customer/legal/financial dispatch path.

Special Ops database-first cutover

Utiliser docs/runbooks/special-ops-monolith-production.md^† for the NDconsulting/Special Ops seed, tenant/workspace isolation, capability graph, AI Ops Sprint, and all-in-one work-graph promotion gates. The DB repository lane is implemented; live customer-data promotion remains blocked until its migration, RLS, backup, closed ND manifest, canary, and rollback evidence is approved.

Production prerequisites

The following items must be resolved before this app is promoted to production with real-tenant data. The design-partner v2 persistence and Vercel relay lane is implemented; unrelated deterministic proof lanes retain their own deferrals.

Do not activate organization authority until all prerequisites above and every decision in docs/runbooks/managed-companyos.md has explicit approval artifacts and implementation sign-off. The archived private-pilot material is ND migration history, not the forward execution checklist.

Organization authority migration history

Historical migration 0012_better_auth_schema.sql remains immutable and creates missing Better Auth tables. Forward-only migration 0016_better_auth_partial_schema_evolution.sql evolves empty partial schemas and fails transactionally when existing rows or column types cannot satisfy the canonical schema. The migration ledger records each version only after its full schema validation commits.

The profile-aware bootstrap preserves existing credentials, requires BOOTSTRAP_ADMIN_PASSWORD only when tboutron@lssm.co does not yet exist, and requires an explicit live profile instead of tenant/workspace selectors. The stable manifests own those values. Better Auth organization IDs are never assumed to equal physical tenant IDs.

Organization authority HTTP lifecycle

The API binds the public CompanyOS authority operations to real routes:

• GET /api/companyos/organizations;
• POST /api/companyos/organizations/set-active;
• GET /api/companyos/auth/authority;
• GET /api/companyos/workspaces.

Browser requests require the exact configured web Origin, ambient credentials, and explicit admitted OPTIONS preflights. Absent Origin is accepted only for server transport. Every success, deny, conflict, and degraded authority projection is Cache-Control: private, no-store.

Set-active preserves every distinct provider Set-Cookie value through the Elysia handler and Node response adapter, including cookies whose Expires attribute contains a comma. The post-write canonical authority read bypasses provider and HTTP caches. Membership rejection returns 403, stale or mismatched canonical authority returns 409, and malformed or unavailable stores return retryable 503.

A session without an active organization may list only its current memberships and select one, but it receives zero workspace authority until canonical revalidation succeeds. The host shares one lazy authority repository/pool across requests and closes it during shutdown.

Migration 0020_organization_active_audit.sql installs a constrained security-definer PostgreSQL trigger that records organization.activeChanged in the same transaction as a real active-organization transition. Re-selecting the current organization emits nothing; invalid authority and audit insertion failure roll back the transition, and provider-owned clearing emits no tenant event. Use the disposable PostgreSQL commands in docs/runbooks/real-organizations-rollout.md^† to prove migration, transition, no-op, and rollback behavior. Repository-local proof does not claim that a live production database was migrated or cut over.

Local commands

bun run --cwd packages/apps/api-application-monolith dev
bun run --cwd packages/apps/api-application-monolith test
bun run --cwd packages/apps/api-application-monolith typecheck
bun run --cwd packages/apps/api-application-monolith lint:check
bun run --cwd packages/apps/api-application-monolith build
bun run --cwd packages/apps/api-application-monolith companyos:db:migrate:test
bun run --cwd packages/apps/api-application-monolith companyos:db:seed:test
bun run --cwd packages/apps/api-application-monolith companyos:db:verify:test
bun run --cwd packages/apps/api-application-monolith companyos:db:prove-rls:test
bun run --cwd packages/apps/api-application-monolith companyos:db:prove-disposable-postgres

# Live/shared DB path: approval-gated, non-destructive, URL-redacting.
bun run --cwd packages/apps/api-application-monolith companyos:db:migrate:live
bun run --cwd packages/apps/api-application-monolith companyos:db:seed:live
bun run --cwd packages/apps/api-application-monolith companyos:db:verify:live

typecheck runs two projects: typecheck:build (tsconfig.build.json, the src/ sources that prebuild also gates) and typecheck:scripts (tsconfig.scripts.json, every scripts/**/*.ts operator script and its tests). The Postgres bootstrap recovery suite (scripts/bootstrap-admin-postgres.test.ts) runs only when MANAGED_COMPANYOS_TEST_DATABASE_URL points at a disposable local database.

Managed Builder public REST surface

The Elysia host exposes Builder operations at /api/companyos/builder/* as a tenant-scoped Builder surface distinct from agent/workflow. The public handler uses AuthOS/control-plane service-principal authorization, rejects raw-looking provider or webhook credentials, and reuses the Builder runtime resources that select DB-backed storage by default (or BUILDER_RUNTIME_STORAGE=memory for tests). Key route families include sessions, sources, intents, spec packs, plan compile/tasks, provider preflight, executions, webhooks, readiness, previews, releases, replay, evidence, analytics, and improvements.

Provider/webhook activation stays fail-closed unless callers pass approved typed refs such as provider_ref:* and webhook_ref:*; raw sk-*, whsec_*, GitHub, Slack, or long secret-looking values return 422.

Auth, DB lifecycle, and RLS closure

The API monolith owns the executable Managed CompanyOS auth/database/RLS slice:

• Session authority is request-derived from the managed_companyos_session cookie or the test-only x-managed-companyos-session header; invalid, missing, revoked, expired, or tenant-mismatched sessions fail closed.
• Auth lifecycle state is exposed through API-local invitation, passkey, lockout, sign-out, and governed session-revoke routes. Invitation administration supports list, send, token-rotating resend, and terminal revoke; invitation and passkey routes return refs only, while raw passwords, public keys, provider tokens, and secret-manager URIs are rejected or kept out of responses. The seeded /api/companyos/auth/test-login helper is disabled outside test mode unless MANAGED_COMPANYOS_ENABLE_TEST_LOGIN=1 is set.
• The app Drizzle schema, migrations, local lifecycle, seed manifest, and mutation repository use canonical managed_companyos_* table names, including managed_companyos_invitations, managed_companyos_passkeys, managed_companyos_passkey_challenges, managed_companyos_auth_lockouts, and managed_companyos_mutation_ledger.
• Drizzle schema code is the canonical source for feasible owned tenant RLS metadata. src/db/schema.ts attaches pgPolicy tenant-isolation policies to tenant-scoped Drizzle tables, while src/db/rls-policy-inventory.ts records executable SQL parity expectations, the explicit-WITH CHECK tenant policies, schema-only classifications and runtime descriptor fallback, and re-exports src/db/rls-policy-inventory-exceptions.ts (the 0066 topology evidence split, platform exceptions and the current Drizzle 0.x version gate: pgPolicy only; no pgTable.withRLS). Migration 0179 makes every inventory tenant policy compare nullif(current_setting('app.tenant_id', true), ''); 0183 validates its non-empty CHECK constraints.
• Checked-in SQL migrations remain the executable artifacts. Before changing policy names, roles, USING, WITH CHECK, ENABLE, or FORCE semantics, run the ContractSpec Connect gate and the static parity tests; treat any table/policy/role SQL drift as compatibility-impacting unless explicitly classified in the plan/evidence bundle.
• Local/test DB lifecycle commands require MANAGED_COMPANYOS_TEST_DATABASE_URL or LSSM_STUDIO_TEST_DATABASE_URL and refuse production-like targets. Reset removes every personal-context, team-grant, user-workspace-grant, personal-calendar, and briefing table before replay, so repeated reset/seed/bootstrap runs do not retain authority state. Auth lifecycle repository fallback to memory is test-only unless MANAGED_COMPANYOS_ENABLE_MEMORY_AUTH_REPOSITORY=1 is explicitly set. When AUTH_PROVIDER_MODE=better-auth, the catch-all better-auth route also fails closed unless one of MANAGED_COMPANYOS_AUTH_DATABASE_URL, MANAGED_COMPANYOS_TEST_DATABASE_URL, LSSM_STUDIO_TEST_DATABASE_URL, or LSSM_STUDIO_DATABASE_URL is configured, preventing accidental in-memory auth fallback in production mode.
• Live/shared DB lifecycle commands are separate: companyos:db:migrate:live, companyos:db:seed:live, and companyos:db:verify:live. They read LSSM_STUDIO_DATABASE_URL (or MANAGED_COMPANYOS_LIVE_DATABASE_URL), emit only a redacted target fingerprint, require approval evidence for all commands, require backup/checkpoint evidence for migrate/seed, and expose no reset/drop/truncate-all live action. Seed and verify accept no forward tenant/workspace selector: one invocation reconciles the selected contract-owned profile (all/core-workspaces: the live lssm and companyos organizations) in deterministic order. Each organization is atomic across its declared families, committed organizations remain resumable after a later failure, and replay succeeds only when receipt, expected counts, and the live semantic digest agree. Optional hybrid booking is configured only through the fixed LSSM or CompanyOS URL/evidence pairs documented in deploy/env/api.env.example. Supplying only half a pair, a non-HTTPS/non-Calendly URL, or either legacy singular selector fails before the seed opens its manifest-wide runner. Receipts and command output expose only configured organization slugs and URL digest evidence; they never emit the raw booking URL.
• companyos:db:prove-rls:test verifies forced RLS metadata and SQL tenant-denial behavior when a permitted local/test DB URL exists. The proof provisions managed_companyos_rls_proof_app, queries pg_roles, and fails unless that role is rolsuper=false and rolbypassrls=false; tenant-denial assertions never run on a superuser or BYPASSRLS role. If no permitted URL is present, report the live proof as not run rather than passed.

AuthOS identity provider & identity-rbac authority

When AUTH_PROVIDER_MODE=better-auth, the API serves a real AuthOS identity provider through the @lssm-tech/integration.authos-better-auth bridge (src/auth/better-auth-setup.ts). The runtime-backed login surface is email+password, email OTP, email magic link, and built-in social login for Google, Microsoft, LinkedIn, TikTok, Facebook, and GitHub. Verified aliases resolve to the same Better Auth user and shared password while OTP, magic-link, and recovery delivery uses the address entered. Public self-signup remains disabled by default; promotion requires every external evidence reference plus production Turnstile configuration. GET /api/companyos/auth/login-methods exposes only enabled method IDs, labels, and link requirements—never credentials.

The reviewed central LSSM identity profile is an isolated host deployment, not a wider CompanyOS cookie mode. With LSSM_IDP_ENABLED=1, both auth and web origins must be exactly https://id.lssm.co, the cookie is host-only, and the OAuth 2.1/OIDC provider exposes standards-compatible discovery aliases. Product applications receive pairwise subjects and continue to own tenant, membership, role, and data authority locally.

LSSM OS is a separate relying party projected through this API. Reviewed activation registers only lssm-os-web, the exact app_lssm_os scope, PKCE, and https://os.lssm.tech/auth/callback/lssm. The browser session remains an API-local SameSite=None; Secure cookie for api.companyos.run; it is not an ecosystem cookie. os.lssm.tech and console.lssm.tech enter the credentialed CORS allowlist only while that reviewed client is fully configured.

The product-access path is a separate fail-closed authority. Public intake is scoped to one registered application; opening the private status link proves email possession and moves the request to review. Approval issues a 256-bit, single-use invitation whose plaintext exists only in email. Acceptance at id.lssm.co/auth/accept-invite provisions or reuses the central identity and atomically records the active coarse entitlement plus redacted provisioning receipts. The OAuth provider requests exactly one product scope and redirects to /auth/access unless that identity has an active, non-expired entitlement. Migration 0058_authos_product_access.sql owns the durable event, invitation, entitlement, and receipt tables; replay is additive and tested with PGlite.

• Single-session authority. Every credential path and enabled plugin funnels through finalizeAuthenticatedSession (src/auth/active-org-hook.ts). A preselected organization is preserved only after current membership validation. Otherwise, new-session selection uses the sole deterministic fallback organization.created_at ASC, organization.id ASC; no membership leaves the organization unset and downstream access fails closed.
• Fresh organization authority. activeOrganizationId is an identity-plane key, not a physical tenant ID. Each protected request rechecks the current Better Auth session and membership, resolves an enabled organization-to-tenant binding plus canonical managed_companyos_organization_grants row, and derives the RLS tenant only from that verified binding. Global user.role and managed_companyos_operators.role remain compatibility/reporting projections and never authorize CompanyOS domain actions.
• Commit-time switch protection. Resource transactions retain the expected session, organization, binding, and grant versions. Immediately before commit they lock and recheck the authoritative Better Auth session row and re-prove membership/binding/grant authority. A concurrent organization switch or authority change rolls the transaction back; callers must begin a fresh request rather than retrying under a newly selected organization.
• Fail-closed plugin config. A capability marked runtime-backed in the spec without a real runtime-wired better-auth plugin throws at setup (assertEnabledPluginRuntimeWiring in src/auth/plugin-config-guard.ts) instead of silently no-opping.
• Provider tokens at rest. Better Auth seals provider OAuth access and refresh tokens (account.encryptOAuthTokens plus a seal-on-refresh hook); legacy plaintext stays readable until it is rewritten, ID tokens are stored as received, and the deploy prerequisites, dual read and rollback rules live in src/auth/oauth-token-encryption.ts.
• Canonical grants feed identity-rbac. The organization grant's validated role maps to the exact, least-privilege identity-rbac permission set in src/middleware/companyos-role-permissions.ts. src/middleware/companyos-subject.ts wraps createSubjectProvider (@lssm-tech/lib.authos-runtime) into the governance Subject, and src/middleware/authorization.ts attaches the resolved permission set to user actors. Control-plane/builder capability gating remains a separate axis; organization membership alone never grants domain, approval, billing, provider, or machine-only authority.
• 401 vs 503 (retryable RBAC distinction). No session → 401. A valid session whose identity-rbac resolution fails (store transiently unavailable / unmapped role) → 503 with an auth.rbac.unavailable signal (hashed tenant, no PII/tokens), NEVER the 401 reserved for "no session".

Profile-aware bootstrap

MANAGED_COMPANYOS_SEED_PROFILE=core-workspaces bun run companyos:bootstrap-admin reconciles the live LSSM and CompanyOS organizations for one canonical account; all selects the same live set. Live commands require an explicit profile and refuse the deprecated reference-only legacy-reference profile because it includes NDconsulting, decommissioned with Hirly on 2026-10-20 (Éléments de preuve^†). The retired lssm-hirly profile is refused by every bootstrap and seed path, local included, and no collaborators:hirly phase runs; the company spec keeps the id exported only as a deprecation window until its next major.

• The bootstrap takes a session-scoped PostgreSQL advisory lock. Better Auth identity operations and tenant-scoped authority transactions are separate, idempotent saga phases; migration 0019 records each completed phase durably instead of claiming cross-connection atomicity.
• Existing users never require or update a password. BOOTSTRAP_ADMIN_PASSWORD is read only when the configured admin account is absent; secrets and the admin email are not emitted in receipts or logs.
• When Better Auth creates the absent user's primary email row first, bootstrap verifies that same-user row in place and preserves its opaque provider ID. A normalized email already owned by another user remains a hard conflict.
• The canonical user has primary tboutron@lssm.co, verified alias theo@tryhirly.com, and one private personal space. LSSM and CompanyOS bind the primary owner email; Hirly, which bound the alias, was decommissioned on 2026-10-20.
• Every selected organization has a distinct physical tenant/workspace binding with only OPA and CommunicationOS enabled by default.
• Replays are idempotent for the same profile and manifest revision. Email, personal-space, membership-email, and module phases have durable receipts.

Migration 0039 adds one-time, attempt-bounded alias verification challenges; 0040 adds owner-controlled join policies, verified-domain claims, and transactional access-request decisions; 0041 adds retryable personal-context provisioning state. Session creation never fails solely because private-space provisioning is temporarily unavailable: the user remains authenticated and can inspect GET /api/companyos/personal-context/provisioning-status before a bounded retry. Better Auth database lookups canonicalize verified aliases for OAuth callbacks without rewriting provider-account identity, so a verified secondary email links to the existing user instead of creating a duplicate.

Authenticated profile, smart-meeting, booking-repair, approval, and Google Calendar routes verify the active workspace's OPA entitlement before touching OPA storage or provider runtimes. A disabled module is therefore hidden by the web shell and denied independently at the API boundary.

Deferred AuthOS capabilities (honest, contract-only with reasons — never marked runtime-backed):

• passkey (WebAuthn): better-auth 1.6.15 ships no passkey plugin; requires @simplewebauthn + cross-package dep wiring — deferred to its own wave. (The app-local managed_companyos_passkeys ref routes above are a separate deterministic proof-path, not the better-auth WebAuthn plugin.)
• sso / saml and scim: modeled as external:* bridge declarations (runtimeWired: false); ADR follow-ups pending real @better-auth/sso / @better-auth/scim wiring.
• audit: Better Auth has no audit plugin; the API-owned /api/companyos/auth/audit projection reads the tenant RLS ledger, returns redacted classified events with signed pagination, and exposes a bounded administrator/auditor CSV export.
• connect-lssm-account-link: the LSSM IdP (oidc-provider) is gated on enableLssmIdp + a security-review ref, neither configured in v1.

Live DB operation checklist:

1. Record the ContractSpec Connect gate/evidence for the migration/RLS decision.
2. Put the live DB URL only in LSSM_STUDIO_DATABASE_URL or MANAGED_COMPANYOS_LIVE_DATABASE_URL; command output redacts URL user/password and records only a target fingerprint.
3. Provide MANAGED_COMPANYOS_LIVE_DB_APPROVAL_EVIDENCE_PATH (or an opaque approval ref) for migrate/seed/verify.
4. Provide MANAGED_COMPANYOS_LIVE_DB_BACKUP_EVIDENCE_PATH (or an opaque backup/checkpoint ref) before migrate/seed.
5. Set MANAGED_COMPANYOS_SEED_PROFILE, run companyos:bootstrap-admin, and require the complete selected authority manifest before business seeding.
6. Run companyos:db:seed:live once for the selected contract-owned profile; do not supply tenant/workspace selectors.
7. Run companyos:db:verify:live and require exact family receipts, counts, semantic digests, tenant isolation, and redacted evidence.
8. Run only companyos:db:migrate:live, companyos:db:seed:live, and companyos:db:verify:live; there is no live reset/drop/truncate-all command.
9. Run static parity first: bun test --cwd packages/apps/api-application-monolith src/db/schema.test.ts src/db/rls-policy-inventory.test.ts src/db/rls-proof.test.ts.
10. Run DB-gated migrate/seed/verify/prove commands only when the URL is permitted.
11. Report skipped or blocked DB proof as not run, never as passed.

The exact-head disposable PostgreSQL 15 proof creates two uniquely named loopback-only databases, compares empty migration with a production-through-0017 forward replay, bootstraps the canonical organizations, forces and resumes a family failure, replays twice, verifies all families, and runs a cross-tenant SELECT/INSERT/UPDATE matrix as a real NOSUPERUSER NOBYPASSRLS role. It stops the cluster, removes its temporary data, and proves the port is closed.

Integration Points

REST API Integration

External systems integrate with Managed CompanyOS via REST routes:

# Workspace projection (workflow state, integrations, replay packets)
curl -H "x-managed-companyos-session: <HMAC-signed-token>" \
  https://api.host/api/companyos/workspace

# Evidence verification (audit proof)
curl -H "x-managed-companyos-session: <token>" \
  https://api.host/api/companyos/evidence?correlationId=corr_xyz

# Health check
curl https://api.host/api/companyos/health

# Degraded health (returns 503 if API or scheduled snapshot duties are unhealthy)
curl https://api.host/api/companyos/health/degraded

# Request-time Vercel snapshot readiness
curl -H "x-managed-companyos-session: <token>" \
  https://api.host/api/companyos/vercel/snapshot

# Replay/evidence snapshot
curl -H "x-managed-companyos-session: <token>" \
  https://api.host/api/companyos/vercel/replay-evidence

# Supervision-equivalent snapshot
curl -H "x-managed-companyos-session: <token>" \
  https://api.host/api/companyos/vercel/supervision

All tenant-scoped queries derive tenantId from the verified session token. Cross-tenant access is rejected with 403.

MCP (Model Context Protocol) Integration

For AI agents and CLI tools, use the planned @lssm-tech/app.managed-companyos-mcp server (see .omx/audits/mcos-mcp-design-20260515.md for design).

MCP tools expose the same operations as the REST API but with additional:

• Tool context factory for tenant/actor/policy decisions
• Resource URIs for replay packets, evidence receipts, and health snapshots
• Prompts for copilot-style operator guidance

Manual refresh / snapshot integration

Web production should request snapshots from the API monolith and let users refresh or navigate to obtain a fresh request-time snapshot. Do not add WebSocket, SSE, EventSource, interval polling, or automatic polling as a replacement in the Vercel-only topology.

The standalone Bun realtime runtime remains documented in the worker package for non-production proofs and future VPS mode only; it is not a managed CompanyOS production dependency while this cost-capped Vercel topology is active.

Central governed-recovery bindings reuse the shared fail-closed HTTPS port from @lssm-tech/lib.data-exchange-server. Each product binding has one exact HTTPS origin and distinct server-only bearer; duplicate application bindings are rejected rather than overwritten. Revocation and rights requests omit worker lease metadata, ambient credentials, and redirects, and accept only bounded schema-valid product evidence.

Managed CompanyOS environment

Copier deploy/env/api.env.example into the deployment secret-manager-backed environment group and apply the canonical environment contract in docs/runbooks/managed-companyos.md. Keep raw provider credentials out of committed files and evidence; concrete providers remain approval-gated.

For the managed monolith Vercel rollout, the supplied API DB URL belongs only in LSSM_STUDIO_DATABASE_URL and MANAGED_COMPANYOS_AUTH_DATABASE_URL. Do not copy it into the web app. MANAGED_COMPANYOS_WAITLIST_DATABASE_URL is optional and requires a separate low-privilege waitlist writer URL; leave it absent/empty otherwise. Using the same supplied API DB URL across production/preview/development and both API DB variables is an intentional blast radius only when all envs + migration were explicitly selected; split runtime, auth, migrator, and waitlist credentials later.

Provider strategy matrix

The executable app-layer provider catalog currently includes:

• managed-reference → reference-managed-channel, configured by MANAGED_COMPANYOS_MANAGED_REFERENCE_CREDENTIAL_REF.
• byok-reference → reference-byok-channel, configured by MANAGED_COMPANYOS_BYOK_REFERENCE_CREDENTIAL_REF.

Both entries expose redacted metadata only (********) and dispatch through an injected/provider-neutral harness. Missing env refs, raw-looking values (sk-*, xox*, bearer tokens, URLs/URIs, or oversized values), unknown provider ids, and unconfigured catalog entries fail closed before dispatch.

The broader provider family matrix is documented in docs/runbooks/managed-companyos.md and specs/companyos-managed-readiness.md as catalog/readiness intent, not blanket live-dispatch approval. Concrete SDK imports/defaults remain confined to app/integration/provider layers; lower bundles/libs/modules must stay provider-neutral.

Forms platform

CompanyOS mounts management at /companyos/forms, public forms at /f/{opaqueToken}, and the API at /api/forms/v1. Configure MANAGED_COMPANYOS_FORMS_DATA_PROTECTION_SECRET, milestone flags, and optional verification, AI, and distributed-defense MANAGED_COMPANYOS_FORMS_* ports. Migrations 0048_forms_platform.sql and 0050_forms_scope_hardening.sql own the product-local schema and its tenant/workspace/owner plus row-bound public RLS upgrade; creator scope is always derived from the resolved API session.

Governed meeting workspace

Migration 0053 installs the OPA meeting-workspace forced-RLS tables. The additive 0061 access-grant, 0063 provider-intake, and 0065 recurring intake-job migrations preserve the same five-axis owner scope. The Elysia host mounts all nineteen exact catalog operations below /api/v2/opa using the verified CompanyOS organization/workspace session, module entitlement, persisted capability grants, app-origin check, and CSRF session reference. Production initialization requires LSSM_STUDIO_DATABASE_URL plus the versioned OPA_BYOK_KEY_VERSION and OPA_BYOK_MASTER_KEY_<version> secret; missing storage or encryption configuration fails closed.

The provider-neutral transcript intake adapter is intentionally not an anonymous HTTP ingress. Its host caller must derive owner scope, active consent receipts, and recorder bindings from verified server state; normalized content remains unpublished until a credentialed provider integration earns its own transport and live qualification evidence.

OPA capture intake

Migration 0075 adds owner-scoped consent receipts after encrypted staging 0074. The seven declared capture routes are mounted under /api/v2/opa. Set OPA_CAPTURE_ENABLED=1, OPA_CAPTURE_STORAGE_REGION=eu, and the existing OPA_BYOK_KEY_VERSION=v1 / OPA_BYOK_MASTER_KEY_v1 secret to enable audio intake. Effective workspace grants must include opa.recording.read, opa.recording.control, and opa.recording.consent_self; existing grants are not implicitly elevated. The meeting must already exist in the canonical workspace.

Configuration exposes the effective policy digest and consent notice version. Grant consent explicitly before creating a microphone/import session; submit sequential digest-bound base64 chunks of at most 1 MiB. Finish checks the announced chunk/byte totals and returns processing, never a fabricated transcript. Native bearer requests are freshly verified without a cookie fallback. Browser writes require the configured web origin and the current session CSRF token.

Processing availability is derived from the approved worker configuration and dispatcher credentials. Bot/system-audio/video intake remains unavailable in this host. Worker deployment, device capture, cleanup and the full release evidence must be qualified before rollout. Revocation, cancellation and deletion remain available when intake is switched off, subject to current membership and legal holds.

Scheduling effect authority

Apply additive migration 0076 before deploying the scheduling receipt producer. Human calendar intents persist a policy-bound authorization receipt. Immediate execution and cron retries reprove current session/membership/workspace, policy, Work placement, calendar write target and lease before provider credential lookup. Policy changes invalidate queued approvals. Legacy pending commands require a fresh owner intent; historical applied effects are retained unchanged.

OPA_SCHEDULING_EFFECTS_DISABLED=1 stops every scheduling provider mutation. Automation policy disabled stops new placement/movement while allowing an otherwise-authorized owner cancellation. These are human-approved continuations; delegated autopilot is not promoted by this change.

Migration 0077 adds encrypted, owner-scoped transcript revision persistence after 0076. It preserves existing artifacts and recordings. CompanyOS AI drafting rejects transcript creation: use recorded/imported evidence through the transcription core. The processing dispatcher and private transcript read route are mounted behind explicit configuration. Transcript review and the remaining release gates are still unqualified.

Durable capture processing

Migration 0078 queues finalized captures and adds bounded worker admission plus restricted dispatcher discovery. Configure a login whose current role is exactly companyos_capture_dispatcher in MANAGED_COMPANYOS_CAPTURE_PROCESSING_DATABASE_URL. The role may call the due-scope function but cannot read media or transcripts. The worker itself reads and writes captures on the restricted runtime login companyos_capture_runtime (migration 0181) in MANAGED_COMPANYOS_CAPTURE_RUNTIME_DATABASE_URL, never on LSSM_STUDIO_DATABASE_URL; the bot crons use companyos_bot_runtime (MANAGED_COMPANYOS_BOT_RUNTIME_DATABASE_URL) and recorder sync companyos_recorder_runtime (MANAGED_COMPANYOS_RECORDER_RUNTIME_DATABASE_URL). Each cron refuses any other current_user, a superuser, BYPASSRLS or an opa_migrator member (CAPTURE_/BOT_/RECORDER_RUNTIME_ROLE_INVALID).

Automatic capture processing is currently paused: the configured binding returns null until Gateway EU transcription and speaker labels are qualified. Existing Mistral credentials or capture flags cannot reactivate the default provider. The cron at /api/cron/opa-capture-processing requires the exact CRON_SECRET (minimum 32 characters) and executes every minute with a 300-second budget.

The worker checks current recording-scope membership and consent independently of the active browser workspace. Transcript persistence and completion share one commit. Cancellation/deletion invalidates queued work and releases capacity. The existing transcript GET route exposes private segments and provenance; it does not approve a transcript or enable participant sharing. Review, participant consent integration and the broader production gates remain incomplete.

Transcription model choice (opa.transcription.settings.get|save, migration 0161) is stored per user and per workspace (workspace default for workspace administrators) at /api/companyos/opa/transcription/settings; the cron worker resolves each capture owner's choice, and only EU-qualified catalog ids are ever forwarded. While the catalog is empty the settings report no_eu_model. Deleting a capture with deleteDerivedOutcomes: true also erases, in the same transaction, the unpublished and unshared drafts, outcomes and context derived from its transcripts (aggregate plus the append-only projections through the 0162 owner-bounded definer function opa_erase_derived_meeting_records), cancels their outcome jobs, keeps published or shared notes and writes an opa.capture.derived_outcomes_deleted audit event with counts only.

Transcript review

Migration 0079 enables encrypted source-bound review history. POST the existing transcript review route with its 3.0.0 input: exact transcriptRef, artifactDigest, expectedRevision and expectedReviewRevision. A missing review has revision zero. The route requires current private read and review permissions and native bearer or browser origin/CSRF authority. Source changes never inherit an old approval.

Reviewed replacement text is a separate encrypted copy; original timed segments remain unchanged and are omitted from the reviewed-copy projection. Parent deletion erases replacement content. The UI's canReview flag is presentation, not execution authority. Review alone does not send or commit any outcome.

Private reviewed meeting outcomes

The existing meeting-workspace routes accept x-opa-owner-view: private to derive individual ownership from the verified user within the selected workspace. Omitting the header preserves context ownership; arbitrary owner selectors are rejected. Use the same private view for outcome analysis and subsequent artifact reads. The web BFF forwards this selector after its existing authentication and mutation-origin checks.

CompanyOS outcome analysis loads the persisted approved transcript review, verifies exact source and review bindings, and checks current intelligence.generate policy before generation and commit. Rejected, changed, unauthorized or workspace-widened sources fail closed. The adapter uses the caller transaction and does not publish private capture text. Model calls run outside aggregate transactions. Finalization reloads current state and rechecks authority and the reviewed source before saving. Durable outcome jobs are available behind explicit configuration; downstream effects and live quality qualification remain open.

Reviewed outcome drafts in CompanyOS

The approved transcript panel can generate and read private meeting drafts through existing OPA operations. Generation controls use server-derived canGenerateOutcomes; authority and automation policy are rechecked server-side. Draft generation creates no messages or Work tasks. French, English and Spanish copy distinguishes loading, generation, retry, denied access and empty history.

Artifact list 2.2.0 accepts optional reviewRef, selecting the current review before source reproof so stale historical drafts do not block current results. Transcript get 2.2.0 adds the generation capability projection. The client pins private ownership and an exact review-derived retry key, including across reloads. Interactive generation has a bounded 180-second request deadline; the web proxy allows a 300-second function budget. Persisted background jobs, signed-native presentation and full browser/accessibility qualification remain incomplete.

Correcting and reviewing outcome drafts

Artifact review 3.0.0 accepts optional editedContentMarkdown when approving. The request still binds the displayed artifact revision and original content digest; the receipt approves the corrected digest. Human edit metadata records the prior digest, actor and timestamp. Empty edits, edits combined with rejection/CRDT snapshots, and independent edits during open collaborative sessions are rejected. A retry key cannot approve a different payload.

The private draft cards expose edit, approve and needs-changes controls using server-derived canReviewOutcomes. Uncertain review responses retain the current draft for retry; access denial removes it. Approval does not send messages, publish links or create Work tasks. Actual edited-review PostgreSQL qualification, complete collaborative editing and downstream actions remain open.

Durable outcome processing

Analyze 3.1.0 accepts executionMode: background on its existing route. Repeating the exact request observes the same persisted job; processing responses carry processingJobRef, while completion returns the saved outcome. The private draft client selects background mode when the server advertises it and can stop polling without cancelling accepted work. Terminal failures remain failures.

Apply additive migration 0080, configure a dedicated companyos_outcome_dispatcher login, and enable OPA_OUTCOME_JOBS_ENABLED=1 only with approved pinned OPA_MEETING_AI_* EU processing. The every-minute /api/cron/opa-outcome-processing route requires CRON_SECRET. Runtime credentials must not be superuser, BYPASSRLS or a member of opa_migrator. The queue admits four global jobs and one per owner, bounds pending owner jobs at 25, retries at most five times and uses six-minute fenced leases. Current membership, module entitlement, intelligence policy, source consent/review and model binding are rechecked before generation and commit.

Meeting follow-up effects cron

/api/cron/opa-meeting-effects (every minute, CRON_SECRET) hosts the meeting effect worker cycle in process, so approved follow-ups deliver without a separate worker host. Apply additive migration 0172 and give companyos_meeting_effect_dispatcher a login in MANAGED_COMPANYOS_MEETING_EFFECTS_DATABASE_URL; that role can only call companyos_meeting_effect_due_scopes, which returns owner scopes, never effect refs or content. Claims, authority reproof, rollout, approval and artifact-digest checks, the Postgres dispatch fence, delivery and settlement run as the RLS-bound runtime role (LSSM_STUDIO_DATABASE_URL, never superuser, BYPASSRLS or opa_migrator) on a pool opened per invocation. Switches: OPA_MEETING_EFFECTS_CRON_ENABLED=1 and OPA_MEETING_FOLLOWUP_DELIVERY_ENABLED=1; OPA_MEETING_FOLLOWUP_TARGETS and a strict companyos entry in OPA_MEETING_EFFECT_ROLLOUTS_JSON are required. Off or unprovisioned answers 200 with stoppedBy and variable names only. Each invocation handles at most 10 owner scopes, 3 leases per scope and a 60 s budget; the log line opa_meeting_effects_cycle carries counts and failure codes only. Run exactly one effect host per database: this cron or @lssm-tech/app.meeting-effect-worker.

The verified_email target routes the reserved recipient owner:self to an owner-only recap: the approved follow-up or summary goes to the approving owner's primary verified account address (individual owner scopes only) through the CompanyOS Briefings Resend mailbox, keyed by the effect for provider deduplication. It is off unless OPA_MEETING_FOLLOWUP_OWNER_RECAP_ENABLED=1 and RESEND_API_KEY are set.

Attendee refs on verified_email and every communicationos_thread effect go through CommunicationOS, composed per delivery inside the owner transaction:

• Authority. The server-side createCommunicationOsAuthorityIssuerV1 issues the Runtime V3 order only for the one send that delivery describes, after the delivery service has re-proved the plan approval, the approver and their dispatch capability. The approval port recomputes that request itself (bound scope, production environment, effect, channel, effect-bound idempotency key, and the approved context digest over the room in threadRef, the address the approved recipient ref resolves to, the re-proved artifact content and the bound principal); the room is the adapter's per-delivery room, bound through that digest. The order's authorization digest commits to the approval evidence. Thread refs use communicationOsRoomThreadRefV1 (communication-room:<base64url(roomId)>), unlike the calendar briefing path, which still sends the raw room id. OPA_MEETING_FOLLOWUP_COMMUNICATION_AUTHORITY_JSON carries the operator deployment (Runtime Node, provider binding, queue profile, TTL); unset or invalid keeps both targets adapter_unavailable, and an invalid value logs OPA_MEETING_FOLLOWUP_COMMUNICATION_AUTHORITY_INVALID (code only).
• Durable record. The admission is deferred to the caller: an email's operation, order, runtime outbox and envelope refs go into its CommunicationOS outbox row, a thread post's into its message event metadata. An explicit authority denial or queue refusal dead-letters the effect; an unavailable approval, a packet mismatch or an outage retries.
• Binding. Only an individual CompanyOS owner scope approved by that owner binds, to the owner's enabled personal CommunicationOS context as user:<id>. Team and workspace scopes stay adapter_unavailable.
• destinataires. A participant:<directory>:<subject> ref resolves only when its owner-salted subject matches exactly one attendee address of that meeting, read live from the owner's calendar (OPA stores no address) once per delivery and bounded to 10 s (a timeout answers 503 and retries). Named attendees resolve once the meeting event reader keeps provider addresses; until then only e-mail-shaped attendee labels do.
• Store and connections. The journal and outbox use the effect host's own pool (the companyos_opa_runtime login in the cron), never a pool on LSSM_STUDIO_DATABASE_URL. A delivery holds its owner transaction while it reads attendees and writes CommunicationOS, so it needs at least two more connections of that pool. No migration grants the cron login membership in communication_os_app yet (without it delivery fails and retries); an operator migration must add it. The login must also hold execute on managed_companyos_resolve_personal_context(text) (0173) and select on the attendee read's tables (managed_companyos_personal_briefing_preferences, managed_companyos_personal_contexts, the personal calendar sources, selections and workspace mappings, managed_companyos_user_workspace_grants, managed_companyos_workspaces, opa_calendar_connections, managed_auth_email_addresses through 0182). Google calendar reads use the Google calendar runtime's own pool.

The email is queued in the CommunicationOS outbox; the CommunicationOS worker and Agent Host send it with the env://COMMUNICATION_OS_CONNECTION_OPA_MEETING_FOLLOWUP_RESEND credential, before its order expires (deployment ttlSeconds, at most 900 s). The effect already counts as delivered, so an expired order must be re-admitted on the CommunicationOS side, not by an OPA retry.

Outcome persistence and completion share a transaction; model calls are outside SQL. Queue rows contain references and authorization evidence, not transcript text or credentials. Model cost may repeat after a crash before commit. Terminal-job self-service repair, queue retention/deletion propagation, live model/provider qualification and production rollout remain open. No production activation is implied by the local tests.

Work commit authority for OPA follow-through

Managed Work mutations now resolve canonical identity, read projections, persist the event/idempotency/outbox, and reprove authority within one outer transaction. The existing verified operator binding is preserved. Current organization, session, workspace and applicable team grants are locked before the effect and checked again before commit. A final denial rolls back all Work writes.

The HTTP mutation route uses the shared verified-bearer resolver, rejects cookie fallback when authorization is present, and requires exact origin/CSRF for browser requests. Bodies are bounded to 1,100,000 bytes. Read-only and suggest-only labels cannot authorize mutation; approval-required and reserved actions remain unavailable until their approval verifier is composed. Errors are content-free and not cached. This is the commit foundation; approved OPA action projection and CommunicationOS delivery still require their explicit adapters.

Canonical Work hierarchy and legacy parity

Apply additive migration 0081 after 0080 before enabling new Work identity allocation. New operators reuse canonical tenant/organization/workspace IDs for the same verified legacy scope, and a principal retains its canonical ID across workspaces within a tenant. The database enforces this during mixed-version rollout; new allocation is serialized per legacy tenant. Existing bindings are read without taking the allocation lock.

Existing rows and Work events remain intact. A coherent legacy mapping is adopted for new operators; conflicting parent or principal mappings block new allocation with WORK_IDENTITY_RECONCILIATION_REQUIRED. Use inspectWorkIdentityParity inside an authorized transaction with the physical tenant GUC set to inventory conflicts. It reports scope categories and counts without rewriting data. Do not pick an arbitrary legacy ID or rewrite immutable Work events to clear the error. A reviewed reconciliation and parity/restore proof are required before enabling shared projection for a conflicted tenant.

The preparation function rejects foreign scope or unavailable trigger enforcement. Personal-context provisioning uses distinct physical tenants/workspaces, which remain isolated. This change is locally verified on PostgreSQL 15; production migration and existing-data reconciliation remain separate release gates.

Evidence-bound action proposals

Meeting prompt 2.0.0 requires structured actions for action-plan generation. Each proposal carries a title, optional description, explicit/uncertain classification and exact quotations tied to supplied citation references. Missing action output or unsupported quotes fails generation. Model output cannot supply owners or deadlines. Quote membership proves traceability, not semantic correctness.

Action-plan artifacts retain actionProposals, and their content digest covers prose and structured actions together. Artifact review 3.1.0 requires acknowledgeActions for a nonempty task list. Reviewers may edit titles/details while preserving verifiable source evidence. The private draft cards display proposed tasks, uncertainty and source quotes with an explicit approve-draft-and-tasks label. Prose-only or collaborative edits clear stale structured actions; edited structured input is revalidated against the current approved transcript.

This creates reviewed proposals, not Work commitments. Assignment, due dates, canonical Work projection, downstream delivery, deletion propagation and the live precision/recall benchmark remain open. Prompt-version changes invalidate incompatible queued generation bindings; never relabel old processing as using the new prompt.

Approved action to canonical Work

opa.task.project 3.0.0 projects one approved structured action through the existing task route. The request binds artifact revision/digest, approval receipt, action reference and selected workspace. It requires explicit workspace disclosure acknowledgment and confirmation for an uncertain proposal. The UI exposes this action only for approved task lists and server-derived projection permission.

Only the reviewed title and details are transferred; raw/private transcript text and source quotes are not copied into Work. Assignees and deadlines remain unset. Current outcome.commit policy, transcript review/consent and Work workspace write authority are rechecked. Work event/idempotency/outbox and the OPA projection receipt commit in one transaction. Repeated projection returns the existing Work object; a receipt represents committed task creation, not task completion or realtime projection convergence.

New owner capability manifests include opa.task.project; existing grants require an authorized update and are not silently widened. Legacy input-only projection clients must update to 3.0.0. CommunicationOS delivery, assignment/due-date controls, real-authority deployment qualification and full release gates remain open.

Native meeting mutation authority

OPA meeting workspace routes use bearer-only session verification whenever Authorization is present. Cookies and test-session headers are stripped before bearer verification; invalid tokens cannot borrow browser authority. Verified bearer POST requests need no fabricated Origin or CSRF. Browser POST requests retain exact origin and current session CSRF checks. Entitlements and current domain authority remain mandatory.

Only GET/POST are accepted, and mutation bodies are streaming-bounded to 1,100,000 bytes even without Content-Length. The CommunicationOS native-session exchange uses the same isolated bearer resolver. Route tests do not qualify signed native clients, MFA/deep links, capture permissions or app-store acceptance.

Migration 0082 adds immutable owner-scoped legacy-to-canonical meeting bindings. The default-off legacy diagnostic probe now uses persisted mappings with current CompanyOS authority reproof; missing mappings cannot initialize synthetic workspaces. This integration only reads mappings. A verified backfill and current workflow parity evidence are required before any legacy route cutover; no production data is reset or automatically rebound.

Private meeting preparation context

CompanyOS graph context now requires a verified individual, an exact five-axis meetingContextOwnerScope, the selected meetingRef, explicit bounded meetingContext text, and declared meetingContextClaimKind and meetingContextSensitivity. Inferences require confidence; estimates also require calculation/expiry timestamps. Generic titles/summaries and unscoped legacy projections are omitted. Append new validated graph projections through the existing Company Intelligence repository; do not rewrite append-only rows to infer missing bindings.

Reads run in a physical-tenant transaction. Every citation must resolve to current, non-superseded evidence and a fragment in the authorized workspace or principal ownership, with a current explicit principal ACL. Revocation tombstones invalidate their superseded sources. Graph payload audience flags and consent strings cannot authorize sharing: this source returns private context only. Generation compares every claim and source revision with a fresh authorized read before model invocation and before accepting the result. Historical artifact erasure and verified participant-sharing sources remain separate release requirements.

Private OPA route families now support exact trusted-origin credentialed browser CORS, using the existing AuthOS trusted-origin configuration. Preflight accepts only the declared methods/headers, including x-opa-owner-view and x-csrf-token; endpoint authentication and mutation checks remain mandatory. Public booking/embed transport is independent. Background preparation without a verified principal/source workspace remains unavailable; a database-ready worker alone is not source or workflow qualification.

Durable private meeting creation

GET /api/v2/opa/meeting-creation-context returns the current private owner-scope digest and remaining meeting capacity. POST /api/v2/opa/private-meetings accepts request.expectedOwnerScopeDigest and a stable request.idempotencyKey. Both operations require current opa.meeting_work_session.manage authority. The digest is a workspace-change guard, not an authorization token.

Creation atomically saves the encrypted workspace aggregate, lookup projection and replay receipt, with current authority checks before and after writes. It creates no calendar event, booking, recording or consent. Exact replays remain valid at the 10,000-meeting per-owner bound. Native bearer requests use the existing MFA-safe mutation resolver; cookie mutations retain origin and CSRF checks. Capture lookup accepts either the current user's persisted private meeting or the selected authorized shared meeting and restores private scope afterward.

These two CompanyOS routes are additive to the unchanged nineteen-operation generic meeting service group. They use existing workspace persistence; no new migration or data reset is required. Existing read-only workspace materialization remains non-persistent and now carries a valid policy digest.

Preparation transaction boundaries

CompanyOS preparation model calls now run outside workspace database transactions. Initial and final phases check current authority, explicit AI policy and context; source validation reuses the caller transaction and restores the OPA owner GUCs after the CI read. Finalization reloads the aggregate, preserves unrelated writes and commits drafts plus replay state atomically. Cached requests remain authorized and cannot change the requested artifact sequence.

Reviewed outcome generation uses its own draft generator inside the existing transcript-review and job-authority orchestration. It no longer requires unrelated graph-context projections. Source/member revocation and cancellation continue to fence outcome finalization. Model calls in these tests were controlled ports; live model quality and full load qualification remain open.

CompanyOS preparation generation now requires additive migration 0083 before deploying this runtime. SqlPreparationAdmissionStore admits one active model request per complete owner scope, using six-minute database-clock leases and at most five attempts per request. Immutable digests bind the request key to its exact input, context and policy; conflicting reuse fails. Concurrent requests receive the existing IDEMPOTENCY_IN_PROGRESS error and may retry the same key. Expired workers cannot commit artifacts or release a replacement worker's lease. Admission completion and artifact persistence share one transaction. Cached artifacts still require fresh authority and source checks. Crashes may repeat model cost after lease expiry; this does not establish global model quotas, background preparation qualification or live-provider acceptance.

GET /api/companyos/work/objects/:objectId reads a canonical UUIDv7 Work object under current server-derived workspace authority. The request accepts no scope parameters. Existing coherent canonical workspace mappings are read without allocation; conflicting mappings fail closed. The API uses the scoped, event-head-aware Work store and reproves read authority before returning. Responses are private/no-store, and absent, foreign or archived objects return not found. Native task-detail presentation is separate qualification work.

POST /api/companyos/work/objects/:objectId/status accepts only a canonical object ID, expected revision, status category and idempotency key. Current writable authority and actor/scope are derived server-side inside the transaction. The existing Work service commits status changes and three outbox destinations atomically. Completion uses server time; reopening clears completion time. Identical retries resolve the stored event before current-state validation. Native controls and live end-to-end qualification remain open.

Work task detail now exposes canonical status choices when the authenticated read projection supplies canUpdateStatus. Missing permission is read-only. Native updates bind the displayed revision and reuse the same request key for an uncertain retry of the same status. Verified event identity, next revision, status and original workspace scope are required before reloading the task. Session invalidation and blur abort the client request without claiming to undo a possible server commit. Signed-device completion/reopening acceptance remains open.

createCompanyBotWebhookIntake composes host-selected owner/deployment/secret resolution, bounded raw UTF-8 signature verification and atomic bound-bot settlement. It returns acceptance only after settlement commits and preserves replay acknowledgments. No public route is mounted by this helper: a durable route registry and domain lifecycle/outbox apply handler are mandatory before enabling bot callbacks. Payload tenant fields cannot select authority.

Bot webhook raw-body intake enforces a ten-second total read deadline in addition to the one-megabyte bound. Aborted, oversized and stalled streams are cancelled without awaiting their cancellation callback. Fatal UTF-8 decoding still preserves exact valid signed text across chunk boundaries. Timeout never acknowledges callback acceptance.

Bot reconciliation uses additive migration 0084 and a coalescing owner-scoped request row. Verified callback intake defaults to enqueueing reconciliation in its receipt transaction, rather than applying delayed provider state. Workers claim three-minute leases, one active per owner, with five failed attempts and a retry delay. New notifications during a lease remain queued after completion; expired/replaced workers cannot settle. More notifications cannot revive an exhausted job. The provider-fetch worker, repair UI and deployment dispatcher still require integration; do not activate callback routes before migration and host wiring.

Confirmed bot bindings may retain the existing capture authorization context inside their encrypted payload. CompanyOS guardCompanyBotCapture requires this context, the bot capture enable flag, current background membership/policy digests, the exact active bot capture, unexpired retention, consent and current meeting access. It reuses the existing background authority resolver rather than browser session state. Legacy bindings without context remain readable identity evidence but cannot execute background bot work. Concrete dispatcher/provider wiring and cleanup authority remain separate integration requirements.

createCompanyBotProviderRead supplies the reconciliation worker's concrete Attendee read adapter. It resolves configuration by the encrypted binding's deployment reference and checks lease, immutable bot identity and CompanyOS capture authority before secrets and again immediately before HTTP dispatch. Cancellation is forwarded and provider I/O remains outside SQL. Hosts must supply the deployment registry and queue/binding stores; no production dispatcher is enabled by importing the factory.

CompanyOS deployment resolution now permits existing-bot reads only for active or draining configurations. It captures the encrypted registry revision, lazily resolves the owner-scoped API secret, and rechecks configuration before secret access and again before HTTP dispatch. Disabling or rotating configuration invalidates pending reads. SqlBotDeploymentStore.readInTransaction reuses the effect-authority transaction without acquiring another connection. Administrative UI, concrete secret-store binding, bot starts, global scheduling and live provider qualification remain open.

Private meeting creation uses createCompanyPrivateMeetingAuthority for the existing individual owner scope, capability checks and transaction-bound membership reproof. Capture authority delegates the same checks and retains its additional consent/policy/source enforcement. The web private-meeting entry requires creation-context, creation, authorized workspace and artifact-list reads to be deployed together; creation alone does not provide recording or editable meeting notes.

Private meeting notes

CompanyOS exposes one private human-authored notes draft per meeting through additive opa.meeting_artifact.get_note and opa.meeting_artifact.save_note operations at GET/POST /api/v2/opa/smart-meetings/:meetingRef/notes. Existing meeting-work-session management permission authorizes this personal authoring surface; recording, transcript generation and model credentials are not prerequisites. Saves use expectedRevision (zero for creation), at most 100000 characters and a stable idempotency key. Notes remain live_notes/private_user/draft, persisted in the existing encrypted aggregate. Empty content clears the draft. Revision conflicts preserve the local draft and show the latest saved notes before an explicit choice to continue. Saving notes creates no Work task and sends no message.

The Work-to-OPA planning loader must assemble each task’s dependencies from the latest relationship state across all aggregates in the exact tenant/organization/workspace scope. Both outgoing blocked_by and incoming blocks edges are prerequisites under the existing Work projection contract. Filtering which tasks can be placed must not erase dependency edges from other Work aggregates. This is a loader correctness invariant; it does not activate the background outbox reoptimizer.

Work planning now uses loadSnapshot(scope) to obtain placement candidates and completedWork references from one scoped event replay. Completed prerequisites remain valid even without estimates or selection for personal placement. loadWork(scope) remains compatible for older callers. Reopening removes completion truth; no estimated duration is fabricated. Interactive proposal digests include completion revisions.

OPA direct workspace authority binds four contiguous SQL parameters; team authority binds five. An unused null parameter in the direct-grant query previously caused PostgreSQL 42P18 and made private meeting readiness unavailable. Current membership, workspace scope, grants and revocation checks remain mandatory. The regression executes the exact workspace query through the production PostgreSQL driver.

WorkProposalPersistence is a preparatory proposals-only publisher for future Work-outbox reoptimization. It uses existing personal plan ownership and canonical Work plan envelopes, requires transaction-local full-owner/lease/current-policy guards both before effects and before commit, and leaves placement/calendar tables untouched. Its guard bindings and dispatcher activation are still unimplemented; constructing the seam is not proof of active background planning.

Private meeting failure diagnostics record only the operation, processing stage, an allowlisted error class and a five-character SQLSTATE. Error messages, SQL text/parameters, note content and credentials are excluded. Disabled OPA workspace modules return the declared FORBIDDEN response rather than being disguised as service unavailability.

Capture processing must resolve meeting access using the same private-first rule as interactive capture: check the captured individual’s private meeting, then the currently authorized workspace/team meeting. Background company context must not make a private meeting disappear. Every fallback restores the complete capture owner scope and retains authority, consent, policy and lease checks.

Explicit regional processing endpoints

New AI/outcome configuration requires the exact Gateway origin with geography other, explicit eu provider inference and separate global-transit approval. The configured model/provider allowlist, no-training and retention restrictions remain mandatory. The host rechecks the binding before transport and accepts only matching EU response evidence. Capture transcription has no active default provider while EU speaker-labelled Gateway processing remains unqualified.

Historical endpoint-bound artifacts remain readable, including explicit Mistral EU/EFTA test fixtures. They do not activate a live provider, and no historical record or queued approval is rewritten. Storage placement and provider inference/transit are independent qualification requirements.

The CompanyOS calendar-intelligence host omits direct-Mistral credentials and model selection, even when the old environment variables remain present. It composes localized deterministic-v2 recaps/briefs and records deterministic fallback status. Calendar reads, booking maintenance and delivery authority are unchanged. Gateway is not wired into this calendar path yet; see docs/runbooks/companyos-briefings-v2.md.

Meeting AI through Vercel Gateway

New production meeting generation uses OPA_MEETING_AI_PROVIDER=vercel-ai-gateway with OPA_MEETING_AI_ENABLED=1, a pinned OPA_MEETING_AI_MODEL, exact OPA_MEETING_AI_ENDPOINT_ORIGIN=https://ai-gateway.vercel.sh, OPA_MEETING_AI_REGION=eu, OPA_MEETING_AI_PROCESSING_APPROVAL_REF, OPA_MEETING_AI_GATEWAY_TRANSIT_APPROVAL_REF, and one approved non-Mistral OPA_MEETING_AI_GATEWAY_PROVIDER. Credentials come from AI_GATEWAY_API_KEY or existing VERCEL_OIDC_TOKEN; no Mistral key/default fallback is read. Outcome jobs additionally require their existing enable switch. References must correspond to actual approved processing/transit decisions before activation.

Gateway transit is recorded as geography other, separately from EU inference. Exact binding checks run immediately before transport and after generation. Returned routing metadata must prove the served provider appears among the approved EU attempts; request flags alone are insufficient. Existing private/shared context filtering and cited outcome validation remain enforced.

Automatic capture transcription is temporarily unavailable: eu_transcription_not_qualified and speaker_labels_not_supported. Its binding returns typed null and its default worker rejects with CAPTURE_PROCESSING_UNAVAILABLE; legacy Mistral credentials/flags cannot reactivate it. Existing records and controlled test ports remain intact. Qualify actual Gateway speaker-labelled EU transcription before changing this boundary.

CompanyOS uses one processing-readiness predicate for the capture configuration view and new-session admission. New captures check readiness before insertion and before commit. Exact authorized create retries bypass new-session admission; existing media can still be uploaded and recovered under current consent, policy and source controls. An unavailable processor does not silently collect new recordings.

Gateway EU response evidence accepts both zone and specific endpoint scopes only when geoRegion is explicitly eu. A more specific EU endpoint is not a global fallback. Missing/global/non-EU evidence remains rejected; requested routing flags alone never prove the served geography. This does not grant private Gateway transit approval.

Work proposal publication v2 carries the exact outbox delivery attempt. Its default SQL lease guard locks the current leased Work record and checks destination, full event, owner, attempt and expiry using database time. It restores the prior tenant context on success or failure. Owner mapping and effective policy guards remain mandatory; the dispatcher is not activated by this binding. Existing valid replay does not write calendar placements or effects.

The shared OPA background authority resolver now supports planning.propose with the exact opa.plan_run.manage capability, alongside existing capture and intelligence actions. It uses current locked organization/workspace/team grants and module entitlement, independently of browser-session lifetime. It returns the resolved policy mode and digests; callers must separately enforce manual/approval/delegation semantics. The capture-named export remains a compatibility alias. No planner dispatcher is enabled by this extraction.

loadWorkProposalOwner resolves existing selected-workspace and personal-owner authority, locks the canonical Work mapping for the production user identity, and produces a combined authority digest plus both policy modes. It allocates no identities and grants no execution authority. All six SQL owner-context settings are restored, or rolled back with an aborted transaction. Work source/input revision proof and the policy-aware dispatcher still require composition.

Workspace revision fencing hashes every canonical Work aggregate head, including unplaced, completed and archived work. Work commits take a shared workspace advisory lock; proposal publication takes its exclusive counterpart and checks the complete digest before persistence. The interactive planner and internal background proposal publisher use this fence. Upgrade all Work writers before qualifying it; older writers that omit the shared lock are not covered. Calendar freshness and policy/approval checks remain independent.

Google free/busy snapshots now carry normalized query provenance. Cache reuse requires the same calendars, time window and timezone, and rejects future or unbound observations. CompanyOS preparation requires covered planning time plus a matching refresh snapshot digest, evaluated at current server time after refresh. Additive migration 0085 adds query_binding; apply it before deploying the new store/read paths. Historical rows remain readable without earning freshness, and older refreshes cannot overwrite newer observations. Calendar identifiers stay in the tenant-scoped server store.

Interactive Work proposals now retain opaque calendar snapshot/configuration evidence and reprove it in the publishing transaction before writes and again before return. Reproof locks current configuration and snapshot rows, rejects changed/disconnected/expired evidence, and restores the caller tenant setting. A workspace advisory lock also fences newly inserted preferences; both Google topology and event-preference writers participate. Upgrade these writers together before qualification. Provider calls remain outside this lock; no calendar effect is applied.

Planner topology selection distinguishes full scheduling preferences from event-calendar binding rows in the shared table. A newer binding without working hours cannot hide the workspace scheduling policy. A real PostgreSQL contention test verifies the actual event-preference writer waits for same-workspace publication while another workspace proceeds. Production rollout and broader load qualification remain separate.

createWorkSuggestionPolicyGuard fills the existing proposal policy-guard port for explicit suggestion workers. It resolves current owner/policy before inputs and again after input and lease reproof, then uses the shared automation gate. The required reproveInputs callback must validate current calendar-then-Work revision evidence and return the actual input digest inside the same transaction. Other modes require their own verified command/approval/delegation composition; this helper does not enable a worker.

Planner input now includes all active focus occupancy owned by the personal user, with buffer margins. Other-workspace titles/timezones are reduced to Busy/UTC before leaving SQL; another user's rows are excluded. A semantic focus digest ignores provider sync metadata and is checked under the existing focus-intent lock before calendar and Work publication locks. No new migration or lock-key protocol is introduced.

generatePersonalWorkProposal also returns its exact inputSnapshot for trusted internal workers; it is not added to HTTP responses. createWorkSuggestionInputRevalidator clones that input and proposal with owner, Work, focus and calendar evidence. It checks publication identity before SQL, then runs the concrete focus/calendar/Work checks in order, verifies current projected and completed Work revisions, and recomputes the private captured input digest. Use only trusted loader/optimizer output, not a client-supplied capture.

Planner reoptimization migration 0086 introduces one private owner/workspace queue entry for coalesced Work, calendar, focus, policy and recovery wakeups. Exact expiring claims fence atomic publication; resource guards precede queue row locks. Exhausted jobs require explicit current-authority reproof and a matching failed revision to repair. The adapter and local tests do not activate trigger fanout, a dispatcher, or production migrations.

Queue-origin planner publication uses the existing WorkProposalPersistence with native job/ref revision identity and explicit queue guards. createQueueSuggestionInputRevalidator shares the trusted focus/calendar/Work input proof without requiring a fabricated Work event. These internal adapters do not activate a worker.

Planner cron /api/cron/planning-suggestions is scheduled every ten minutes for service principals and is a no-op until OPA_REOPTIMIZATION_ENABLED=1 (the global kill switch; OPA_PLANNING_SUGGESTIONS_ENABLED is no longer read). Activation requires migrations 0086, 0087 and 0130, the normal LSSM_STUDIO_DATABASE_URL, and a distinct MANAGED_COMPANYOS_PLANNING_DISPATCH_DATABASE_URL authenticated exactly as companyos_planning_dispatcher (function execution only; provision its password through the secret manager). Each run first drains due wakeups reserved with FOR UPDATE SKIP LOCKED (batch 20), then re-plans one cursor page of owners whose last run is older than two hours, within a 120 s budget and a 45 s per-owner timeout. Work mutations, task status changes and focus block changes enqueue savepoint-isolated, debounced (30 s) wakeups in their own transaction. Background planning is admitted when "Plan work" is "Suggestions only" or higher and paused by "Manual only"/"Disabled"; preconditions such as a stale calendar defer without consuming attempts, failures back off exponentially and dead-letter after five attempts until PlanningReoptimizationJobs.repair. A refreshed proposal is published only when it differs from the current plan and carries content-free diff provenance (opa.plan.refreshed); placements are never applied in the background.

Notetaker bots (W5): opa.bot_capture.* routes under /api/v2/opa/bot-captures/** and /api/v2/opa/bot-capture-settings let a member send an Attendee notetaker bot to one Google Meet/Teams meeting after explicit recording consent and a confirmed participant notice (both recorded with the capture consent receipt in the append-only opa_bot_capture_events audit). Migration 0165 adds opa_bot_captures (encrypted meeting link, route digest, lease/attempt/dead-letter work queue), workspace settings and per-meeting switches. /api/cron/opa-bot-dispatch (start, observe, leave, import, provider cleanup, retention erasure) and /api/cron/opa-bot-reconciliation (webhook/observe wakeups over 0084) run every minute through MANAGED_COMPANYOS_BOT_DISPATCH_DATABASE_URL (exact companyos_bot_dispatcher). Callbacks arrive at /api/webhooks/opa-bots/:routeToken (route bound to one capture, signature verified). Global OPA_BOTS_ENABLED=1, workspace and meeting switches are rechecked before every provider call; switching off defers (global) or stops/leaves (workspace, meeting, lapsed consent). Recordings import into encrypted EU capture storage and finish into the EU transcription pipeline; without an EU speech model the EU-confirmed provider transcript (OPA_BOTS_PROVIDER_TRANSCRIPT_REGION=eu) or the recording alone is kept. Production stays off: see docs/evidence/opa/opa-bots-production-readiness-2026-10-19.md.

Work planning enrollment: the planner and the background re-planner address an owner only through a Work identity binding (managed_companyos_work_identity_bindings, one per tenant, organization, workspace and user). ensureWorkPlanningEnrollment creates it after rechecking membership, organization authority and an enabled direct or team grant on an active, non-personal workspace, serialized per tenant, idempotent, with one opa.work_planning.enabled audit event. It runs on company workspace selection (best effort), on first plan generation, and from POST /api/v2/opa/work-planning/enable (GET /api/v2/opa/work-planning reports the state and never allocates). Existing users are enrolled with bun run companyos:opa:backfill-work-planning (COMPANYOS_WORK_PLANNING_BACKFILL=dry-run, then =1; output is per-organization counts only; re-runs report bindings as existing). Recovery counts an owner whose grants no longer allow background planning as paused rather than failed.

Planner inputs optionally carry unscheduledWork for owner-selected pending items requiring an estimate. They retain Work revisions, appear as estimate_required, and never receive invented durations or placements. Existing callers default to an empty list.

Task split preferences use the existing scheduling proxy and opa.work_split_preference.get/save operations. Owner identity is server-derived; saves use revision CAS plus an idempotency receipt and enqueue replanning atomically. Apply migrations 0088/0089 and verify runtime grants before deploying this workflow. Absent/null preference remains unsplit, and saving never changes the Work estimate or applies calendar effects. Production acceptance remains pending.

Builder delivery authoring isolation

Every delivery route requires an authenticated tenant. The draft workspace uses a SHA-256 tenant namespace under WORKSPACE_ROOT/.contractspec/builder-delivery-tenants/. Body and query fields cannot select another tenant. Actor/operator references come from the authenticated principal; caller role descriptions confer no permissions. Missing-loop preflight returns 404. Shared legacy drafts are never read as a fallback: review ownership before explicitly adopting them into a tenant workspace. This filesystem composition remains single-writer authoring storage, not the production multi-tenant state service.

The authenticated CompanyOS session-authority response includes permissionRefs from the canonical server role-permission resolver after fresh organization authority is established. Clients must not infer permissions from grantRole themselves. Fleet read/manage keys are granted to the existing full-permission enterprise-admin role; narrower roles and runtime deployment authority are unchanged.

Public Builder requests require an authenticated tenant. Supplied tenant IDs must match that identity; missing tenant authority and mismatches fail before runtime execution. This boundary does not activate production deployment. Authorized Builder request execution binds the authenticated tenant and principal to the existing RLS pool context. That context is scoped to the async request and does not persist into later requests.

Member authoring uses fresh contextAuthority.effectiveCapabilities, not role names or machine capability inheritance. The route contract is src/handlers/builder/builder-member-policy.ts: creation needs builder.chat.web and builder.fusion.resolve; intent/read needs builder.chat.web; blueprint, plan, preview and readiness need their exact fusion/compile/generate/harness grants. Configure these through the existing organization/team/workspace authority store; no grants are installed automatically. Auditor and AI-operator mutations remain denied. Mutations require the exact APP_WEB_BASE_URL origin and the current session CSRF token. All member reads/writes check tenant, owner and original organization/team/ workspace scope. Legacy unbound workspaces need explicit adoption before member use. Creation IDs are derived from the member, scope and request ID; the original request ID can recover a lost response in the same context. Creation replay reads existing state instead of regenerating it. Member payloads cannot choose owners, providers, channels or authority. Execution/release endpoints remain outside this admission.

Vercel source uploads exclude TypeScript and JavaScript test entrypoints through root .vercelignore. In particular, api/index.test.js remains part of local QA and must not appear as a deployed serverless function alongside api/index.js.

Preview authentication

COMPANYOS_AUTH_PROFILE=preview-v1 selects the additive preview topology. Set COMPANYOS_PREVIEW_WEB_ORIGIN and COMPANYOS_PREVIEW_API_ORIGIN to exact HTTPS origins outside the production cookie domains. In the API, BETTER_AUTH_BASE_URL and APP_WEB_BASE_URL both equal the preview web origin because browser auth uses its same-origin proxy. Configure AUTH_PROVIDER_MODE=better-auth, a dedicated COMPANYOS_PREVIEW_AUTH_SECRET (at least 32 characters), and COMPANYOS_PREVIEW_DATABASE_URL. LSSM_STUDIO_DATABASE_URL must match that database; optional auth/channel database references must also match. Unset BETTER_AUTH_SECRET, BETTER_AUTH_COOKIE_DOMAIN and production federation flags. Production Vercel deployments cannot select this profile. Cookies use the companyos-preview prefix, no parent domain, and the preview web origin for passkeys.

Provision and verify dedicated data and credentials before enabling this profile. Matching configuration strings are not evidence of actual provider isolation. Database migrations, synthetic accounts, callback behavior, session revocation, tenant checks and deployed browser sign-in still require qualification.

Better Auth account identity requires issuer plus account_id. Apply tracked migration 0090 before deploying the updated Drizzle account schema. It preserves password hashes and normalizes password-bearing credential rows to local:credential plus user_id; ambiguous duplicates abort atomically. It does not guess OAuth issuers. Existing external accounts with a null issuer require provider-specific reconciliation and login qualification before production promotion. Newly created accounts receive the issuer from Better Auth itself.

Standalone container hosting

After build:elysia, start:elysia runs server.mjs, binds HTTP on PORT (default 3000), and handles SIGTERM/SIGINT through the app lifecycle with a bounded shutdown deadline. The Vercel adapter still imports the same application bundle. Build the package Dockerfile from the repository root. Its pinned Node/Bun build stages produce a non-root Bun runtime containing only the built API, packaged Loro runtime and standalone entrypoint. Use the root route as a process-start probe; database, identity and application-journey readiness require separate checks. In preview mode, login discovery omits email-delivery methods when Resend is not configured; password login remains available for provisioned synthetic accounts.

The standalone Bun launcher emits fixed startup phases: loading, loaded and listening. Import failure and a 90-second import deadline fail startup without logging credentials or exception payloads. These markers diagnose startup; only the listening application answers health checks.

Builder company context

builder.companyContext.resolve and POST /api/companyos/builder/context/resolve accept an owned Builder workspace and a question up to 4096 UTF-8 bytes. The shared member surface invokes this query through the authenticated web BFF. Missing configuration returns 503; query failures are never retried as saved mutations.

The host binds the persisted Builder workspace to its verified actor and selected company context. Current Company Intelligence Brain authorization and field projection select approved, fresh, visible entries. Contradictory sources refuse retrieval. Canonical source/version/asset/part/fragment/evidence records are checked for tenant, ACL, validity, deletion and supersession, then re-read after storage IO. Point reads filter object identity before pagination. Verified citations retain source, redaction and replay references even when the question paraphrases them. Knowledge supplies context; existing release and execution permissions still apply.

Shared server startup

Both standalone Bun and serverless requests use getBuilderRuntimeResources. Its first initialization reads the optional server-only BUILDER_GROUNDING_CONFIGURATION JSON through the versioned BuilderGroundingStartupManifestSchema. Unconfigured, malformed, expired or missing-secret profiles leave authoring available and grounding unavailable. getBuilderGroundingStartupState reports a static configuration state without secret details. A configured state is not a live qualification result.

The manifest names explicit models, independent contexts, allowed tenant/workspace pairs, a request limit per minute, review/retrieval/code references and approved source objects/excerpts. It uses the existing AI provider factory and SecretProviderManager with environment-backed references:

• env://BUILDER_GROUNDING_MODEL_SECRET may serve both model roles.
• env://BUILDER_GROUNDING_DRAFTER_SECRET and env://BUILDER_GROUNDING_VERIFIER_SECRET allow separate accounts.
• env://BUILDER_GROUNDING_STORAGE_SECRET contains the existing S3 connection fields: accessKeyId, secretAccessKey, HTTPS endpoint, region, bucketName and urlStyle. Keep credentials in deployment secrets, outside the manifest.

OpenAI, Anthropic, Mistral and Gemini use explicit model IDs through the canonical factory. The same vendor/account can serve both roles when model identity and independence domain differ. Separate role clients receive independent prompts and contexts. Models get no tools, automatic retries are disabled, and canonical claim/citation verification remains mandatory.

Each source approval binds an opaque storage reference to an exact S3 bucket/key, byte cap, SHA-256 and optional object version. Each reviewed excerpt additionally binds its evidence ID, content SHA-256 and redaction decision. Only matching canonical text/plain line excerpts enter a model. Asset reads are bounded to 1 MiB and excerpts to 16 KiB. PDF/media extraction requires another qualified profile. Storage cancellation bounds waits and requests stream teardown; it does not independently establish that remote IO stopped.

The profile scope intersects existing Brain authority. It does not grant an operations manager administrative content access. Eligible model requests consume the existing tenant/principal Company Intelligence request quota first; unavailable quota persistence fails closed. The runtime needs source/Brain SELECT permission and the existing managed_companyos_ci_api_budgets SELECT/INSERT/UPDATE path under FORCE RLS. Source provisioning remains an operator-owned canonical repository operation. Request quotas do not replace monetary reservation/reconciliation.

Configuration and clients are reused across warm requests. Deploy/restart after changing a manifest or environment-backed secret. Trusted tests or explicit host compositions can still use configureBuilderRuntimeGrounding before the first initialization; rebinding an active singleton is refused.

Qualification status

Actual Railway S3 and constrained PostgreSQL qualification verified six canonical records and the exact 176-byte synthetic source, including replay with zero new effects and cross-tenant denial. The complete SQL-to-answer composition is tested with mock model/storage ports. Live model connections, cancellation, redaction, spend reservation and full member journeys require separate qualification before production acceptance. No member Brain grant or model call is implied by the source-read proof.

Critical production schema build gate

The Vercel production build first runs scripts/critical-schema-preflight.ts. It requires account.issuer (text) on the resolved authentication database and opa_google_availability_snapshots.query_binding and managed_companyos_personal_briefing_deliveries.generation_provenance (jsonb) on the runtime database. The probe uses a read-only PostgreSQL session, metadata inspection and zero-row SELECTs, with five-second connection, ten-second statement and five-second close bounds. Missing configuration, incompatible columns or unavailable read access fail the build; previews explicitly skip without qualification. Credentials and SQL error details are never printed. The gate never migrates or reads customer rows. Use the existing authorized migration workflow to repair prerequisites.

This proves only these columns and read access, not account reconciliation, all migrations, booking journeys or full readiness. The snapshot column is derived from current source requirements, not a confirmed diagnosis of the particular column behind the observed production SQLSTATE 42703. This app-owned deployment contract is not an operation spec; no CLI operation-validation success is claimed.

Planner rollout preflight v1.1 rejects missing or duplicate required catalog entries and checks physical topology_version, workspace_id and query_binding columns, including migration 0091 prerequisites. Failures remain content-free. It is read-only: it does not apply migrations, repair schema, or prove provider execution and full workflow readiness.

Calendar briefing model provenance

Apply migration 0092 before deploying the briefing store: finish writes nullable generation_provenance JSONB even for deterministic drafts. Legacy receipts remain unqualified with null provenance. CompanyOS keeps direct Mistral disabled. Gateway generation additionally requires the private-processing admission adapter described in "AI-written, cited briefings (OPA)" above; without it the labelled template is sent. Accepted generation requires supplied citation validation, explicit served EU/provider evidence, stop completion, text-only output and post-generation admission recheck. Prompt size is bounded to 80000 serialized characters. Neither environment configuration nor a briefing delivery toggle grants private-processing authority. No live activation is established by this slice.

AI-written, cited briefings (OPA)

Morning recaps, meeting preparation, preview e-mails and private drafts share one generator (src/calendar/opa-ai-briefing-*). A briefing is written through the Vercel AI Gateway only when the private-processing admission adapter admits the owner. Otherwise the deterministic template is sent and labelled ("Standard template — <reason>"). Admission requires, in order:

1. OPA_AI_BRIEFINGS_ENABLED=1;
2. the approval references OPA_AI_BRIEFINGS_PROCESSING_APPROVAL_REF and OPA_AI_BRIEFINGS_GATEWAY_TRANSIT_APPROVAL_REF, and a Gateway credential resolved per request by @lssm-tech/lib.ai-providers/vercel-gateway-auth: AI_GATEWAY_API_KEY, else on Vercel the invocation's x-vercel-oidc-token header (pinned to VERCEL_PROJECT_ID when exposed), else VERCEL_OIDC_TOKEN. Cron, preview, settings and draft routes pass their request, so scheduled runs on Vercel Functions authenticate too;
3. the owner's explicit opt-in (Settings → Personal briefings → AI briefings). It is stored in the owner-only consent record and bound to a digest of the processing policy (catalog, EU routing, zero retention, no training, sent fields, approvals). A policy change makes the consent stale and asks the owner again;
4. an organization automation policy that does not disable intelligence.generate, plus the opa.meeting_outcome.analyze capability;
5. a model from the shared catalog @lssm-tech/lib.provider-spec/gateway-model-catalog.

Model precedence: owner override → workspace default → OPA_AI_DEFAULT_MODEL → catalog default. Organization owners and admins with the enterprise-admin grant set the workspace default (migration 0125, opa_ai_briefing_workspace_models). Before 0125 is applied the workspace default reads as empty and cannot be changed; everything else works.

Only event titles, times, attendee display names and agendas are sent. E-mail fallbacks for attendees are reduced to their local part, and links, e-mail addresses and phone numbers are removed from agendas. Company knowledge is added only when the owner selects it. Every claim must cite a supplied source: unknown citations are removed, uncited claims are dropped, and output without a cited summary falls back to the template. Admission is re-proved before and after each call, and the served route must prove EU inference.

AI briefings record provenance 1.1.0 in generation_provenance: model, prompt version, sources digest, generation time, model source and citation count. Settings changes append companyos.calendar_intelligence.ai_briefings.settings_changed to managed_companyos_audit_events. Endpoints: GET|POST /api/companyos/opa/briefings/ai-settings (owner) and GET|POST /api/companyos/opa/briefings/ai-settings/workspace (administrators). GET /api/companyos/health/degraded reports the secret-free opaAiBriefings status (enabled, disabled_flag, missing_approval, no_gateway_auth); it never degrades overall health.

Meeting context sources (OPA preparation and AI briefings)

src/organization-planning/meeting-context/ binds one aggregate knowledge source, knowledge:companyos-meeting-context, into meeting preparation (next to the Work Graph source) and into AI briefings. On every load it re-reads the owner's source choices (stored with the AI processing consent; revoked consent enables nothing) and runs each enabled adapter inside a MeetingContextSourceBudget (items, bytes, time, 15-minute TTL snapshot cache so generation reproofs see the same context). A failing or slow adapter adds nothing and logs opa_meeting_context.source_collected with a stable code; no provider id, e-mail address or message body is logged.

OPA_MEETING_CONTEXT_SOURCES (comma list: communication-history, participants, drive, notion, slack, hubspot) decides which kinds the deployment offers; unset offers none, so deploying changes nothing. Grants use accountRef = individual:<authority segment of the user id> in the physical tenant. Token refresh uses GOOGLE_DRIVE_OAUTH_CLIENT_ID/SECRET (Drive's own Google client; refused when it equals the calendar client, because Google revocation drops every scope a user granted one client) and HUBSPOT_OAUTH_CLIENT_ID/SECRET.

Meeting context connections (OAuth connect flows)

meeting-context/oauth-connect-routes.ts implements OPA_MEETING_CONTEXT_CONNECTIONS_CONTRACT (organization-planning spec) for the owner's personal grants. The routes are composed into the personal-briefings plugin, so the web BFF reaches them under /api/companyos/opa-os/briefings/meeting-context/*:

Providers and consent scopes: google-drive (drive.metadata.readonly, PKCE, offline access; client GOOGLE_DRIVE_OAUTH_CLIENT_ID/SECRET, never the calendar one), notion (owner=user; NOTION_OAUTH_CLIENT_ID/SECRET), slack (user scope search:read, token rotation off; SLACK_OAUTH_CLIENT_ID/SECRET) and hubspot (oauth crm.objects.contacts.read; HUBSPOT_OAUTH_CLIENT_ID/SECRET). The provider redirect URI is the API callback, ${BETTER_AUTH_BASE_URL}/api/companyos/opa/briefings/meeting-context/<provider>/callback (default origin https://api.companyos.run), and must be registered with each provider app. A provider shows "Connect" only once the operator lists it in OPA_MEETING_CONTEXT_CONNECT_SOURCES (drive, notion, slack, hubspot) after registering that redirect URI and scopes, so a client already set for refresh never sends owners to an unprepared consent page.

The OAuth state is sealed with the BYOK cipher under the owner's personal tenant key and names the provider, user, a session digest, the PKCE verifier and a ten-minute expiry. The single live attempt per owner and provider is recorded in opa_oauth_tokens (provider meeting-context-oauth-state:<provider>) and consumed under a row lock before the code exchange, so a replayed, parallel or superseded callback fails without a provider call. The row holds only the nonce digest; one inert row per owner and provider remains until the personal context is deleted. A grant missing the source's required scope, or one the vault fails to store, is revoked and not stored. Grants are stored under the reader key above. Disconnect asks the provider to revoke (Google, Slack, HubSpot; Notion has no revocation endpoint, so the owner removes the integration in Notion), then overwrites the row with an inert token: opa_app has no DELETE policy on opa_oauth_tokens, so the delete only succeeds for a role that may delete.

Connecting never enables a source. List a kind in OPA_MEETING_CONTEXT_SOURCES only after its connect flow passed an end-to-end canary on the deployment.

The PGlite suites (*.pglite.test.ts in meeting-context/) run against a disposable local PostgreSQL instead when OPA_MEETING_CONTEXT_TEST_DATABASE_URL names a local server (each file creates and drops its own database).

Vercel delegates API production builds to scripts/vercel-build.ts, keeping the configured command below the platform limit. The orchestrator runs the critical-schema gate before crypto utilities, LSSM OS contracts and API compilation, and stops on the first failure.

Runtime schema diagnostics distinguish absent columns from incompatible types, inspect role attributes and the planning migration ledger, and optionally compare the expected Supabase project/database. Only status and coarse classifications are returned; the script does not print connection details, read customer rows, migrate or grant authority.

Builder candidate routes

POST /api/companyos/builder/plans/{prepare,approve,execute,status} uses the existing member/session/CSRF admission and Builder capabilities. Prepare/status require builder.plan.compile; approve/execute require builder.plan.execute. The server resolves identity and workspace scope, strips caller authority, and forwards only reviewed plan reference and request identity to the runtime. Returned available actions are intersected with current actor capabilities. Configure the concrete BuilderCandidateService through trusted runtime composition; no default approval, order issuance or successful execution exists.

Private briefing consent and non-delivering draft previews require migrations 0093/0094. Explicit consent binds model and source scope; signed one-use human-command receipts bind current policy and inputs. Failed generation does not silently rerun under the same command. Concurrent revocation can wait behind active shared locks, and new-table retention/deletion integration remains incomplete; these routes are not production-qualified. Microsoft identity and isolated OAuth storage require 0095/0096, with legacy Microsoft state/credential reconciliation before cutover.

Local/test reset now removes private draft command receipts, processing consents and Microsoft identity/OAuth state before personal context rows. This prevents stale authority surviving a test reset; it does not implement production erasure or retention, which remain separate outstanding workflows.

The new Microsoft-only vault uses encryption domain v2, binding tenant, workspace, user, provider purpose and account reference. Ciphertext copied between accounts or OAuth/PKCE purposes fails authentication. It does not accept the earlier unactivated owner-only domain; any pilot rows written with that draft implementation require controlled reauthorization rather than silent decryption fallback. This does not change the shared Google vault.

Microsoft vault envelope v3 supersedes the local v2 draft and additionally authenticates scopes/expiry. Reads reject metadata mismatches; no old envelope is silently accepted. No production vault migration or Microsoft activation is claimed.

Private briefing handlers use the existing streaming bounded JSON reader: draft input is capped at 4096 bytes and processing consent at 64000 bytes. Oversized bodies return 413 after authentication/origin checks and before service execution; malformed/non-object JSON returns 422.

Local Builder installation

From this package, enroll a private local owner once:

bun scripts/install-local-builder-owner.ts /absolute/local/auth http://127.0.0.1:43119 local-tenant local-workspace 'Local Builder'
bun scripts/serve-local-builder.ts /absolute/local/auth /absolute/local/authoring

Enrollment writes a private owner profile and prints only its path. Do not expose or commit that file. The launch command binds the configured loopback origin and exposes no public signup or organization administration. Pair through POST /local/auth/pair with the configured Origin and the local pairing credential as Bearer authentication; the result sets an HttpOnly session cookie. Subsequent Builder mutations require that cookie, the exact Origin and x-csrf-token equal to the session ID returned by GET /local/auth/session.

The shipped launch command enables durable authoring only. It does not configure candidate execution. Programmatic createLocalBuilderApplication may receive a qualified candidate service composed by createBuilderCandidateLocalHost; all project, topology, worker, policy, signing and recovery evidence must be supplied explicitly. Grant removal is reread for every session check; new grants cannot broaden an already-running local authority. Sign-out revokes the current session.

Close drains in-flight work before database shutdown. An unconfirmed drain retains storage ownership for reconciliation. This local API increment does not claim a complete console UI, live generated candidate, hosted preview or release workflow.

verifyEncryptedBackup authenticates the complete encrypted backup stream, validates manifest sizes/hash and computes a plaintext digest without returning or writing plaintext. It retains restoreVerified:false: cryptographic integrity is not a PostgreSQL restore rehearsal, independent key custody or PITR qualification.

Submit an outcome to the running local authoring API without manually copying cookies or session IDs:

bun scripts/local-builder-intent.ts /absolute/local/auth 'Create an accessible project checklist'

The command reads the private local profile, pairs through AuthOS, submits the intent with session/CSRF binding, and signs out its temporary session. Output contains only the workspace identity and acceptance status. It does not execute a candidate, call a model, or ship a release.

Personal Microsoft calendar OAuth

Personal connection contracts expose POST /api/v2/opa/personal-calendar/microsoft/authorize and GET /api/v2/opa/personal-calendar/microsoft/callback. Ownership comes from the authenticated personal context. PKCE state and encrypted credentials use the Microsoft-only owner-scoped storage; callbacks pin verified Microsoft identity. These operations do not yet provide calendar discovery or qualify booking/planning integration. Production activation requires configured Microsoft credentials/callback, migrations and least-privilege grants, followed by real account acceptance.

GET /api/v2/opa/personal-calendar/microsoft/calendars enumerates the current personal connection through the verified account runtime. Its response is bounded and excludes raw provider identifiers and credentials. Calendar selection and planner activation remain separate steps.

Graph scopes (least privilege). The app requests exactly offline_access (refresh), User.Read (GET /me id pinned before credentials persist) and Calendars.Read (calendar list and calendarView reads). CompanyOS writes nothing to Microsoft calendars (focus blocks and bookings go to Google only), so Calendars.ReadWrite is no longer requested; grants consented earlier with it stay valid. The Entra app registration only needs these delegated permissions; a future Microsoft write effect needs a reviewed scope change and owner re-consent.

Reauthorization. A refresh refused by the Microsoft identity platform (invalid_grant — expired/revoked refresh token, revoked consent —, interaction_required/consent_required/login_required, or any other 400/401 except invalid_client/unauthorized_client) moves the personal opa_calendar_connections row from connected to reauthorization_required and enqueues one opa.calendar.reauthorization_required outbox alert (providerKind: microsoft), in a fresh transaction after the failed read rolled back. The maintenance cron relays it as one en/fr/es email to the owner, linking /companyos/opa-os/settings. Discovery, selection save and briefing reads then answer 409 CALENDAR_REAUTHORIZATION_REQUIRED without calling Microsoft until the owner reconnects; a successful OAuth callback restores connected. 429/5xx/temporarily_unavailable/timeouts are transient (503 MICROSOFT_CALENDAR_UNAVAILABLE, Retry-After when Microsoft sent one) and never change state; invalid_client is logged as microsoft_calendar_connection.client_rejected (operator fault). GET /api/v2/opa/personal-calendar/microsoft/health returns { reauthorizationRequired, checkedAt } from stored state only; the web shell uses it for the reconnect banner on every OPA page. Recorded-shape fixtures for these responses live in packages/integrations/provider-calendar/test/fixtures/microsoft/.

Published profile handle reservations

Apply migration 0097 before deploying profile draft-renaming changes. It permits separate live and draft reservations while retaining global handle uniqueness. Backfill aborts on conflicting historical claims; operators must reconcile those claims without stealing another profile’s handle. Publication releases the previous reservation in the same transaction as its public-pointer update.

Native scheduling authorization

Personal scheduling mutations accept verified native bearer sessions without an Origin header. Invalid bearer credentials never borrow a browser cookie session. Cookie-authenticated browser requests retain exact-origin validation. Domain session, membership and policy checks remain required; transport authentication alone grants no scheduling effect.

Build compute policy

Automatic Vercel Git builds are disabled for this app. Build compute is assigned to Railway; this does not change the existing runtime or domain topology. See the operator policy and evidence^† for configuration scope and the unqualified Vercel prebuilt delivery gap.