Expose the Statement Vault to external agents over MCP

A user wants to manage patrimonial history — a document-backed record of a
family's wealth where every figure traces back to the statement it came from —
by pointing an external agent harness at Sure. That model belongs in the
harness, not in Sure: it needs numbered build deltas, golden tests and closed
periods that a mutable Postgres row cannot provide.

What Sure was missing was the seam. The Statement Vault already does most of
the work — original bytes retained, SHA-256 dedup, period detection, account
matching with a confidence score, reconciliation against ledger balances, and a
month-by-month coverage map — but it is reachable only from the web UI. An
agent could not archive a document, cite one, or check for gaps.

Adds five preview MCP tools over what already exists, plus a citation grammar
for values the agent writes:

- upload_account_statement, list_account_statements, get_account_statement,
  get_statement_coverage
- record_valuation, whose source citation is parsed rather than trusted:
  ["estimated: "] citation [" (grade: A|B|C)"]. An uncited or free-styled
  value is rejected at the write boundary instead of landing in the ledger
  looking authoritative.

link and reject are deliberately not exposed. Attaching a statement to an
account is the human's decision, and the vault UI is where it is made; the
agent reports the suggested match and stops there.

Assistant.function_classes now takes a user so preview tools stay out of the
default surface. They are hidden from tools/list and not callable by name
without the preference enabled, and the vault tools re-check the manager role
and per-account permissions, since MCP calls never pass through a controller.

Docs: the blueprint this implements, and a guide covering which side owns which
layer, the vocabulary map between the two, the monthly runbook, and the gaps
(non-user holders, non-statement documents, one value per date).

No migrations, no API endpoints, no UI.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JFDp9HhXDeswadu4cxFojn

test/models/assistant/function/get_account_statement_test.rb

@@ -0,0 +1,73 @@
+require "test_helper"
+
+class Assistant::Function::GetAccountStatementTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:family_admin)
+    @account = accounts(:depository)
+    @function = Assistant::Function::GetAccountStatement.new(@user)
+  end
+
+  test "returns statement identity and reconciliation checks" do
+    statement = create_statement(account: @account)
+    statement.update!(
+      period_start_on: Date.new(2024, 1, 1),
+      period_end_on: Date.new(2024, 1, 31),
+      opening_balance: 100,
+      closing_balance: 200,
+      currency: @account.currency
+    )
+
+    result = @function.call("statement_id" => statement.id)
+
+    assert result[:success]
+    assert_equal statement.id, result[:statement][:id]
+    assert_equal statement.content_sha256, result[:statement][:content_sha256]
+    assert_equal "2024-01-31", result[:statement][:period_end_on]
+    assert result[:statement].key?(:reconciliation_checks)
+  end
+
+  test "returns not_found for an unknown id" do
+    result = @function.call("statement_id" => SecureRandom.uuid)
+
+    assert_not result[:success]
+    assert_equal "not_found", result[:error]
+  end
+
+  test "returns not_found for a non-uuid id" do
+    result = @function.call("statement_id" => "nope")
+
+    assert_not result[:success]
+    assert_equal "not_found", result[:error]
+  end
+
+  test "returns not_found for a statement the user cannot view" do
+    statement = create_statement(account: accounts(:other_asset))
+
+    result = Assistant::Function::GetAccountStatement.new(users(:family_member)).call("statement_id" => statement.id)
+
+    assert_not result[:success]
+    assert_equal "not_found", result[:error]
+  end
+
+  test "refuses a user who cannot manage the vault" do
+    statement = create_statement(account: @account)
+
+    result = Assistant::Function::GetAccountStatement.new(family_guest).call("statement_id" => statement.id)
+
+    assert_not result[:success]
+    assert_equal "forbidden", result[:error]
+  end
+
+  private
+    def create_statement(account:)
+      AccountStatement.create_from_upload!(
+        family: @user.family,
+        account: account,
+        file: uploaded_file(
+          filename: "statement-#{SecureRandom.hex(4)}.csv",
+          content_type: "text/csv",
+          content: "date,amount\n2024-01-01,#{SecureRandom.random_number(1000)}\n"
+        )
+      )
+    end
+end

