mirror of
https://github.com/we-promise/sure.git
synced 2026-08-04 16:12:14 +00:00
ec38a89d0c
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
90 lines
2.8 KiB
Ruby
90 lines
2.8 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
class Assistant::Function::GetStatementCoverage < Assistant::Function
|
|
include Assistant::Function::StatementVaultSupport
|
|
|
|
class << self
|
|
def name
|
|
"get_statement_coverage"
|
|
end
|
|
|
|
def description
|
|
<<~INSTRUCTIONS
|
|
Report, month by month, which statements the family actually holds for an
|
|
account in a given year — the document-coverage map behind the numbers.
|
|
|
|
Each month comes back with one status:
|
|
|
|
- `covered` — a linked statement covers the month and reconciles
|
|
- `mismatched` — a statement covers it, but its balances disagree with the ledger
|
|
- `missing` — no statement on record; the month's figures have no document behind them
|
|
- `ambiguous` — a statement was suggested for this account but nobody has confirmed the link
|
|
- `duplicate` — two or more linked statements overlap the same month
|
|
- `not_expected` — outside the account's expected statement range
|
|
|
|
Use it before asserting anything about a period: "no statement on record"
|
|
is a legitimate and necessary answer, and is very different from "the
|
|
balance was zero". Use it to tell the user exactly which documents to go
|
|
find.
|
|
|
|
Example:
|
|
|
|
```
|
|
get_statement_coverage({ account_id: "abc123-def456", year: 2026 })
|
|
```
|
|
INSTRUCTIONS
|
|
end
|
|
end
|
|
|
|
def strict_mode?
|
|
false
|
|
end
|
|
|
|
def params_schema
|
|
build_schema(
|
|
required: [ "account_id" ],
|
|
properties: {
|
|
account_id: {
|
|
type: "string",
|
|
description: "UUID of the account to report coverage for."
|
|
},
|
|
year: {
|
|
type: "integer",
|
|
description: "Calendar year. Defaults to the most recent year with expected statements."
|
|
}
|
|
}
|
|
)
|
|
end
|
|
|
|
def call(params = {})
|
|
return not_a_statement_manager unless statement_manager?
|
|
|
|
account_id = params["account_id"].to_s
|
|
return error("invalid_account_id", "account_id must be a UUID.") unless valid_uuid?(account_id)
|
|
|
|
account = family.accounts.accessible_by(user).find_by(id: account_id)
|
|
return error("account_not_found", "No accessible account found with that ID.") unless account
|
|
|
|
coverage = AccountStatement::Coverage.for_year(account, params["year"])
|
|
|
|
{
|
|
success: true,
|
|
account: account_ref(account),
|
|
year: coverage.selected_year,
|
|
available_years: coverage.available_years,
|
|
summary: coverage.summary_counts,
|
|
months: coverage.months.map { |month| month_payload(month) }
|
|
}
|
|
end
|
|
|
|
private
|
|
def month_payload(month)
|
|
{
|
|
month: month.date.strftime("%Y-%m"),
|
|
status: month.status,
|
|
statement_ids: month.statements.map(&:id),
|
|
unconfirmed_statement_ids: month.ambiguous_statements.map(&:id)
|
|
}.compact_blank
|
|
end
|
|
end
|