@hasna/economy 0.4.0 → 0.5.0

package/dist/types/index.d.ts

@@ -78,8 +78,11 @@ export interface Budget {
     alert_at_percent: number;
     created_at: string;
     updated_at: string;
+    /** Omitted by legacy callers; server responses always identify the metric. */
+    metric?: 'legacy_request_cost_usd' | 'metered_api_usd';
 }
 export interface BudgetStatus extends Budget {
+    period_bounds: import('../lib/periods.js').CalendarPeriodBounds;
     current_spend_usd: number;
     percent_used: number;
     is_over_limit: boolean;
@@ -91,12 +94,41 @@ export interface IngestState {
     value: string;
 }
 export interface CostSummary {
+    /** Compatibility subtotal of known stored values, including separately reported session-only values. */
     total_usd: number;
+    complete_total_usd: number | null;
+    basis: 'known_usage_value_subtotal';
+    completeness: 'complete' | 'partial' | 'unavailable' | 'no_records';
+    coverage_scope: 'selected_stored_records';
+    source_coverage: 'not_established';
+    period_bounds: import('../lib/periods.js').CalendarPeriodBounds;
+    request_rows: number;
+    recorded_metered_api_usd: number;
+    estimated_usage_value_usd: number;
+    subscription_included_value_usd: number;
+    /** Lifetime totals of overlapping sessions without request rows; not allocated to this period. */
+    session_only_value_usd: number;
+    unknown_price_requests: number;
+    unknown_basis_requests: number;
+    session_only_sessions: number;
     sessions: number;
     requests: number;
     tokens: number;
     period: Period;
 }
+export interface BillingSummary {
+    /** Compatibility subtotal of the selected imported provider rows, never a complete invoice claim. */
+    total_usd: number;
+    recorded_total_usd: number | null;
+    complete_total_usd: null;
+    basis: 'recorded_provider_rows_subtotal';
+    status: 'observed' | 'no_records';
+    coverage_scope: 'selected_stored_records';
+    source_coverage: 'not_established';
+    period_bounds: import('../lib/periods.js').CalendarPeriodBounds;
+    record_count: number;
+    by_provider: Record<string, number>;
+}
 export interface ZeroCostModelBreakdown {
     agent: import('../lib/agents.js').Agent;
     model: string;
@@ -194,6 +226,14 @@ export interface SyncOptions {
     dedupe?: boolean;
     /** Claude/Takumi JSONL root override (tests). */
     projectsDir?: string;
+    /**
+     * Refuse collectors that read ANOTHER Hasna app's on-box SQLite (today: the
+     * `loops` collector, which reads `~/.hasna/loops/loops.db`). Set by the
+     * hosted push (`syncAllToCloud`): a client with a hosted credential never
+     * takes another app's local store as fleet truth — that data must come from
+     * the loops API. PORT-TO-API, tracked for W13 (fleet-alignment ruling d).
+     */
+    noCrossAppLocalReads?: boolean;
 }
 export interface SessionFilter {
     agent?: import('../lib/agents.js').Agent;
@@ -217,6 +257,11 @@ export interface Subscription {
     active: number;
     created_at: string;
     updated_at: string;
+    account_key?: string;
+    observed_station?: string | null;
+    observed_at?: string | null;
+    fee_basis?: import('../db/observation-provenance.js').AmountBasis;
+    included_basis?: import('../db/observation-provenance.js').AmountBasis;
 }
 export interface UsageSnapshot {
     id: string;
@@ -227,6 +272,27 @@ export interface UsageSnapshot {
     unit: string;
     machine_id: string;
     updated_at: string;
+    provider?: string;
+    account_key?: string;
+    observed_at?: string | null;
+    source_timestamp?: string | null;
+    window_start?: string | null;
+    window_end?: string | null;
+    reset_at?: string | null;
+    window_seconds?: number | null;
+    value_kind?: import('../db/observation-provenance.js').ValueKind;
+}
+export interface ScanReceipt {
+    id: string;
+    machine_id: string;
+    source: string;
+    attempted_at: string;
+    completed_at: string;
+    status: 'success' | 'unchanged' | 'missing' | 'unsupported' | 'failed';
+    latest_event_at: string | null;
+    parser_version: string;
+    error_code: string | null;
+    updated_at?: string;
 }
 export interface MachineRegistry {
     machine_id: string;

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAE9D,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAA;AAC9E,MAAM,MAAM,YAAY,GAAG,OAAO,kBAAkB,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAA;AAEjG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAEzE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,YAAY,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,OAAO,kBAAkB,EAAE,SAAS,CAAA;IACjD,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,YAAY,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,EAAE,OAAO,kBAAkB,EAAE,KAAK,GAAG,IAAI,CAAA;IAC9C,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC1C,iBAAiB,EAAE,MAAM,CAAA;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,OAAO,CAAA;IACtB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,kBAAkB,EAAE,KAAK,CAAA;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,yBAAyB,EAAE,MAAM,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,yBAAyB,EAAE,MAAM,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,yBAAyB,EAAE,MAAM,CAAA;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,EAAE,CAAC,EAAE,OAAO,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,kBAAkB,EAAE,KAAK,CAAA;IACxC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,OAAO,kBAAkB,EAAE,KAAK,GAAG,IAAI,CAAA;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,EAAE,MAAM,CAAA;IACvB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,OAAO,kBAAkB,EAAE,KAAK,CAAA;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAA;CACnB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -1,6 +1,6 @@
 # Economy documentation
 
-Economy can run as an on-machine SQLite application or as a client of a shared self-hosted HTTP service. These guides describe the current command and network surfaces:
+Economy can run as an on-machine SQLite application or as a client of a shared HTTP service. These guides describe the current command and network surfaces:
 
 - [CLI reference](cli.md) — the `economy` command and the four installed binaries.
 - [Ingestion](ingestion.md) — supported sources, default paths, sync behavior, billing, and account attribution.

package/docs/cli.md

@@ -6,7 +6,7 @@ Installing `@hasna/economy` provides four binaries:
 | --- | --- |
 | `economy` | Ingest, query, and manage Economy data. |
 | `economy-mcp` | Run the MCP server over stdio or Streamable HTTP. |
-| `economy-serve` | Serve the REST API, or migrate a self-hosted database. |
+| `economy-serve` | Serve the REST API, or migrate the server database. |
 | `economy-otel` | Ingest OTLP/HTTP metrics or simplified cost events into local SQLite. |
 
 Use `<binary> --help` and `economy <command> --help` for the exact help emitted by the installed version.

package/docs/configuration.md

@@ -54,9 +54,9 @@ export HASNA_ECONOMY_LOCAL=1
 
 The unprefixed `ECONOMY_LOCAL=1` alias is accepted. The opt-in yields to every hosted signal (a URL, a key, or a pointer in the environment outranks it), and a local run prints one line on stderr — `economy: local mode (HASNA_ECONOMY_LOCAL=1) …` — so an unhosted run is never mistaken for a hosted one that came back empty.
 
-Retired `*_STORAGE_MODE` / `*_MODE` variables no longer exist as selectors: `HASNA_ECONOMY_STORAGE_MODE` (and `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, `ECONOMY_MODE`, plus the accounts variants `HASNA_ACCOUNTS_*_MODE`) are a hard error on the client — delete them and let the resolved credential do the routing.
+The retired `*_STORAGE_MODE` / `*_MODE` variables — `HASNA_ECONOMY_STORAGE_MODE`, `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, `ECONOMY_MODE`, plus the accounts variants `HASNA_ACCOUNTS_*_MODE` — are inert: they select nothing, gate nothing, and error nothing (owner directive 2026-08-15). A wrapper may still export `HASNA_ECONOMY_STORAGE_MODE=cloud`; it changes nothing. Transport and backend come from the resolved credential / DSN above.
 
-In cloud-client mode, data commands use the HTTP API, and local auto-sync, explicit `economy sync`, and `economy billing sync` are skipped. Clients never need or use a Postgres DSN.
+In cloud-client mode, data commands use the HTTP API: read commands answer from the API's GET routes (on-box auto-sync is skipped), and the explicit `economy sync` / `economy billing sync` verbs run the same on-box provider ingest against a scratch store and push the rows to `/v1/ingest`. Clients never need or use a Postgres DSN.
 
 ## REST server
 
@@ -71,7 +71,7 @@ economy-serve --port 3456
 
 Without a local token, the current server defaults to `0.0.0.0` and API routes are unauthenticated. Set a token and an intentional bind address before exposing a local-mode server to another host.
 
-## Self-hosted server
+## Server deployment
 
 The server backend follows the database URL alone — `postgresql` when one of these is set, `sqlite` when none is:
 
@@ -81,7 +81,7 @@ ECONOMY_DATABASE_URL
 DATABASE_URL
 ```
 
-`HASNA_ECONOMY_STORAGE_MODE` (and `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, `ECONOMY_MODE`) no longer selects a backend: the server refuses to start and prints a migration hint. Delete it and set a DSN instead. The client follows the same rule — the variables are a hard error there too, and API routing comes from the URL + key pair above.
+`HASNA_ECONOMY_STORAGE_MODE` (and `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, `ECONOMY_MODE`) never select a backend: the stale variables are inert and the server starts regardless — the DSN alone decides. The client follows the same rule: the variables select nothing, and API routing comes from the URL + key pair above.
 
 Apply migrations with `economy-serve migrate`. `ECONOMY_PG_POOL_MAX` defaults to 5. A non-loopback server also requires one of `HASNA_ECONOMY_API_SIGNING_KEY`, `HASNA_API_SIGNING_KEY`, or `API_KEY_SIGNING_SECRET`; API keys are then verified by `@hasna/contracts`. The signing secret belongs only on the server.
 
@@ -96,6 +96,6 @@ See [REST API authentication](rest-api.md#authentication) for request headers an
 | `ECONOMY_OTEL_PORT` | OTLP sidecar port; default 4318 and overridden by `--port`. |
 | `ECONOMY_OTEL_BIND` | OTLP sidecar bind host; default `127.0.0.1`. |
 | `HASNA_ECONOMY_INGEST_CACHE` | Path of the hosted `economy sync` mtime cache (a JSON file, never SQLite). Default `<cache root>/economy/ingest-cache.json`, where the cache root is `HASNA_CACHE_HOME`, else `~/Library/Caches/Hasna` (macOS) or `~/.cache/hasna`. Losing it costs one re-read; the server upserts are idempotent. |
-| `HASNA_AGENT_REGISTRY_DB_PATH` | File for the MCP agent registry. Default: in memory when hosted, `agent-registry.db` under the data directory under `HASNA_ECONOMY_LOCAL=1`. |
+| `HASNA_AGENT_REGISTRY_DB_PATH` | Local-lane path override for the MCP agent registry. Ignored when hosted; default under `HASNA_ECONOMY_LOCAL=1` is `agent-registry.db` in the data directory. |
 
 Source- and billing-specific environment variables are listed in [Ingestion](ingestion.md).

package/docs/cost-reporting.md

@@ -0,0 +1,49 @@
+# Cost certainty and subscription comparisons
+
+Token counts and configured prices estimate usage value. They do not prove a
+payment. An agent name does not identify an account's billing route: the same
+agent can use a subscription, an API key or a router.
+
+Unpriced models have an unavailable amount. The numeric SDK estimate and native
+CLI/MCP estimate report `MODEL_PRICING_UNAVAILABLE`; they never return zero for a
+missing price. An explicitly free model variant or a configured zero price can
+return zero. Token counts must be nonnegative safe integers. Provider catalog
+rates remain estimates; this repair does not refresh or attest their currency.
+
+The savings endpoint describes an **estimated subscription comparison**:
+
+`net_comparison_usd = included_consumed_usd - subscription_fee_usd`
+
+Here, included consumption means the priced usage value of requests explicitly
+identified as subscription-included. It is not provider credit consumption and
+is not clipped to a plan's credit limit. The fee is the current configured or
+observed monthly rate allocated across the selected full UTC calendar period.
+Each month uses its own day count, including leap years and cross-month weeks.
+This allocation is not a historical invoice or evidence of when a subscription
+started. All-time fees require billing history and are unavailable here.
+
+Paid API usage does not become savings. Separately observed on-demand charges
+are not subtracted again from the included-usage comparison. Their account and
+window identities must be known: duplicate cumulative readings use the latest
+source observation, exact delta windows are deduplicated, and overlapping or
+partially selected windows remain unavailable. Missing charge observations do
+not prove that no charge occurred.
+
+An exact account mapping is required between included requests and their plan.
+Shared fees are counted once in the fleet comparison and are not allocated to
+agents by usage share. A missing or ambiguous mapping, unknown fee, unpriced
+model, or unknown billing route makes the comparison unavailable. Session-only
+aggregates remain estimates. Legacy fee records retain their original amounts
+with unknown provenance until reconciled.
+
+`comparison_status` is `estimated`, `not_applicable`, or `unavailable`.
+`net_comparison_usd` retains negative results; `saved_usd` is its positive part
+only when a comparison is available. Unavailable amounts are JSON `null` and
+display as `unavailable`, never `$0.00`. The response also carries known priced
+usage, recorded metered amounts, unknown counts, and authored reason codes.
+The SDK refuses the legacy savings contract rather than presenting its old
+calculation. Deploy a compatible service before upgrading these consumers.
+
+Existing Codex lifetime aggregates, Cursor cumulative daily requests and older
+agent-name billing classifications need a separate preserved, guarded data
+migration. Source repair alone does not rewrite or validate historical records.

package/docs/historical-data-reconciliation.md

@@ -0,0 +1,203 @@
+# Historical usage reconciliation
+
+The former collectors could store a whole Codex session as one `-0` request,
+a Hermes session as one `-rollup` request, a cumulative Cursor account summary
+as a daily request, and token-priced Claude usage as `metered_api` based only
+on the harness name. The repaired collectors do not establish the provenance
+of historical rows. A matching identifier alone is not permission to change one.
+
+Use the maintained server operator for a bounded inventory:
+
+```sh
+economy-serve legacy-inventory --limit 25
+economy-serve legacy-inventory --family codex_aggregate --limit 25
+economy-serve legacy-inventory --family codex_aggregate --after '<last request id>'
+```
+
+It resolves the existing server PostgreSQL configuration, uses one read-only,
+repeatable-read transaction, and returns counts, at most 100 candidate metadata
+rows, exact logical row digests and a continuation cursor. It performs no
+migration, ingestion, schema creation, backup, archive or record mutation.
+It has no SQLite fallback. Database failures have a fixed redacted diagnostic.
+
+The digest encoding is `postgres-row-json-text-v1`: SHA-256 of PostgreSQL's
+`row_to_json(requests)::text` in UTF-8, with UTC, ISO/YMD dates and
+`extra_float_digits=3`. Hashing occurs inside PostgreSQL before driver number
+conversion, preserving nonfinite floats and large integers. Reconciliation
+must use this same encoding against the same table schema. Only the digest
+and selected metadata are returned. IDs and cursors retain the ingest contract
+of up to 1,024 characters, including non-NUL controls, escaped in JSON output.
+
+Each page and its counts share a snapshot. Separate pages can observe changes;
+an exhausted cursor is not a frozen export of a concurrently changing store.
+Both commands refuse reads when row-level security would filter the population;
+they do not disable policies or grant the operator a bypass. Relation locks are
+taken before the snapshot's first query, so concurrent schema changes cannot mix
+old column metadata with newly shaped originals. Existing finite lock and query
+timeouts still apply, and ordinary ingestion remains possible during these reads.
+Counts refer to the documented source-shape predicates, not to proven errors.
+The Claude class in particular needs a source and billing-provenance review:
+some records may describe actual API usage. The inventory does not relabel them.
+
+Before reconciliation, preserve and read back the exact originals, verify a
+restored copy, review explicit targets and reasoned dispositions, and require
+exact current-row preconditions plus a durable idempotent receipt. Quarantining
+old aggregate representations must retain their original evidence and prevent
+later ingestion from recreating the same double-counting. Reconstruct event
+rows only from real source events. Unknown historical billing remains unknown;
+never infer payment from a harness name or invent a historical price.
+
+The inventory command is the read-only preparation step. Applying a disposition
+requires the execution steps below and applicable production authority; inventory
+supplies neither.
+
+For explicitly reviewed candidates, prepare one bounded reconciliation proposal:
+
+```sh
+economy-serve legacy-plan --input /absolute/path/selection.json
+```
+
+The input is `economy.legacy-selection.v1`, with `items` containing 1–100
+unique requests. Each item supplies `id`, `family`, `original_sha256` from the
+inventory, a reasoned `disposition`, `reason`, and an `evidence_ref` identifying
+the source review. The three aggregate families accept `quarantine_aggregate`;
+Claude billing candidates accept `mark_billing_unknown`. An actual API charge
+with verified provenance must not be selected merely because it matches the
+Claude predicate. A supplied evidence reference is recorded, not authenticated
+or approved by this tool. Never include credentials in this file.
+
+The planner checks all selected originals against one read-only snapshot,
+then binds each associated session and its complete request population. It
+refuses missing or changed rows, changed family classification, missing sessions,
+and selections spanning more than 10,000 requests. The bound is explicit: a
+single larger session requires a separately reviewed procedure, not partial
+membership. The file must be regular, at most 256 KiB, and cannot be a symlink;
+nonblocking descriptor validation refuses FIFOs without waiting for a writer.
+
+`original_encoding` matches the inventory. `members_sha256` hashes UTF-8 JSON
+arrays of `[request_id, original_sha256]` pairs ordered by PostgreSQL `C`
+collation, so unselected inserts, deletions and changes affect the precondition.
+The plan also records table column definitions, database and relation locators,
+the snapshot instant and a SHA-256 of its JSON body (everything preceding
+`plan_sha256`, in emitted order). Database locators do not attest production
+ownership; two installations can have the same local identifiers. Different
+snapshot times intentionally produce different plan digests.
+
+No originals leave the database and nothing is changed. This proposal is not
+preservation, restore proof, approval, an idempotent apply receipt or a rollback.
+The apply command preserves exact originals and atomically rechecks these
+preconditions while excluding ingestion. Its runtime integration retains
+quarantined evidence, refuses ingestion into protected request identities, and
+uses effective request and session views for reporting. Excluding a request
+while retaining its session aggregate would still double-count usage;
+`legacy-plan` alone cannot repair that state.
+
+Preserve a reviewed proposal with the server's existing PostgreSQL configuration:
+
+```sh
+economy-serve legacy-preserve --input /absolute/path/plan.json --output /absolute/private-directory/originals.json
+economy-serve legacy-rehearse --input /absolute/private-directory/originals.json
+```
+
+`legacy-preserve` rechecks the complete plan in one read-only snapshot and captures
+every request belonging to its selected sessions, including unselected events,
+plus each session original. A changed row, population, schema or store locator
+refuses capture. Original PostgreSQL JSON stays text, preserving large integers
+and nonfinite floats without a JavaScript number conversion. The capture is
+bounded to 10,000 requests and 16 MiB of original row text; the final file cannot
+exceed 32 MiB. Split a larger selection by session, never truncate it.
+
+The output requires an existing owner-only directory. The file is created
+exclusively with mode 0600, flushed and read back. An existing or interrupted
+file is never overwritten or deleted. Standard output contains a compact hash
+and count receipt, never original records. Retain the private capsule and receipt
+under the applicable evidence and retention policy.
+
+`legacy-rehearse` imports the raw preserved JSON through PostgreSQL's native row
+types into transaction-local temporary tables, compares every reconstructed
+original byte, then rolls back those tables. It changes no application records.
+This verifies logical restoration of the selected sessions and their complete
+request populations against the current table definitions. It is not a complete
+database backup, production ownership attestation or disaster-recovery exercise.
+Neither command authorizes quarantine or performs application or rollback of a
+reconciliation.
+
+## Apply, observe and roll back
+
+Deploy the reviewed runtime integration and apply its appended PostgreSQL schema
+migration before executing a reconciliation. Old migration bytes are unchanged.
+The migration runner serializes competing invocations and commits each migration
+and its completion marker atomically. After a lost commit response, rerun the
+same migration command to read committed markers. Unexpected pre-existing,
+unmarked definitions are refused rather than silently adopted or overwritten.
+The operator never migrates on startup and never falls back to local storage.
+Use the existing server configuration and an explicitly authorized database
+principal; client agent credentials are not database operator authority.
+
+```sh
+economy-serve legacy-target
+economy-serve legacy-apply --input /absolute/private-directory/apply.json --capsule /absolute/private-directory/originals.json
+economy-serve legacy-receipt --operation '<original operation key>'
+economy-serve legacy-rollback --input /absolute/private-directory/rollback.json
+```
+
+An apply intent has exactly these fields:
+
+```json
+{
+  "schema": "economy.legacy-apply.v1",
+  "operation_key": "a-stable-key-for-this-reviewed-operation",
+  "target_sha256": "<digest returned by legacy-target>",
+  "plan_sha256": "<digest from the reviewed plan>",
+  "capsule_sha256": "<digest from the preserved capsule>",
+  "actor_ref": "<operator identity reference>",
+  "authority_ref": "<exact applicable authorization reference>"
+}
+```
+
+The angle-bracket values above are placeholders. Digests must be lowercase
+64-character SHA-256 values. Operation keys accept 1–200 letters, digits, dots,
+underscores, colons and hyphens; actor and authority references accept 1–512 of
+those characters plus slashes. The target digest binds the effective host,
+port, database, principal, connection options and TLS state resolved by the same
+pool, including supported query and environment overrides, without exporting
+credentials. It complements the preserved database and table locators; it does
+not attest ownership. References record authority but do not authenticate it or
+lift preservation and production gates.
+
+Apply locks the ledger, sessions and requests before its repeatable-read snapshot,
+rechecks every original and complete selected-session membership, and rehearses
+restoration through the actual PostgreSQL types inside a savepoint. Reconstruction
+is read-only except for its temporary rows. Rolling back that savepoint restores
+write mode while retaining the outer locks through commit. Apply then records and
+reads back the capsule, and appends the selected dispositions in one transaction.
+It refuses stale rows, changed schemas, incomplete RLS populations and sessions
+with an active reconciliation. Original requests and sessions are not rewritten
+or removed. Quarantined aggregates disappear from effective reports; Claude
+rows selected as unverified retain their recorded amount in the unknown bucket.
+Affected session totals are recomputed from effective requests, and an empty
+quarantined session cannot re-enter totals through the session fallback.
+
+The response is a compact immutable receipt with operation, plan and capsule
+bindings, counts and commit time. A response loss can occur after commit. Keep
+the original intent and key, query `legacy-receipt`, and explicitly retry that
+same intent if needed. A same-key replay returns the original receipt plus its
+current active state; a different intent under that key is refused. Every
+receipt and active-state observation uses one bounded read-only snapshot and
+refuses policy-filtered visibility, including on replay. An absent
+receipt does not prove that an in-flight command cannot still commit. Neither
+the CLI nor the operator silently retries or invents a replacement key.
+
+A rollback intent uses `schema: "economy.legacy-rollback.v1"`, its own stable
+`operation_key`, the same target/plan/capsule bindings and actor/authority fields,
+and an additional `apply_key` naming the original application. Rollback rechecks
+all preserved source bytes and membership, then appends an immutable rollback
+record. The original rows become effective again; neither application history
+nor capsule is removed. If later ingestion or maintenance changed the selected
+sessions, rollback refuses and preserves that later work. Prepare a fresh
+reviewed reconciliation instead of forcing stale originals over newer data.
+
+Protected request identities refuse ordinary update, delete and replacement.
+Fresh event identities can still be ingested. The guards are integrity controls
+for the application runtime, not protection from a database owner who can alter
+the schema. Keep operator access separate from normal service credentials.

package/docs/ingest-journal.md

@@ -0,0 +1,108 @@
+# Ingest journal recovery and maintenance
+
+The hosted collector writes an immutable command intent before its first POST.
+A lost response leaves that intent pending. Reconciliation only reads the exact
+hosted receipt: receipt absence, a different actor, authentication failure or an
+unavailable authority never authorizes another POST. Hosted reads do not run
+journal maintenance.
+
+Completed commands share the existing limits of 1,000 commands and 64 MiB.
+Admission reserves 4 KiB for each pending receipt and 16 KiB for fixed control
+metadata. Server response extensions are discarded; the canonical receipt is
+validated before persistence. Older directories over the byte admission limit
+remain inspectable, but cannot admit new work until completed records retire.
+Unresolved commands can legitimately exhaust capacity and must be reconciled.
+
+A fresh command's own POST response with status 400, 409, 413 or 422 writes a
+separate immutable refusal record bound to the exact intent, target and body
+hash. Its status and a bounded authored reason are retained. Reconciliation
+validates this terminal state and permits a different command, including a
+corrected newer source version. The same rejected key returns the saved refusal
+without another POST, even after restart. Status reports `rejected` separately
+from uncertain `pending` commands; rejected originals still count against both
+hard caps and are not eligible for completed-receipt Trash retirement. If many
+rejections consume capacity, deliberate recovery remains necessary.
+
+Only an invocation which freshly staged the intent can persist refusal proof,
+and only from that command's first POST response. A timeout (including HTTP
+408), a 5xx, malformed success, receipt GET failure or absent receipt never
+creates refusal proof. Other 4xx statuses are conservatively retained without
+terminal proof. Earlier-version pending intents without such proof remain
+uncertain; a later 4xx cannot resolve an earlier ambiguous attempt. Interruption
+before refusal proof is durable also remains uncertain. Receipt and refusal
+records are disjoint; corrupt bindings, orphan records and dual outcomes fail
+closed. No operator input can relabel an uncertain intent as rejected.
+
+A bounded sweep starts at 64 commands, 48 MiB, or insufficient next-command
+headroom. It retires at most 32 pairs or approximately 1 MiB per pass; a single
+large pair is handled individually. Each pass has a 30-second network deadline.
+The active journal remains bounded; Trash's recoverable remote retention and
+unfinished transfer staging are governed by Trash's own policy.
+
+## Recovery prerequisite
+
+Enable automatic completed-record retirement explicitly with
+`HASNA_ECONOMY_INGEST_RECOVERY=trash`. The client lazily loads the exact published
+`@hasna/trash` 0.2.3 SDK. Trash resolves its own credential and station identity;
+Economy never passes its credential to Trash, registers a station, starts a
+backup, requests cold retrieval, or selects a local Trash store.
+
+For a self-hosted Economy authority, also explicitly configure
+`HASNA_TRASH_API_URL` for its supported Trash service. Without this setting,
+Economy refuses before importing Trash or consulting an internal credential.
+The fleet gateway may use the station's existing package-owned Trash resolver.
+Run the owning Trash station readiness/setup procedure before enabling actual
+maintenance. Native configuration drift is a station setup prerequisite, not
+permission for Economy to rewrite the native configuration.
+
+Missing recovery authority can defer automatic sweeping while admission still
+fits. At capacity, or after any interrupted capture, ingestion reports
+`INGEST_JOURNAL_MAINTENANCE_REQUIRED` with a bounded reason and preserves the
+remaining source and recovery state. Do not clear the directory manually.
+
+## Controls
+
+The shared typed operation accepts:
+
+- `{ "action": "status" }`: local counts and reservation; no hosted mutation.
+- `{ "action": "reconcile" }`: resume the exact outstanding Trash transaction,
+  then read hosted receipts for pending commands. It never repeats ingestion.
+- `{ "action": "maintain", "confirm": true, "limit": 32 }`: resume the exact
+  outstanding transaction and retire verified completed pairs. Pending commands
+  remain intact. Limit is 1–32. A capped pass reports remaining completed work.
+
+Use `economy ingest journal status`, `economy ingest journal reconcile`, or
+`economy ingest journal maintain --confirm --limit 32`. The MCP tool is
+`ingest_journal` with the typed input above; SDK clients use `ingestJournal`.
+All three surfaces return compact structured results. Refused CLI operations
+exit nonzero; MCP refusals set `isError`. They never report successful sync.
+
+## Preservation and interruptions
+
+A permanent empty kernel-lock file serializes cooperating processes on Linux
+and macOS. Process exit releases the lock. No file deletion, timed stale-owner
+assumption, or process signal is used to take ownership. Do not replace that
+file while the target journal exists.
+
+Before capture, Economy revalidates the current actor's exact key/body-hash
+receipt and compares its meaning with the local receipt. It captures the local
+receipt first, then the intent, then their small maintenance manifest through
+Trash. Both original SHA-256 and the SDK's distinct capsule identity are bound.
+The SDK preserves byte/mode identity and verifies the hosted object before
+source removal. The manifest records each exact Trash operation ID at the
+snapshot checkpoint, before reservation. Earlier interruptions are located in
+this target's dedicated Trash operation journal. Recovery resumes those IDs;
+it never starts a replacement capture for an uncertain operation.
+
+One immutable authority anchor remains after retirement. It references a
+committed Economy receipt, contains no credential, and prevents a changed
+principal from silently treating previously retired keys as new commands.
+Restored records keep their original key/body and are reconciled normally.
+Changing or losing the anchor's authority requires deliberate recovery under
+an eligible original principal; successful authentication as another principal
+is insufficient. The same-key path checks hosted history before staging or
+sending a new command.
+
+These are client source contracts. Publication, fleet readiness, actual hosted
+capture/restore and independent release review require their own acceptance
+evidence.