# Qzotic ledger, portfolio and notifier repairs

Python 3.10+; default root /Users/bpa/ForesixaQuant (the installed system, not its Desktop spreadsheet folder).

## Install
Extract the archive, open Terminal in its folder, then run:

```bash
bash install_mac.sh /Users/bpa/ForesixaQuant
```

Installer runs 24 isolated tests, backs up the three existing modules, and replaces them one by one. It never runs the operational validator/ranker/notifier or opens business databases. No JSON ledger or credentials are included. Supervisor, Luxzia, host schedules and databases are not changed. For another root pass it explicitly; module CLI paths must likewise be overridden.

## Check on your actual host

```bash
python3 /Users/bpa/ForesixaQuant/generated/verify_ledger_json.py
python3 /Users/bpa/ForesixaQuant/generated/portfolio_performance_ranker.py
python3 /Users/bpa/ForesixaQuant/generated/telemetry_notifier.py
```

Validator and ranker are read-only. The notifier command is DRY_RUN by default. If the validator reports issues, retain the ledger and reconcile to actual source evidence; do not recreate or replace it with demonstration data. The old validator may already have overwritten a ledger when it was previously run. This repair prevents future overwrites; recovery of historical source data requires the owner's original records/backups.

## Ledger contract
Nonempty JSON array, required equity_symbol, date_acquired, date_sold_or_disposed, gross_proceeds, cost_basis, net_gain_or_loss. Currency is USD. Monetary values must be strings or integers, bounded, finite, with up to six fractional digits. No silent rounding or acceptance of JSON floats. Uses exact Decimal arithmetic, reporting dollar values to six places. Formula: net gain/loss = proceeds - basis + explicit adjustment_amount (default zero). Nonzero adjustments require adjustment_reason. This is a declared ledger reconciliation contract, not an assertion of the allowable tax adjustments for a return.

Date-only YYYY-MM-DD is allowed. Full timestamps require an explicit offset; acquisition and disposal must use the same representation. Mixed representations, missing dates and reversed dates fail. Duplicated transaction IDs and exact duplicate rows fail. Missing transaction IDs generate warnings because independent uniqueness cannot be guaranteed. Partial totals are withheld when rows fail. Breakeven and losses are distinct. Delta values are dollars, not percentages. Actual transaction/broker reconciliation, tax treatment, IRS schemas/business rules, return completeness and CPA approval remain outside this module. Its PASS is not tax filing clearance.

## Ranker contract
Uses allocated_budget_cents from the current portfolio schema and actual recorded remediation statuses. Opens SQLite mode=ro and reads a consistent snapshot. TEST_ names are excluded explicitly from business totals without deleting their records. This is a name-based filter; it cannot discover unidentified sample records. Date-only/naive deadlines become NEEDS_DEADLINE_REVIEW rather than guessed deadlines. Missing execution evidence is exposed. Review priority is a declared sorting rule, not a performance percentage: deadline-data review, failed/unknown action, overdue active project, other. No arbitrary 100/90/50 efficiency scores, investment win-rate, asserted successful remediation, revenue/assets claims or database writes.

## Notifier contract
Standalone stdlib adapter replaces the 52-byte comment placeholder. Supports private notification_credentials.json (app_token/user_token) or explicitly supplied credentials.env using NOTIFIER_APP_TOKEN/NOTIFIER_USER_TOKEN. Checks private ownership/mode; no keys are printed. Default CLI never sends. Optional authorized phone test:

```bash
python3 /Users/bpa/ForesixaQuant/generated/telemetry_notifier.py --send --message "Qzotic notification connection test"
```

Only run that after configuring the owner's recipient credentials and authorizing the test. If using the existing .env explicitly pass --credentials /Users/bpa/ForesixaQuant/credentials.env. The adapter posts to https://api.pushover.net/1/messages.json with TLS verification and rejects redirects. API_ACCEPTED proves provider acceptance, not phone observation/acknowledgement. Ambiguous failures remain UNKNOWN. No automatic retries or separate scheduler is added by this module. The repaired Consigliere supervisor already owns its outbox dispatch via an equivalent adapter; do not run another automated sender alongside it. Luxzia outbox is still unconnected. No SMS capability is claimed by the legacy compatibility method name.

## Verification
24 tests use isolated data, temporary databases, harmless amounts and mock API transport. Include unchanged ledger/DB bytes, invalid data, exact six-decimal arithmetic, chronology, duplication, adjustments, breakeven, current-schema ranker, missing evidence, test-record exclusion, credentials checks, acceptance vs delivery and dry-run defaults. Mac operational data results and real phone delivery remain to be verified. No production-ready or ecosystem release claim.

Primary notification API documentation: https://pushover.net/api