Research

The research.* family (5 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Apply Decisionsresearch.session.applyDecisions

(DEFERRED). Writes the seam-patched decisions + the seam-derived status (the RESEARCHING->AWAITING_REVIEW auto-flip). { sessionId, decisions, status? }. Not FINALISED.

Call POST /v/research.session.applyDecisions with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool research.session.applyDecisions.

Createresearch.session.create

(DEFERRED). { matterId, addonKey, bucketSchemaKey, initialBuckets?, createdById }. The addon-active + bucket-schema checks stay seam-side reads; the kernel fences the matter in the workspace + inserts. Mints rsess_.

Call POST /v/research.session.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool research.session.create.

Finaliseresearch.session.finalise

(Sensitive)/MEMBER (DEFERRED). Terminal lock. { sessionId, finalisedById }. Idempotent: an already-FINALISED session returns the existing finalised_at.

Call POST /v/research.session.finalise with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool research.session.finalise.

Merge Findingsresearch.session.mergeFindings

(DEFERRED). Writes the seam-merged working_knowledge (additive; the dedupe/cap stays seam-side). { sessionId, workingKnowledge }. Not FINALISED; no CAS (append is additive - preserves the current last-write semantics).

Call POST /v/research.session.mergeFindings with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool research.session.mergeFindings.

Replace Knowledgeresearch.session.replaceKnowledge

(DEFERRED). CAS write of working_knowledge with the AWAITING_REVIEW->RESEARCHING reset. { sessionId, workingKnowledge, expectedUpdatedAt? }. Not FINALISED.

Call POST /v/research.session.replaceKnowledge with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool research.session.replaceKnowledge.