# Luxzia research layer

Python 3.10+, macOS/Linux. This package creates a separate lucxia_research.db when the runtime is started. No changes to Consigliere, its database, trading, tax or notification configuration. No network calls, cron jobs or host clock changes. Persona and research descriptions remain metadata; no predictive or diagnostic capability is claimed.

## Installation
Extract this archive, open Terminal in the extracted folder, and run:

```bash
bash install_mac.sh /Users/bpa/ForesixaQuant
cd /Users/bpa/ForesixaQuant
python3 luxzia_core.py --root /Users/bpa/ForesixaQuant
```

Installer runs isolated tests, backs up existing Python files and installs replacements. It does not start the runtime. Runtime creates the separate private research database and validates its schema. Existing incompatible research databases are rejected without dropping their data; obtain their schema for a reviewed migration. Consigliere live actions remain disabled.

## Features
- Append-only knowledge revision history, enforced by application API and update/delete SQLite triggers. Database administrators can still modify schema/data; this is not cryptographically immutable storage.
- Recorded-event API with explicit timezone timestamps and supplied verification/evidence labels. Evidence references are required for EVIDENCE_REVIEWED, but not automatically independently verified.
- Fictional scenarios use stable IDs, separate from real-event records. Seed explicitly with --seed-fictional-scenarios. November 1 scenario target is explicitly 2026-11-01T23:59:59Z; the simulated gate is exactly 72 hours earlier at 2026-10-29T23:59:59Z. These are scenario parameters, not predicted encounters or required business dates. A clock-independent scan uses stored data; logging timestamps still use the real clock.
- schedule_reminder(project,target_timestamp,payload,request_uid=None) validates timezone-aware inputs and supports idempotent request IDs. All arithmetic is normalized to UTC.
- --check-reminders queues reminders on the first scan at/after target minus 72 hours and before target. Scans at/after target mark MISSED_LATE_RUN and do not dispatch overdue reminders. Queue insertion and reminder state transition commit together. Suppression applies to pending reminders only.
- One OS lock per research DB prevents concurrent cooperating processors. Private files and owner checks protect local records. Host disk encryption, retention, deletion/export governance and sensitive-data permissions remain operational responsibilities. Do not use this local research layer as a taxpayer or child-profile repository.

## Reminder limitations
lucxia_notification_outbox contains actual queued payloads, not delivery claims. It is local to the research DB and is not connected to Consigliere/Pushover. This package installs no scheduler: --check-reminders is a one-pass check, so exact wall-clock delivery is not promised. An authenticated bridge and independently tested host scheduler are needed before live reminder delivery. Do not pass fictional scenarios to a real notification sender automatically.

## Research API example

```python
from lucxia_core import LuxziaResearchSystem
with LuxziaResearchSystem('/Users/bpa/ForesixaQuant/lucxia_research.db') as journal:
    journal.record_knowledge_revision(
        topic='Your study topic',
        focus_desc='Your exact research focus',
        sources='Specific sources and evidence, or clearly label unverified notes',
        feedback='Your observations'
    )
```

No automatic Remote Viewing sample or claim of completed study is inserted on startup. Study completion and capability evaluation require separate evidence.

## Verification
python3 test_luxzia.py runs 17 isolated tests: separation, empty startup, revision preservation, append-only history, idempotent scenarios, clock-independent exploration, exact 72-hour boundary, late runs, timezone validation, duplicate request conflicts, suppression, rollback, evidence-reference checks, runtime lock, unsupported-schema preservation and restart. Tests do not send messages or modify your operating database. Mac host installation and actual journal use remain to be verified there.

## Rename compatibility
New installations use luxzia_research.db. If lucxia_research.db already exists, it is reused automatically with its records and table names intact. The old lucxia_core.py command and LucxiaResearchSystem import remain compatible through the installed shim/alias. If both database filenames exist, startup stops for explicit reconciliation. The persona identity now displays Luxzia. This rename does not change live-execution settings or establish public name clearance.