docs: consolidate multi-user + packaging planning artifacts#3
Merged
Conversation
…erver beta) Survey of the shipped server-beta runtime + three auth stores; headline decision to extend rather than build new; per-gap decisions for shared store, UUID ids, actor_id denormalization, auth reconciliation, and a visibility/privacy model; a non-regressing local->team migration path; open questions handed to Workstream 3. Local-only per coordinator constraint: no push, no PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019WSGNPpdcNkTexMTXf9y2f
…c packaging bug
Spec + bite-sized implementation plan for the observation → Chroma vector-sync
packaging defect (100% broken on published 13.9.x): worker-service.cjs lazy-requires
../sqlite/SessionStore.js + ../sqlite/observations/files.js, which the build never
emits and package.json#files never ships → MODULE_NOT_FOUND, swallowed to `{}`.
Recommends a HYBRID fix (static-inline parseFileList; emit+allowlist SessionStore),
a fresh consolidated branch crediting the three competing PRs (thedotmack#3102/thedotmack#3108/thedotmack#3116),
a static packaging guard (build-time + smoke:clean-room PART 3), and a logger fix so
Bun ResolveMessage errors stop rendering as `{}`. Adds docs/BUILDER_QUEUE.md with the
queued item plus split-out backlog (folder-CLAUDE.md fix, Workstreams 2 & 3).
Planning only — no production code touched. Local branch, no PR/push.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019WSGNPpdcNkTexMTXf9y2f
…otmack#3082 search routing; scope-vocabulary mismatch) - Plan 1: make the `search` MCP tool runtime-aware — route to PG-backed /v1/search under CLAUDE_MEM_RUNTIME=server (mirroring observation_*), adopt-and-extend community PR thedotmack#3082 (re-targeted to post-rename symbols, adds platformSource routing, extracts a testable pure router, adds a timeline/get_observations server-runtime guard). - Plan 2: align the local hook bootstrap key scopes (events:*/observations:*) with the /v1 enforcement vocabulary (memories:read/memories:write), the vocabulary every route and test already uses. Both are correctness fixes on existing OPEN server-beta code, independent of the IP-boundary question. Implementation lands on Mark's fork later. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019WSGNPpdcNkTexMTXf9y2f
…0001) Sequences the implementation arc that onboards Mark's REMOTE teammates onto the shipped server-beta runtime without regressing local-first worker mode. Extends docs/architecture/decisions/2026-07-02-multi-user-cross-team-memory.md. - Hosting: VPS/Docker-Compose (H1) steady state, Tailscale-exposed appserver (H3) zero-cost pilot; managed cloud (H2) and reserved SaaS (H4) noted. - Day-1 remote onboarding: consume-only (shipped PR thedotmack#3070) vs contribute (needs Phase 0 scope fix + write-capable /v1/keys mint). - Additive seams: actor_id/api_key_id denormalization + Chroma actorId; visibility enum (private|team|org, default team). - Vector recall in team mode: REUSE finding — Chroma vector proven in SDK client.search() but /v1/search + /v1/mcp are FTS-only; wire, don't build. Chroma-wired-first vs pgvector fast-follow flagged as the key decision. - Migration: additive, reversible SQLite->Postgres backfill via memory_items. - Phased sequence 0-5 with commercial-boundary markers; Phases 0-4 OPEN, Phase 5 (org->team bridge/SSO/dashboard) straddles reserved line. - Non-regression invariant stated + per-phase preservation table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019WSGNPpdcNkTexMTXf9y2f
There was a problem hiding this comment.
Pull request overview
This PR consolidates multi-user/server-beta and packaging planning artifacts into the repo’s docs/ tree, including a new ADR (0001), two Phase 0 server-beta bug-fix plans, and an onboarding roadmap, plus an ADR index and architecture overview cross-reference.
Changes:
- Added
docs/architecture/decisions/ADR index and ADR 0001 for the “extend server-beta” multi-user direction. - Added Phase 0 fix-plan docs for server-beta scope vocabulary reconciliation and runtime-aware
searchrouting (thedotmack#3082). - Added builder execution queue + a phased onboarding roadmap doc tying the above artifacts together.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/BUILDER_QUEUE.md | Adds a builder-facing queue for planned/shippable work items with links to the corresponding plans. |
| docs/bug-fixes/serverbeta-scope-vocabulary-reconciliation.md | Fix plan doc for aligning server-bootstrap API key scopes with /v1 enforcement (memories:*). |
| docs/bug-fixes/3082-search-server-runtime-routing.md | Fix plan doc for making the MCP search tool runtime-aware in server mode, plus server-mode guards. |
| docs/bug-fixes/2026-07-02-chroma-observation-sync-packaging.md | Detailed spec + implementation plan for the Chroma observation sync packaging regression and guardrails. |
| docs/architecture/decisions/README.md | Introduces an ADR index with ADR 0001 and pointers to related architecture docs. |
| docs/architecture/decisions/2026-07-02-multi-user-cross-team-memory.md | ADR 0001 proposing to extend the shipped server-beta runtime to support multi-user/cross-team memory. |
| docs/architecture/2026-07-02-distributed-team-onboarding-roadmap.md | Roadmap describing hosting/onboarding phases for remote teammates, sequencing the remaining seams. |
| docs/architecture-overview.md | Adds a cross-reference to the ADR index and ADR 0001 from the architecture overview. |
|
|
||
| | # | Status | Item | Spec + Plan | Depends on | Notes | | ||
| |---|--------|------|-------------|------------|-------| | ||
| | 1 | 📋 | **Fix observation → Chroma vector sync packaging bug** — ship `plugin/sqlite/SessionStore.js` + inline `parseFileList`; add a static packaging guard; make MODULE_NOT_FOUND-class errors visible. Consolidates PRs #3102/#3108/#3116; closes #3091/#3092/#3107. | [`docs/bug-fixes/2026-07-02-chroma-observation-sync-packaging.md`](bug-fixes/2026-07-02-chroma-observation-sync-packaging.md) | — | Fresh consolidated branch, `Co-authored-by:` bionicbutterfly13 + KaizenPrompt + Garcia6l20. **Hybrid** approach: B (static-inline) for `parseFileList`, A (emit + `files` allowlist) for `SessionStore`. **Exclude** #3116's folder-`CLAUDE.md`/`HybridSearchStrategy` changes → item #2. High severity (headline feature broken on every 13.9.x install). | |
|
|
||
| - `../sqlite/observations/files.js` (`parseFileList`) — loaded by `loadFilesHelper()`, called inside | ||
| `formatObservationDocs()`. Pure: its only import is `logger` (no `bun:sqlite`). | ||
| - `../sqlite/SessionStore.js` (`SessionStore` ctor) — loaded by `loadSessionStoreCtor()`, used by the backfill paths. |
Comment on lines
+270
to
+274
| // createRequire(import.meta.url)('../sqlite/SessionStore.js') call (see | ||
| // ChromaSync.ts loadSessionStoreCtor), not a static import: SessionStore | ||
| // pulls in `bun:sqlite`, so a static import would drag it into the cmem-sdk | ||
| // (tsup) bundle and fail scripts/check-sdk-bundle.cjs. esbuild's worker | ||
| // bundle does not follow that indirection either, so SessionStore.js must be |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consolidates the planning artifacts produced during the multi-user + packaging work onto one branch so they live alongside the shipped code (and the roadmap↔ADR cross-reference resolves):
docs/architecture/decisions/2026-07-02-multi-user-cross-team-memory.md— ADR 0001 (extend Hosted Server beta)docs/architecture/2026-07-02-distributed-team-onboarding-roadmap.md— the phased team-onboarding arcdocs/bug-fixes/2026-07-02-chroma-observation-sync-packaging.md— WS1 plan (shipped as PR fix: ship sqlite runtime modules + packaging guard + Chroma error logging #1)docs/bug-fixes/3082-search-server-runtime-routing.md+serverbeta-scope-vocabulary-reconciliation.md— Phase 0 plans (shipped as PR fix(server-beta): runtime-aware search routing (#3082) + canonical memories:* hook scopes #2)docs/BUILDER_QUEUE.md, ADR index + overview cross-refDocs only — no code. Fork-internal.