v0.4: Refinement & extensibility: finish what we started
| Field | Value |
|---|---|
| Date finalised | 2026-05-25 |
| Author | Rômulo Febasi <romulo@febasi.com.br> |
| Scope | Roadmap brainstorm for Synapse v0.4.0: the consolidation cycle that closes v0.3’s acknowledged debts and opens the editor/companion extensibility surface, before v0.5’s semantic layer changes the centre of gravity. |
| Status | shipped 2026-05-26: 18/18 issues (12 core + 6 stretch); milestone #6 closed; tag v0.4.0 pending |
| Decisions log | Owner answered the §9 open questions on 2026-05-25: (1) cut syn agent (autonomous loop with batch proposals) from v0.4: defer to v0.6 so it lands after the semantic layer matures; (2) keep numbering as v0.4.0; (3) open milestone + issues immediately. The “refinement-first” framing was greenlit explicitly: v0.4 closes v0.3 dívidas before adding new product surface. |
| Inputs | The v0.3 brief (2026-05-25-v0.3-multi-context-developer.md); audit of every “deferred to v0.4” / “limitação documentada” / “follow-up” reference inside the v0.3 code, ADRs (012, 013, 014), and issue comments; the live v0.4 milestone (#6) which already held SYN-130 (syn-lsp) and SYN-150 (mcp/server.rs split) before the brief; internal critique of v0.3 ship vs promise. |
| Out of scope | Semantic search and embeddings (v0.5, gated by --features vector). syn agent autonomous loop (moved to v0.6). GitHub/Linear ingestors (deferred post-v0.5 by owner during v0.3). Sigstore-style transparency log, cross-bundle merge, HTTP discovery of identity bundles (v0.5+). Schema declarable per-workspace (v1.0 candidate). TUI / syn ui (backlog). Share entity granular (backlog). |
Executive summary
v0.3 shipped 18/18 tickets under EU AI Act deadline pressure. Three categories of work landed with explicit, documented limitations: accepted at the time as honest scope reductions, but they leave the product feeling “mal acabado” in production review: (a) syn audit replay does not actually re-run the model; (b) the identity bundle prototype has no mandatory crypto and no revocation; (c) MCP Tasks is a feature-flagged placeholder. Plus four primitives shipped half-way (tag-level federation redaction, syn at <ref> missing graph/list/info, resources pagination, x-ai-history on re-mutations).
v0.4 closes those debts before v0.5 changes the centre of gravity. Theme: “Refinement & extensibility: finish what we started, open the doors.” Two extensibility tracks join the cleanup: the mcp/server.rs split (ADR-015 mandates it) and the syn-lsp editor companion (highest-leverage adoption play that is not SaaS-shaped).
A bonus disruptive thread that the owner greenlit during the v0.3 ADR-014 review surfaces here as first-class: the portable identity bundle becomes a curriculum surface: syn experience add, skills auto-derived from workspace tag frequency, syn cv export rendering a deterministic Markdown CV from data the human already owns.
1. Context and premisses
What state is assumed (post-v0.3.0)
- v0.3.0 shipped 2026-05-25 with: 13 MCP tools + 4 resources + 3 prompts +
mcp_tasksfeature flag; audit trail (.synapse/audit.ndjson) with 90-day rotation;x-ai-*provenance stamps with[provenance] inline = falseescape; portable identity bundle prototype (syn identity export|import|inspect); capability disclosure (.synapse/server-card.json); time-travelsyn timeline+syn at <ref>subset; cross-workspacesyn audit stale;syn capture. - 99 tests green, clippy clean, cargo fmt clean. CI: release + mirror pipelines work; pre-push hook now enforces
cargo fmt --checkper the 2026-05-25 CI fix. - ADR index covers 001-015 (008 documented gap, 015 sets the file-size policy).
- Cargo.toml at
0.3.0. Milestone#6(v0.4) already holds two issues: SYN-130 (syn-lsp) and SYN-150 (mcp/server.rssplit).
What is explicitly off-limits in this brief
- Semantic search / embeddings: reserved for v0.5 behind
--features vector(SYN-80..89). syn agentautonomous loop with batch proposals: owner moved to v0.6 on 2026-05-25 so it lands on top of mature semantic search, not before.- GitHub / Linear ingestors: deferred post-v0.5 during v0.3 because external-API tokens conflict with local-first invariant.
- Sigstore transparency log, cross-bundle merge, HTTP discovery: deferred from ADR-014; revisit when there is real demand.
- Schema declarable per-workspace: v1.0 candidate; architectural cost outweighs current need.
- TUI /
syn ui, share entity granular: cut from v0.3 by the market scan; no signal to reverse. - Cursor / Copilot territory: Synapse remains the business context layer.
Triggers for this brief
- v0.3 closed 18/18 tickets under deadline pressure; several known limits stayed documented but unimplemented (audit replay, identity crypto, MCP Tasks placeholder, etc.). Production review of any of these blocks would fail.
- SYN-150 (mcp/server.rs split, ADR-015) was filed during v0.3 and blocks every new MCP feature in v0.4 until it lands.
- SYN-130 (
syn-lsp) was deferred to v0.4 with owner greenlight; it is the cheapest possible IDE integration play and the time to ship it is now. - Owner flagged in ADR-014 §Future direction that the identity bundle has a natural evolution into a curriculum-like surface: schema kept open precisely so that v0.4 (or later) could pick it up. v0.4 picks it up.
2. Audit of v0.3 limitations (the “mal acabado” inventory)
This section is the load-bearing piece of this brief. It is not a market scan: v0.4 is consolidation, not new-frontier. It is a systematic audit of every limitation v0.3 left documented, with severity and the v0.4 ticket that addresses it.
2.1 Audit / Provenance debt
| Item | Where it was deferred | Severity | v0.4 ticket |
|---|---|---|---|
syn audit replay does not re-run the model: only shows payload + snapshot + visual diff | cli/audit.rs doc, AUDITABILITY.md §2, SYN-113 commit | High: Bet 5 of v0.3 brief promised re-run; we shipped half | SYN-136 |
--no-network flag accepted as no-op | cli/audit.rs | Cosmetic until --execute ships | (subsumed by SYN-136) |
x-ai-history for entities mutated twice: second accept overwrites stamps; full history lives only in audit trail | ADR-012 §Open question | Medium: breaks repro for sequential mutations | SYN-137 |
prev_hash Merkle chain in audit | ADR-013 §Consequences | Low: slot reserved, no external demand | stays deferred to v0.5+ |
syn audit verify: re-hash pending payloads against audit.payload_sha256 | Not implemented in v0.3 | High: without verify, the hash is decorative; CI cannot gate | SYN-135 |
Stale ranking heuristic hand-tuned in risk_for() | cli/audit.rs | Medium: works, can be refined with richer signals (commits, blame) | stays as-is until user demand |
syn doctor --lint-provenance: validate consistency of x-ai-* stamps vs audit row | Not implemented | Medium: detects manual tampering or drift | SYN-146 |
2.2 MCP debt
| Item | Where it was deferred | Severity | v0.4 ticket |
|---|---|---|---|
MCP Tasks placeholder: mcp_tasks feature flag declares intent, does NOT implement progress reporting | SYN-118 commit + get_info().instructions | High: advertised but unfinished; users discover the gap | SYN-138 |
| Resources pagination via cursor | list_resources in mcp/server.rs | Medium: workspaces with thousands of entities suffer | SYN-139 |
| Resource templates (URI templates per spec) | Not implemented | Low: current per-entity listing works | stays deferred |
Tag-level federation redaction: only type-level shipped; SearchHit does not carry tags | SYN-117 commit | High: Bet 4 promised tags + types; only types shipped | SYN-140 |
2.3 Time-travel debt
| Item | Where it was deferred | Severity | v0.4 ticket |
|---|---|---|---|
syn at <ref> only search + show; graph, list, info subcommands missing | SYN-122 commit explicit | Medium: closes the surface | SYN-141 |
| Full as-of FTS rebuild: today filters current hits, NOT rebuilds index | SYN-122 commit + AUDITABILITY.md | High: current shape is misleading for compliance review | SYN-142 |
syn timeline --all (project-wide, not per-entity) | Not implemented | Low: workflow option | stays deferred |
2.4 Identity bundle debt
| Item | Where it was deferred | Severity | v0.4 ticket |
|---|---|---|---|
Mandatory ed25519 signing + syn identity keygen | ADR-014 §v0.3 explicit non-goals | High: without crypto the bundle verifies nothing | SYN-131 |
| Attestation revocation surface | ADR-014 | Medium: required before real-world use | SYN-131 (combined) |
Curriculum-like surface (syn experience add, auto-derived skills, exportable CV) | ADR-014 §Future direction; owner-flagged | High: owner asked explicitly, schema already kept open | SYN-132, SYN-133, SYN-134 |
| Cross-bundle merge | ADR-014 | Low | stays deferred to v0.5+ |
| HTTP discovery | ADR-014 | Backlog | stays deferred |
| Sigstore-style transparency log | ADR-014 | Low: no consumer asking | stays deferred to v0.5+ |
2.5 Federation debt
| Item | Status | Severity | v0.4 ticket |
|---|---|---|---|
| Cross-workspace write entity references (D3 v0.3: “kept read-only”) | Read shipped via SYN-117; write deferred | Medium | stays deferred: needs more user-side demand |
syn ws clone <git-url> lifecycle | Not implemented | Medium: adoption / portability story | SYN-143 |
syn ws fork, syn ws archive | Not implemented | Low | stays deferred |
2.6 Extensibility (new in v0.4)
| Item | Status | Source |
|---|---|---|
syn-lsp editor companion (slug / type / tag completions) | Already filed | SYN-130 (v0.4 milestone since 2026-05-25) |
mcp/server.rs refactor into submodules (ADR-015) | Already filed | SYN-150 (v0.4 milestone since 2026-05-25) |
2.7 Documentation debt
| Item | Status | v0.4 ticket |
|---|---|---|
docs/IDENTITY.md user-facing (covers bundle + curriculum) | Not written | SYN-149 |
| ADR-016: portable identity v2 (mandatory crypto + revocation) | Not written | SYN-147 |
| ADR-017: curriculum schema (experience kind, skill derivation, CV format) | Not written | SYN-148 |
3. Cross-check vs prior hypotheses
This brief was written against the v0.3 brief. The cross-check is shorter than v0.3’s because the goal is closing v0.3’s loops, not re-litigating direction.
| v0.3 deferral | Status in v0.4 | Reason |
|---|---|---|
| Block A: Time & audit | Completion: SYN-135 / 136 / 137 / 141 / 142 / 146 close the gaps | All flagged High severity in §2 |
| Block B: MCP resources + prompts + tasks | Completion: SYN-138 (Tasks real), SYN-139 (pagination), SYN-140 (tag redaction) | All flagged High/Medium in §2 |
| Block C: Ingestors | Stays deferred (post-v0.5) | Owner decision 2026-05-25: external-API conflict |
| Block D: Briefings | Stays as v0.3 shipped (syn audit stale is the briefing surface) | No new signal |
| Bet 1: Portable identity | Completion + expansion: SYN-131 (crypto + revoke), SYN-132 (experience), SYN-133 (CV) | Owner-flagged future direction in ADR-014 |
| Bet 2: Decision-trace frontmatter | Already shipped; refinement via SYN-137 (x-ai-history) | Open question from ADR-012 |
| Bet 3: Stale advisory | Already shipped; no change | Heuristic refinement out of scope |
| Bet 4: Capability disclosure | Shipped type-level; completion via SYN-140 (tag-level) | Was promised in bet, half-shipped |
Bet 5: syn audit replay | Shipped read-only; completion via SYN-136 (real --execute) | Was promised in bet, half-shipped |
D2: syn agent | Cut from v0.4 to v0.6 (owner decision 2026-05-25) | Lands after semantic layer matures |
syn-lsp (D4 in v0.3 cross-check) | Already filed as SYN-130 | Owner greenlit during v0.3 |
New thread (not in v0.3 brief)
mcp/server.rsrefactor (SYN-150) per ADR-015: file crossed 1,100 lines during v0.3. Architecture is now load-bearing; refactor lands first in v0.4 to unblock every other MCP-touching ticket.
4. Positioning
v0.4 does not move Synapse on the competitor matrix; the v0.3 matrix already captured the lanes Synapse occupies. v0.4 deepens the lanes:
| Axis | v0.3 state | v0.4 target |
|---|---|---|
| Auditable AI writes (EU AI Act-grade) | partial: replay is visual diff, no model re-run; no verify | full: syn audit verify gates CI; syn audit replay --execute round-trips through MCP client |
| Portable knowledge identity | prototype: no crypto, no revoke, no CV | production-grade: ed25519 mandatory, revocation list, syn cv export |
| Cross-workspace capability disclosure | type-level | tag + type level (SYN-140) |
| MCP-native surface (resources / prompts / tasks) | resources + prompts; Tasks placeholder | Tasks real (SYN-138); pagination (SYN-139) |
| Editor integration | none (syn open only) | LSP companion (SYN-130): completions in Cursor, Helix, Neovim, VSCode, Zed |
| Internal architecture | mcp/server.rs red-tier per ADR-015 | split per use case, all files green-tier (SYN-150) |
| Curriculum surface | none | first-class: syn experience add, skills, CV |
Defensible moat preserved. No competitor can ship “local-first auditable AI second brain that the human owns across employers”; v0.4 closes the half-shipped edges of that pitch and lets the user prove it (verify hash, re-run prompt, export CV) without trusting Synapse on faith.
5. Recommendation
Theme
“Refinement & extensibility: finish what we started, open the doors.”
Prioritised blocks
| # | Block | Justification | Cost | Defensible? |
|---|---|---|---|---|
| 1 | Refactor mcp/server.rs (SYN-150) | ADR-015 mandates it; blocks every other MCP ticket by merge-conflict risk. Lands FIRST. | L | Architecture: internal, no marketing |
| 2 | Identity completion: ed25519 keygen + mandatory signing + revocation (SYN-131); syn experience add + skills auto-derive (SYN-132); syn cv export Markdown (SYN-133); ADR-016 + ADR-017; docs/IDENTITY.md (SYN-149) | Bundle without crypto verifies nothing. Curriculum surface owner-flagged in ADR-014. Closes the bet that v0.3 only sketched. | L | Very strong: no SaaS can ship CV from data the human owns |
| 3 | Audit completion: syn audit verify (SYN-135); syn audit replay --execute (SYN-136); x-ai-history chain (SYN-137); syn doctor --lint-provenance (SYN-146) | Closes EU AI Act bet to real replay + hash verification. Without these, the audit story is decorative. | M+L | Strong: git-diff-able + CI-gateable |
| 4 | syn-lsp companion (SYN-130) | Cheapest possible IDE integration; one binary, every LSP editor. Adoption play. | L | Medium: anyone can build, but Synapse owns the workspace semantics |
| 5 | MCP completion: Tasks real (SYN-138); resources pagination (SYN-139); tag-level federation redaction (SYN-140) | All flagged High severity in §2 audit. Closes promises made on the v0.3 wire. | M+M+M | Strong: MCP-native is the moat |
| 6 | Time-travel completion: syn at <ref> graph/list/info (SYN-141); full as-of FTS rebuild (SYN-142) | Closes the time-travel surface. Compliance review of v0.3 shape exposes the “current hits at ref” misleading. | M+L | Medium: only meaningful in git-tracked workspaces |
| 7 | Workspace lifecycle starter: syn ws clone <git-url> (SYN-143) | Aligns with portable-identity story (human carries graph across machines). Forks / archives stay deferred. | M | Medium |
Explicit non-goals for v0.4
Same as §1.2 plus reinforced:
syn agentautonomous loop → v0.6 (owner decision).- Semantic search / embeddings → v0.5.
- GitHub / Linear ingestors → post-v0.5.
- Sigstore transparency log, cross-bundle merge, HTTP discovery → v0.5+.
- TUI /
syn ui, share entity granular → backlog. - Schema declarable per-workspace → v1.0 candidate.
6. Disruptive bets
Most of the disruption is already inside the recommended blocks (curriculum surface, real audit replay, mandatory crypto). Two adjacent bets worth keeping on the radar but not scoped for v0.4:
Bet 1: syn cv export --as pdf (v0.5 candidate)
Markdown CV ships in v0.4 (SYN-133). PDF rendering depends on a deterministic Markdown→PDF path: adding it now risks pulling in a heavy chain (typst, weasyprint, headless chromium). Reassess in v0.5 once the Markdown surface stabilises and user feedback narrows the formatting expectations.
Bet 2: syn audit verify as a GitHub Action
v0.4 ships syn audit verify as a local CLI returning a non-zero exit code on hash mismatch. A natural follow-up is a tiny GitHub Action wrapper that runs it in PR / nightly cron and posts a status check. Out of v0.4 (action / marketplace publication is its own work), but the CLI shape stays compatible.
7. Ticket sketch (provisional IDs SYN-130..SYN-149 + SYN-150)
These are sketches, not GitHub issues. Issues open with the milestone.
Core (must land for v0.4 to be honest)
| Sketch ID | Block | Title | Size |
|---|---|---|---|
| SYN-150 | Refactor | mcp/server.rs split into submodules (ADR-015) | L |
| SYN-130 | Extensibility | syn-lsp companion (slug/type/tag completions in any LSP editor) | L |
| SYN-131 | Identity | syn identity keygen + ed25519 mandatory signing + revocation list | L |
| SYN-132 | Identity | syn experience add + skills auto-derive from tag frequency | M |
| SYN-133 | Identity | syn cv export Markdown deterministic from bundle + workspace | M |
| SYN-135 | Audit | syn audit verify: re-hash pending vs audit.payload_sha256, CI-friendly | M |
| SYN-136 | Audit | syn audit replay --execute: real model re-run via MCP client | L |
| SYN-138 | MCP | MCP Tasks real (reindex + federated_search progress reporting) | M |
| SYN-141 | Time | syn at <ref> -- graph|list|info subcommands | M |
| SYN-147 | ADRs | ADR-016 portable identity v2 (mandatory crypto + revocation) | M |
| SYN-148 | ADRs | ADR-017 curriculum schema (experience kind, skill derivation, CV format) | M |
| SYN-149 | Docs | docs/IDENTITY.md user-facing + curriculum section | M |
Stretch (lands if window allows; otherwise rolls to v0.5)
| Sketch ID | Block | Title | Size |
|---|---|---|---|
| SYN-137 | Audit | x-ai-history chain on entity re-mutations | M |
| SYN-139 | MCP | MCP resources pagination via cursor | M |
| SYN-140 | MCP | Tag-level federation redaction (SearchHit carries tags) | M |
| SYN-142 | Time | Full as-of FTS index reconstruction (sandbox index) | L |
| SYN-143 | Lifecycle | syn ws clone <git-url> | M |
| SYN-146 | Audit | syn doctor --lint-provenance | M |
Total: 18 sketched tickets (12 core + 6 stretch). SYN-150 lands first to unblock every other MCP-touching ticket. Identity (SYN-131, 132, 133) is the second-priority lane because it carries the most owner-flagged work and the most disruptive surface (curriculum).
Estimate 6-8 weeks for core at the v0.3 pace; +2-3 weeks for stretch.
8. Risk register
| Risk | Severity | Mitigation |
|---|---|---|
| Scope creeps past 8 weeks | High | Stretch tickets (SYN-137/139/140/142/143/146) are explicit cuttables; core ships even if stretch slips to v0.5. |
| SYN-150 refactor introduces regressions in MCP wire surface | High | Acceptance criteria already require byte-stable JSON for tools/list, prompts/list, resources/list. Smoke compares before/after with jq. |
syn audit replay --execute (SYN-136) needs an MCP client roundtrip: clients differ in how they accept server-initiated calls | High | Implement against the rmcp 1.7 sampling API where supported; document explicit “not available with this client” fallback. |
| ed25519 mandatory signing breaks v0.3 bundle import path | High | v0.4 import accepts unsigned bundles with explicit --allow-unverified and a stderr warning. Export-side always signs. ADR-016 documents the migration. |
| Curriculum surface (SYN-132/133) ambition exceeds v0.4 | Medium | Markdown-only syn cv export; PDF deferred. Skills auto-derive uses only tag frequency in v0.4; richer signals (project depth, decision count) deferred. |
| MCP Tasks spec still RC at v0.4 ship time | Medium | Keep mcp_tasks feature flag opt-in. Implement against the RC as-shipped; document the version pinned in ADR-016 footnote. |
syn ws clone <git-url> shells out to git (CLAUDE.md forbids) | Low | Use gix::clone not subprocess; already in dep tree for SYN-68. |
syn experience add overlaps with capture_fact semantically | Medium | syn experience writes the attested_involvement array on the self: true person; capture_fact writes free-form entities. Different storage, different scope. ADR-017 spells it out. |
9. Open decisions
All resolved on 2026-05-25:
| # | Question | Decision |
|---|---|---|
| 1 | syn agent autonomous loop in v0.4? | Cut. Lands in v0.6 on top of semantic layer. |
| 2 | Curriculum surface (syn cv export): Markdown only or include PDF? | Markdown only in v0.4. PDF is a v0.5 candidate. |
| 3 | Identity v2: break v0.3 import path or stay backward-compatible? | Stay backward-compatible via --allow-unverified flag. ADR-016 documents the migration with explicit warnings. |
| 4 | Version number | v0.4.0 (no skip). |
| 5 | Milestone opening | Open immediately. Milestone #6 already exists; this brief fills it. |
The brief is accepted and actioned.
10. References
Inputs internos
- v0.3 brief: every “deferred to v0.4” cross-referenced.
- ADR-012 Provenance frontmatter: §Open question (x-ai-history).
- ADR-013 audit.ndjson: §Consequences (prev_hash deferred),
audit verifyimplicit. - ADR-014 Portable identity bundle: §Future direction (curriculum surface owner-flagged), §v0.3 explicit non-goals.
- ADR-015 File-size policy: SYN-150 mandate.
docs/AUDITABILITY.md: Phase 1 limitation onsyn at <ref>is documented and now closed by SYN-141 / SYN-142.docs/business/ROADMAP.md: v0.4 placeholder.docs/business/BUSINESS_RULES.md§12: no rule change required by v0.4.
Inputs externos (carry-over from v0.3 brief)
- MCP 2026-07-28 RC: Tasks extension spec watch (SYN-138).
- SEP-1649 .well-known/mcp discovery: capability disclosure trajectory (SYN-140 tag-level).
- EU AI Act Article 50:
syn audit verify(SYN-135) and replay (SYN-136) are the regulatory follow-throughs.