Declared account value

What the numbers mean

Declared value affected associates a current account declaration with observed activity. Renewal exposure selects accounts by their declared renewal date. Neither proves a failed payment, lost revenue, an invoice, predicted churn or complete profit. Observed purchase-event revenue is a separate measure.

Choose one project and one exact account type. Historical observation windows use current membership and current declarations. Account types and projects can overlap; do not add them. Currencies and nominal payment periods stay separate. A yearly declaration is never prorated into a monthly read. Unknown value, renewal, price, attribution or retention is never zero. A declared amount of "0.0000" is known value and counts in declaration coverage.

Authority and exact account profiles

Financial reads require mcp:read through MCP and both groups:read and groups:business:read. Issue measurements also require errors:read and persons:read; incident measurements additionally require incidents:read. Account model spend uses llm:read, persons:read and both account read grants. Optional run references need agents:read; their absence does not remove the complete query evidence.

Interactive host OAuth can carry explicitly approved financial read grants. For declaration changes, switch to an owner-created, project-bound management API key with those same selected read grants plus groups:business:write, mcp:read for the complete preview and mcp:write for MCP execution. Explicit missing-account creation also requires groups:write. No default investigation bundle automatically acquires finance. Capture, application and client delivery keys have no financial authority. Missing scope or unavailable policy is a refusal, never zero.

Preserve exact account type and key, including case, whitespace, punctuation and Unicode. Captured SDK plan, tier and mrr properties remain ordinary properties; they never supply this financial declaration. Alias conflicts remain ambiguous rather than picking an account.

anectico accounts get company ' exact/key ' --project PROJECT_ID --include-stats --include-business-inputs -o json
anectico accounts list --project PROJECT_ID --type company --include-business-inputs --limit 20 -o json
anectico accounts business get company ' exact/key ' --project PROJECT_ID -o json

The existing get_account_profile action accepts include_stats and include_business_inputs. Preserve its profile_revision, properties_availability and stats_availability independently from optional financial state and provenance. Unavailable statistics carry no count. Opted-in issues impact requires one explicit authorized project; organization-wide collapsed rows cannot be priced. Several account types have separate snapshot receipts and times. Enriched displayed rows supply no combined monetary total. There is no Accounts page or account financial proof address.

Prepare a complete declaration

A set file is one complete customer record, for example declaration.json:

{"plan":"Enterprise","tier":"priority","important":false,"paid_amount":"137.2501","currency":"USD","period_unit":"month","period_count":1,"renewal_date":"2026-11-20","paid_period_start":"2026-10-01T00:00:00Z","paid_period_end":"2026-10-02T00:00:00Z"}

Field	Meaning and validation
plan, tier	Optional exact text, 1–256 UTF-8 bytes; a present empty string refuses.
important	Optional boolean; absent, false and true are distinct.
paid_amount	Nonnegative decimal string, 0–4 fractional digits, at most 99999999999.9999; returned with four digits.
currency, period_unit, period_count	Present together with amount, or all absent. Currency is three uppercase ASCII letters, shape-checked; period is day, week, month or year, count 1–12.
renewal_date	Optional valid civil date, YYYY-MM-DD; a declaration, not an invoice.
paid_period_start, paid_period_end	Optional paired absolute timestamps with microsecond precision; start strictly before end. These explicit bounds govern spend comparison; the nominal period does not infer them.

A plan-only declaration is valid and supplies no money. Omitted or null optional fields remove previous values on replacement. Server-owned revision, state, source and declaration time are not input. Numeric money, unknown or duplicate fields, incomplete tuples and unpaired or rounded paid bounds refuse the whole request before mutation. Ordinary property updates do not refresh financial retention.

Commands and exact input formats

Select the project with --project PROJECT_ID; use -o json for complete machine results.