test/models/assistant/function/get_statement_coverage_test.rb

@@ -0,0 +1,56 @@
+require "test_helper"
+
+class Assistant::Function::GetStatementCoverageTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:family_admin)
+    @account = accounts(:depository)
+    @function = Assistant::Function::GetStatementCoverage.new(@user)
+  end
+
+  test "reports a covered month and the months with no statement on record" do
+    # A full prior year: every month is inside the expected window, so the one
+    # month with a statement is covered and the rest report as missing.
+    january = Date.current.prev_year.beginning_of_year
+    statement = AccountStatement.create_from_upload!(
+      family: @user.family,
+      account: @account,
+      file: uploaded_file(filename: "statement.csv", content_type: "text/csv", content: "date,amount\n2024-01-01,1\n")
+    )
+    statement.update!(period_start_on: january, period_end_on: january.end_of_month)
+
+    result = @function.call("account_id" => @account.id, "year" => january.year)
+
+    assert result[:success]
+    assert_equal @account.id, result[:account][:id]
+    assert_equal january.year, result[:year]
+
+    covered = result[:months].find { |m| m[:month] == january.strftime("%Y-%m") }
+    assert_equal "covered", covered[:status]
+    assert_includes covered[:statement_ids], statement.id
+
+    february = result[:months].find { |m| m[:month] == january.next_month.strftime("%Y-%m") }
+    assert_equal "missing", february[:status]
+  end
+
+  test "rejects a non-uuid account id" do
+    result = @function.call("account_id" => "nope")
+
+    assert_not result[:success]
+    assert_equal "invalid_account_id", result[:error]
+  end
+
+  test "rejects an account the user cannot access" do
+    result = Assistant::Function::GetStatementCoverage.new(users(:family_member))
+      .call("account_id" => accounts(:other_asset).id)
+
+    assert_not result[:success]
+    assert_equal "account_not_found", result[:error]
+  end
+
+  test "refuses a user who cannot manage the vault" do
+    result = Assistant::Function::GetStatementCoverage.new(family_guest).call("account_id" => @account.id)
+
+    assert_not result[:success]
+    assert_equal "forbidden", result[:error]
+  end
+end

test/models/assistant/function/list_account_statements_test.rb

@@ -0,0 +1,84 @@
+require "test_helper"
+
+class Assistant::Function::ListAccountStatementsTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:family_admin)
+    @account = accounts(:depository)
+    @function = Assistant::Function::ListAccountStatements.new(@user)
+  end
+
+  test "lists statements with identity and provenance" do
+    statement = create_statement(account: @account, content: "date,amount\n2024-01-01,1\n")
+
+    result = @function.call
+
+    assert result[:success]
+    assert_equal 1, result[:returned]
+    assert_not result[:has_more]
+    payload = result[:statements].first
+    assert_equal statement.id, payload[:id]
+    assert_equal statement.content_sha256, payload[:content_sha256]
+    assert_equal @account.id, payload[:account][:id]
+  end
+
+  test "filters by review status" do
+    create_statement(account: @account, content: "date,amount\n2024-01-01,1\n")
+    create_statement(account: nil, content: "date,amount\n2024-02-01,2\n")
+
+    result = @function.call("review_status" => "unmatched")
+
+    assert result[:success]
+    assert_equal 1, result[:returned]
+    assert_equal "unmatched", result[:statements].first[:review_status]
+  end
+
+  test "filters by content sha256" do
+    statement = create_statement(account: @account, content: "date,amount\n2024-01-01,1\n")
+    create_statement(account: @account, content: "date,amount\n2024-02-01,2\n")
+
+    result = @function.call("content_sha256" => statement.content_sha256)
+
+    assert_equal 1, result[:returned]
+    assert_equal statement.id, result[:statements].first[:id]
+  end
+
+  test "rejects an invalid review status" do
+    result = @function.call("review_status" => "whatever")
+
+    assert_not result[:success]
+    assert_equal "invalid_review_status", result[:error]
+  end
+
+  test "rejects an invalid date filter" do
+    result = @function.call("period_start_on_or_after" => "last tuesday")
+
+    assert_not result[:success]
+    assert_equal "invalid_date", result[:error]
+  end
+
+  test "hides statements linked to accounts the user cannot see" do
+    private_account = accounts(:other_asset)
+    create_statement(account: private_account, content: "date,amount\n2024-03-01,3\n")
+
+    result = Assistant::Function::ListAccountStatements.new(users(:family_member)).call
+
+    assert result[:success]
+    assert_empty result[:statements]
+  end
+
+  test "refuses a user who cannot manage the vault" do
+    result = Assistant::Function::ListAccountStatements.new(family_guest).call
+
+    assert_not result[:success]
+    assert_equal "forbidden", result[:error]
+  end
+
+  private
+    def create_statement(account:, content:)
+      AccountStatement.create_from_upload!(
+        family: @user.family,
+        account: account,
+        file: uploaded_file(filename: "statement-#{Digest::MD5.hexdigest(content)}.csv", content_type: "text/csv", content: content)
+      )
+    end
+end

