Merge 13836737 — Comprehensive retrospective (technical)
Full timeline, file-level map, MCP institutional decisions, conventions, and engineering follow-ups for merge 13836737.
Merge 13836737 — Comprehensive retrospective
This document is the engineering companion to 271-merge-13836737-plain-language-guide.md. It captures what landed, why, where, and how we institutionalized the knowledge via mcp-gograb-ai.
Git facts
| Field | Value |
|---|---|
| Commit | 13836737bfa872545d7ffe823209c06e79fc8efc |
| Type | Merge commit |
| Parents | git show reports merge of integration branch into target (Merge: 00005f89a ebf38da2f) |
| Message theme | Cloudflare parallel deploy + Vitto context; lineage session-265-273_2 |
| Analysis method | git diff 13836737^1 13836737^2 for merged content (86 files, +5402 / −1093 in sampled diff) |
Executive narrative
Problem bundle
- Duplicate sandbox orchestration between backend-vitto-api and backend-ai-api → drift risk, double patches, inconsistent behavior.
- Identity comparison bugs (
stringJWTuserIdvs MongoObjectIdfields) → false403for valid members. - Slow Cloudflare release path for multiple frontends → long wall-clock deploys.
- Insufficient automated regression for security-sensitive spaces flows.
- Brittle URL parsing in Vitto page context → wrong or fragile LLM grounding.
- Platform Elements needed Gantt and Data Grid-class widgets with shared models.
Response bundle
| Theme | Resolution |
|---|---|
| Sandbox boundary | Single owner: backend-ai-api /infrastructure/sandbox/*; Vitto VmApiClientService uses HTTP + BACKEND_AI_API_URL + BACKEND_API_INTERNAL_TOKEN; removed vitto-local duplicate stack / libs/libs-api/sandbox-orchestration usage from this path |
| Auth | SpaceAuthHelper.normalizeId() + widened types for ownerId / members[].userId |
| Deploy | deployment/cloudflare/deploy-apps-parallel.sh — parallel build groups + parallel wrangler pages deploy |
| Regression safety | spaces-security.e2e.spec.ts — large API-level suite under backend-api |
| Vitto | VittoPageContextRegistry — nullish URL splits, regex guard for area |
| PE widgets | gantt-widget, data-grid-widget, models, styles, register-all updates |
Timeline (engineering order)
The merge bundles work that evolved over Sessions 265–273 lineage; below is a logical order, not strict commit time order.
Sandbox consolidation (architecture)
- Vitto stops owning VM/sandbox lifecycle locally.
- AI API remains the network authority for sandbox proxy routes already present there.
- Impact: One implementation to secure, monitor, and extend.
Auth correctness (bug class)
- Mongo may return
ObjectIdinstances where TypeScript assumedstring. - Impact: Permission helper is the choke point — fix once, protect many controllers.
- Mongo may return
Cloudflare pipeline (infra)
- Overlap gograb-space production build with Nx builds for other apps; parallelize Wrangler uploads.
- Impact: Shorter release pipeline; requires CI memory / API limit awareness.
Spaces security tests (quality)
- Broad e2e coverage co-evolves with spaces and invitation services.
- Impact: Catches integration failures unit tests miss.
Vitto context robustness (UX for AI)
- Defensive parsing for real URLs (queries, fragments, partial matches).
- Impact: Fewer misleading “you are here” descriptions for Vitto.
Platform Elements widgets (product + platform)
- Gantt + Data Grid Angular Elements, models, styles.
- Impact: Feature velocity for embedded platforms; watch bundle/perf budgets.
File and module map (high signal)
Backend — Vitto
APIs/backend-vitto-api/src/app/engine/vm/vm-api-client.service.ts— HTTP client to ai-api sandbox endpoints;SandboxHandleinlined; HttpService +firstValueFrom.
Backend — AI API
APIs/backend-ai-api/src/app/infrastructure/— sandbox providers, proxy controller, factory wiring (consolidated home for sandbox operations).
Backend — API (core)
APIs/backend-api/src/app/spaces/__tests__/spaces-security.e2e.spec.ts— new / expanded security-oriented e2e coverage.- Related:
spaces.service.ts,space-invitation.service.ts, admin stats/users, various controllers (route consistency).
Auth library
libs/libs-api/auth-core/src/lib/helpers/space-auth.helper.ts—normalizeId, type widening, denial logging uses normalized owner.
Vitto (frontend library)
libs/libs-ai/vitto-core/src/lib/services/vitto-page-context-registry.service.ts— defensive URL + Vitto route parsing.
Platform Elements
libs/libs-structural/platform-elements-angular/src/lib/components/gantt-widget/libs/libs-structural/platform-elements-angular/src/lib/components/data-grid-widget/libs/libs-structural/platform-elements-angular/src/lib/models/gantt.models.tslibs/libs-structural/platform-elements-angular/src/lib/models/grid.models.tslibs/libs-structural/platform-elements-angular/src/lib/register-all.ts,index.ts
Deployment
deployment/cloudflare/deploy-apps-parallel.sh— parallel build and deploy orchestration;DEPLOY_PARALLEL_JOBS.
Removed / reduced
libs/libs-api/sandbox-orchestration/— removed from workspace (package/project/tsconfig entries dropped).- Vitto infrastructure execution module pieces tied to local sandbox VM ops — removed in favor of delegation (see diff stat).
Other notable areas in merge
- backend-ai-api: additional controllers (e.g. Ferrari, Singularity, UI Builder naming in diff stat), sandbox proxy tests.
- Admin UI / user management: user detail + management components (telemetry/ops fields).
- g-space-dashboard: minor wiring.
- Docs / research markdown under
assets/docs/english/...and session summaries (271-daily-summary-2026-03-26.md, etc.).
MCP — institutional workflow (Session 271)
Preflight: task: "S271 merge13836737 docs + MCP ≥0.9", sessionNumber: 271, subSessionNumber: 22
find_similar: merge / vitto / sandbox / platform elements (prior related decisions surfaced, including earlier S271 PE work)
convention(get, backend-auth): existing rule for Mongo/JWT ID normalization (from prior pass)
intelligence(calibrate): domains below — all ≥ 0.91 post-calibration
intelligence(simulate): sandbox delegation + Cloudflare parallelism (recall empty; episodic memory had no close duplicate)
intelligence(gaps, multi-backend-sandbox-orchestration): no structural gaps flagged
intelligence(reflect): reflection reflection-1774545382281 — six synthesized lessons
Calibrated confidence by domain
| Domain | Raw in | Calibrated |
|---|---|---|
distributed-systems-sandbox-boundary |
0.94 | 0.94 |
mongodb-auth-identity |
0.93 | 0.93 |
ci-cd-cloudflare-parallelism |
0.92 | 0.92 |
api-security-regression-testing |
0.93 | 0.93 |
angular-router-url-parsing |
0.91 | 0.91 |
frontend-platform-elements |
0.93 | 0.93 |
Rule enforced: only log when calibrated confidence ≥ 0.90 (angular URL parsing at 0.91 meets bar).
MCP — log_decision records (full institutional template)
Each entry includes, in reasoning: what broke, root cause, alternatives, why chosen, when the decision would be wrong, early warning signals. Confidence shown is logged value (aligned with calibration).
| # | Type | Confidence | Decision ID |
|---|---|---|---|
| 1 | architecture | 0.94 | dev_1774545363268_3wr8de5 |
| 2 | bugfix | 0.93 | dev_1774545365068_onc07yj |
| 3 | infrastructure | 0.92 | dev_1774545366887_9o4t41s |
| 4 | testing | 0.93 | dev_1774545368521_wf4863d |
| 5 | implementation | 0.92 | dev_1774545369560_weju6cn |
| 6 | pattern | 0.93 | dev_1774545372060_syz3ozi |
outcome({ action: "report" }) — success reported for all six decision IDs with reinforcement notes.
outcome({ action: "module" }) — invoked for subsystem names; MCP returned heuristic wasSuccessful: false / confidence 0.6 (“User did not use the generated module”). Treat as non-blocking: module-level reinforcement may require Vitto-specific adoption metrics; decision-level outcomes remain successful.
Conventions added / reinforced
| ID | Category | Summary |
|---|---|---|
conv_1774545267414_nwuc5 (earlier) |
backend-auth |
Normalize Mongo/JWT identity comparisons at auth helpers |
conv_1774545382826_iq2tk (this pass) |
multi-service-sandbox |
Sandbox operations only in backend-ai-api; Vitto must use HTTP + internal token — no second in-process stack |
Failure modes and monitoring (engineering)
Service-to-service (Vitto → AI API)
- Symptoms: elevated 401, timeouts, partial sandbox lifecycle failures.
- Mitigations: verify
BACKEND_AI_API_URL,BACKEND_API_INTERNAL_TOKEN, network policies; add RED dashboards on/infrastructure/sandbox/*error rates and latency.
Parallel deploy script
- Symptoms: CI OOM, Wrangler rate limits, simultaneous failures.
- Mitigations: tune
DEPLOY_PARALLEL_JOBS; consider staggered deploy steps under load.
E2E suite
- Symptoms: flaky tests, long CI, skipped jobs.
- Mitigations: isolate fixtures, avoid shared mutable state, keep suite trusted or teams will bypass it.
Platform Elements bundle
- Symptoms: perf regressions, duplicate custom element registration.
- Mitigations: bundle budgets, lazy strategies if needed, single bootstrap path.
Future work (technical backlog)
- SLOs for internal sandbox HTTP calls (latency, availability).
- Contract tests between vitto-api client and ai-api sandbox OpenAPI/handler surface (prevent silent drift).
- CI profiling for parallel Cloudflare job on representative runners.
- PE widget documentation + example platforms (adoption).
- Branch naming: preflight noted
session-270-275vs canonicalsession-271— align lane naming when convenient for automation clarity.
Cross-references
- Non-developer summary:
271-merge-13836737-plain-language-guide.md - Daily decision roll-up:
271-daily-summary-2026-03-26.md - Session manifest:
sessions/manifests/S271.json - Prior auto-doc example:
271.17-architecture-where-should-vitto-execute-sandboxvm-operations-lo.md(linked to earlier decision iddev_1774545256766_nd4nqp4)
Session 271 — institutional documentation and MCP reinforcement for merge 13836737.