Job	CLI	MCP action
Read	accounts business get TYPE KEY	get_account_business_inputs
List	accounts business list --type TYPE	list_account_business_inputs
Replace	accounts business set TYPE KEY --file declaration.json --expected-revision 0 --idempotency-key STABLE_KEY	set_account_business_inputs
Clear	accounts business clear TYPE KEY --expected-revision REVISION --idempotency-key CLEAR_KEY	clear_account_business_inputs
Import	accounts business import --file rows.json --format json --idempotency-key BATCH_KEY	batch_set_account_business_inputs
Recover	accounts business write-result --operation-id OPERATION_ID or --idempotency-key STABLE_KEY	get_account_business_write_result
Export	accounts business export --type TYPE --format json	export_account_business_inputs

Discover actions with list_read_actions and list_write_actions. Execute reads through execute_read_action, writes through execute_internal_action. An organization credential must supply project_id; a project-bound key may use its immutable binding. Get, set and clear use exact account_type and account_key. Do not place exact keys inside URL path segments.

List and export support --plan, --tier, --important true|false, --renewal-since, --renewal-until, --currency, --period, --period-count, --minimum-value, --cursor and --limit. --important false is a filter; omission is unfiltered. Minimum value requires a complete currency and period bucket. Follow only the returned cursor with unchanged selectors. Each page is a current observation, with normalized effective selectors, count and read time. Lists include declared and cleared records in exact account-key order; get can also show an undeclared live account. The cursor binds project, account type, purpose and filters. Default page size is 20, maximum 100. Expired content is excluded before filtering, and current disclosure checks run again before returning a page. Pages do not form a frozen global snapshot.

V1 JSON import is a rows array, with integer revision tokens:

[{"account_type":"company","account_key":" exact/key ","expected_revision":0,"record":{"paid_amount":"137.2501","currency":"USD","period_unit":"month","period_count":1},"create_missing":false},{"account_type":"company","account_key":"new-account","expected_revision":0,"record":{"important":true},"create_missing":true}]

CSV requires account_type,account_key,expected_revision. Optional columns are plan, tier, important, paid_amount, currency, period_unit, period_count, renewal_date, paid_period_start, paid_period_end and create_missing. Empty optional cells mean absence; booleans are true or false. Quote commas, quotes and newlines with standard CSV quoting. Unknown or duplicate headers, duplicate coordinates, inconsistent widths or an invalid late row reject the entire file. One import is at most 500 rows and 1 MiB; never split it automatically. --file - reads stdin. All rows use the selected project; org and project fields in a file refuse. MCP and REST write revisions are canonical decimal strings, including "0"; the CLI converts its integer flags and import tokens without floating point.

Preview, confirm and recover

The first set, clear or import returns a server preview and does not apply. Inspect every account's full before and proposed record, presence states, expected revision, required grants and creation effect. An existing account is required unless the person explicitly approves --create-missing on set or create_missing: true on that import row. Creation makes an empty account definition with no person membership.

Show the complete preview before approval. After approval repeat the same file, selectors, revision, actor, project and stable key with --confirm-token SERVER_TOKEN. The token lasts ten minutes and binds that entire proposal. A changed row or stale revision requires a new complete preview; a batch conflict commits no rows. A preview above 4 MiB refuses instead of truncating. There is no automatic confirmation or native bypass.

Retain the operation ID and exact stable key. After a timeout, first read write-result using exactly one of them under the original actor and credential. Recover the first receipt and its original revision transitions, not today's declaration. An identical retry returns that outcome; a different request with the same key conflicts. Missing means outcome unknown, not “no write”. Redacted or expired request binding permits only the retained minimal outcome and cannot reapply the old proposal. Outcome metadata has no automatic time expiry; this does not extend sensitive content lifetime. Never guess by issuing a new key.

Measure impact and rank a full eligible population