test/models/assistant/function/record_valuation_test.rb

@@ -0,0 +1,89 @@
+require "test_helper"
+
+class Assistant::Function::RecordValuationTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:family_admin)
+    @account = accounts(:other_asset)
+    @function = Assistant::Function::RecordValuation.new(@user)
+    @source = "Appraisal report 2024-06-30 (grade: A)"
+  end
+
+  test "records a valuation and stores the citation on the entry" do
+    result = nil
+
+    assert_difference "@account.entries.valuations.count", 1 do
+      result = @function.call(params)
+    end
+
+    assert result[:success]
+    assert_not result[:replaced_existing]
+    assert_equal "A", result[:provenance][:grade]
+
+    entry = Entry.find(result[:entry_id])
+    assert_equal @source, entry.notes
+    assert_equal 1234.56.to_d, entry.amount
+  end
+
+  test "flags when an existing valuation on the same date is replaced" do
+    @function.call(params)
+
+    result = @function.call(params(amount: 2000))
+
+    assert result[:success]
+    assert result[:replaced_existing]
+  end
+
+  test "rejects a citation that does not follow the grammar" do
+    result = @function.call(params(source: "estimated: pulled from a spreadsheet"))
+
+    assert_not result[:success]
+    assert_equal "invalid_source_citation", result[:error]
+    assert_match(/reliability grade/, result[:message])
+  end
+
+  test "rejects a missing citation" do
+    result = @function.call(params(source: ""))
+
+    assert_not result[:success]
+    assert_equal "invalid_source_citation", result[:error]
+  end
+
+  test "rejects an unparseable date" do
+    result = @function.call(params(date: "June 30th"))
+
+    assert_not result[:success]
+    assert_equal "invalid_date", result[:error]
+  end
+
+  test "rejects a non-numeric amount" do
+    result = @function.call(params(amount: "a lot"))
+
+    assert_not result[:success]
+    assert_equal "invalid_amount", result[:error]
+  end
+
+  test "rejects an account the user cannot write to" do
+    result = Assistant::Function::RecordValuation.new(users(:family_member)).call(params)
+
+    assert_not result[:success]
+    assert_equal "account_not_found", result[:error]
+  end
+
+  test "accepts an estimated citation carrying a grade" do
+    result = @function.call(params(source: "estimated: linear interpolation over 2024-01 / 2024-12 anchors (grade: C)"))
+
+    assert result[:success]
+    assert result[:provenance][:estimated]
+    assert_equal "C", result[:provenance][:grade]
+  end
+
+  private
+    def params(overrides = {})
+      {
+        "account_id" => @account.id,
+        "date" => "2024-06-30",
+        "amount" => 1234.56,
+        "source" => @source
+      }.merge(overrides.transform_keys(&:to_s))
+    end
+end

test/models/assistant/function/upload_account_statement_test.rb

