research+ideation(team-server): tier v1 compatible-component survey + structured ideation

[Knapp-Kevin]

Summary

Two /qor-research + /qor-ideate artifacts for the team-server tier v1 design cycle. No code changes — governance artifacts only.

1. Research brief (docs/research-brief-team-server-tier-v1-2026-05-14.md, ~250 lines): surveys all team-mode-compatible components in the codebase. 8/8 blueprint alignment checks MATCH. Identifies 9 gap areas and produces 6 prioritized recommendations (R1-R6).

2. Ideation artifact (docs/ideation-team-server-tier-v1-2026-05-14.md): structured /qor-ideate output with all 10 sections populated. Both operator decisions are now resolved:

   • R1 (transport boundary): Option 1 selected — MCP local server + JSONL stored remotely via BackendAdapter. No separate team server process. (Decision by @jinhongkuan)
   • Coexistence: Full migration to BackendAdapter for team-sync repos. Git replication retired.

3. META_LEDGER: Entry GitHub Action: sticky PR-comment drift report on open/update #49 (renumbered from Pre-push git hook: surface drift warnings before git push #48 after link_commit fails with SurrealDB 'Invalid revision 116' + recommended v0.13.9 not on PyPI #252 Layer 4 merged as Pre-push git hook: surface drift warnings before git push #48). Chained to Pre-push git hook: surface drift warnings before git push #48.