anectico issues value-impact ISSUE_ID --project PROJECT_ID --account-type company --since 2026-10-15T00:00:00Z --until 2026-10-16T00:00:00Z --env production --limit 1 -o json
anectico accounts affected-value --project PROJECT_ID --account-type company --since 2026-10-15T00:00:00Z --until 2026-10-16T00:00:00Z --issue-id ISSUE_A --issue-id ISSUE_B -o json
anectico issues list-by-value --project PROJECT_ID --account-type company --since 2026-10-15T00:00:00Z --until 2026-10-16T00:00:00Z --currency USD --period month --period-count 1 --order value --env production --limit 1 -o json

get_account_value_impact measures one issue, an explicit issue union or the whole selected service or project window. list_issues_by_account_value ranks every eligible canonical issue before limiting; an older valuable issue can outrank the newest page. It is a current top list with eligible, returned and omitted counts and no cursor. value uses exact selected-bucket money; importance,value first compares distinct marked-important accounts, then value. Importance has no invented coefficient. Known zero and missing value stay different. Per-issue amounts overlap: never sum ranked rows to claim a project or incident total.

Issue and window reads share --service, --release, --env, --platform, --mechanism and --query; ranking additionally has --status. All share paired --renewal-since and --renewal-until, bucket, order and limit. MCP uses service_name, environment and period_unit for CLI --service, --env and --period. Renewal intervals include the first date and exclude the last. Missing dates and valued accounts in other buckets remain explicit.

Read coverage before repeating amounts: for example “12 of 40 affected accounts have a declared value.” Preserve missing or cleared value, definition gaps, importance true, false and unset, renewal coverage, attribution remainders and exact unshown totals. The same account counts once across an explicit union, regardless of occurrences or people. A display cap never changes the full denominator or buckets. These observations do not certify complete incoming telemetry.

An MCP result_set_id stays the same across a server rebuild when the query and complete returned result are unchanged. A new response timestamp or changed evidence can still produce a different ID; the ID does not retain an earlier result.

Read an incident union and live proof

anectico incidents value-impact INCIDENT_ID --project PROJECT_ID --account-type company --since 2026-10-15T00:00:00Z --until 2026-10-16T00:00:00Z --limit 1 -o json

get_incident_account_value_impact uses one stable selection of linked error issues and one account union. Shared accounts contribute once. Checked links preserve original and canonical issue references, local version, counts and snapshot provenance. Mixed supported and unsupported sources measure linked error activity only. Alert-only, anomaly-only and empty-link incidents have insufficient_evidence with no money; a failed required source refuses the whole read, with no successful partial total. Incident selectors cannot override links with a service or issue.

Only existing issue and incident proof pages display live money. A triage row's issue link carries that exact single-issue absolute query, including all occurrence, renewal and bucket selectors. The read-only card uses current authority and current evidence. Compare baselines only when their version and exact query identity agree. Clock-only refreshes and unrelated issues do not imply a change. Changed relevant declarations, memberships or incident links are current changed state; different queries are incomparable. Digests cannot recover earlier amounts. A copied number or a Finding does not create immutable financial history.

Compare observed priced model spend

anectico llm account-spend --project PROJECT_ID --account-type company --account-key ' exact/key ' --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --compare-paid-period --limit 1 -o json

llm_account_spend counts observed model-call spans; a rolled-up parent without a model is not counted again. Client and table prices include known zero. Missing prices or tokens remain explicit unpriced coverage. Allocation needs retained root and identity context establishing one current account of the chosen type. Several people in one account can share a trace; conflicting accounts, unresolved identities, blank identity and missing root context retain unallocated cost and calls. Full priced, unpriced, unallocated and unshown figures precede the output limit.

Cost is exact nano-USD. Arithmetic requires a USD declaration and stored paid bounds equal to the complete, closed requested window. currency_mismatch, period_not_comparable, declared_value_unavailable and incomplete_window supply no ratio or difference. zero_paid_amount has no ratio; a permitted difference can still be present. A matching comparable_priced_cost_only supplies exact numerator, denominator and declared payment less observed priced model cost. Unknown prices still leave total cost unknown. Infrastructure and other serving costs are absent; no full-cost or profitability verdict follows. The aggregate has rerunnable query evidence and no account proof page. Older general spend reads can use an inclusive end; this account read uses the explicit half-open window.