@@ -0,0 +1,114 @@
+require "test_helper"
+
+class Assistant::Function::UploadAccountStatementTest < ActiveSupport::TestCase
+  setup do
+    @user = users(:family_admin)
+    @account = accounts(:depository)
+    @function = Assistant::Function::UploadAccountStatement.new(@user)
+    @content = "date,amount\n2024-01-01,1\n"
+  end
+
+  test "has correct name and is not strict" do
+    assert_equal "upload_account_statement", @function.name
+    assert_not @function.strict_mode?
+    assert_includes @function.params_schema[:required], "content_base64"
+  end
+
+  test "stores a statement in the vault" do
+    result = nil
+
+    assert_difference "AccountStatement.count", 1 do
+      result = @function.call(params(filename: "statement.csv"))
+    end
+
+    assert result[:success]
+    assert_not result[:duplicate]
+    assert_equal Digest::SHA256.hexdigest(@content), result[:statement][:content_sha256]
+    assert_equal "statement.csv", result[:statement][:filename]
+  end
+
+  test "re-uploading identical bytes returns the existing statement without creating a row" do
+    first = @function.call(params(filename: "statement.csv"))
+
+    assert_no_difference "AccountStatement.count" do
+      second = @function.call(params(filename: "different-name.csv"))
+
+      assert second[:success]
+      assert second[:duplicate]
+      assert_equal first[:statement][:id], second[:statement][:id]
+    end
+  end
+
+  test "links to an account when one is given" do
+    result = @function.call(params(filename: "statement.csv", account_id: @account.id))
+
+    assert result[:success]
+    assert_equal @account.id, result[:statement][:account][:id]
+    assert_equal "linked", result[:statement][:review_status]
+  end
+
+  test "leaves the statement unmatched when no account is given" do
+    result = @function.call(params(filename: "statement.csv"))
+
+    assert_equal "unmatched", result[:statement][:review_status]
+    assert_nil result[:statement][:account]
+  end
+
+  test "reports a duplicate without disclosing a statement filed against a hidden account" do
+    @function.call(params(filename: "statement.csv", account_id: accounts(:other_asset).id))
+
+    result = Assistant::Function::UploadAccountStatement.new(users(:family_member))
+      .call(params(filename: "statement.csv"))
+
+    assert result[:success]
+    assert result[:duplicate]
+    assert_equal Digest::SHA256.hexdigest(@content), result[:statement][:content_sha256]
+    assert_nil result[:statement][:account]
+    assert_nil result[:statement][:filename]
+  end
+
+  test "refuses a user who cannot manage the vault" do
+    result = Assistant::Function::UploadAccountStatement.new(family_guest).call(params(filename: "statement.csv"))
+
+    assert_not result[:success]
+    assert_equal "forbidden", result[:error]
+  end
+
+  test "rejects an unsupported file type" do
+    result = @function.call(params(filename: "notes.txt"))
+
+    assert_not result[:success]
+    assert_equal "unsupported_file_type", result[:error]
+  end
+
+  test "rejects content that is not base64" do
+    result = @function.call("filename" => "statement.csv", "content_base64" => "not base64 @@@")
+
+    assert_not result[:success]
+    assert_equal "invalid_content", result[:error]
+  end
+
+  test "rejects an unknown account_id rather than silently uploading unlinked" do
+    result = @function.call(params(filename: "statement.csv", account_id: SecureRandom.uuid))
+
+    assert_not result[:success]
+    assert_equal "account_not_found", result[:error]
+  end
+
+  test "rejects a file whose contents do not match its extension" do
+    result = @function.call(
+      "filename" => "statement.pdf",
+      "content_base64" => Base64.strict_encode64("this is not a pdf")
+    )
+
+    assert_not result[:success]
+    assert_equal "invalid_file", result[:error]
+  end
+
+  private
+    def params(filename:, account_id: nil, content: @content)
+      { "filename" => filename, "content_base64" => Base64.strict_encode64(content) }.tap do |p|
+        p["account_id"] = account_id if account_id
+      end
+    end
+end