# HowSure clients, CLI and local MCP Solve one task: **find your exact market → read its conditions and supported sources → estimate 500 YES shares from visible depth → keep the complete result**. Public reads need no account, API key or paid model. They do not place orders, sign a wallet, save private documents, send email or start background collection. Evidence/books explicitly request bounded upstream data. ## Versions and installation | Surface | Version | Requirement | | --- | --- | --- | | JavaScript/TypeScript, CLI, local MCP | 0.1.33 | Node >=22.17 | | Python | 0.1.25 | Python >=3.10 | | HTTP specification | OpenAPI 1.22.0 | HTTPS client; preserve each response schema version | These are downloadable source archives, **not npm or PyPI registry releases**. Default origin: `https://howsure-web.vercel.app`. Current **0.1.33 (JS/CLI/MCP)** and **0.1.25 (Python)** also accept the exact `https://www.howsure.com` origin for scoped private research. The Vercel origin continues to work; immutable package defaults stay there for compatibility. Redirects never forward a key, even between these two first-party hosts. Other hosts, including `howsure.com` without `www`, are not trusted for private calls. HTTP schemas and OpenAPI 1.22.0 are unchanged. Older archives remain immutable; upgrade the complete package before choosing the new origin. The canonical domain is live. Select it explicitly: ```js const client = new HowsureClient({ origin: 'https://www.howsure.com', agentToken: process.env.HOWSURE_AGENT_TOKEN }); ``` For CLI and MCP set `HOWSURE_ORIGIN=https://www.howsure.com` in the process environment. Python: `HowSureClient("https://www.howsure.com", agent_token=os.environ.get("HOWSURE_AGENT_TOKEN"))`. Public reads remain keyless. Credentials belong in private process configuration, never in a URL or argument. This online guide is updated independently of immutable archived READMEs; earlier archive bytes and their historical instructions remain unchanged. Version **0.1.32 (JS/CLI/MCP)** and **0.1.24 (Python)** validate the native condition ID against the canonical ID for books and collected evidence. Both book schemas recompute gross depth, filled shares, VWAP and minimum-size status even when fees are unknown. JS Check reads accept the exact Gamma slug endpoint; equivalent UTC deadline spelling is compared without rewriting either retained capture or its raw fingerprint. These are validation fixes, not an authenticity proof or execution guarantee. HTTP shapes and OpenAPI 1.22.0 are unchanged. Version **0.1.31 (JS/CLI/MCP)**, **0.1.23 (Python)** and **OpenAPI 1.22.0** read an existing owner watch only after separate explicit permission for this exact watch and key. Optional `sharedWatch` retains actual schedule/status outside the immutable version; the existing updates feed returns retained comparisons. Old version-only grants do not expand. New clients send `include_watch=true`; older clients/HTTP without it retain their previous response shape. This adds no tool, scope, source call or watch control. See [Owner-shared watch results](#owner-shared-watch-results). Version **0.1.30 (JS/CLI/MCP)**, **0.1.22 (Python)** and **OpenAPI 1.21.0** add exact PCE watch receipts to the existing private methods. A separate, default-off service pilot can observe one exact saved Core PCE monthly contract; installing a client, reading or saving evidence does not enable it. The baseline binds month/year, core monthly metric, precision, threshold, confirmed BEA date and retained named-release version. Preserve `pending`, cached, incomplete and changed states, both baseline and preceding-check comparisons, and every source clock. Original-release bytes, seasonal-adjustment provenance and settlement remain unverified. See [Exact PCE release watch](#exact-pce-release-watch). Version **0.1.29 (JS/CLI/MCP)**, **0.1.21 (Python)** and **OpenAPI 1.20.0** let an owner explicitly share one exact saved Check version with a chosen existing agent key. New clients request `include_shared=true` on private list/read calls; the read also keeps `include_corrections=true`. Raw HTTP without the new flag continues to expose only agent-created versions. Shared reads require the exact version ID and return `provenance: owner_shared_unverified` plus `sharedAccess`. Only the previewed one-claim projection is returned; private title, summary, notes, thesis, context and assessment are excluded. Shared access does not permit append, watch, grants, other documents or future versions. JS/CLI/MCP rechecks preserve the shared metadata and correction review even on a failed source read. The owner can revoke a grant or key; already-read copies cannot be recalled. This adds no new tool, source call, paid model or automatic monitoring. Version **0.1.28 (JS/CLI/MCP)**, **0.1.20 (Python)** and **OpenAPI 1.19.0** add a current HowSure `correctionReview` when opening a saved research version. The clients request `include_corrections=true` on the existing private GET; plain HTTP with the flag omitted or false keeps the legacy response shape. The registry data version can advance without a client upgrade while its `schemaVersion: 1` shape stays compatible. The review is separate from `versions[].content`: original IDs, saved text, source captures and exports stay unchanged. `affected` names an exact known HowSure interpretation correction and the action to review; `unknown` requires review, while `not_affected` only means no match to the finite known registry. An absent review from an older server is unavailable, never proof of no errors. JS/CLI/MCP preserve the review during explicit source rechecks, including cached sources and failed reads. Read-only scopes are sufficient; no new tool, source request, save, revision, watch, email or paid model is introduced. A locally retained/offline copy receives no new notice until the saved version is read again. Version **0.1.27 (JS/CLI/MCP)**, **0.1.19 (Python)** and **OpenAPI 1.18.0** add the source-bound next scheduled meeting for supported December Fed readings. Optional `contract_reading.calendar.nextMeeting` retains the next year's January start/end dates, `status: tentative` and `confirmationEstablished: false`. Its `noStatementCutoff.date` is that meeting's end date; time and time zone remain null and `exceptionEstablished` remains false. The complete December/January rows and calendar qualifications must agree with the selected contract. The shared Note's separate January date is never substituted for the actual next meeting. No new request flag, source call or automatic watch is added. Upgrade both clients to validate this new field: earlier packages can return it without checking the cutoff. Older calendar formats, decisions, provisional ranges and saved versions keep their existing meaning. Version **0.1.26 (JS/CLI/MCP)**, **0.1.18 (Python)** and **OpenAPI 1.17.0** add the exact Core CPI/PCE monthly **0.6% or more** template. Explicit monthly release reads return optional `reportedValueComparison`: inclusive numeric comparison of the retained one-decimal figure, with `qualifyingConditionEstablished: false`. Exactly 0.6% meets the numeric threshold; missing facts remain unavailable. Overall `conditionAssessment` stays `unknown`. Equality payloads omit the new field; all existing flags, source limits and save/recheck paths remain unchanged. Upgrade both clients: older JS rejects these new readings, while older Python does not validate the new comparison field. Python now also binds the complete question/terms, selected period and schedule before accepting monthly facts. Version **0.1.25 (JS/CLI/MCP)**, **0.1.17 (Python)** and **OpenAPI 1.16.0** add the exact historical Q4 2025 GDP reading. The contract still names January 29; a retained official postponement notice and schedule must both corroborate the February 20 Advance publication. Its 1.4% value remains separate from the indexed April 9 Third Estimate of 0.5%. The existing explicit GDP release scope allows up to five sources, or six with the full bracket roster. No new flag is required. Clients reject altered dates, notice text or disagreement between the retained narrative, table and derived values. Earlier archives may reject this new reading; upgrade the complete package. Source fingerprints do not prove unchanged original-release bytes, and these facts do not establish settlement. Version **0.1.24 (JS/CLI/MCP)** and **0.1.16 (Python)** admit two exact retained official wording variants: July 2026 CPI's prior-month "unchanged" narrative, bound to a zero June core Table A value; and June 2026 PCE's complete prospective annual-update and PIO archive notices, preserved verbatim. Values, month/year, release date and source scope remain checked. Earlier archives keep their bytes and may reject these newly admitted readings; install the complete current package. HTTP/OpenAPI 1.15.0, request flags and response schemas are unchanged. This adds no paid model, automatic watch, original-release proof or settlement claim. PCE seasonal-adjustment provenance remains unverified. Version **0.1.23 (JS/CLI/MCP)** adds exact monthly CPI/PCE fact comparison to saved-version rechecking and an explicit `includeMonthly: true` mode for two raw responses. Values, source provenance and failed reads have separate results. The HTTP API and Python remain unchanged; this is not an automatic watch. Version **0.1.22 (JS/CLI/MCP)** added explicit exact-version rechecking to the existing private research read. After a restart, only the document/version IDs and a scoped read key are needed. See [Resume a saved task](#resume-a-saved-task-after-restart). The HTTP API and Python 0.1.15 are unchanged; this orchestration and shared local comparison run in the JavaScript package, CLI and local MCP. Version 0.1.21 (JS/CLI/MCP), 0.1.15 (Python) and OpenAPI 1.15.0 add the `retained_archive_release` CPI observation. The same explicit CPI release read can follow the exact selected-period archive URL listed in the retained BLS index. The archive path, printed release date, month/year, core monthly measure and narrative/table values must agree. The existing current-summary payload remains valid, including when its index also contains an archive link. Neither form proves unchanged original-release bytes or establishes settlement. Install these versions for the new archive observation; old archives are not guaranteed to accept it. Version 0.1.20 (JS/CLI/MCP) and 0.1.14 (Python) introduced the complete July PCE precision-example wording and August CPI em-dash wording. The July PCE reader retains its future annual-update notice and cross-checks the exact monthly core value; GDP readings acknowledge a validated event roster even while the qualifying figure is pending or unavailable. HTTP schemas and flags are unchanged. Install these versions for those newly admitted cases. Earlier packages retain their former coverage; they are not guaranteed to accept the new readings. The online guide may be corrected after a release; existing archives keep their original bytes and included README. Do not replace an installed module in isolation: JS modules have relative imports, and TypeScript declarations ship in the package. ```sh # Run in your own project directory; download and inspect before installation. curl --fail --show-error --proto '=https' --max-time 30 \ 'https://howsure-web.vercel.app/downloads/howsure-client-0.1.33.tgz' -o howsure-client-0.1.33.tgz npm install ./howsure-client-0.1.33.tgz npx --no-install howsure capabilities npx --no-install howsure markets --query 'Fed October' --limit 20 ``` Installation resolves the pinned MCP SDK dependency. `--no-install` prevents npx from fetching another package. An MCP host's model is configured independently; HowSure does not run or charge for a model through these read-only tools. ## Five-minute JavaScript / TypeScript task Save this as `howsure-task.mjs`. Run it once without an argument to inspect the returned questions, then pass the exact Polymarket ID you select. `FOMC` is another rate-related search phrase; matching a topic does not establish equivalent contracts. ```js // Save as howsure-task.mjs. First run: node howsure-task.mjs // Read the questions, then run: node howsure-task.mjs 'EXACT_RETURNED_ID' import { HowsureClient, HowsureApiError } from '@howsure/client'; const client = new HowsureClient(); const search = await client.searchMarkets({ q: 'Fed October', limit: 20 }); if (!process.argv[2]) { console.log(JSON.stringify(search, null, 2)); // choose, do not assume first = best process.exit(0); } const market = search.data.results.find(row => row.id === process.argv[2]); if (!market || market.source.venue !== 'polymarket') { throw new Error('Select an exact Polymarket ID from this search response.'); } async function capture(read) { try { return { ok: true, data: await read() }; } catch (error) { if (!(error instanceof HowsureApiError)) throw error; return { ok: false, error: { code: error.code, status: error.status, api_error: error.apiError, message: error.message, details: error.details, retryable: error.retryable, retry_after: error.retryAfter, hint: error.hint } }; } } const [conditions, evidence, depth] = await Promise.all([ capture(() => client.readConditions(market.id, { limit: 10 })), capture(() => client.collectSourceEvidence(market.id)), capture(() => client.readOrderBook(market.id, { quantity: '500', outcome: 'YES', side: 'buy', })), ]); console.log(JSON.stringify({ receivedAt: new Date().toISOString(), selectedMarketId: market.id, search, conditions, evidence, depth }, null, 2)); ``` The second run performs four GETs: search plus three independent reads. Append `> howsure-result.json` to save the complete receipt; that JSON is your captured copy, not a link to permanently fixed current data. Each successful stage is kept if another fails. `ok` means a validated request, not complete coverage: inspect statuses, times, gaps, estimate and fees. No retries/pagination loops run implicitly. TypeScript imports use `@howsure/client` and its included `howsure-client.d.mts`. The optional evidence `contract_reading` can be null or absent; it explains captured recognized Fed meeting/annual, US GDP growth, complete Core PCE/Core CPI monthly equality or exact 0.6% or more templates, or Binance price-threshold terms, not verified meaning or an outcome. Bounded source policies read the exact declared official FOMC calendar or BEA GDP URL. GDP terms distinguish the quarter, annualized metric, Advance Estimate, revisions and fallback; an unavailable or different-vintage BEA passage remains explicit. Unknown or conflicting terms return null. Existing SDK/MCP 0.1.6 and Python 0.1.5 already preserve the additive GDP field; JS 0.1.7 includes its TypeScript declaration. Version 0.1.8 added opt-in sale proceeds. Version 0.1.9 added local source-evidence comparison. JS/CLI/MCP 0.1.10 and Python 0.1.7 expose optional structured contract-rule comparison on the existing HTTP endpoint. Repository maintainers: the packaged `evidence-comparison/*.mjs` files are compiled from the existing UI comparison modules. After changing those TypeScript sources, run `node scripts/build-source-evidence-client.mjs` from `frontend`; `--check` verifies their bytes. The focused comparison test also checks this, so the package does not maintain a separate comparison algorithm. ## CLI: the same selected ID ```sh howsure_market_id='EXACT_RETURNED_ID' npx --no-install howsure conditions "$howsure_market_id" --limit 10 npx --no-install howsure evidence "$howsure_market_id" npx --no-install howsure book "$howsure_market_id" --quantity 500 --outcome YES --side buy npx --no-install howsure --help ``` `HOWSURE_ORIGIN` or `--origin` changes origin. Default deadlines are **10 seconds for retained reads, 30 for evidence, 15 for books**. `HOWSURE_TIMEOUT_MS` or `--timeout-ms` overrides all (integer 1–60000 milliseconds). JSON, including failure envelopes, goes to stdout. Exit 0 means completed read; 1 failed/incomplete operation; 2 invalid usage. A completed read can still have stale values or incomplete data. ## Local MCP: ten tools Install the JS archive, then configure a client supporting stdio. Replace the module path with the absolute path to your installation. `node` must resolve to Node >=22.17 in that application's environment; an absolute Node binary path also works. ```json { "mcpServers": { "howsure": { "command": "node", "args": ["/absolute/path/to/your-project/node_modules/@howsure/client/howsure-mcp.mjs"], "env": { "HOWSURE_ORIGIN": "https://howsure-web.vercel.app" } } } } ``` This is a **local process, not a hosted MCP URL**. No HowSure token is required. Tool names and JavaScript methods: | MCP tool | JavaScript method | Input / purpose | | --- | --- | --- | | `howsure_capabilities` | `capabilities()` | Static support, not health | | `howsure_search_markets` | `searchMarkets({q, category, limit, offset, generation})` | One retained catalog page | | `howsure_read_snapshot` | `readSnapshot(slug)` | Exact returned public slug; separate observation | | `howsure_read_conditions` | `readConditions(marketId, {before, limit})` | Retained Polymarket history | | `howsure_collect_source_evidence` | `collectSourceEvidence(market, options?)` | Exact Polymarket contract and bounded allowlisted sources | | `howsure_compare_source_evidence` | `compareSourceEvidence(previous, current)` (named export) | Compare two supplied raw evidence responses locally; no new reads | | `howsure_read_order_book` | `readOrderBook(market, {quantity, outcome, side, includeCost})` | Independent CTF YES/NO depth and source-bound purchase-cost model (default v2) | | `howsure_list_checks` | `listChecks({marketId})` | Published registry, optional exact ID filter | | `howsure_read_check` | `readCheck(checkId, {marketId})` | Fixed Check plus separate applicability; up to three GETs | | `howsure_compare_contracts` | `compareContracts([id1,id2], {includeRules})` | 2–3 distinct retained PM/HIP-4 canonical IDs; optional supported retained rules | MCP uses the same parameter names except `howsure_compare_contracts` takes `{"marketIds":["FIRST_ID","SECOND_ID"]}`. For the task, search with `{"q":"Fed October","limit":20}`, select an exact result, pass it as `marketId` to conditions and `market` to evidence/book. Book selection: `{"market":"EXACT_RETURNED_ID","quantity":"500","outcome":"YES","side":"buy"}`. ## Compare retained contract rules JS/CLI/MCP 0.1.10 and Python 0.1.7 can request the same structured reading as web Compare. Select 2–3 distinct canonical IDs from search and preserve their order: ```js const result = await client.compareContracts([firstId, secondId], { includeRules: true }); if (result.status !== 'comparison_read') throw new Error(JSON.stringify(result.errors)); console.log(JSON.stringify(result.response, null, 2)); ``` ```sh npx --no-install howsure compare "$first_id" "$second_id" --include-rules true ``` MCP: call the existing `howsure_compare_contracts` with `{"marketIds":["FIRST_ID","SECOND_ID"],"includeRules":true}`. Python: `client.compare_contracts([first_id, second_id], include_rules=True)`. HTTP: repeat `market_id` and append `include_rules=true&rules_version=2` on `GET /api/free/v1/contracts/compare`. JS/CLI/MCP 0.1.13 and Python 0.1.9 request `rules_version=2` with their existing `includeRules` / `include_rules` opt-in. The optional `comparison.ruleReading` reads complete recognized Fed meeting/annual, GDP, Brazil-election and House-control terms: metric/period, YES/NO, rounding, vintage, fallbacks and pair-completeness limits. A same-year annual/meeting Fed pair keeps its different horizons and conditions in separate columns; a compatible hypothetical scenario is not an observed result. New snapshots contain `parserVersion:2`; original snapshots without it remain readable. HTTP callers omitting `rules_version` retain the original Fed/GDP-only format, including older installed clients. Candidate/party pairs are not assumed exhaustive. It retains `same_reading`, `different_reading` and `not_comparable`; unknown terms, partial coverage and different families remain explicit. Unsupported readings are valid results, not transport failures. No source is refreshed or independently verified; `equivalence` remains `not_assessed`. Keep the full response, including original fields, exact contract IDs, metadata/observation times and limitations. Omitted or false keeps the original raw-field response. `includeRules` must be a boolean (CLI accepts only `true` or `false`). When explicitly requested, a missing or malformed rule block fails as `malformed_response`; the client does not silently substitute raw fields or invent a reading. JS returns an unavailable envelope, CLI exits 1, MCP sets `isError:true`, and Python raises `HowSureError`. Older archives retain their bytes and default comparison behavior. There is still one comparison tool, one request, and no model call or private account save. ## Explicit Fed decision evidence JS/CLI/MCP 0.1.14 and Python 0.1.10 add an opt-in on the existing evidence operation: ```js const pack = await client.collectSourceEvidence(exactMarket, { includeDecision: true }); const decision = pack.contract_reading?.decision; ``` ```sh npx --no-install howsure evidence "$howsure_market_id" --include-decision true ``` ```python pack = client.collect_source_evidence(exact_market, include_decision=True) ``` For MCP, call `howsure_collect_source_evidence` with `{ "market": "EXACT_REFERENCE", "includeDecision": true }`. HTTP uses `include_decision=true`; omission or false preserves the original source policy. The opt-in response has `collection_scope: "fed_decision"`, including partial/unsupported results, and at most four source records. For a complete recognized meeting, one additional official statement or latest published rate-range passage is retained. `contract_reading.decision` separates `observed`, `pending`, `unavailable` and `unsupported`. Observed facts keep the selected meeting date, statement/release time, before/after target ranges, basis-point change, condition assessment and source IDs. A future meeting's `currentRange` is provisional context, not its guaranteed preceding rate. An inaccessible statement is not proof of the no-statement exception. `settlementEstablished` remains false; there is no model call or trade. Save/export preserves the original passages and their timestamps in the existing capture. Explicit manual recheck of such a saved capture retains this collection scope. Decision captures cannot enable the existing Fed/GDP automatic source watch; no collection cadence or subscription changes. Older installed clients continue to request the original two-source response and old archives are unchanged. ## Explicit GDP Advance release evidence Use the same evidence operation with `includeRelease: true` in JavaScript/MCP, `--include-release true` in the CLI, or `include_release=True` in Python: ```js const pack = await client.collectSourceEvidence(exactMarket, { includeRelease: true }); const release = pack.contract_reading?.release; ``` ```sh howsure evidence "$howsure_market_id" --include-release true ``` ```python pack = client.collect_source_evidence(exact_market, include_release=True) ``` The HTTP parameter is `include_release=true`; the response keeps the evidence v1 schema with `collection_scope: "gdp_release"` and at most five source records (including a separately indexed historical revision when supported). This opt-in reads the official BEA index and follows only its matching quarter's Advance release. `includeRelease` and `includeDecision` cannot both be true; clients reject that combination before a request. Omitted/false preserves the standard two-source collection. To resolve shared numeric boundaries, explicitly add `includeBrackets: true` (CLI `--include-brackets true`, Python `include_brackets=True`, HTTP `include_brackets=true`). This requires release collection and adds the exact complete event roster, including closed contracts, for at most six sources. The scope is `gdp_release_brackets`; `release.brackets` retains the selected and assigned contract IDs, event hash and observation time. Internal shared boundaries go to the higher bounded range. Equality at the strict greater-than upper tail remains unknown. A missing, incomplete or incompatible roster never fabricates an assignment. Omitted/false keeps the release response and its five-source bound. `contract_reading.release` separates the required quarter/year/Advance vintage, its observed figure and publication time, and any later second/third estimate. A later revision cannot replace the Advance figure just because it is newer. Pending, unavailable and unsupported remain explicit; absence alone does not establish the contractual fallback. The bounded YES-condition assessment is not venue settlement. This performs no model call, save or background monitoring. Save/export retains the source passages and times; an extended baseline can be rechecked explicitly, but does not silently broaden a watch. ## Compare two saved source reads locally Use this when your agent has already retained two evidence responses for the **same exact contract** and needs to identify changed passages or conditions. This is separate from comparing two contracts or reading a published Check. If you saved through the private agent API and only have its document/version IDs, use [exact-version rechecking](#resume-a-saved-task-after-restart) instead. JavaScript/CLI/MCP 0.1.9 introduced local retained-text comparison. Version 0.1.11 introduced the current UI comparison of listed Fed/GDP publication destinations. A changed listed destination is index evidence only; the linked content was not fetched or assessed. Comparing a legacy capture with a new link-aware passage compares the original text and reports `publication_links_not_previously_captured`: whether the destination changed is unknown. Two link-aware captures can report `listed_publication_links_changed`. Older archives remain unchanged and may report `different_source_scope` when comparing legacy and new passages; upgrade the complete package for current comparison semantics. Inputs must be the **raw `SourceEvidenceResult` objects**, each with `schema_version: "howsure.evidence-request.v1"`, from `collectSourceEvidence`, `howsure evidence`, or the evidence HTTP endpoint. Pass the earlier capture as `previous` and the later one as `current`. Do not pass a market ID, file path to MCP, whole mixed-task receipt, saved private document, or `evidence_bundle` alone. For the five-minute task above, first check `response.evidence.ok`, then extract **`response.evidence.data`** from each saved response. The wrapper is not accepted as an evidence response. ```sh # first.json and repeat.json already contain raw evidence responses. npx --no-install howsure evidence-compare first.json repeat.json ``` The CLI reads the two files and prints JSON. It does not fetch sources or rewrite the input files. Save stdout to a **different** filename if you want a comparison receipt; shell redirection to `first.json` or `repeat.json` would truncate that input before the command runs. Both inputs must be regular UTF-8 JSON files. Optional flags are `--include-decision`, `--include-release` and `--include-monthly`, each taking `true|false`. At most one may be true; origin/timeout environment settings are ignored because this command constructs no HTTP client. Valid comparison results, including `incomplete` or `not_comparable`, exit 0 (MCP `isError:false`); inspect the result status. Invalid JSON, unreadable or non-regular files, oversized files and malformed response objects exit 2 with `invalid_argument` and a `previous`/`current` field detail. Do not retry an unchanged bad input. MCP accepts objects, not filesystem paths. ```js import { readFile } from 'node:fs/promises'; import { compareSourceEvidence } from '@howsure/client'; const previous = JSON.parse(await readFile('first.json', 'utf8')); const current = JSON.parse(await readFile('repeat.json', 'utf8')); const comparison = compareSourceEvidence(previous, current); console.log(JSON.stringify(comparison, null, 2)); ``` For MCP, call **`howsure_compare_source_evidence`** with `{ "previous": , "current": }`. Those placeholders stand for complete JSON objects, not strings. Use the tool's structured result and keep the original receipts alongside it. For a structured comparison of retained Fed decision facts, explicitly set `includeDecision: true` in JS or the same MCP tool, or run: ```sh howsure evidence-compare first.json repeat.json --include-decision true ``` This returns `howsure.source-evidence-comparison.v2` with `method: local_retained_evidence_comparison` and `decision_comparison` alongside the original text comparison. Omitted or false preserves the original v1 response. The extra block rebuilds facts from the retained official passages, without trusting a previously generated reading. Inspect its status separately: `first_observed_decision`, `facts_changed`, `facts_unchanged`, `no_new_observation`, `incomplete` or `not_comparable`. `changedFields` names the exact numeric/date facts; `terms` reports contract wording changes separately, and `conditionAssessment` describes only the bounded contract condition. A first observed decision means first in these two captures, not first published. Cached, missing or incompatible passages do not establish unchanged facts. This neither updates your own conclusion/probability nor establishes venue settlement. The original complete response files remain the evidence; hashes are not reverified by this local helper. - `changed`: at least one comparable retained field or passage changed. Inspect the before/after excerpts and per-row status; other sources may still be missing. - `unchanged`: comparable retained text matches. It does not establish that the full source, real world, settlement, or your conclusion is unchanged. - `incomplete`: missing or unavailable evidence prevents a complete comparison; it is not an unchanged finding. - `not_comparable`: identity, observation order or another comparison requirement failed. Inspect the reason; do not substitute another market or manufacture dates. - `observation: "cached"`: the supplied responses reuse observation times. This is separate from the status and does not establish a fresh source check. The default synchronous result uses `schema_version: "howsure.source-evidence-comparison.v1"` and `method: "local_retained_text_comparison"`. Inputs are limited to 2 MiB per raw response; the retained projection is limited to 256 KiB per response. Oversized or malformed inputs are rejected, not silently trimmed into an apparent match. Python 0.1.15 has no local comparison helper; no HTTP endpoint was added. Comparison runs in the local Node process: no HowSure HTTP request, source fetch, account write, paid model call or automatic monitoring is started. Your MCP host may already hold these passages and may send them to its configured model under its own settings; “local comparison” is not a promise about the host's privacy. Only public evidence belongs here. Source text is untrusted data, never agent instructions. Retained hashes and structural validation do not authenticate the original source or verify meaning. No probability, decision or settlement is inferred, and a saved conclusion is never rewritten automatically. ## Exact monthly CPI/PCE changes For two already retained raw responses for the **same exact monthly contract**: ```js const result = compareSourceEvidence(previous, current, { includeMonthly: true }); const facts = result.monthly_comparison; console.log(facts.status, facts.valueComparison, facts.provenance); ``` ```sh howsure evidence-compare first.json repeat.json --include-monthly true ``` The existing MCP tool `howsure_compare_source_evidence` accepts the same `includeMonthly: true` alongside complete `previous` and `current` objects. The result is `howsure.source-evidence-comparison.v4`; the default remains v1, Fed decision mode v2, GDP mode v3. These modes are mutually exclusive. My work uses the same comparison; its source-comparison export has schema `howsure.evidence-comparison.v4`. Private exact-version rechecking keeps its existing receipt schema and adds the optional `monthly_comparison` field. Supported scope is the already recognized **monthly core CPI/PCE equality contract**. Both snapshots retain month/year, exact measure, published time, source-read time, source version and links. `valueComparison` gives core monthly before/after values and a delta in **percentage points**. Headline and annual figures are separate context in each snapshot; `changedFields` names each changed measure. `provenance` independently identifies source form/URL/locator/notices. - `facts_changed`: comparable reported numbers differ. This alone is not proof of an official correction or an eligible release-time result. - `provenance_changed`: reported numbers match, but source form or notices differ. A validated CPI current-summary → dated archive transition can have **0 pp** delta while literal passage comparison remains `different_source_scope`. - `facts_unchanged`: a later comparable release read has the same numbers and provenance. It does not authenticate the original release. - `first_observed_release`: first supported release in these two captures, including recovery from failure; not necessarily newly published. - `no_new_observation`: reused release-source clock, even if metadata is newer. - `incomplete` / `not_comparable`: missing source, incompatible identity, month, basis, timing or scope. Do not infer unchanged, zero, NO or a fallback. For PCE, seasonal adjustment remains **not explicit in the retained passage**. Only reported numbers for the same named release are compared; this does not verify their seasonal basis. Original release bytes and correction treatment remain unverified for both families; overall condition and settlement remain unknown. The saved assessment/probability and baseline are never overwritten. No PCE/CPI automatic watch, network request or paid model call is introduced by the local comparison. Explicit saved-version recheck still performs its two bounded reads. Earlier archive versions retain their original behavior. ## Python: one exact-market task [Download Python 0.1.25](https://howsure-web.vercel.app/downloads/howsure-python-0.1.25.tar.gz), then install in your virtual environment: ```sh python -m pip install ./howsure-python-0.1.25.tar.gz ``` Alternatively save [howsure_client.py](https://howsure-web.vercel.app/examples/howsure_client.py) beside your script. Runtime uses the standard library; archive installation uses setuptools. Constructor `timeout` is in **seconds** (positive, at most 60); default read/evidence/book deadlines are 10/30/15 seconds. JS/CLI use milliseconds. ```python import json from howsure_client import HowSureClient, HowSureError client = HowSureClient() page = client.search_markets(q="Fed October", limit=20) print(json.dumps(page, indent=2)) # Keep partial/source warnings with the selection. market_id = input("Paste one exact returned Polymarket ID: ").strip() if not any(row["id"] == market_id and row["source"]["venue"] == "polymarket" for row in page["data"]["results"]): raise SystemExit("Select an exact Polymarket ID from this page.") result = {"selected_market_id": market_id, "search": page} for name, read in [ ("conditions", lambda: client.read_conditions(market_id, limit=10)), ("evidence", lambda: client.collect_source_evidence(market_id)), ("depth", lambda: client.read_order_book( market_id, quantity="500", outcome="YES", side="buy")), ]: try: result[name] = {"ok": True, "data": read()} except HowSureError as error: result[name] = {"ok": False, "error": { "code": error.code, "message": getattr(error, "message", error.code), "details": getattr(error, "details", []), "retry_after": getattr(error, "retry_after", None)}} print(json.dumps(result, indent=2)) ``` Other methods: `capabilities()`, `list_checks(market_id=None)`, `read_snapshot(slug)`, `compare_contracts([id1,id2])`, `read_check(check_id)`, `read_updates(check_id)`. Search/history options are keyword arguments. Each method makes one GET and returns an API dictionary; there is no automatic pagination. **Check methods differ by language:** Python `read_check` returns only the fixed record; `read_updates` separately raises `PartialResponseError` for validated partial HTTP 503, preserving `.data`, `.status` and `.retry_after`. Catch it before `HowSureError` if retaining updates. Python validates shape/identity but does not produce the JS combined answer or repeat its retained evidence-hash verification. JS `readCheck`/`compareContracts` return envelopes; inspect `errors`, `status`, `fixed_record`/`response` instead of assuming every failed read throws. ## Identities and pages - Search `id` is canonical; `slug` is the HowSure public slug. Snapshot requires that returned public slug, with **no query parameters**. It is a separate read, not pinned to search generation. `as_of`/`generation` on snapshot return 400. - Conditions require a Polymarket canonical ID. Compare requires 2–3 distinct retained canonical PM/HIP-4 IDs and preserves their order. Compare does not accept Kalshi, public slugs or venue URLs. Its scope is `retained_serving_only`, and equivalence remains `not_assessed`; no current cross-venue equivalence is offered. - Evidence/books accept a returned Polymarket canonical ID/public slug with a retained active/archive mapping, or an exact native slug or `https://polymarket.com/market/SLUG`. The live condition must match. Unknown mappings, event URLs, arbitrary URLs, query strings, HIP-4 and protocol V2 books are unsupported. Successful responses keep a native `market_slug`; do not mistake it for the public slug. - Search limit 1–100; offset 0–10000. Keep filters/limit fixed, follow `next_offset` and a non-null `generation`; inspect `scope.truncated`. On 409 discard old pages and restart at offset 0 without the token. Null generation is unpinned, not a token. - Conditions use exclusive `before=nextCursor`, limit 1–20: omit on the first page, stop at null, never convert to offset. `not_retained` does not mean unchanged. ## Correct errors without losing partial results | Result | CLI / MCP | Interpretation | | --- | --- | --- | | Validated search/snapshot HTTP 200 with `meta.partial` | 0 / `isError:false` | Usable response, preserve source status, times and missing fields | | Partial evidence / partial visible fill | 0 / `isError:false` | Keep gaps/unfilled shares; no complete bundle/fill inferred | | Unsupported evidence / unavailable selected book / failed Check applicability | 1 / `isError:true` | Inspect reason; retain validated historical or partial data | | Invalid input | CLI 2 / MCP `isError:true` | Fix the field; validation may reject before HTTP | For `quantity="banana"`, read the structured details and explicitly retry with a valid decimal share string such as `"500"`. Do not retry unchanged. HTTP 400 means invalid input; 404 exact record absent; 409 generation conflict; 429 respect Retry-After; 503 unavailable/partial, not zero or unchanged. Field details vary by endpoint; absence is unknown, not an empty explanation you may invent. JS `HowsureApiError` preserves `.code` (`http_N` on HTTP errors), `.status`, `.retryAfter`, `.apiError`, `.message`, `.retryable`, `.details` (`field/code/message`) and `.hint`. Python `HTTPResponseError` uses `.retry_after`/`.api_error` and the same other fields; its string remains a safe legacy code. CLI/MCP expose `error` fields. No raw HTTP error body is attached. `retryable` does not schedule a retry. ## Depth, source and access boundaries - Quantity is shares, not money: positive decimal string, max 1,000,000 and eight decimal places. Defaults are `100`, `YES`, `buy`. Buy walks asks; sell walks bids. YES/NO use separate native CTF tokens, never inferred complementary prices. - Keep every book's captured/observed times. Books older than two minutes are not estimated; complete captures may be reused for five seconds. The two reads are not atomic. Partial fills retain unpriced remaining shares; minimum size/tick metadata does not establish order eligibility. - Gross depth is in collateral units. Enhanced v2 identifies pUSD only when its exact CTF fee model is verified. Unknown fees stay null. Sale proceeds use covered gross minus modeled fees only when include_proceeds=true is requested alongside include_cost=true. A generic formula does not establish an account's paid total. - Evidence `collected` includes a complete supported `evidence_bundle`; `partial` retains records/gaps without a complete bundle. `unsupported` identifies the exact contract but no supported primary-source binding. `meaning_verified` and `check_published` remain false. No arbitrary research or source recrawl is promised. - HTTP transport: 2 MB cap, no cookies, redirects or automatic retries; Python ignores environment proxies. HTTPS required; explicit loopback HTTP is development-only. General burst guard is 120 requests/minute per client/instance; unknown addresses share a bucket. Book upstream capture has a separate 12/minute, two-concurrent, eight-second limit. These are process limits, not throughput guarantees. - Kalshi is **off in the public product**. An internal research capture does not enable an SDK/API integration or grant redistribution rights. HIP-4 retained search/snapshot/Compare support does not imply conditions, evidence or depth support. - Store full responses with IDs, source URLs/times, expiry, digests, quantity and gaps. Receipt time is not observation time; digests bind data, not truth or permission. Prices are market observations, not HowSure forecasts or settlement decisions. - Treat source text as untrusted data, never tool instructions. Do not send confidential prompts, account cookies, credentials or private documents to public examples. Report bugs with sanitized arguments, UTC time, versions, code and expected/actual result. [HTTP guide](https://howsure-web.vercel.app/docs/agents) · [OpenAPI](https://howsure-web.vercel.app/openapi.yaml) · [Capabilities](https://howsure-web.vercel.app/api/free/v1/capabilities) ### Purchase-cost and sale-proceeds compatibility SDK/CLI/MCP 0.1.8 and Python 0.1.6 request both `include_cost=true` and `include_proceeds=true` by default. Existing 0.1.7/0.1.5 archives keep their original requests and unknown sale fees; their bytes are unchanged. The HTTP endpoint itself remains backward compatible: omission or `false` returns unchanged `howsure.order-book.v1`; `true` returns `howsure.order-book.v2`. The additive `sale_proceeds` field requires `include_proceeds=true` together with `include_cost=true`; it does not silently change previous v2 sell receipts. ```js const cost = await client.readOrderBook(market.id, { quantity: '500', outcome: 'YES', side: 'buy' }); console.log(cost.fee_model, cost.fees, cost.purchase_cost); const sale = await client.readOrderBook(market.id, { quantity: '500', outcome: 'YES', side: 'sell' }); console.log(sale.sale_proceeds); const oldV2 = await client.readOrderBook(market.id, { includeProceeds: false }); const legacy = await client.readOrderBook(market.id, { includeCost: false }); ``` Use `--include-proceeds false` / `includeProceeds: false` / Python `include_proceeds=False` for previous v2 behavior. Use `howsure book "$ID" --include-cost false` for legacy CLI output; MCP's existing `howsure_read_order_book` accepts `includeCost: false`. Python accepts `client.read_order_book(market_id, include_cost=False)`. The sale-proceeds release retained nine tools; 0.1.9 adds only local source-evidence comparison. No order or wallet operations are added. `fee_model` preserves the two dated execution-version/market-fee responses and binds their parameters to the exact condition, outcome tokens and captured book hashes. A verified model alone is not a usable estimate. The client validates costs against the selected captured price levels, with each level's fee rounded half-up to five decimals. It does not apply the fee curve to VWAP. For an eligible buy, `purchase_cost.total_for_covered` is displayed-depth gross plus modelled fees. `total_for_requested` is present only for full coverage; partial books never invent the missing price. With `include_proceeds=true`, an eligible sale returns `sale_proceeds.net_for_covered` as gross minus modeled fees and `net_for_requested` only for full coverage. The inapplicable purchase/sale result stays unknown. Missing fee evidence keeps both fee and net unknown, not zero. This is a point-in-time model, not an executable quote or actual debit: fee checks and books are non-atomic, source timing must remain visible, and funding/builder charges, rebates and actual fill partitioning are not established. Both decimal strings and the complete response belong in an export; do not drop the model, partial state or limitations. ## Corrections to a saved HowSure answer A source can be unchanged while HowSure corrects its own earlier interpretation. Open the exact saved version normally; the current clients request the separate `correctionReview` automatically. Raw HTTP clients opt in explicitly: ```text GET /api/agent/research/DOCUMENT_ID?version=VERSION_ID&include_corrections=true Authorization: Bearer ``` The review binds `documentId`, `versionId`, each `claimId` and its `marketId` to the returned retained content. Preserve `registryVersion`, findings, reasons and limitations in the agent's result. For an affected finding, show the correction `before`, `after`, `action`, public `href` and evidence/release references. Do not treat `not_affected` as a certificate that the answer is correct. `unknown` means retained details could not establish applicability; an absent field means this check was not available. Corrections describe HowSure's output, not new source facts, settlement or an automatic change to the author's probability. The initial registry covers one precise GDP bracket-list warning. It does not mark every historical GDP answer or every old client response as wrong. Original saved bytes and their old exports remain available. This review is delivered on read; it is not pushed to offline files or to agents that never return. Saving a new conclusion remains a separate explicit write with its own immutable version. ## Resume a saved task after restart JS/CLI/MCP **0.1.22** can resume an agent-created saved version without a separate raw response file. The key needs only `research:read`; local writes stay disabled. Current clients also read one exact owner-shared Check projection as described below; other human-only documents and Private notes stay inaccessible. Recover the exact returned `documentId` and `versionId`; a recheck never silently substitutes latest. ```js import { HowsureClient } from '@howsure/client'; const client = new HowsureClient({ agentToken: process.env.HOWSURE_AGENT_TOKEN }); const result = await client.readResearch('DOCUMENT_ID', { version: 'VERSION_ID', recheck: true, }); console.log(JSON.stringify(result, null, 2)); ``` ```sh # Keep the credential in HOWSURE_AGENT_TOKEN, never a command argument. howsure research-read DOCUMENT_ID --version VERSION_ID --recheck true > recheck.json ``` MCP uses the **existing** `howsure_read_research` tool: `{"documentId":"DOCUMENT_ID","version":"VERSION_ID","recheck":true}`. Without `recheck:true`, it only reads the retained document as before. The explicit mode makes at most two sequential GETs: a private exact-version read, then a public evidence read with only its native market URL and original supported scope. The token is confined to the private request. There are no automatic retries, saves, watches, paid model calls or new HTTP endpoints. Both existing request budgets apply; the client performs the comparison locally using the same logic as My work. Unsupported/ambiguous legacy scope fails before the public read. The `howsure.saved-evidence-recheck.v1` receipt contains `saved_version` (IDs, time, revision and browser link), `collection_scope`, provenance and limitations: - `status: "compared"` means comparison ran, not that sources are complete or unchanged. Inspect `comparison.status`, `observation`, reasons, source times and both bounded captures. Cached, incomplete and incompatible observations remain distinct. - `status: "unavailable"` with `error` means the public read/validation failed. `comparison` is null; the saved version reference remains. Do not reuse an earlier successful comparison as the result of this attempt. Private access/version errors fail before any public source request. - Fed decision and GDP release baselines include the existing optional `decision_comparison` / `release_comparison`. In 0.1.23, exact CPI/PCE release baselines include `monthly_comparison` automatically, using their original collection scope. Inspect its status independently from the literal-text result. Author probability and settlement are not inferred or updated. The report excludes title, summary, assessment and Private notes. It includes retained source passages and contract context, which can reveal what you study; keep it private unless you choose to share. Agent-supplied evidence remains unverified. A successful recheck leaves the original version unchanged; saving a new version or enabling a supported watch remains a separate explicit action. Python/HTTP consumers retain their existing read and collection operations; the new local orchestration is not a `recheck` HTTP parameter or a Python method. ## Read a Check the owner explicitly shared In My work, the owner opens one exact saved Check version, chooses **Agent access to this version**, previews the one included claim and chooses an existing scoped key. Sharing is an owner action: no agent tool or API credential can create a grant. The projection retains that claim's original statement and validated source capture. It excludes the private document title/summary, notes, thesis, context, assessment and all other claims. The returned title is the selected question. The original document/version/claim IDs and saved version remain unchanged. Use the existing list/read tools after the owner grants access. A list can contain several shared versions of the same document: keep each `versionId`, do not dedupe by `documentId`. Shared reads always require an exact version: ```text GET /api/agent/research?include_shared=true GET /api/agent/research/DOCUMENT_ID?version=VERSION_ID&include_shared=true&include_corrections=true ``` SDK, CLI and MCP send the flags automatically. Python uses `read_research(document_id, version=version_id)`. JavaScript can explicitly recheck the original supported source scope with `readResearch(documentId, {version: versionId, recheck: true})`; the existing MCP `howsure_read_research` and CLI `research-read` take the same exact IDs. Rechecking is read-only: no save, append, watch, source-scope expansion or model. Shared results carry `provenance: "owner_shared_unverified"` and `sharedAccess`: `grantId`, `projectionSha256`, `grantedAt`, `expiresAt`. The digest is a confirmation reference for the sanitized projection, not independent authentication or proof that the sources are true. The server binds it to the chosen key and version; clients validate its shape, exact identities, safe content fields and clocks. The existing correction review stays separate and may identify an old HowSure interpretation error without changing the shared statement. Grant/key revocation or expiry blocks later access. A shared version cannot be read with another key, appended to, watched or used to access later revisions. Missing/revoked/unavailable access uses a generic error; it does not disclose whether another private document exists. Request the exact version or ask the owner to check its grant. Copies already read by an agent cannot be recalled. ## Optional private research (current clients) Public tools remain keyless. In your signed-in HowSure account, create a scoped, expiring agent key. Keep its one-time token in your process/agent host's secret storage as `HOWSURE_AGENT_TOKEN`; never put it in command arguments, tool input, source code, shared configuration or screenshots. Revoke it from the account UI. By default, only agent-created versions are accessible. The owner can additionally share one exact Check version with one chosen key; other personal documents and private notes remain excluded. New clients opt in to those shared list/read results. - `research:read`: list/read agent-created or explicitly owner-shared exact versions, plus retained agent-watch updates and results of exact owner watches separately shared with this key. - `research:write`: save an immutable agent evidence baseline or append to an agent-created document; never append to an owner-shared Check. - `watch:write`: explicitly manage the existing supported agent-created source watch; it does not enable a watch for an owner-shared Check. Scopes are independent. The JS SDK also requires `allowAgentWrites: true` for writes; Python requires `allow_agent_writes=True`. MCP exposes three private read tools when a token is configured. Two write tools appear only when `HOWSURE_AGENT_WRITE=1` is also set. A read-only token still cannot write. CLI `research-save` and `research-watch` are explicit write commands; their JSON input comes from a regular file or stdin (`-`), never from inline JSON arguments. ```js import { HowsureClient } from '@howsure/client'; const client = new HowsureClient({ agentToken: process.env.HOWSURE_AGENT_TOKEN, allowAgentWrites: true, }); // Read evidence explicitly; saving itself performs no new source/model calls. const evidence = await client.collectSourceEvidence('EXACT_POLYMARKET_REFERENCE'); const saved = await client.saveResearch({ idempotencyKey: 'my-stable-task-id-001', title: 'My contract baseline', evidence, }); // Store saved.href to open this exact version in your signed-in browser. const fixed = await client.readResearch(saved.documentId, { version: saved.versionId }); // Enable only when the user has requested bounded periodic checks. await client.setResearchWatch({ documentId: saved.documentId, versionId: saved.versionId, claimId: saved.claimId, enabled: true, }); const page = await client.readResearchUpdates(); // Persist page.nextCursor. Use it unchanged on the next read; page has no implicit loop. ``` ```sh howsure research-list howsure research-read DOCUMENT_ID --version VERSION_ID howsure research-save research-input.json howsure research-watch watch-input.json howsure research-updates --cursor OPAQUE_CURSOR --limit 10 ``` A save input has `idempotencyKey`, `title`, optional `summary`, and exactly one of `evidence` (the raw source-evidence response) or `capture` (a complete EvidenceCapture). Append by also supplying `documentId` and the exact latest `expectedVersionId`. Keep an idempotency key for retries of the identical input; reuse with changed input fails. Concurrent edits return a version conflict. Save does not enable monitoring. A watch input requires returned `documentId`, `versionId`, `claimId` and explicit `enabled: true` or `false`. Python exposes `list_research()`, `read_research(document_id, version=...)`, `save_research(input)`, `set_research_watch(document_id=..., version_id=..., claim_id=..., enabled=...)` and `read_research_updates(cursor=..., limit=10)`. Pass `agent_token=os.environ.get("HOWSURE_AGENT_TOKEN")` to `HowSureClient`. `project_source_evidence_capture(evidence)` makes the local evidence projection; complete capture validation is enforced by the server on save. Private credentials go only to fixed `/api/agent/` paths at `https://howsure-web.vercel.app` or `https://www.howsure.com`, or HTTP loopback with explicit local opt-in. Redirects and arbitrary HTTPS hosts are refused; public endpoints never receive the token. The clients do not retry writes or advance cursors automatically. Read results preserve unverified provenance, exact version links, source gaps, failures and retention limitations. An empty feed does not prove that sources were unchanged. Legacy overview watches keep their six-hour/14-day policy. Expanded fact watches use the same scheduler and shared capacity but are separately disabled by default. Retained text changes do not establish their effect on a conclusion, probability, outcome or trading decision. No paid model is invoked. MCP replies include both text JSON and `structuredContent`, with an object `outputSchema`; error replies preserve `isError` and safe codes. Older archived packages keep their original behavior and bytes. ## Compare saved GDP release facts locally JavaScript `compareSourceEvidence(previous, current, { includeRelease: true })`, CLI `howsure evidence-compare first.json repeat.json --include-release true`, and MCP `howsure_compare_source_evidence` with `includeRelease:true` return `howsure.source-evidence-comparison.v3` and `release_comparison`. Supply the raw responses retained from earlier evidence reads. No source call or write occurs. The Python client collects those same responses; the local comparator is JS/CLI/MCP. Keep `first_observed_advance`, `revision_changed`, `facts_changed`, `facts_unchanged`, `no_new_observation`, `incomplete` and `not_comparable` distinct. First observed means first supported Advance in these two inputs, not its first publication. The qualifying Advance and later revisions have separate fields. Event-roster assignment changes are separate in `bracketAssessment`; they do not imply a change to official GDP. Missing sources are neither removed facts nor unchanged facts. `conditionAssessment` does not establish venue settlement or revise an author's thesis. Both inputs must describe the same exact contract and release collection scope. Bracket comparison is inferred from retained roster sources: there is no separate `includeBrackets` comparison flag. Choose `includeRelease` or `includeDecision`, never both true. Omitted/false preserves text-only v1; Fed opt-in preserves v2. ## Read an inclusive monthly CPI/PCE threshold Use the existing explicit `includeCpiRelease: true` or `includePceRelease: true` flag for the exact selected contract. Only the recognized full template and literal **0.6% or more** question are supported; `0.7% or more`, `more than`, `or less`, or extra precision are not silently interpreted. ```js const pack = await client.collectSourceEvidence(exactMarket, { includeCpiRelease: true }); const reading = pack.contract_reading?.cpiRelease; const numeric = reading?.reportedValueComparison; // numeric?.status: meets_numeric_threshold | below_numeric_threshold | unavailable // numeric?.qualifyingConditionEstablished is false; reading?.conditionAssessment is unknown. ``` July 2026 CPI reports 0.2% and June 2026 PCE reports 0.1% in the retained fixtures; each is numerically below 0.6%. This does not prove the qualifying original release-time condition, resolve later corrections, or establish settlement. A saved version retains these limitations and a recheck compares the new source facts without editing the author's probability or replacing the saved answer. ## Prepare a Core PCE monthly contract This is the **default terms and overview preparation**, without a monthly-release opt-in. JS/CLI/MCP 0.1.19 types `contract_reading.family:us-core-pce` and preserves the same conditions when saving/exporting a version. Python 0.1.12 and later preserve these default JSON fields. Use the existing evidence operation with the exact selected contract; default preparation needs no new flag, tool or paid model. The explicit monthly-release scopes described below require JS/CLI/MCP 0.1.19 or Python 0.1.13 and their corresponding PCE/CPI release flag. The complete recognized Core PCE MoM equality template and exact **0.6% or more** variant are supported. Read the exact month/year, seasonally adjusted core one-month change, equality or inclusive threshold at the named release's one-decimal precision, delayed-release fallback and source IDs. Headline PCE, CPI, year-over-year data, another month and arbitrary threshold wording are not substitutes. The venue's scheduled date is not an independently confirmed release or proof that a fallback applied. The fixed BEA PCE overview is **context only**. Its available headline annual figures or listed next date do not establish the contract's qualifying core monthly value. The exact release-time observation and later correction/revision treatment remain unknown; this default collection does not fetch a qualifying monthly release or infer settlement. An unavailable overview returns partial evidence with the readable venue terms and explicit gaps, never a fabricated zero or NO. The existing public evidence result can be projected and explicitly saved as an immutable private version, then read/exported through the same UI/API/MCP paths. Saving does not enable observation. PCE overview alone cannot authorize a watch. An exact monthly PCE baseline can use the separate opt-in policy below; Fed/GDP watches keep their existing bounded scope and limits. Versions 0.1.17 and older retain their original archive bytes and advertised behavior. ## Bounded saved fact watches JS/CLI/MCP 0.1.17 and OpenAPI 1.13.0 describe optional nested watch `policy`, `attemptsRemaining`, `stopReason`, and update `factComparison` / `transitionFactComparison`. Existing private methods/tools and strict top-level response fields are unchanged; Python 0.1.12 and JS 0.1.16 preserve the added data. The server derives scope from the immutable baseline: exact native identity, Fed meeting or GDP quarter/Advance vintage and optional complete event roster. A caller cannot add a policy to the watch mutation or broaden a saved scope. Expanded watches are disabled by default. When explicitly enabled by the service, the pilot allows 3 targets, 7 days and 28 attempts per target / 84 total, including failed attempts. All scopes share the six-hour interval, 40 attempts/day and finite storage. Re-enabling never resets expiry or allowance. Expanded agent watches stop when their enabling key expires, is revoked or loses authorization; overview behavior is unchanged. No save/read/export silently starts a watch. A fact receipt kind is `fed_decision`, `gdp_release`, or `pce_release` under the separate PCE policy below. `factComparison` compares to the immutable saved baseline; `transitionFactComparison` compares to the preceding retained check. Read the status, observation, previous/current facts, exact sources and times, and limitations together. Preserve cached `no_new_observation`, null failed reads, `incomplete`, and separate GDP revisions. First observed does not mean first published. Neither author probability nor settlement changes. Opaque cursor replay reads retained receipts without a source request. Advance the cursor only after processing the returned page. Preserve explicit `research_watch_facts_disabled`, `research_watch_fact_limit`, `research_watch_attempt_capacity`, `research_watch_scope_mismatch` and `research_watch_credential_revoked` errors; do not silently retry enabling or create replacement watches to bypass finite limits. Disabling preserves the saved baseline and earlier receipts. No new tool, paid model or client polling loop is introduced. ## Exact PCE release watch First explicitly collect an exact supported Core PCE monthly contract with `includePceRelease: true` (Python `include_pce_release=True`) and save that complete capture as an agent-created baseline. Enable only that returned document/version/ claim through the existing `setResearchWatch` / `set_research_watch` / MCP `howsure_set_research_watch` operation. It requires `watch:write`, local write opt-in and the independently enabled service pilot. An owner-shared human Check remains read-only even when a key has write scopes; create no replacement copy to bypass this boundary. UI owners use the saved Check's explicit observation action. The separate pilot has **one lifetime exact target and 28 attempts**, including failures. It retains the common six-hour interval and shared daily capacity without changing the Fed/GDP three-target allowance. Its seven-day window is fixed at UTC midnight one day before the confirmed BEA date through midnight six days after it. This is an operational checking window, **not the source's release clock**. Enrollment is allowed no more than 45 days before the window. Disabling, re-enabling or replacing a key never resets its allowance or expiry. Credential revocation/expiry stops authorized agent watches; disabled receipts remain readable. `policy.scope: pce_release` contains the exact monthly context and `window`. `factComparison.kind: pce_release` holds a `MonthlyFactComparison` against the immutable saved capture. Optional `transitionFactComparison` uses the previous retained check. Preserve numeric and provenance changes separately, along with `settlementEstablished: false`. A changed schedule or metric cannot yield a comparable delta. No author probability or saved answer is rewritten. Top-level update `pending` requires a newer, successful exact BEA index read that still shows the release is pending. A reused index is `cached`; a failed or missing source is incomplete/unavailable. Pending is not a zero figure, NO, fallback or settlement. Read these retained rows through existing `readResearchUpdates`, `read_research_updates` or MCP `howsure_read_research_updates`, persisting `nextCursor` unchanged. Reading the feed performs no source request. An empty page proves no new retained row only. `research_watch_pce_disabled`, `research_watch_pce_limit` and `research_watch_schedule` are non-retryable without an operator/input change; review the saved scope/date instead of retrying or creating replacement targets. The current agent state has the same top-level fields as before. No new tool, endpoint, client polling loop, PCE/CPI-wide watch or paid model is introduced. CPI watches remain unsupported. Old downloadable archives remain unchanged. ## Explicit Core PCE / Core CPI monthly release reads The flags were introduced in JS 0.1.19 / Python 0.1.13. JS 0.1.20 / Python 0.1.14 added the July PCE and August CPI wording; use JS 0.1.21 / Python 0.1.15 for the newly source-bound CPI archive observation. Use the same source-evidence operation. Choose one scope; omitted flags keep the existing request and never start a watcher. GDP `includeRelease` remains GDP only. ```js const pce = await client.collectSourceEvidence(exactPceMarket, { includePceRelease: true }); const cpi = await client.collectSourceEvidence(exactCpiMarket, { includeCpiRelease: true }); ``` ```sh howsure evidence EXACT_PCE_REFERENCE --include-pce-release true howsure evidence EXACT_CPI_REFERENCE --include-cpi-release true ``` MCP uses the existing `howsure_collect_source_evidence` tool with `includePceRelease:true` or `includeCpiRelease:true`. Python uses `collect_source_evidence(exact_market, include_pce_release=True)` or `include_cpi_release=True`. The HTTP names are `include_pce_release` and `include_cpi_release`; returned scopes are `pce_release` and `cpi_release`. They cannot be combined with each other, `includeDecision` or GDP `includeRelease`. GDP `includeBrackets` still requires its own GDP release scope. Preserve `contract_reading.pceRelease` / `.cpiRelease`, their exact required period, all retained sources and capture/publication times. Core monthly, headline monthly and year-over-year numbers are separate fields. A current table, another month or an overview never substitutes for the required publication. The PCE retained monthly paragraph/table does not explicitly establish seasonal adjustment; annual update and archive notices remain visible. CPI current-summary seasonal revision notices remain visible. The CPI policy follows the exact selected-month archive URL from the retained BLS index when listed, otherwise the fixed current summary. Archive URL date and printed release date must match the contract schedule, and its reference period and monthly core measure must match the full terms. An unlisted archive URL is never guessed. A missing, inaccessible or mismatched release stays unavailable; another month is not a replacement. `sourceVersion` distinguishes `retained_archive_release` from `retained_current_summary`. `publishedAt` is the printed embargo/release label normalized to UTC, not independently observed first online publication. Neither historical page proves unchanged initial-release bytes or establishes venue settlement. Consequently the present overall condition assessment remains `unknown`, even when a source-bound reported value is observed. Pending, failed source, unsupported template and observed value remain distinct. Saving a result does not activate CPI/PCE source watches. No paid model is called. The JS runtime recomputes these additive readings from the same pure retained-source readers used by the service. Python validates the structured fields, publication labels, exact source relations and retained table-value parity; it does not execute HTML extraction or certify the publisher's original historical bytes. ## Owner-shared watch results In **My work**, open the exact saved Check, then **Agent access to this version**. The owner separately permits the chosen key to read saved and future retained results of this one existing watch. Version-only sharing does not include results, start collection, copy the document or grant watch control. Only `research:read` is needed; there is no `updates:read` scope. Current clients automatically request: ```text GET /api/agent/research/DOCUMENT_ID?version=VERSION_ID&include_shared=true&include_corrections=true&include_watch=true GET /api/agent/updates ``` The read returns optional `sharedWatch` only with active version and watch-result grants for this key. Its document/version/claim, revision, saved time, market and policy bind the exact retained projection. Missing `sharedWatch` does not prove no watch exists. Absent/false `include_watch` preserves the previous exact-read shape even with a result grant. The immutable version and projection digest are unchanged; schedule/status metadata remains separate. Future `startedAt` / `nextAttemptAt` with null `lastAttemptAt` means scheduled collection, not a completed observation. The feed contains only retained receipts: preserve pending/cached/incomplete/failure states, baseline and preceding-check comparisons, source clocks and limitations. Explicit rechecks preserve shared status on success and failure; they do not alter the watch. The cursor binds the owner, key and active watch-result grant set. HTTP **409 `agent_updates_access_changed`** requires an explicit new read without cursor. Keep processed update IDs and deduplicate by ID. The SDK never silently retries or discards this signal. Other keys and version-only grants cannot read results. Revoking result access blocks later result reads while leaving version access and the owner watch intact; revoking version/key access blocks both. Copies already read cannot be recalled. Private notes, author assessment and personal probabilities are excluded and are never automatically changed.