Snapshots, retention and bounds

Preserve requested and effective [since,until) bounds, retention floor and coverage outcome. Partial retention measures only the readable subset. Outside retention means no monetary zero was measured. A complete retained empty cohort is a measured observed zero, with incoming completeness still unknown. Source read, identity snapshot, business snapshot and fresh disclosure validation have their own receipts and times; they are not a global transaction. Erasure, clear, retention invalidation or lost policy can discard an assembled answer even if identity stayed unchanged. Clear followed by redeclaration cannot validate the earlier content.

The engineering bounds and measured population ceilings are in limits. Oversized exact jobs refuse as a whole. A shorter display limit never licenses truncated sums, automatic batch splitting, currency conversion or annual-period proration. Intended-bound capacity and composed and browser qualification remain separate; installable skills and case definitions do not imply a real-host pass. The connection and automated-work catalog adds no separate account-value allowance or query charge.

Export, clear and privacy

Successful declaration export must explicitly configure both account-properties content allowances, preserving the rest of the policy:

Content class	Sink	Decision
group_properties	read	allow
group_properties	export	allow

Default EXPORT is denied. Neither financial grants nor export:read overrides either decision. Every export page checks both under current authority before predicates and disclosure. Policy failure or revocation on a later page makes the export incomplete; never change policy merely to bypass a refusal.

JSON export contains version 1, semantics, exact selection, current pages with provenance and completion. NDJSON emits manifest, page, declaration and completion; CSV uses those same record_kind values with page metadata, selection_json and optional-field _present columns. --format json, ndjson or csv streams machine data to stdout and diagnostics to stderr. Require successful completion with page and row counts; failed or canceled streams exit nonzero without that completion. A partial JSON file can be syntactically incomplete. Export is live current-page data, not one frozen snapshot, a workspace bundle, an import file or backup proof.

Clear deliberately removes customer fields and advances revision, while permitting a later fresh declaration. Permanent account erasure removes reconstructable account content and prevents recreation. Shared account declarations remain when a member is erased and are excluded from that member's archive. If the account itself is the subject, request account erasure explicitly; an email-shaped key does not prove personal ownership. Retention follows the original declaration time. Sensitive receipt bindings are minimized or destroyed and cannot authorize reapply. Already downloaded copies are outside later erasure.

Current identities and membership

Financial measurement uses complete current identities and current account membership, including known aliases that had no activity in the observation window. A UUID-shaped event identifier is still an exact declared identifier; it is never treated as a person automatically. If one person's aliases currently belong to different accounts of the selected type, that person's activity is ambiguous and is assigned to neither account. Different people belonging to one account do not multiply its declared value. Missing membership or a missing account definition is not monetary zero.

Complete identity context is bounded to 250,000 requested and expanded identifiers together, with a 32-MiB context ceiling. Account context is bounded to 100,000 unique account keys and 32 MiB. A read that exceeds a ceiling refuses completely. These initial bounds remain subject to workload qualification; no partial monetary total is presented as exact.

Local receipts and disclosure checks

A financial read carries separate telemetry time, identity observations, account context time and receipt, and final visibility-check time. These are local observations, not one globally atomic snapshot. Even past observation windows use current membership and current declarations; historical valuation is unsupported.

The read checks identity again before returning. If identity changed, it discards and retries the entire assembly once within the original deadline and work budget. Repeated change refuses with identity_changed. It then checks that every account's original content is still visible. Erasure, clearing, expired original content or unavailable privacy decisions refuse the whole financial body even when identity stayed unchanged. Clear followed by a new declaration does not revive an earlier record. An ordinary later replacement or membership change may preserve the explicitly dated earlier context; the receipt states which context was used.

These checks accompany financial reads and require no separate snapshot command. The ready account-value skill teaches management and investigation; host qualification is separate.