Readiness: ready for /qor-plan. Next step: /qor-plan scoping the BackendAdapter-mediated team sync + auth shim design (#215 Track 2).

Review & Testing Checklist for Human

• Verify research brief findings are still accurate against current dev HEAD (file:line citations may shift after recent merges)
• Confirm R1 decision (Option 1: MCP local + remote JSONL) aligns with team's strategic direction
• Review ideation Section 9 (Failure Remediation Plan) — are the failure classes comprehensive?

Notes

• Merge conflict with dev (from PR feat(cli): #252 Layer 4 — portable JSON-Lines ledger export/import #258 merge) resolved: META_LEDGER entry renumbered Pre-push git hook: surface drift warnings before git push #48 → GitHub Action: sticky PR-comment drift report on open/update #49
• PR feat(cli): #252 Layer 4 — portable JSON-Lines ledger export/import #258 (ledger export/import) is now Entry Pre-push git hook: surface drift warnings before git push #48; this research brief is Entry GitHub Action: sticky PR-comment drift report on open/update #49
• The ideation artifact captures Jin's architectural direction: there is no "team server" — the BackendAdapter contract IS the team transport layer

Link to Devin session: https://app.devin.ai/sessions/6ba1d2bf90b546a4ba90ec9925ce1313

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7de547c5-25d1-4235-a7ed-a8ef60281828

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch research/team-server-tier-v1-survey

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

/qor-ideate — Operator Decision Points

I've advanced this PR beyond research-only by adding a structured ideation artifact (docs/ideation-team-server-tier-v1-2026-05-14.md) following the /qor-ideate protocol. All 10 sections are populated from the research brief. Two operator decisions are needed before /qor-plan can proceed:

---

Decision 1: R1 — Transport Boundary Line

Where should the tier-v1 transport surface live?

Option	What it solves	Trade-off
Option 1: In-MCP handler	Per-developer auth + push/pull within the existing MCP server. Minimal surface area. Ships fastest. Most consistent with v0 doctrine.	Doesn't scale to hosted multi-team without a second component later.
Option 3: BackendAdapter-over-HTTP	Cleanest separation. Required for Stage 2 (Hosted-Repo). Each team gets a hosted server; BackendAdapter subclass speaks HTTP to it.	Requires building an HTTP server runtime — which #242 removed (though the warning was about OAuth workers, not all HTTP). Bigger scope.

Option 2 (beside-MCP broker) is excluded per research brief — reintroduces the daemon pattern #242 warned about.

These aren't mutually exclusive long-term. Option 1 can ship as v1; Option 3 as v2 when evidence demands it. The question is: which does /qor-plan target first?

---

Decision 2: Coexistence with git replication (#196)

When team-server is active, what happens to the existing JSONL/git path?

Mode	Behavior	Risk
(a) Additive	Write JSONL AND push to team-server; consumer dedups	Safest. Redundant writes; slightly higher cost.
(b) Primary with fallback	Team-server primary; JSONL when unreachable	Middle ground. Requires availability detection.
(c) Full migration	JSONL off when team-server URL set; git retired	Cleanest. Highest risk — no fallback.

---

@jinhongkuan @Knapp-Kevin — please weigh in on these two decisions so I can proceed to /qor-plan. The ideation artifact has the full context including assumption ledger, failure remediation plan, and governance profile (L3 risk grade).

cc: Silong

[jinhongkuan]

there shouldnt be a "team server" - 1. Option 1 2. mcp local server + jsonl stored remotely should be the final setup

[Knapp-Kevin]

Answers grounded in the research brief

Decision 1 — Transport boundary line: Option 1 first

Rationale, in order of weight:

1. Substrate is sufficient. The brief's central finding is that BackendAdapter (events/backends/__init__.py:20-50) + canonical_id UUIDv5 UNIQUE (ledger/schema.py:137,165) + per-author JSONL (events/writer.py:132) already covers the wire-level multi-author story. Option 1 builds tier v1 as a handler that uses this substrate, not as a new substrate. Option 3 builds tier v1 as a new BackendAdapter shape that uses HTTP. Both reuse the substrate; Option 1 reuses more of the existing handler scaffolding.

2. Auth shim fit. BicameralAI/bicameral-daemon#9 Track 2's three design options (per-developer JWT in the MCP envelope / mTLS over stdio tunnel / OS-keychain-backed credentials) all assume the principal is verified at the MCP envelope boundary. Option 1 places the verification at the boundary the auth shim is already designed against. Option 3 requires a second verification point at the HTTP boundary.

3. chore(team-server): scale down to v0-conformant remote event-log store; remove self-hosted server runtime #242's lesson is still load-bearing. The warning was about self-hosted Slack/Notion OAuth workers + per-source Docker daemons, not about all HTTP servers. Option 3 doesn't violate the letter of chore(team-server): scale down to v0-conformant remote event-log store; remove self-hosted server runtime #242 but it does reintroduce a managed server runtime that has to be deployed, monitored, and version-aligned with clients. Option 1 keeps the deployment shape (one MCP server per operator) unchanged.

4. Sequencing is not lossy. Option 1 first → Option 3 second is feasible without rework. Option 1 ships the auth shim and the team-mode-aware handler; Option 3 later adds an HTTP-speaking BackendAdapter subclass that shares the same auth-shim verification primitive. Going Option 3 first means building the hosted server before the auth shim and before evidence of demand for hosted multi-team — premature.

5. Evidence threshold for Option 3. Promote to Option 3 when: (a) ≥1 design-partner deployment requires hosted multi-team isolation that single-tenant BackendAdapter cannot provide, OR (b) the Stage-2 business-model surface (visual-plans/bicameral-business-model.html) becomes a committed roadmap deliverable. Until then, Option 1 covers the operator-facing need.

Concrete next step: /qor-plan cycle for tier v1 = Option 1, scoped as a new team-mode-aware handler in the MCP server that uses the existing BackendAdapter under the hood and gates writes on the Track 2 auth-shim principal.

---

Decision 2 — Coexistence with BicameralAI/bicameral-daemon#15's (a)/(b)/(c) framing: reframe before answering

The (a)/(b)/(c) options in BicameralAI/bicameral-daemon#15 predate both #242 (self-hosted server removed) and #279 Phase 2 (BackendAdapter shipped). The framing assumed "team-server is a separate substrate; git is the existing substrate; pick how they coexist." Post-#242 + #279 Phase 2 the topology has changed:

• JSONL is the wire substrate. Per-author <email>.jsonl files (events/writer.py:132) are the canonical event-log format.
• BackendAdapter is the transport abstraction. LocalFolder and Google Drive are the two shipped backends; team-server tier v1 would be a third.
• Git is no longer the event-log substrate. Operators with team: config in .bicameral/config.yaml use BackendAdapter; the brief found no code path where git is still the event-log replication channel.

With that reframing, the original (a)/(b)/(c) collapse:

• (a) "Additive — write JSONL and push to team-server, dedup at consumer" — this is what already happens. The JSONL write happens regardless of backend; the BackendAdapter push is what makes peers see it. There is no "JSONL OR team-server" choice; team-server consumes JSONL events.
• (b) "Team-server primary, JSONL fallback" — semantically empty post-[v0-productization §3] Pull-based meeting ingestion — sync-and-brief CLI + SessionStart hook + source pullers #279 Phase 2. JSONL is not a fallback for the backend; JSONL is the wire format the backend transports.
• (c) "Full migration; JSONL writer off when team-server URL set" — directly wrong. JSONL is the wire format, not an alternate transport. Turning off the JSONL writer means turning off the event-log substrate entirely.

Re-stated answer: tier v1 team-server is a BackendAdapter subclass (or in Option 1's framing, a handler that consumes BackendAdapter). It transports JSONL events the same way LocalFolderAdapter and GoogleDriveAdapter do. The "git replication path" referenced in BicameralAI/bicameral-daemon#15 was retired by #279 Phase 2; the brief found no surviving code path where decisions replicate via git rather than the backend.

What BicameralAI/bicameral-daemon#15 should be updated to: close-as-superseded by #279 Phase 2 + the tier-v1 plan that R1 picks, OR re-scope to a specific gap the brief identified — most relevant candidate: "team-server tier exposes a write-coordination protocol beyond first-write-wins canonical_id dedup" (currently first-write-wins; lossy on divergence; the brief's R3 calls this out as a real gap).

---

Cross-refs

• Research brief: docs/research-brief-team-server-tier-v1-2026-05-14.md (in this PR)
• Substrate doc: docs/v0-architecture-current.md
• Trust boundary: docs/policies/threat-model-and-trust-boundary.md (merged in docs(security): #215 Track 1 — declare MCP-transport trust boundary (SOC2-01) #324)
• Blueprint alignment table (brief § "Blueprint alignment check"): 8 of 8 MATCH; no drift to remediate before tier v1.

@jinhongkuan @Knapp-Kevin — pending your concurrence or correction.

[devin-ai-integration]

@jinhongkuan — merged to dev. Research brief + ideation artifact with your R1 decision recorded (Option 1: MCP local + remote JSONL via BackendAdapter, no team server). All 6 CI gates green. Ready for /qor-plan when you're ready to proceed.

[Knapp-Kevin]

Design strategy: backends as pluggable shelves

Refining the brief's R1 framing into something simpler, grounded in the research findings.

One sentence

Bicameral writes one JSONL file per person; teammates need somewhere to share those files. That "somewhere" is the BackendAdapter — a swappable plug picked by deployment shape, not a single forever-choice.

The research brief (this PR, § "Findings") confirms this is the substrate the architecture was built to support. Quote from the original plan committed in 8965337 as Bicameral-Arc.md: "SurrealDB remains the operational graph database. CodeGenome becomes the identity, evidence, and evaluation engine that enriches Bicameral's graph." The team-server question is about transport, not about substrate.

What's already verified by the research

From the brief's blueprint-alignment check (§ "Blueprint alignment check"): 8 of 8 checks return MATCH. No drift between architecture-as-coded and architecture-as-documented at the v0 boundary. Specifically:

• BackendAdapter ABC at events/backends/__init__.py:20-50 defines four methods: push_events, pull_events, lock, list_peers. The ABC is backend-agnostic by construction.
• LocalFolderAdapter (events/backends/local_folder.py:1-75) and GoogleDriveAdapter (events/backends/google_drive.py:1-80+) are two implementations proving the ABC handles different transports without leaking into consumers.
• canonical_id UUIDv5 UNIQUE index (ledger/schema.py:137,165) gives DB-level idempotent replay across peers regardless of which backend transports the events.
• Per-author file isolation (events/writer.py:132) means peers never write to each other's files; backend ACL needs only "peer can read everyone, write own."

The brief's central finding: the BackendAdapter contract + canonical_id UUIDv5 + per-author JSONL isolation is sufficient as the wire substrate. Tier v1 (whatever its shape) should be additive on top, not a replacement.

The shelves (BackendAdapter implementations)

Shelf	Fits	Status
Local folder (NFS / Dropbox / Syncthing)	One team on a shared filesystem	Shipped via #279 Phase 2
Google Drive	One team on Google accounts	Shipped via #279 Phase 2
Git repo	One team, OR open-source project	Not built
S3 / R2 / MinIO bucket	One team, OR cross-org cloud	Not built
Hosted bicameral-team-server	Cross-org commercial	Not built; gated on Stage 2 demand

Same JSONL files. Different storage locations. Adding new backends is incremental — no rewrite of the substrate, consumers, or materializer.

---

Why not just Google Drive

Drive was the right MVP. As the only backend it collapses on every other use case. Specifics, with code references:

• OAuth single point of failure. The Bicameral OAuth client at events/backends/google_drive.py:38, 41-49 is one shared project (bundled credentials per RFC 8252). If Google rate-limits it, suspends it, or unpublishes the consent screen, every operator's adapter breaks at once. Outside operator control.
• drive.file scope quirk (events/backends/google_drive.py:37). Only files Bicameral's OAuth client wrote are visible to Bicameral. Files uploaded via Drive's web UI are invisible. Reduces "drop a file, see it sync" interop and complicates manual recovery.
• Per-org-tenant binding. Drive folders live in someone's Drive. Cross-org means the consumer authenticates to the host org's Google domain — often blocked by SSO / DLP policy.
• Sovereignty walls. EU Schrems-II, US DoD environments, Russian data-residency rules, classified workflows: Drive is unusable by policy.
• OSS contributor friction. A random open-source contributor will not grant Drive access to a Bicameral-issued OAuth app to participate in a project's decisions.
• No machine-to-machine path. Service accounts require GCP project setup; Bicameral doesn't ship that flow (per events/backends/google_drive.py OAuth-only design). CI runners and autonomous agents can't sync.
• No air-gapped mode. Network dependency makes regulated / classified deployments impossible.

The research brief's gap analysis (§ "Gaps & blank spots") flagged related items: no backend health probes (BackendAdapter ABC omits a status method), no per-peer bandwidth metering, no per-backend observability. Drive amplifies all of these — quota failures are silent until they aren't.

These aren't bugs in the Drive adapter. They're constitutional limits of using Drive as the substrate. The fix isn't to make Drive bigger. It's to add the other shelves.

---

The hard limits of any file-share manifestation

This is the load-bearing finding from the research: even when we swap Drive for Git, S3, or NFS, we're still using a file-share substrate. Certain limits attach to the pattern itself, not to Drive specifically. The brief's gap list (§ "Gaps & blank spots") catalogs the symptoms; this section maps them to root causes.

What file-share substrates do well

• Within-org collaboration. Trust terminates at the substrate's own ACL (Drive permissions, Git auth, S3 IAM). Peers within an org already trust each other not to overwrite or read maliciously. Matches the trust-boundary scope statement in docs/policies/threat-model-and-trust-boundary.md (shipped in docs(security): #215 Track 1 — declare MCP-transport trust boundary (SOC2-01) #324).
• OSS / public-commons federation (specifically with Git or public S3). Public-read + signed-write matches the OSS trust shape.
• Append-only event-log transport. JSONL files are exactly the shape every file-share knows how to handle. Per-author file separation (events/writer.py:130-132) means there's no cross-author write contention at the file level.
• Deterministic replay. canonical_id UUIDv5 dedup (events/materializer.py:99-195) means file-level transport doesn't have to be conflict-aware. Materializer fail-soft on out-of-order / missing context (events/materializer.py:108-113) keeps single-peer outages from corrupting the consumer's state.

Where file-share substrates hit a wall

These limits hold regardless of whether the shelf is Drive, Git, S3, NFS, or any future file-share-shaped backend. The brief's R3 (conflict-resolution semantic) and gap analysis already named several; here they are mapped to the deployment-shape boundary they break at:

1. No selective sharing primitive at the substrate level. A file is either readable by a consumer or it's not. There's no "this decision is shareable with Org X but not Org Y" without a tagging layer in Bicameral itself. Cross-org partial-sharing is structurally impossible with file-share alone.
2. No tenancy. The substrate doesn't model org boundaries. A Drive folder, a Git repo, an S3 bucket are flat namespaces — every reader sees the same content. Multi-tenant cross-org isolation requires either per-tenant-substrate-instance (one folder per org pair, doesn't scale) or a tenancy layer above the file layer.
3. No real-time push. All file-share substrates are poll-based or trigger-by-paid-feature (Drive watch API, S3 event notifications). Bicameral's cli/sync_and_brief_cli.py orchestration (cli/sync_and_brief_cli.py:68-101) is poll-driven. Real-time team awareness wants push, which file-share doesn't natively provide.
4. Identity is substrate-scoped. "Who wrote this file" is verifiable only through the substrate's own auth (Drive owner, Git committer, S3 ACL). Cross-substrate identity portability requires Bicameral-level signing — open issue Proposal: Ed25519 signed EventEnvelopes for tamper-evident decision history #23 (Ed25519 signed EventEnvelopes) is the existing proposal for this primitive.
5. Audit trail is substrate-scoped. Each substrate's audit log lives in its own admin console (Workspace admin, Git provider, AWS CloudTrail). Cross-org consumers can't audit who has read their published events end-to-end.
6. Last-writer-wins on <email>.jsonl. File-share substrates don't enforce append-only at the wire level. One operator + two devices editing the same JSONL clobbers. Materializer shrink-detection (events/materializer.py:77-78) handles the consumer side, but the substrate can't prevent the rewrite. The brief's R3 calls this out as a real gap.
7. No bandwidth / quota awareness. Pull/push ops are fire-and-forget. The current LocalFolderAdapter and GoogleDriveAdapter both treat failures as exceptions, not as metered backoff. The brief's R4 (BackendAdapter health probes) is the substrate-level fix; per-peer quotas are above that.
8. Trust topology is binary. "Has substrate access" or "doesn't." No graduated trust (read-only consortium member vs. read-write peer vs. signed-snapshot subscriber). Per-developer agent identity (context.py:100-147 from [#216 followup, team-server gate] Per-agent session-id source for rate-limit isolation #231) gives per-operator identification but not graduated authorization.

What this means by deployment shape

Deployment shape	File-share verdict	What unlocks it
Team (one org, one substrate)	Sufficient	Drive / LocalFolder shipped via #279 Phase 2
Org-wide (one org, many teams, mixed substrates)	Sufficient with decision tagging	Add publish_scope field at write time
OSS / standards-body federation	Sufficient with Git backend + envelope signing	Add GitBackendAdapter + close out #23
Compliance / regulated (air-gapped, audited)	Sufficient with courier pattern	Promote #252 Layer 4 ledger-export/import to a CourierBackendAdapter
Cross-org commercial (multi-tenant)	Hits the ceiling	Hosted bicameral-team-server with Bicameral-enforced tenant boundaries; Stage 2 of visual-plans/bicameral-business-model.html

The last row is the structural ceiling. Limits 1, 2, 5, 8 from the list above cannot be worked around inside file-share alone at the scale of selective cross-org sharing. The hosted bicameral-team-server option becomes necessary not for technical reasons but for trust-topology reasons: cross-org commercial deployments need tenant boundaries Bicameral itself enforces, not boundaries the operator manages by juggling N Drive folders or N S3 buckets per counterparty.

This aligns with the brief's R1 Option 3 framing, but corrects the original binary: Option 3 isn't competing with Option 1; it's the answer for one specific deployment shape that file-share substrates structurally can't satisfy. Option 1 (in-MCP handler) is the right answer for the other four shapes.

---

Updated R1 recommendation

The brief's original R1 framing was binary (Option 1 vs. Option 3). The corrected axis is:

Which shelf, in which order, for which collaboration shape?

1. Team (within-org) — shipped via [v0-productization §3] Pull-based meeting ingestion — sync-and-brief CLI + SessionStart hook + source pullers #279 Phase 2. Drive + LocalFolder. No further work for the baseline.
2. Org-wide selective — add decision tagging (publish_scope field at write time) before adding more backends. Without it, no substrate change unlocks selectivity. Smallest possible cycle; unblocks everything else; touches events/writer.py, ledger/schema.py, handlers/ingest.py, the team: config block. One /qor-auto-dev-1 cycle.
3. OSS / standards-body federation — add GitBackendAdapter + close out Proposal: Ed25519 signed EventEnvelopes for tamper-evident decision history #23 (Ed25519 signed EventEnvelopes). Unlocks public-substrate federation without inventing a server. The Git backend is also closer to what existed pre-chore(team-server): scale down to v0-conformant remote event-log store; remove self-hosted server runtime #242, so operators familiar with the prior architecture have low ramp-up. One cycle each.
4. Compliance / regulated — promote the existing ledger-export / ledger-import pair (link_commit fails with SurrealDB 'Invalid revision 116' + recommended v0.13.9 not on PyPI #252 Layer 4) to a proper CourierBackendAdapter so the same code path covers "hand-deliver a JSONL bundle on a USB drive" as "live sync." Small cycle.
5. Cross-org commercial (the structural-ceiling case) — hosted bicameral-team-server with tenant-aware auth. Build only when at least one design partner concretely demands it AND Stage 2 becomes a committed roadmap item. The brief's R6 (defer until evidence) applies here. Research + plan + multi-cycle implementation, not before.

The brief's R2 (Track 2 of BicameralAI/bicameral-daemon#9 — auth shim design) folds into items 3 and 5: federation Git + #23 envelopes is the OSS-shaped auth shim; tenant-aware JWT is the commercial-shaped one. Same architectural primitive, different surface.

What ships next

Two candidates for the next /qor-auto-dev-1 cycle, both small, both inside v0 doctrine, neither requires a server:

• (a) Decision tagging — publish_scope field at write time. Unblocks every downstream cross-org pattern; touches the schema and the ingress path; pairs well with the existing signoff axis.
• (b) GitBackendAdapter — concrete second shelf. Unlocks OSS federation immediately. Doesn't require (a) but is more useful with it.

Both are forward-compatible. Picking (a) first lets every backend benefit; picking (b) first ships a visible new capability faster. Recommendation: (a) first, then (b). Tagging is foundational; without it, every later backend ships in "publish everything" mode, which is wrong by default for cross-org.

@jinhongkuan @Knapp-Kevin — does this reframe match the team-server-not-necessary position? If yes, item (a) becomes the work-after-#215-Track-1 cycle. If the position is also "no need for cross-org at all in v0," items (a) and (b) defer; the next cycle becomes something else from the open P1 backlog (#281 ledger projection bug is a strong candidate).

[devin-ai-integration]

@jinhongkuan — one open operator decision from the ideation (A6):

First-write-wins conflict resolution — is this acceptable as the v1 semantic?

Currently, canonical_id (UUIDv5 from (description, source_type, source_ref)) is a UNIQUE index. When two peers write the "same" decision with different rationales, the first-write-wins and the second is silently skipped during replay (events/materializer.py:108-113).

Options:

1. Accept first-write-wins (current behavior) — simple, deterministic, but risks silent loss of conflicting peer intent
2. Surface conflicts to the human via a new MCP tool — preserves information but adds UX surface
3. Merge via a deterministic rule (lexicographic peer-ID, latest-wins, etc.) — no UX surface but biases the resolution

This doesn't block /qor-plan (plan can proceed with first-write-wins as default), but the decision should be recorded before /qor-implement.