# @lssm-tech/app.api-application-monolith

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `12.0.1`
- Package path: `packages/apps/api-application-monolith`
- Manifest path: `packages/apps/api-application-monolith/package.json`
- Manifest Git blob: `df905c0adceab76e4a35d3900e8a2ab2506dbe7a`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.api-application-monolith](https://lssm.co/docs/packages/app.api-application-monolith/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.api-application-monolith.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "app-composition",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Application composition and product hosts](https://lssm.co/docs/areas/app-composition/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/api-application-monolith/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/README.md",
  "blobSha": "cd4ffe2f02f51708515028a093780144806b7e34",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# 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](https://lssm.co/docs/packages/app.api-application-monolith/#readme-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`](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/docs/company-intelligence-persistence-runbook.md)
for resumable backfill, corruption checks, forward repair, and purge controls.
Use
[`docs/company-intelligence-operations-runbook.md`](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/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 (evidence [source link unresolved: `../../../docs/evidence/authos/decommission-hirly-ndconsulting-2026-10-20.md`]); 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.

Apply `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` [source link unresolved: `../../../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
(evidence [source link unresolved: `../../../docs/evidence/authos/decommission-hirly-ndconsulting-2026-10-20.md`]). 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` [source link unresolved: `../../../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.

| Purpose | Route |
| --- | --- |
| Graph/status snapshot | `GET /api/companyos/vercel/snapshot` |
| Replay/evidence snapshot | `GET /api/companyos/vercel/replay-evidence` |
| Supervision-equivalent snapshot | `GET /api/companyos/vercel/supervision` |
| Manual integration sync trigger | `POST /api/companyos/integrations/sync-trigger` |
| Scheduled snapshot trigger | `GET /api/cron/companyos-snapshot` |
| Profile cache invalidation dispatch | `GET /api/cron/profile-cache-invalidation` |
| Design-partner evidence relay | `GET /api/cron/companyos-design-partner-evidence-relay` |

`/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:

| Field | Value |
| --- | --- |
| Tenant ID | `tenant_ndconsulting_design_partner_demo` |
| Workspace ID | `workspace_ndconsulting_desliance_demo` |
| Scenario ID | `scenario_atlantique_industrie_mission_retournement` |
| Scenario title | `Atlantique Industrie — mission retournement` |

Routes:

| Method | Path | Role gate |
| --- | --- | --- |
| `GET` | `/api/companyos/special-ops/design-partner-readiness` | Read roles: founder, operations, expert, auditor, AI, frontline, enterprise admin; all remain tenant/workspace/feature scoped. |
| `POST` | `/api/companyos/special-ops/design-partner-readiness/decision-packets/:packetId/attest` | `expert_reviewer` only; requires packet version, statement, and idempotency key; returns the durable receipt. |
| `POST` | `/api/companyos/special-ops/design-partner-readiness/decision-packets/:packetId/founder-approval` | `founder_approver` only; requires an accepted expert attestation on the exact version; `enterprise_admin` is denied as a founder substitute. |

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

Use `docs/runbooks/special-ops-monolith-production.md` [source link unresolved: `../../../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.

| Prerequisite | Status | Detail |
|---|---|---|
| **JWT/session middleware for tenant identity** | ✅ **IMPLEMENTED** | All routes now derive `requestTenantId` from a verified HMAC-HS256 session token (`x-managed-companyos-session` header) via `src/middleware/session.ts`. Invalid or tampered tokens return 401. Set `MANAGED_COMPANYOS_SESSION_SECRET` to a strong secret before admitting real-tenant data. |
| **Persistent storage adapter** | ✅ **IMPLEMENTED FOR MANAGED COMPANYOS TABLES** | App-owned Drizzle/local lifecycle paths use canonical `managed_companyos_*` tables for tenant, session, invitation, passkey, lockout, audit, replay/evidence, capability, and mutation-ledger state. External production DB access remains URL-gated; live credentials are not committed. |
| **Production queue** | Approval-gated | Background job logic is in-process. A durable queue must be approved and wired before live workloads. |
| **Provider strategy** | ✅ **IMPLEMENTED APP-LAYER REFERENCE CATALOG** | `src/production/providers.ts` exposes an executable provider-neutral catalog and dispatch adapter for managed-reference and BYOK-reference modes. The wider provider family matrix remains a readiness/runbook contract until each family has app/provider-layer smoke evidence. Dispatch accepts env-backed redacted reference aliases only and fails closed before the harness when refs are missing, raw-looking, or not redacted. |

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` [source link unresolved: `../../../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

```bash
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 (evidence [source link unresolved: `../../../docs/evidence/authos/decommission-hirly-ndconsulting-2026-10-20.md`]).
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:

```bash
# 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

Copy `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.

| Variable | Purpose |
| --- | --- |
| `MANAGED_COMPANYOS_STATE_FILE` | Local/VPS preview only. Do not configure on Vercel; production state uses PostgreSQL. |
| `CRON_SECRET` | Bearer secret used by Vercel Cron service-principal authorization. Required for scheduled snapshot, waitlist purge, channel dispatch, and connect-review sweep crons. |
| `MANAGED_COMPANYOS_SESSION_SECRET` | **Required in production.** HMAC-HS256 signing secret for `x-managed-companyos-session` tokens. Must be a strong random value (≥32 bytes). Never commit to source control. |
| `MANAGED_COMPANYOS_CONTEXT_AUTH_SECRET` | **Required for profile editing in production.** Distinct server-only HMAC key (≥32 bytes) that verifies web profile-context assertions. |
| `MANAGED_COMPANYOS_DEFAULT_TENANT_ID` | Local/CI fixture fallback only. Leave empty in production; browser, query, and body tenant identifiers never authorize access. |
| `MANAGED_COMPANYOS_ORG_AUTHORITY_CUTOVER` | Production authority selector. `1` requires verified organization membership, binding, grant, and organization-owned workspace scope. |
| `MANAGED_COMPANYOS_PILOT_TENANT_ID` / `MANAGED_COMPANYOS_PILOT_WORKSPACE_ID` / `MANAGED_COMPANYOS_PILOT_SCENARIO_ID` | Exact legacy ND admission inputs during shadow/pre-cutover and for a rehearsed rollback build that requires cutover `0`; excluded from auth readiness and never forward authority. |
| `MANAGED_COMPANYOS_REMOTE_CONFIG_URL` | **Required.** Signed tenant remote-config manifest URL for feature flags, runtime endpoints, and kill switches. Use `https://…` in deployment or `managed-companyos://fixture/<tenant>` in deterministic tests. |
| `MANAGED_COMPANYOS_REMOTE_CONFIG_SIGNING_KEY_REF` | **Required.** Redacted key reference for remote-config manifest verification. Never commit raw signing material. |
| `MANAGED_COMPANYOS_PROVIDER_APPROVAL_REQUIRED` | Must remain `true` until explicit provider approval exists. |
| `LSSM_STUDIO_DATABASE_URL` | Shared managed CompanyOS PostgreSQL database used by the API and profile SEO. SEO assumes transaction-local NOINHERIT reader/builder roles; it does not require additional database URLs. |
| `MANAGED_COMPANYOS_AUTH_DATABASE_URL` | Auth DB URL. May intentionally match `LSSM_STUDIO_DATABASE_URL` only for the approved all-env migrate rollout; prefer split credentials later. |
| `LSSM_IDP_ENABLED` | Set to `1` only in the reviewed `id.lssm.co` deployment; omit elsewhere. |
| `LSSM_IDP_SECURITY_REVIEW_REF` | Opaque approved security-review evidence reference required by the central identity profile. |
| `LSSM_IDP_PAIRWISE_SECRET` | Secret-manager value of at least 32 characters used to derive pairwise relying-party subjects; never expose it to clients or logs. |
| `LSSM_IDP_VALID_AUDIENCES` | Comma-separated exact HTTPS relying-party audience origins. Wildcards and an empty audience set fail closed. |
| `LSSM_IDP_RP_RECONCILE_TOKEN` | Temporary 32+ character operator bearer for `POST /internal/authos/relying-parties/reconcile`. Configure only during a controlled client create/rotation ceremony, then remove and redeploy. |
| `{HCIRCLE,PACTENA}_LSSM_RP_ENABLED` / `{HCIRCLE,PACTENA}_LSSM_RP_SECURITY_REVIEW_REF` / `{HCIRCLE,PACTENA}_LSSM_RP_CLIENT_SECRET` | Central IdP reconciliation inputs for the matching catalog client. Secrets are read only from the identity host environment and never accepted in the request. Remove the central client secret after the database reconciliation receipt is verified; the product API retains its matching runtime secret. |
| `LSSM_IDP_LSSM_OS_RP_*` / `LSSM_OS_RP_*` | The `LSSM_IDP_` names are temporary central reconciliation bindings for the dedicated LSSM OS client; the unprefixed names belong only to the product runtime. Legacy central use of the unprefixed names remains compatible, but new ceremonies must use the explicit prefix so central readiness cannot confuse registration with product activation. |
| `LSSM_GOVERNED_DATA_DATABASE_URL` | Central identity only: least-privilege forced-RLS runtime connection for governed projection grants, leased deliveries, rights jobs, revocation events, and acknowledgements. Run additive migrations separately; never supply a migrator/admin URL. The recovery console requires a fresh central `admin` session with verified MFA. |
| `LSSM_GOVERNED_{HCIRCLE,PACTENA,COMPANYOS,LSSM_OS}_CATALOG_TOKEN` | Central identity only: distinct 32+ character product-service bearer for immutable projection and localized sharing-offer publication. Never reuse recovery, provisioning, or cron credentials. |
| `LSSM_GOVERNED_{HCIRCLE,PACTENA,COMPANYOS,LSSM_OS,PERSONAL_OS}_RECOVERY_ORIGIN` | Central identity worker: exact HTTPS origin for a qualified product recovery ingress. Omit unqualified products. |
| `LSSM_GOVERNED_{HCIRCLE,PACTENA,COMPANYOS,LSSM_OS,PERSONAL_OS}_RECOVERY_TOKEN` | Central identity worker: distinct 32+ character server-only bearer for the matching product. Never expose to web clients or reuse `CRON_SECRET`. |
| `COMPANYOS_GOVERNED_DATA_DATABASE_URL` / `LSSM_OS_GOVERNED_DATA_DATABASE_URL` | Matching product API only: separate product-local forced-RLS encrypted-copy database. Never use the central grant database or a migrator connection at runtime. |
| `COMPANYOS_GOVERNED_RECOVERY_TOKEN` / `LSSM_OS_GOVERNED_RECOVERY_TOKEN` | Matching product API only: distinct 32+ character recovery bearer. Database plus recovery bearer may be configured without enabling new materialization. |
| `COMPANYOS_GOVERNED_DATA_REGION` / `LSSM_OS_GOVERNED_DATA_REGION` | Exact receiving-product residency region. Must be configured together with the matching materialization binding registry or startup fails closed. |
| `COMPANYOS_GOVERNED_MATERIALIZATION_BINDINGS` / `LSSM_OS_GOVERNED_MATERIALIZATION_BINDINGS` | Secret-manager JSON array of exact `sourceApplicationId` and distinct 32+ character `bearerToken` pairs. Enables only `POST /internal/governed-data/materializations/:sourceApplicationId`; unknown/duplicate sources fail closed. Never use one ecosystem-wide token. |
| `COMPANYOS_GOVERNED_DATA_AUTO_MIGRATE` / `LSSM_OS_GOVERNED_DATA_AUTO_MIGRATE` | Controlled activation only. Runtime defaults to no migration; apply additive schema with an approved migration owner first. |
| `COMPANYOS_GOVERNED_DATA_SSL_MODE` / `LSSM_OS_GOVERNED_DATA_SSL_MODE` | `require` by default; `allow` or `prefer` only for a qualified local target. |
| `LSSM_OS_RP_ENABLED` | Set to `1` only in the reviewed, dedicated `api.os.lssm.tech` deployment; it cannot share the CompanyOS RP deployment. |
| `LSSM_OS_RP_SECURITY_REVIEW_REF` | Opaque approved security-review evidence required before the LSSM OS client or origins are exposed. |
| `LSSM_OS_RP_CLIENT_SECRET` | Secret-manager value of at least 32 characters for `lssm-os-web`; never expose it as `NEXT_PUBLIC_*`. |
| `LSSM_OS_MEMBERSHIP_PROVISION_TOKEN` | Dedicated 32+ character server-only token for idempotent central AuthOS → LSSM OS local membership provisioning. |
| `LSSM_OS_MEMBERSHIP_PROVISION_URL` / `LSSM_OS_MEMBERSHIP_PROVISION_TOKEN` | Exact HTTPS LSSM OS receiver and matching central caller token. The receiver URL is `/internal/authos/product-memberships`; no query, fragment, or embedded credentials are accepted. |
| `HCIRCLE_MEMBERSHIP_PROVISION_URL` / `HCIRCLE_MEMBERSHIP_PROVISION_TOKEN` | Exact HTTPS hCircle receiver and its independent 32+ character central caller token. |
| `PACTENA_MEMBERSHIP_PROVISION_URL` / `PACTENA_MEMBERSHIP_PROVISION_TOKEN` | Exact HTTPS Pactena receiver and its independent 32+ character central caller token. |
| `MANAGED_COMPANYOS_WAITLIST_DATABASE_URL` | Optional public waitlist writer URL. Must be separate and low-privilege; omit unless that credential exists. |
| `MANAGED_COMPANYOS_BOOKING_GRANT_PEPPER` | **Required for the Postgres-backed booking provider-effect host.** Distinct server-only random pepper (≥32 bytes). |
| `MANAGED_COMPANYOS_GOOGLE_CALENDAR_CLIENT_ID` / `MANAGED_COMPANYOS_GOOGLE_CALENDAR_CLIENT_SECRET` / `MANAGED_COMPANYOS_GOOGLE_CALENDAR_REDIRECT_URI` | Dedicated Google Workspace Calendar OAuth application. The exact HTTPS redirect is `/api/companyos/integrations/google-calendar/oauth/callback`; localhost is allowed only for local development. |
| `MANAGED_COMPANYOS_BOOKING_QUEUE_URL` / `MANAGED_COMPANYOS_BOOKING_DELIVERY_SERVICE_URL` / `MANAGED_COMPANYOS_BOOKING_DELIVERY_SERVICE_TOKEN` | Optional external booking notification queue/service pair. Configure all three together; when the queue URL is omitted the calendar-maintenance cron uses the Postgres-durable direct relay. |
| `OPA_PROFILE_SEO_MAX_PAGES` | Builder publication page gate, capped at 49,998. |
| `OPA_PROFILE_SEO_MAX_BUILD_DURATION_MS` | Maximum authenticated repeatable-read build duration before rollback. |
| `OPA_PROFILE_SEO_MAX_TOTAL_BYTES` | Maximum aggregate canonical page bytes before rollback. |
| `OPA_PROFILE_SEO_MAX_PAGE_BYTES` | Maximum canonical bytes per page; must remain below 50 MiB. |
| `POSTHOG_API_KEY` | Optional server-side PostHog key. The emitter is noop when unset. |
| `POSTHOG_HOST` | PostHog server-side capture host. Use EU Cloud ingest `https://eu.i.posthog.com`. |
| `MANAGED_COMPANYOS_MANAGED_REFERENCE_CREDENTIAL_REF` | Platform-managed reference-provider credential alias for the executable provider-neutral catalog. The value must be a redacted reference label/alias, not a raw key, webhook URL, bearer token, or secret-manager URI. |
| `MANAGED_COMPANYOS_BYOK_REFERENCE_CREDENTIAL_REF` | Tenant-owned BYOK reference-provider credential alias for the executable provider-neutral catalog. The app stores and returns only redacted metadata. |
| `MANAGED_COMPANYOS_MANAGED_<PROVIDER>_CREDENTIAL_REF` / `MANAGED_COMPANYOS_BYOK_<PROVIDER>_CREDENTIAL_REF` | Future provider-family env names for approved app/provider-layer adapters. Keep values in the deployment secret manager and pass only redacted aliases/metadata through API responses, logs, tests, and evidence. |


### 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`.
- **Recipients.** 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.

| Owner kind | Adapter | Store / grant |
| --- | --- | --- |
| `tasks` | open Work tasks, personal workspace | Work event log, `workspace.read` |
| `communication-history` | meeting threads + recent messages | CommunicationOS journal, owner personal scope |
| `participants` | attendees × HubSpot contacts | live calendar read + `opa_oauth_tokens` `hubspot` |
| `drive`, `notion`, `slack` | title search, metadata only | `opa_oauth_tokens` `google-drive`, `notion`, `slack` |
| (always, consent-gated) | PersonalOS context | unbound until PersonalOS ships a consented read |

`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/*`:

| Route | Gate | Answer |
| --- | --- | --- |
| `GET …/meeting-context/connections` | session + personal context | per provider: `connectable` (listed in `OPA_MEETING_CONTEXT_CONNECT_SOURCES` and an OAuth client set), `offered` (listed in `OPA_MEETING_CONTEXT_SOURCES`), `state` |
| `POST …/meeting-context/{provider}/connect` | trusted web origin | `{ authorizationUrl }` (https consent page) |
| `GET …/meeting-context/{provider}/callback` | the same session | always 303 to `/companyos/opa-os/settings?meetingContext=connected\|failed&provider=…[&reason=…]`; an ended session is `reason=session_required` |
| `POST …/meeting-context/{provider}/disconnect` | trusted web origin | `{ provider, state: 'not_connected' }` |

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:

```sh
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:

```sh
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 [source link unresolved: `../../../deploy/lssm-ecosystem/build-compute-policy.md`]
for configuration scope and the unqualified Vercel prebuilt delivery gap.


### Source links needing reconciliation

- `../../../docs/evidence/authos/decommission-hirly-ndconsulting-2026-10-20.md` — source path absent from pinned inventory: docs/evidence/authos/decommission-hirly-ndconsulting-2026-10-20.md.
- `../../../docs/runbooks/opa-smart-meeting.md` — source path absent from pinned inventory: docs/runbooks/opa-smart-meeting.md.
- `../../../docs/runbooks/managed-companyos.md` — source path absent from pinned inventory: docs/runbooks/managed-companyos.md.
- `../../../docs/runbooks/special-ops-monolith-production.md` — source path absent from pinned inventory: docs/runbooks/special-ops-monolith-production.md.
- `../../../docs/runbooks/real-organizations-rollout.md` — source path absent from pinned inventory: docs/runbooks/real-organizations-rollout.md.
- `../../../deploy/lssm-ecosystem/build-compute-policy.md` — source path absent from pinned inventory: deploy/lssm-ecosystem/build-compute-policy.md.

## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/app.api-application-monolith` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/api-application-monolith/src/index.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- `@aws-sdk/client-s3`: `^3.1135.0`
- `@better-auth/drizzle-adapter`: `1.7.5`
- [@lssm-tech/bundle.library](https://lssm.co/docs/packages/bundle.library/): `workspace:*`
- [@lssm-tech/bundle.managed-companyos](https://lssm.co/docs/packages/bundle.managed-companyos/): `workspace:*`
- [@lssm-tech/bundle.workspace](https://lssm.co/docs/packages/bundle.workspace/): `workspace:*`
- [@lssm-tech/integration.authos-better-auth](https://lssm.co/docs/packages/integration.authos-better-auth/): `workspace:*`
- [@lssm-tech/integration.builder-telegram](https://lssm.co/docs/packages/integration.builder-telegram/): `workspace:*`
- [@lssm-tech/integration.builder-whatsapp](https://lssm.co/docs/packages/integration.builder-whatsapp/): `workspace:*`
- [@lssm-tech/integration.communication-channel-email](https://lssm.co/docs/packages/integration.communication-channel-email/): `workspace:*`
- [@lssm-tech/integration.communication-os-host-auth](https://lssm.co/docs/packages/integration.communication-os-host-auth/): `workspace:*`
- [@lssm-tech/integration.communication-os-persistence](https://lssm.co/docs/packages/integration.communication-os-persistence/): `workspace:*`
- [@lssm-tech/integration.communication-os-runtime](https://lssm.co/docs/packages/integration.communication-os-runtime/): `workspace:*`
- [@lssm-tech/integration.company-intelligence-postgres](https://lssm.co/docs/packages/integration.company-intelligence-postgres/): `workspace:*`
- [@lssm-tech/integration.crdt-loro](https://lssm.co/docs/packages/integration.crdt-loro/): `workspace:*`
- [@lssm-tech/integration.governed-data-postgres](https://lssm.co/docs/packages/integration.governed-data-postgres/): `workspace:*`
- [@lssm-tech/integration.governed-product-data-postgres](https://lssm.co/docs/packages/integration.governed-product-data-postgres/): `workspace:*`
- [@lssm-tech/integration.lssm-os-state-sqlite](https://lssm.co/docs/packages/integration.lssm-os-state-sqlite/): `workspace:^`
- [@lssm-tech/integration.meeting-intake-worker-postgres-http](https://lssm.co/docs/packages/integration.meeting-intake-worker-postgres-http/): `workspace:^`
- [@lssm-tech/integration.opa-calendar-bridge](https://lssm.co/docs/packages/integration.opa-calendar-bridge/): `workspace:*`
- [@lssm-tech/integration.opa-meeting-context-bridge](https://lssm.co/docs/packages/integration.opa-meeting-context-bridge/): `workspace:*`
- [@lssm-tech/integration.opa-notification-bridge](https://lssm.co/docs/packages/integration.opa-notification-bridge/): `workspace:*`
- [@lssm-tech/integration.osint-managed-runtime](https://lssm.co/docs/packages/integration.osint-managed-runtime/): `workspace:*`
- [@lssm-tech/integration.osint-store](https://lssm.co/docs/packages/integration.osint-store/): `workspace:*`
- [@lssm-tech/integration.provider-calendar](https://lssm.co/docs/packages/integration.provider-calendar/): `workspace:*`
- [@lssm-tech/integration.provider-codex](https://lssm.co/docs/packages/integration.provider-codex/): `workspace:*`
- [@lssm-tech/integration.provider-database](https://lssm.co/docs/packages/integration.provider-database/): `workspace:*`
- [@lssm-tech/integration.provider-einvoicing](https://lssm.co/docs/packages/integration.provider-einvoicing/): `workspace:*`
- [@lssm-tech/integration.provider-email](https://lssm.co/docs/packages/integration.provider-email/): `workspace:*`
- [@lssm-tech/integration.provider-embedding](https://lssm.co/docs/packages/integration.provider-embedding/): `workspace:*`
- [@lssm-tech/integration.provider-llm](https://lssm.co/docs/packages/integration.provider-llm/): `workspace:*`
- [@lssm-tech/integration.provider-meeting-recorder](https://lssm.co/docs/packages/integration.provider-meeting-recorder/): `workspace:*`
- [@lssm-tech/integration.provider-messaging](https://lssm.co/docs/packages/integration.provider-messaging/): `workspace:*`
- [@lssm-tech/integration.provider-sms](https://lssm.co/docs/packages/integration.provider-sms/): `workspace:*`
- [@lssm-tech/integration.provider-storage](https://lssm.co/docs/packages/integration.provider-storage/): `workspace:*`
- [@lssm-tech/integration.provider-vector-store](https://lssm.co/docs/packages/integration.provider-vector-store/): `workspace:*`
- [@lssm-tech/integration.provider-voice](https://lssm.co/docs/packages/integration.provider-voice/): `workspace:*`
- [@lssm-tech/integration.runtime](https://lssm.co/docs/packages/integration.runtime/): `workspace:*`
- [@lssm-tech/integration.runtime-managed](https://lssm.co/docs/packages/integration.runtime-managed/): `workspace:*`
- [@lssm-tech/integration.work-durable-store](https://lssm.co/docs/packages/integration.work-durable-store/): `workspace:*`
- [@lssm-tech/lib.ai-providers](https://lssm.co/docs/packages/lib.ai-providers/): `workspace:*`
- [@lssm-tech/lib.authos-runtime](https://lssm.co/docs/packages/lib.authos-runtime/): `workspace:*`
- [@lssm-tech/lib.authos-spec](https://lssm.co/docs/packages/lib.authos-spec/): `workspace:*`
- [@lssm-tech/lib.billing-france](https://lssm.co/docs/packages/lib.billing-france/): `workspace:*`
- [@lssm-tech/lib.billing-runtime](https://lssm.co/docs/packages/lib.billing-runtime/): `workspace:*`
- [@lssm-tech/lib.billing-spec](https://lssm.co/docs/packages/lib.billing-spec/): `workspace:*`
- [@lssm-tech/lib.builder-runtime](https://lssm.co/docs/packages/lib.builder-runtime/): `workspace:*`
- [@lssm-tech/lib.builder-spec](https://lssm.co/docs/packages/lib.builder-spec/): `workspace:*`
- [@lssm-tech/lib.communication-runtime](https://lssm.co/docs/packages/lib.communication-runtime/): `workspace:*`
- [@lssm-tech/lib.communication-spec](https://lssm.co/docs/packages/lib.communication-spec/): `workspace:*`
- [@lssm-tech/lib.companyos-runtime](https://lssm.co/docs/packages/lib.companyos-runtime/): `workspace:*`
- [@lssm-tech/lib.companyos-spec](https://lssm.co/docs/packages/lib.companyos-spec/): `workspace:*`
- [@lssm-tech/lib.contracts-integrations](https://lssm.co/docs/packages/lib.contracts-integrations/): `workspace:*`
- [@lssm-tech/lib.contracts-runtime-server-rest](https://lssm.co/docs/packages/lib.contracts-runtime-server-rest/): `workspace:*`
- [@lssm-tech/lib.contracts-spec](https://lssm.co/docs/packages/lib.contracts-spec/): `workspace:*`
- [@lssm-tech/lib.contractspec-connect](https://lssm.co/docs/packages/lib.contractspec-connect/): `workspace:^`
- [@lssm-tech/lib.data-exchange-core](https://lssm.co/docs/packages/lib.data-exchange-core/): `workspace:*`
- [@lssm-tech/lib.data-exchange-server](https://lssm.co/docs/packages/lib.data-exchange-server/): `workspace:*`
- [@lssm-tech/lib.design-catalog](https://lssm.co/docs/packages/lib.design-catalog/): `workspace:*`
- [@lssm-tech/lib.founder-intelligence-spec](https://lssm.co/docs/packages/lib.founder-intelligence-spec/): `workspace:*`
- [@lssm-tech/lib.identity-rbac](https://lssm.co/docs/packages/lib.identity-rbac/): `workspace:*`
- [@lssm-tech/lib.jobs](https://lssm.co/docs/packages/lib.jobs/): `workspace:*`
- [@lssm-tech/lib.knowledge](https://lssm.co/docs/packages/lib.knowledge/): `workspace:*`
- [@lssm-tech/lib.lssm-os-runtime](https://lssm.co/docs/packages/lib.lssm-os-runtime/): `workspace:^`
- [@lssm-tech/lib.lssm-os-spec](https://lssm.co/docs/packages/lib.lssm-os-spec/): `workspace:^`
- [@lssm-tech/lib.notification](https://lssm.co/docs/packages/lib.notification/): `workspace:*`
- [@lssm-tech/lib.observability](https://lssm.co/docs/packages/lib.observability/): `workspace:*`
- [@lssm-tech/lib.organization-planning-runtime](https://lssm.co/docs/packages/lib.organization-planning-runtime/): `workspace:*`
- [@lssm-tech/lib.organization-planning-spec](https://lssm.co/docs/packages/lib.organization-planning-spec/): `workspace:*`
- [@lssm-tech/lib.personalization](https://lssm.co/docs/packages/lib.personalization/): `workspace:*`
- [@lssm-tech/lib.provider-spec](https://lssm.co/docs/packages/lib.provider-spec/): `workspace:^`
- [@lssm-tech/lib.work-runtime](https://lssm.co/docs/packages/lib.work-runtime/): `workspace:*`
- [@lssm-tech/lib.work-spec](https://lssm.co/docs/packages/lib.work-spec/): `workspace:*`
- [@lssm-tech/module.auth-os](https://lssm.co/docs/packages/module.auth-os/): `workspace:*`
- [@lssm-tech/module.billing-os](https://lssm.co/docs/packages/module.billing-os/): `workspace:*`
- [@lssm-tech/module.company-metrics](https://lssm.co/docs/packages/module.company-metrics/): `workspace:*`
- [@lssm-tech/module.design-studio](https://lssm.co/docs/packages/module.design-studio/): `workspace:*`
- [@lssm-tech/module.forms](https://lssm.co/docs/packages/module.forms/): `workspace:*`
- [@lssm-tech/module.lssm-os-control-plane](https://lssm.co/docs/packages/module.lssm-os-control-plane/): `workspace:^`
- [@lssm-tech/module.work-management](https://lssm.co/docs/packages/module.work-management/): `workspace:*`
- `@opentelemetry/api`: `^1.9.1`
- `@opentelemetry/sdk-trace-base`: `^2.10.0`
- `@vercel/functions`: `^3.9.5`
- `ai`: `catalog:ai`
- `better-auth`: `1.7.5`
- `drizzle-orm`: `catalog:data`
- `elysia`: `catalog:server`
- `googleapis`: `catalog:integrations`
- `loro-crdt`: `^1.16.1`
- `next`: `catalog:`
- `pg`: `catalog:server`
- `postgres`: `^3.4.9`
- `posthog-node`: `^5.51.7`
- `react`: `catalog:`
- `react-dom`: `catalog:`
- `twilio`: `catalog:integrations`
- `zod`: `catalog:`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- `@electric-sql/pglite`: `catalog:data`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@peculiar/x509`: `1.14.3`
- `@types/node`: `catalog:types`
- `@types/pg`: `catalog:types`
- `@types/react`: `catalog:types`
- `@types/react-dom`: `catalog:types`
- `drizzle-kit`: `catalog:data`
- `typescript`: `catalog:`
- `xml-crypto`: `6.3.2`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "clean": "rm -rf dist api/dist .turbo",
  "build": "bun run build:elysia",
  "build:identity": "mkdir -p ../../../api/dist && bun build --target node --packages bundle --outfile ../../../api/dist/identity-index.js src/identity-app.ts",
  "build:lssm-os": "mkdir -p ../../../api/dist && bun build --target node --packages bundle --outfile ../../../api/dist/lssm-os-index.js src/lssm-os-app.ts",
  "dev": "bun run dev:elysia",
  "start": "bun run start:elysia",
  "build:elysia": "bun build --target node --packages bundle --external '@google-cloud/storage' --external '@elevenlabs/elevenlabs-js' --external '@fal-ai/client' --external '@composio/core' --external 'loro-crdt' --outfile dist/index.js src/app.ts && mkdir -p api/dist/node_modules/loro-crdt && cp dist/index.js api/dist/index.js && cp node_modules/loro-crdt/package.json api/dist/node_modules/loro-crdt/package.json && cp -R node_modules/loro-crdt/nodejs api/dist/node_modules/loro-crdt/nodejs && cp -R node_modules/loro-crdt/base64 api/dist/node_modules/loro-crdt/base64 && cp src/runtime/loro-base64-package.json api/dist/node_modules/loro-crdt/base64/package.json",
  "start:elysia": "bun run ./server.mjs",
  "dev:elysia": "bun run --watch src/app.ts",
  "lint": "bun run lint:fix",
  "lint:fix": "node ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "test": "bun test",
  "typecheck": "bun run typecheck:build && bun run typecheck:scripts",
  "typecheck:build": "bun --bun x tsgo --project tsconfig.build.json --noEmit",
  "typecheck:scripts": "bun --bun x tsgo --project tsconfig.scripts.json --noEmit",
  "companyos:db:migrate:test": "bun src/db/local-test-lifecycle.ts migrate",
  "companyos:db:seed:test": "bun src/db/local-test-lifecycle.ts seed",
  "companyos:db:verify:test": "bun src/db/local-test-lifecycle.ts verify",
  "companyos:db:reset:test": "bun src/db/local-test-lifecycle.ts reset",
  "companyos:db:prove-rls:test": "bun src/db/rls-proof.ts",
  "companyos:briefings:postgres:test": "bun test src/db/calendar-intelligence-postgres.integration.test.ts",
  "companyos:db:prove-disposable-postgres": "bash scripts/companyos-disposable-postgres-proof.sh",
  "companyos:db:prove-existing-postgres": "bash scripts/companyos-existing-postgres-proof.sh",
  "companyos:db:company-intelligence:test": "bun test src/company-intelligence/repositories/company-intelligence-postgres.integration.test.ts && bun test src/company-intelligence/ingestion/continuous-ingestion-postgres.integration.test.ts && bun test src/company-intelligence/ingestion/continuous-ingestion-receipts-postgres.integration.test.ts",
  "test:company-intelligence:persistence": "bun run companyos:db:company-intelligence:test && bun test src/company-intelligence/repositories/structured-extraction-postgres.integration.test.ts",
  "test:company-intelligence:governed-learning-persistence": "bun test src/company-intelligence/learning/governed-learning-repository.test.ts src/company-intelligence/learning/governed-learning-repository-postgres.integration.test.ts",
  "test:company-intelligence:ingestion": "bun run --cwd ../../domains/company/runtime test:company-intelligence:ingestion && bun test src/company-intelligence/ingestion/ingestion-idempotency-parity.test.ts",
  "test:company-intelligence:graph-repository": "bun test src/company-intelligence/graph/graph-repository.test.ts src/company-intelligence/graph/graph-repository-regression.test.ts src/company-intelligence/graph/graph-repository-postgres.integration.test.ts",
  "test:company-intelligence:brain": "bun test src/company-intelligence/brain/brain-repository.test.ts src/company-intelligence/brain/brain-projection.test.ts",
  "test:company-intelligence:api": "bun test src/company-intelligence/api/api-contract.test.ts src/company-intelligence/api/api-state-migration.test.ts src/company-intelligence/api/api-state-postgres.test.ts src/company-intelligence/api/api-postgres-orchestrator.test.ts src/company-intelligence/api/api-postgres-operations.test.ts src/company-intelligence/api/api-postgres-authorization.test.ts src/company-intelligence/api/api-local-authorization.test.ts src/company-intelligence/api/api-governed-learning-postgres.test.ts src/handlers/companyos/company-intelligence-handler.test.ts src/handlers/companyos/company-intelligence-durable-controls.test.ts src/handlers/companyos/company-intelligence-negative.test.ts",
  "test:company-intelligence:api:negative": "CI_SCENARIO=auth bun test src/handlers/companyos/company-intelligence-negative.test.ts && CI_SCENARIO=limits bun test src/handlers/companyos/company-intelligence-negative.test.ts && CI_SCENARIO=outages bun test src/handlers/companyos/company-intelligence-negative.test.ts",
  "billing:db:migrate:test": "bun src/db/billing/local-test-lifecycle.ts migrate",
  "billing:db:reset:test": "bun src/db/billing/local-test-lifecycle.ts reset",
  "billing:db:prove-rls:test": "bun src/db/billing/rls-proof.ts",
  "companyos:bootstrap-admin": "bun scripts/bootstrap-admin.ts",
  "companyos:booking-surfaces:activate": "bun scripts/activate-booking-surfaces.ts",
  "companyos:opa:reconcile-meeting-authority": "bun scripts/reconcile-opa-meeting-authority.ts",
  "companyos:authority:repair-jsonb": "bun scripts/repair-authority-jsonb.ts",
  "companyos:jsonb:normalize-text": "bun scripts/normalize-json-text.ts",
  "companyos:opa:backfill-work-planning": "bun scripts/backfill-work-planning-enrollment.ts",
  "companyos:opa:reset-canonical": "bun scripts/reset-canonical-opa-surfaces.ts",
  "companyos:auth:rotate-admin-password": "bun scripts/rotate-admin-password.ts",
  "companyos:auth:close-accounts": "bun scripts/close-accounts.ts",
  "companyos:org:decommission": "bun scripts/decommission-organization.ts",
  "companyos:sso:mock-idp": "bun scripts/sso-mock-idp.ts",
  "prebuild": "bun --bun x tsgo --project tsconfig.build.json --noEmit",
  "companyos:builder:db:migrate:test": "bun run companyos:db:migrate:test",
  "companyos:builder:db:seed": "bun run companyos:db:seed:test",
  "companyos:builder:db:verify": "bun run companyos:db:verify:test",
  "companyos:builder:db:prove-rls": "bun run companyos:db:prove-rls:test",
  "companyos:builder:api-smoke": "bun test src/handlers/builder/builder-public-handler.test.ts",
  "companyos:builder:webhook-smoke": "bun test src/handlers/builder/builder-public-handler.test.ts",
  "companyos:builder:provider-smoke": "bun test src/handlers/builder/builder-public-handler.test.ts",
  "companyos:db:migrate:live": "bun scripts/companyos-live-db.ts migrate",
  "companyos:db:opa-v2-activation": "bun scripts/opa-v2-owner-activation.ts",
  "companyos:db:seed:live": "bun scripts/companyos-live-db.ts seed",
  "companyos:db:verify:live": "bun scripts/companyos-live-db.ts verify",
  "companyos:db:test:live-safety": "bun test src/db/live-safe-lifecycle.test.ts src/db/local-test-lifecycle.test.ts",
  "profile-seo:postgres-conformance": "bun scripts/profile-seo-postgres-conformance.ts"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.api-application-monolith.txt",
  "route": "/llms/app.api-application-monolith",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.api-application-monolith.txt",
  "blobSha": "cd4ffe2f02f51708515028a093780144806b7e34",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```