Power features: write modes, capabilities, composite publish, invocation descriptors

[DecisionNerd]

Problem

Engineer/agent reproducibility and write-coordination surfaces (write modes, capabilities, composite transactions, invocation descriptors) are invisible in the extension.

Tracks under #1 (Phase 4).

Objective

Expose write mode and capabilities in Check Environment / status; Advanced palette commands for enable capability, prepare/invoke descriptor, list algorithm runs, and expert composite publish — agent-exportable artifacts.

Debt / regime

• Debt type: development + product-framing
• Quality regime: B (product) / A (compute correctness for descriptors)

Requirements

• Show write mode on open/Check Environment (default single_writer); Advanced command to open with queued_writer / optimistic_multi_writer when supported.
• GraphForge: Show Capabilities / Enable Capability… (flat).
• Advanced: prepare/invoke descriptor for a verb path; list algorithm runs; export last descriptor fingerprint/bytes to an editor (agent-friendly).
• Composite publish entry is Advanced-only with link to engine docs; no visual builder.
• Destructive/expert ops require confirm.

Acceptance Criteria

• Write mode visible in Check Environment / status
• Descriptor export works for at least one verb path (e.g. rank)
• Composite entry is Advanced-only with documentation link
• Enable Capability is explicit and confirmable

BDD Completion Scenarios

Scenario: Write mode visible
Given open project
When user runs Check Environment
Then write mode is reported

Scenario: Export descriptor
Given open project
When user prepares a rank invocation and exports descriptor
Then editor buffer contains fingerprint/canonical artifact

Implementation Notes

• writeMode options on construct; enableCapability, projectCapabilities
• prepare*Invocation, invokeDescriptor, invokeRecorded, listAlgorithmRuns
• publishCompositeTransaction — expert path only
• Align with Setup UX: detect @graphforge/node, install/link binding, detect or init project #2 Check Environment output

Observability

Report mode + capabilities list; never log full composite payloads by default.

Security And Privacy

Composite/capability changes mutate project — confirm; no secrets in exported descriptors.

Testing

• Unit for mode/capability formatting
• Manual expert paths gated on binding
• Document non-automated rationale if composite too heavy for CI

Documentation

• README Power / Advanced commands; link ADR 0015 write modes + composite contract docs

Non-Goals

• Full composite visual builder
• MCP exposure (later)
• Changing engine write-mode semantics

Related Issues

• Parent: Tracker: Wire GraphForge engine workbench in VS Code (palette-first) #1
• Setup / Check Environment: Setup UX: detect @graphforge/node, install/link binding, detect or init project #2
• Analyst verbs catalog: Analyst verbs: load by= from algorithm descriptor contracts; palette-first invoke #4

Open Questions

• Whether queued/optimistic modes need a dedicated “reopen project with mode” confirm flow

[coderabbitai]

🔗 Related PRs

CurateLabs/startops-nextjs#47 - Promote DocSlime product and design docs [merged]
CurateLabs/startops-nextjs#73 - Promote staging to production [merged]
CurateLabs/startops-nextjs#115 - Promote observability and unit economics to production [merged]
CurateLabs/graphforge#217 - feat(api): add embedded write modes [merged]
CurateLabs/graphforge#220 - feat(bindings): expose embedded write modes [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[DecisionNerd]

Implemented on feat/phase-3-4-search-power (commit f2ee652, in isolated worktree graphforge-vscode-phase34):

src/commands/power.ts (+ session.writeMode, session.reopenWithWriteMode, and write-mode-aware attachForge in graphForgeSession.ts):

• GraphForge: Open with Write Mode… — reopen the active project under single_writer / queued_writer / optimistic_multi_writer; hard-confirmed since it recreates the native engine handle.
• GraphForge: Enable Capability… — capability id + version, hard-confirmed atomic manifest mutation.
• GraphForge: Export Invocation Descriptor… — prepares (does not execute) a descriptor for one of rank/cluster/analyze/similar, shows its fingerprint/canonical bytes in a JSON buffer, with an optional immediate "Invoke" follow-up.
• GraphForge: List Algorithm Runs — lists recorded runs from the ledger.
• GraphForge: Publish Composite Transaction… (Advanced) — deliberately Advanced-only, no visual builder: warns it's expert-only, links to engine docs, opens a JSON editor buffer, then requires a modal confirm before the single-shot publish.
• graphforge.showCapabilities now also shows the active write mode and live (engine) capabilities alongside the on-disk manifest capabilities.
• Every new binding call is feature-detected (typeof forge.method === "function") and raises UnsupportedByBindingError with a clear message when the loaded @graphforge/node predates it.

Gaps: no live-binding integration test in this sandbox (engine is still moving); descriptor export/invoke is only wired for the four non-find/paths verbs per the AC's "at least one verb path" bar — paths/find descriptor prep exists on the session layer (prepareInvocation covers paths too) but isn't yet exposed in this specific command's UI. tsc --noEmit / build / unit tests pass.

[DecisionNerd]

Shipped in PR #14, merged to main at 4a60284.