Skip to content

Personal result and execution foundation

personal-result-v1 and the operation design catalog are the foundation contracts of the personal tools. 67 business-specific tools are active in Registry v20 alongside 51 financial/discovery entries. See personal tools and trusted management for their per-tool DTOs and bindings. The fact-only argus:tools:public OAuth default (25 business tools) and existing financial wire responses remain supported. Consumer connections on /mcp list the 20 consumer tools instead, which return consumer-result-v1. The generated personal-contract-foundation.v1.json is separate from the active tool schema catalog. All 58 design entries say planned_not_callable and cannot grant permissions. The executable registry and per-tool schema catalog define current business-specific payloads and activation; the design catalog is not an availability list.

Result kind Payload and interpretation
financial Existing strict DataPackage, with source evidence and original financial completion states. Optional notices live only in this opt-in wrapper.
private_object Owner, lifecycle, domain and versioned private records. Text is explicitly untrusted user or user-selected agent content. Source references grant no excerpt rights.
management Current owner/account state, state version, update time and a fixed account management path; no credentials.
usage Real sampled windows and result buckets, time range and explicit completeness. Unavailable/no-record results cannot carry invented counters.
task Owner/lifecycle, task identity/type, actual state/time, optional real units and snapshot time. No fabricated percentage.
confirmation Owner/lifecycle, operation, object versions, issued/expiry times and actual confirmation state. A client boolean cannot confirm an operation.

Every new result has a discriminator, schema version, request/audit identifiers and exactly one payload or coded problem. Input models reject unknown fields, owner/identity overrides and secret parameters. Text has these limits: 120-character/480-byte titles, 65,536-byte bodies and 20 tags of at most 32 characters/128 bytes; a private response page is capped at 100 records. Private text is data, never instructions or an Argus financial conclusion.

The private-object record provides shared metadata and content. Saved queries, holdings, import previews, notifications and other domain records have implemented business-specific models; consult their per-tool result schemas instead of decoding every payload as generic text.

Execution and authority

CoreServiceBoundary.execute_typed retains write-ahead/terminal audit, identity, isolation and ordinary permission checks. It also requires a trusted private authorization component before private preparation and again at delivery and commit. No component means denial before execution. The component must read current owner/domain consent; supplying a callable is an internal integration point, not a public authorization claim. New input bodies are excluded from generic audit and metrics. Results are revalidated, audit-linked and owner-checked. Financial results still pass the existing license, evidence and output pipeline. Internal revalidation retains excluded evidence fields for governance and commit; public serialization continues to hide them. Delivery authorization runs after the commit hook, so revocation or a new lifecycle during commit suppresses the old private result. Financial operations that read private state, such as saved-query reruns or asset calculations, must also supply that guard. Its owner, lifecycle and domain remain bound throughout preparation, commit and delivery; a financial result kind does not bypass an explicitly supplied private guard. Writes use the commit hook and the implemented lifecycle/consent transactional fencing. The foundation schema alone is not a write engine or an authorization.

personal_operations.py defines intended scopes, input/result families, idempotency, concurrency, confirmation, three-interface mappings and MCP hints. Agent business grants are intersected with current owner consent. Read and write scopes are separate; old fact tokens acquire neither. Subscription creation and resumption require independent background consent. Agent export additionally intersects each requested domain's read permission; full export requires trusted account management. An export download is a controlled stream following status and authorization, not a public object URL.

Writes bind their request key to owner, lifecycle, operation and normalized input digest. Replaying the same key returns the original result; a different input under that key conflicts. Updates/deletes require the expected object version; creation is conditional on absence. Bulk deletion/overwrite binds a confirmation to exact objects/versions and expires within five minutes. Ordinary edits do not require repeated login. Sensitive session/client/domain/all-authorization revocation, account deletion, identity changes and full export have only trusted account mappings, with recent owner verification and explicit confirmation. They have no ordinary MCP/CLI tool mapping. The active business tools and trusted management adapters enforce these rules; the historical design catalog grants no execution authority.

MCP hints distinguish reads from writes, destructive delete/import commits and safe retry with a bound request key. A stored import preview changes private state and is declared a write. Hints never replace server enforcement.

Financial compatibility and problems

Legacy completion values remain complete, partial, empty, unavailable. Stale, rights-restricted, gaps, source conflicts, restatements, entity ambiguity and inaccessible evidence are notices in the new wrapper, or existing quality and restriction fields for legacy clients. There is no new legacy completion enum. Publication time, reporting period, first-known time and query time remain in DataPackage; fetching again changes retrieval metadata only. New wrappers reject future-known facts, publications and revisions, and unlinked notice evidence.

Problem messages are enumerated localization keys, without raw prose/details. Input/idempotency errors require corrected input, version conflicts require reloading versions, expired confirmation requires a new confirmation, ambiguity requires entity selection, conflicts require a reviewed source revision, permission/rights failures require new authorization or rights review. These are not blind retries. Source/evidence/state outages permit retry only after the named dependency recovers; capacity errors require capacity to become available. Restatement is quality/version information, not a transport outage. Error classification and retry conditions are validated together.

Run the existing interface and release generators to regenerate the foundation catalog and Python schema module. Their --check gates and the personal contract tests verify closed schemas, six-way separation, serialization round trips, unchanged legacy responses, safe audit and shared execution semantics.