diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 2bc036f..72e5e84 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -1,53 +1,37 @@ # Security Policy -## Scope +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -This repository contains public documentation only. No production source code, -credentials, model weights, or client data are stored here. However, we take -seriously any security-relevant finding that touches Disuza Quantitative's -public surfaces: +## CURRENT — scope -- This repository and its contents. -- The Disuza Quantitative website at [disuza.com](https://disuza.com). -- Any Disuza-operated endpoints that are reachable from the public internet. +This repository contains public documentation and its read-only quality +checks. It does not contain the private trading code, credentials, model +weights, private datasets, account details, or operational infrastructure. -## Reporting a vulnerability +Security reports in scope for this policy concern files, workflows, links, or +metadata published by this repository. -**Please do not open a public GitHub issue for security findings.** +## CURRENT — reporting -Send an email to **[contact@disuza.com](mailto:contact@disuza.com)** with: +Do not publish a suspected vulnerability or sensitive value in a GitHub issue. +Send a minimal report to +[contact@disuza.com](mailto:contact@disuza.com), including: -- A description of the finding and its suspected impact. -- Steps to reproduce (proof-of-concept, logs, or scripts as needed). -- Any suggested mitigation or fix. -- Your contact details and whether you wish to be credited in an acknowledgment. +- the affected public file or workflow; +- the observed impact; +- safe reproduction steps; and +- contact details if a reply is requested. -You can also reference the canonical security contact at -[disuza.com/.well-known/security.txt](https://disuza.com/.well-known/security.txt) -(RFC 9116). +Do not include credentials, private data, or unnecessary exploit material. +Receipt of a report does not create a service-level, bounty, employment, or +commercial commitment. -## Timelines +## CURRENT — boundaries -- **Acknowledgment:** within 48 hours of receipt. -- **Triage and initial response:** within 7 days. -- **Resolution:** proportionate to severity, typically 30 days or less for - confirmed issues on our public surfaces. - -## Out of scope - -- Third-party services, dependencies, and cloud providers (please report to - their respective security teams). -- Social engineering, physical security, or issues targeting Disuza personnel. -- Self-inflicted misconfigurations in forks or adaptations of this - documentation. -- Findings already reported or publicly known at the time of your report. - -## Recognition - -We appreciate coordinated disclosure and will acknowledge researchers who -report valid findings in good faith (with their permission). Disuza does not -currently operate a monetary bug-bounty programme. +This policy does not represent a live trading platform, a public security +programme for private infrastructure, or a monetary bug bounty. Third-party +services and dependencies remain governed by their own reporting processes. --- -*Disuza Quantitative Security — [contact@disuza.com](mailto:contact@disuza.com)* +Disuza Quantitative Public Technical Reference · v4.0.0 candidate · Unreleased · Last verified 2026-09-01 diff --git a/.github/profile/README.md b/.github/profile/README.md index d35334d..e68e053 100644 --- a/.github/profile/README.md +++ b/.github/profile/README.md @@ -1,79 +1,69 @@
+ + # Disuza Quantitative -**Private quantitative trading research laboratory · Madrid, Spain · Founded 2025** +Private pre-deployment quantitative R&D initiative -[Website](https://disuza.com) · [Guest Portal](https://disuza.com/guest) · [Wikidata](https://www.wikidata.org/wiki/Q139491356) · [LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) · [LLM Context](https://disuza.com/llms.txt) +Public documentation v4.0.0 candidate · Unreleased · Last verified 2026-09-01 ---- +[Website](https://disuza.com) · +[LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) · +[Public technical reference](https://github.com/DisuzaQuantitative/Disuza-Quantitative)
-## About - -Disuza Quantitative engineers systematic execution algorithms for digital asset -perpetual futures (BTC, ETH) and US equity index futures (NQ, ES). The firm -operates proprietary capital and invitation-only partner accounts under a -closed-access, non-custodial model. It is not a high-frequency -trading firm, not a retail-facing signal-selling service, and not a public hedge -fund. - -## Founders +--- -- **Yasmine Bendhiab** — Co-Founder & CEO. Strategic operations and corporate - compliance. Based in Madrid, Spain. - [LinkedIn](https://www.linkedin.com/in/yasmine-bendhiab-22379319a/). +## CURRENT — about -- **Fares Bendhiab** — Co-Founder & CTO. Lead architect of the quantitative - infrastructure. Based in Bizerte, Tunisia. - [LinkedIn](https://linkedin.com/in/fares-bendhiab-40866828a) · - [GitHub](https://github.com/FaresDisusa). +Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. Its work +concerns research governance, validation discipline, software design, and the +controlled development of a systematic research stack. -## Technology +The initiative is pre-deployment. Public descriptions must not be read as +claims of live trading, managed capital, investment services, investment +performance, legal registration, licensing, regulatory approval, or +authorization. -Rule-based systematic engine with a layered risk overlay, running on Google -Cloud. Machine learning is restricted to auxiliary roles (meta-labeling, dynamic -position sizing, regime detection) per López de Prado's framing — never as the -primary signal generator. Multi-source ingestion pipeline combining -exchange market data (OHLCV + L2 + trades + funding + open interest + -liquidations), redundant venue-direct WebSocket capture for forward-stream -resilience, macro context, and on-chain regime gating signals used -strictly as L1-L2 macro context, processed through point-in-time feature -pipelines. Execution via -prop-trading-programme APIs and self-custody perpetual venues under -trade-only permissions. +Forward-only market-data capture and monitoring are operational for research +data collection. They do not place orders, operate accounts, connect capital, +or constitute a trading runtime. A bounded execution-engine contract is +qualified on deterministic synthetic fixtures only; it has not processed market +data and does not qualify performance or deployment. -## Regulatory posture +## Status -Operating in a pre-licensing phase, monitoring the MiCA (EU) and FINMA (Swiss) -regulatory landscapes. Non-custodial client relationships. CFTC Rule 4.41 -acknowledged for simulated performance. Not soliciting retail investors and not -offering regulated investment services at this stage. +| Label | Public meaning | +| --- | --- | +| **CURRENT** | Documentation, governance work, and research tooling under controlled development. | +| **IN PROGRESS** | Validation, data, execution, risk, and operational controls being developed or evaluated. | +| **TARGET** | An auditable, deployment-ready research and execution stack, subject to qualification gates. | -## Public repositories +Target-state documentation does not establish present capability. -This organisation maintains a small number of public repositories for technical -reference and transparency: +## Public repository - **[Disuza-Quantitative](https://github.com/DisuzaQuantitative/Disuza-Quantitative)** - — the living technical reference. Architecture, methodology, and operations. + — the versioned public technical reference, including machine-readable + [public facts](../../PUBLIC_FACTS.yml). -Source code for the trading platform itself is proprietary and not hosted on -GitHub. +The repository does not publish a production trading platform, proprietary +source code, private datasets, model weights, secrets, or a performance record. ## Contact -**[contact@disuza.com](mailto:contact@disuza.com)** — all inquiries. +[contact@disuza.com](mailto:contact@disuza.com) ---- +## Licence -
- -*Disuza Quantitative is a closed-access research laboratory. Documentation is -released under CC BY 4.0; source code, model weights, trademarks, and -operational know-how remain proprietary.* - -**© 2025-2026 Disuza Quantitative** - -
+Current public documentation is available under +[CC BY 4.0](../../LICENSE). +Historical grants remain governed by the notices shipped with their exact +versions. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a306ecd..e5423c4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,40 +1,46 @@ - - If you are inside Disuza Quantitative, thank you — please remove this - comment and complete the template below. ---> +## Public-facts contract -## Summary +- [ ] I checked every changed claim against `PUBLIC_FACTS.yml`. +- [ ] Present capabilities are labelled **CURRENT**. +- [ ] Unfinished and future capabilities are labelled **IN PROGRESS** or + **TARGET**. +- [ ] This change makes no unsupported live, production, performance, + investment-service, legal-status, or regulatory-readiness claim. - +## Confidentiality -## Consistency with facts.ts +- [ ] No internal identifiers, results, trial or split details, data locators, + hashes, infrastructure coordinates, access details, secrets, thresholds, + counterparties, or private-repository identifiers are included. -- [ ] I have verified these docs are consistent with the FACTS_PUBLIC export - in the website repo (`lib/facts.ts`). -- [ ] This PR does not introduce new facts that are not already in the site's - published `llms.txt` / `llms-full.txt`. +## Automated and visual checks -## IP-safety grep +- [ ] The `Public surface` workflow is green. +- [ ] Markdown, links, anchors, CFF, Mermaid, and secret scanning pass. +- [ ] I previewed the GitHub Markdown and the 1200×630 Open Graph image. -- [ ] I ran the IP-safety grep and it returns `✓ IP-safe`. +## Release boundary -## Rendering check +- [ ] The maintainer checked biographies and responsibilities against current + source material. +- [ ] The maintainer confirmed `contact@disuza.com` as the public contact. +- [ ] The maintainer checked CC BY 4.0 and `NOTICE.md` against the intended + public licence boundary. +- [ ] Candidate version and verification markers are current; any release date + is added only when the release actually occurs. -- [ ] I previewed this PR on GitHub and confirmed Mermaid diagrams render - correctly. -- [ ] Cross-references (links between doc pages) resolve. +## Downstream boundary -## Version bump +- [ ] This PR does not modify `disuza.com`, `/guest`, `llms.txt`, + `llms-full.txt`, the organization-level `.github` repository, LinkedIn, + Wikidata, or SEO metadata outside this repository. +- [ ] Follow-up work is tracked in + `docs/downstream-alignment-checklist.md`. -If this PR materially changes the documentation surface: +--- -- [ ] I have updated `CHANGELOG.md`. -- [ ] I have updated the `last_updated` HTML comments on every touched page. -- [ ] If this is a new version, I have updated the version marker in the - root `README.md` and `CITATION.cff`. +Disuza Quantitative Public Technical Reference · contribution checklist diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml new file mode 100644 index 0000000..f679bdd --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,104 @@ +name: Public documentation quality + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: docs-quality-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + public-surface: + name: Public surface + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - name: Check out repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.12" + + - name: Validate public facts, claims, links, and anchors + run: python scripts/check_public_surface.py + + - name: Install strict YAML validator dependency + run: python -m pip install --disable-pip-version-check --no-input PyYAML==6.0.2 + + - name: Validate YAML syntax and reject duplicate keys + run: python scripts/validate_yaml.py + + - name: Set up Node.js + uses: actions/setup-node@v6 + with: + node-version: "22" + + - name: Lint Markdown + run: npx --yes markdownlint-cli2@0.22.1 + + - name: Check external links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --config .lychee.toml + './README.md' + './CONTRIBUTING.md' + './CHANGELOG.md' + './NOTICE.md' + './**/*.md' + './.github/**/*.md' + './CITATION.cff' + './PUBLIC_FACTS.yml' + './LICENSE' + fail: true + jobSummary: false + lycheeVersion: "v0.23.0" + output: /tmp/lychee.md + + - name: Validate citation metadata + uses: citation-file-format/cffconvert-github-action@2.0.0 + with: + args: "--validate" + + - name: Render canonical Mermaid diagram + run: | + python scripts/extract_mermaid.py \ + docs/architecture.md \ + /tmp/target-architecture.mmd + npx --yes @mermaid-js/mermaid-cli@11.15.0 \ + --input /tmp/target-architecture.mmd \ + --output /tmp/target-architecture.svg \ + --puppeteerConfigFile scripts/mermaid-puppeteer-config.json \ + --quiet + + - name: Install Gitleaks + env: + GITLEAKS_VERSION: "8.30.1" + GITLEAKS_ARCHIVE_SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb" + run: | + curl --fail --silent --show-error --location \ + "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \ + --output /tmp/gitleaks.tar.gz + echo "${GITLEAKS_ARCHIVE_SHA256} /tmp/gitleaks.tar.gz" | sha256sum --check + tar --extract --gzip --file /tmp/gitleaks.tar.gz --directory /tmp gitleaks + + - name: Scan current tree for secrets with redacted output + run: >- + /tmp/gitleaks dir + --redact=100 + --no-banner + --no-color + . diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 0000000..0f888b9 --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,10 @@ +accept = [200, 204, 206, 429] +include_mail = false +max_retries = 3 +retry_wait_time = 2 +timeout = 20 + +# These services block automated link checkers even when the public page exists. +exclude = [ + "^https://(?:www\\.)?linkedin\\.com/", +] diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..2117674 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,22 @@ +{ + "config": { + "default": true, + "MD001": false, + "MD013": false, + "MD024": { + "siblings_only": true + }, + "MD026": false, + "MD033": { + "allowed_elements": [ + "div" + ] + }, + "MD041": false + }, + "globs": [ + "**/*.md", + "!.git/**", + "!node_modules/**" + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md index c9544df..7e6762e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,195 +1,148 @@ # Changelog -All notable changes to this public technical reference are documented here. +Notable changes to the Disuza Quantitative Public Technical Reference are +recorded here. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +Release numbers describe this public documentation, not a trading system or +investment product. ---- +## [4.0.0] — Unreleased -## [3.1.0] — 2026-05-22 +Last verified: 2026-09-01. ### Context -V3.1 is a corrective release aligned with Disuza's internal governance -update on machine-learning usage policy: the platform is **rule-based -primary**, and machine learning is restricted to auxiliary roles -(meta-labeling, dynamic position sizing, regime detection) per López de -Prado's framing — never as the primary signal generator. Structure of -the 15 documentation files is preserved; all changes are targeted -patches. +Version 4.0.0 resets the public reference around one canonical positioning: +Disuza Quantitative is a **private pre-deployment quantitative R&D +initiative**. + +Architecture and capability descriptions now distinguish **CURRENT**, +**IN PROGRESS**, and **TARGET** state. A target description is not evidence of +deployment, integration, trading activity, or performance. ### Added -- Anti-overfit validation pipeline surfaced publicly in - `docs/regulatory.md` and cross-linked: Combinatorial Purged - Cross-Validation (CPCV), Deflated Sharpe Ratio (DSR), Probability of - Backtest Overfitting (PBO) per López de Prado. -- Methodology section covering frozen temporal splits - (dev / validation / holdout / forward), pre-registered hypotheses, - and per-result reproducibility scripts. -- New FAQ entry "What backtest methodology does Disuza Quantitative use?" -- US equity index futures (NQ, ES) added to the documented market scope. -- "Methodology rigor" added as a fourth source of operational edge in - `docs/overview.md` thesis. +- `PUBLIC_FACTS.yml` as the machine-readable source for public positioning, + lifecycle, status definitions, repository scope, and explicit non-claims. +- `NOTICE.md` for attribution, licence scope, and continuity of historical + licence grants. +- `docs/status.md`, `docs/research-methodology.md`, and a separate downstream + alignment checklist. +- Repository-wide status vocabulary for present state, active work, and + intended future state. +- Explicit boundaries for information that must not be published. +- Read-only documentation CI for facts, claims, Markdown, links, anchors, CFF, + Mermaid, and redacted secret scanning. ### Changed -- ML framing reformulated across the documentation surface: from - "systematic ensemble ML engine paired with a layered risk model" to - "rule-based systematic engine with a layered risk overlay; machine - learning restricted to auxiliary roles". -- Analytics store reference updated from PostgreSQL on Cloud SQL to - BigQuery. -- Execution-protocol description generalised from "FIX-based - institutional-protocol brokers" to "prop-trading-programme APIs - (broker-specific protocols, trade-only scope)". -- Data-source taxonomy reorganised: - - On-chain analytics demoted from primary class to "regime gating - signals (L1-L2 macro context only, not primary alpha)". - - Derivatives flow (L2 order book, trades, funding, open interest, - liquidations) surfaced as part of the primary exchange-data class. - - Venue-direct WebSocket capture surfaced as a redundant - forward-stream-resilience class. -- "Retrain job" renamed to "Calibration job"; "monthly retraining" to - "periodic calibration". -- Skills section "Machine learning" renamed to "Systematic strategy - design" with auxiliary-ML caveat. -- Technology section "Machine learning" renamed to "Engine and - calibration". +- Reframed the root README, organization-profile mirror, citation metadata, + and contribution policy around pre-deployment research and development. +- Reclassified architecture, data, execution, risk, technology, and operations + descriptions by lifecycle status. +- Distinguished operational forward-only research data capture from any + trading runtime, order placement, account operation, or capital connectivity. +- Recorded the bounded synthetic-fixture engine evidence without claiming + market-data, strategy-performance, paper, live, or deployment qualification. +- Separated the current engine route's purged and embargoed anchored + walk-forward plus DSR controls from CPCV and PBO programme methods that apply + only where their evaluation geometry supports them. +- Corrected the public non-technical business, legal, and administrative role. +- Consolidated the architecture into one target-only Mermaid diagram and kept + superseded documentation paths as one-major-version compatibility stubs. +- Rebuilt the 1200×630 Open Graph image around pre-deployment systematic + trading R&D. +- Made CC BY 4.0 the canonical licence for the current public documentation. +- Reduced technical descriptions to a documentation-safe level. ### Removed -- "Attention signals" data class (not in current scope). -- "FIX 4.4 session management" listed as a competency (replaced by - generic "prop-trading-programme API integration"). -- "Monthly retraining cycle" framing. - -### Notes for downstream readers - -The 12-month archived backtest (Apr 2025 – Apr 2026) and the 5-month -validation artefact at `/compliance/validation-2026-04/` (hosted on -disuza.com) are preserved verbatim. Their framing is from a prior model -iteration and does **not** represent the current platform direction. -The OpenTimestamps proofs remain valid as historical artefacts; readers -should not infer current platform performance from those numbers. See -`/compliance/validation-2026-04/LEGACY_FRAMING.md` (added in the website -deployment that accompanies this V3.1 documentation release) for -detailed framing. - -### Migration - -| V3.0 framing (withdrawn) | V3.1 replacement | -| --- | --- | -| Systematic ensemble ML engine | Rule-based systematic engine with auxiliary ML | -| Gradient boosting toolchains (primary) | Scientific Python tooling; ML in auxiliary roles | -| PostgreSQL on Cloud SQL (analytics) | BigQuery | -| FIX-based / institutional-protocol brokers | Prop-trading-programme APIs (broker-specific protocols) | -| Attention signals | (removed — out of current scope) | -| On-chain analytics (primary class) | On-chain regime gating (L1-L2 context only) | -| Digital asset markets (only) | Digital asset perpetual futures + US equity index futures (NQ, ES) | -| Retrain job / monthly retraining | Calibration job / periodic calibration | - ---- +- Statements that could be read as claims of a live or production trading + platform. +- Performance, returns, validated-alpha, managed-account, custody, capital, and + investment-service claims. +- Claims of legal registration, licensing, regulatory approval, or + authorization. +- Guest-portal links and references to historical performance artefacts. +- Private identifiers, control thresholds, infrastructure coordinates, + proprietary implementation details, and unpublished research results. + +### Licence continuity + +The licence change is prospective for the current distribution. Rights already +granted under licence notices attached to earlier versions remain in effect for +the exact historical material covered by those notices. See `NOTICE.md`. + +## [3.1.0] — 2026-05-22 + +### v4 preservation notice + +This historical entry is retained as a disclosure-safe summary. Version 4.0.0 +withdraws every v3.1 statement that could be read as current deployment, +platform, performance, investment, legal, or regulatory status. The exact +entry originally published with v3.1 remains available in the existing Git +history; its removal from current `main` is explicit rather than a silent +rewrite. + +### Historical context + +V3.1 was a corrective documentation release that: + +- changed the stated primary research policy from model-led to rule-based, + with machine learning limited to auxiliary research roles; +- added high-level anti-overfit methodology, temporal separation, + pre-registration, trial accounting, and reproducibility language; +- added NQ and ES to the stated research scope; +- revised technology, data-source, execution-protocol, and calibration + descriptions; and +- removed several superseded technology and data-class claims. + +### Withdrawn v3.1 claims + +- Historical performance and validation-artifact references are not current + evidence and are not republished in v4. +- Statements implying a current platform direction, deployed execution, or + operating infrastructure are withdrawn. +- Any architecture or capability surviving into v4 is restated independently + under **CURRENT**, **IN PROGRESS**, or **TARGET**. ## [3.0.0] — 2026-04-20 -### Context +### v4 preservation notice -Version 3 is a full rewrite of this repository. Previous versions (V1, tagged -`v1.0.0-archive`, originally released January 2025) contained documentation -that described an aspirational architecture rather than the system in -production. Specifically, V1 referenced orchestration via Apache Airflow / -Cloud Composer, a LightGBM quantile-regression model, MetaTrader 5 as the -primary execution venue, and the `ccxt` library for exchange connectivity. -**None of those statements reflect the current production system.** +V3.0 was a full rewrite of the earlier showcase. Its detailed architecture, +operating, legal, regulatory, and organizational language is superseded by +version 4.0.0. The exact original entry remains available in Git history for +provenance; v4 intentionally does not republish sensitive or unsupported +details from that entry. -V1 is preserved as a git tag (`v1.0.0-archive`) for historical reference -but is no longer navigable from `main`. All links to documentation should -now resolve to V3 content. +### Historical scope -### Added -- Living technical reference framing (replacing "portfolio showcase"). -- Architecture description at an IP-safe abstraction level: systematic - ensemble ML engine paired with a layered risk model. -- Public data-source framing: multi-source ingestion (on-chain analytics, - exchange microstructure, macro context, attention signals) through - point-in-time pipelines. -- Execution venue framing: institutional-protocol brokers (FIX-based, - trade-only scope) plus self-custody perpetual venues (trade-scoped API - wallets). -- Regulatory section covering MiCA and FINMA landscape monitoring, - CFTC Rule 4.41 acknowledgment, pre-licensing posture, and explicit - non-solicitation notice. -- Team section with founder bios (Yasmine Bendhiab — Madrid; Fares - Bendhiab — Bizerte). -- FAQ rewritten as a verbatim-lookup surface for LLM retrieval (20+ - questions, each phrased as a prospect or LLM user would ask). -- Mermaid architecture diagrams (high-level, data flow, execution - reconciliation) rendered natively by GitHub. -- `CITATION.cff` for citation-tool compatibility. -- `.github/ISSUE_TEMPLATE/` with question and documentation-clarification - templates. -- Cross-references to `disuza.com`, `disuza.com/llms.txt`, Wikidata item - Q139491356, and LinkedIn company page. +The v3.0 release introduced: -### Changed -- Licence migrated from Apache 2.0 to Creative Commons Attribution 4.0 - International (CC BY 4.0), appropriate for a documentation-only repo. - Added explicit carve-outs for trademarks, source code, model weights, - and a no-endorsement clause. -- Positioning shifted from "portfolio showcase for hiring managers" to - "canonical living technical reference for the firm's architecture, - methodology, and regulatory posture." +- a living-technical-reference format; +- high-level data, research, execution, and risk descriptions; +- founder biographies, FAQ, diagrams, citation metadata, and issue templates; +- cross-references to external identity surfaces; and +- an announced move toward CC BY 4.0 for documentation. -### Removed -- All references to Apache Airflow / Cloud Composer as an orchestrator - (replaced by Cloud Scheduler + Pub/Sub + Firestore). -- All references to LightGBM, quantile regression, specific model - families, feature counts, hold-duration windows, and drawdown - percentages (replaced by abstracted framings per IP-safety policy). -- All references to MetaTrader 5 (MT5) and Compute Engine Windows Server - (no longer part of the execution architecture). -- All references to `ccxt` (replaced by native protocol clients). -- Named counterparty references (FTMO, BrightFunded, Hyperliquid) - collapsed to venue-class descriptions. -- Specific cloud region disclosure (europe-west4) generalised to - "Google Cloud (EU region)." -- Specific data-provider names (Glassnode, Binance) collapsed to - source-class descriptions (on-chain analytics, exchange microstructure). -- Dedicated backtest-methodology page (content merged into the - regulatory section at a much shallower level to avoid providing a - reproduction specification for adversaries). -- Operational cadence details (reconciliation frequency, watchdog - heartbeats, orphan-detection windows) that would have disclosed - attack-window information without marketing value. - -### Security -- Added explicit carve-out in the licence clarifying that trade secrets, - algorithms, model parameters, and operational know-how are not licensed. -- Removed descriptions of API-key scoping patterns that constituted - security-through-publication leakage. -- Added non-solicitation banner in the repository-root README, front-loaded - so it is visible to anyone redistributing the documentation under CC BY - 4.0. - -### Notes for downstream readers -Where the V1 repository made specific technical claims that readers may -have cached or cited, please refer instead to the corresponding V3 section -below: - -| V1 claim (withdrawn) | V3 replacement | -| --- | --- | -| Apache Airflow / Cloud Composer orchestrator | Cloud Scheduler + Pub/Sub + Firestore (see `docs/architecture.md`) | -| LightGBM quantile regression | Systematic ensemble ML engine (see `docs/technology.md`) | -| MT5 on Compute Engine for execution | Institutional-protocol brokers + self-custody venues (see `docs/execution.md`) | -| `ccxt` library | Native protocol clients (see `docs/execution.md`) | -| `europe-west4` region | Google Cloud (EU region) (see `docs/technology.md`) | - ---- - -## [1.0.0-archive] — 2025-01-03 (superseded) - -Initial portfolio-showcase documentation. **Withdrawn.** Claims did not -reflect the production system. Preserved only as a git tag -(`v1.0.0-archive`) for historical reference. Do not cite. +It also removed or generalized named technologies, providers, counterparties, +infrastructure locations, model details, control values, and operational +cadences from earlier public material. + +### Withdrawn v3.0 claims + +- The description of an existing production system is withdrawn. +- Model-led, live-execution, current-infrastructure, performance, legal-status, + and regulatory-readiness language is not current. +- V3 diagrams and component descriptions are superseded by the single v4 + **TARGET — not deployed** architecture. +- Earlier licensing notices remain effective for the exact historical material + to which they applied. + +## [1.0.0-archive] — 2025-01-03 + +Archived initial documentation release. Its claims are withdrawn and it must +not be treated as a current description. The exact historical entry and +release remain available in Git history for provenance. diff --git a/CITATION.cff b/CITATION.cff index 859b5eb..118ca52 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,38 +1,25 @@ cff-version: 1.2.0 -message: "If you cite or reference this documentation, please use the metadata below." -title: "Disuza Quantitative — Public Technical Reference" +message: "This is an unreleased v4.0.0 candidate. If you reference it, identify it as an unreleased candidate." +title: "Disuza Quantitative Public Technical Reference" abstract: >- - Living technical reference for Disuza Quantitative, a private - quantitative trading research laboratory based in Madrid, Spain. - Covers architecture, methodology (anti-overfit validation pipeline - per López de Prado: CPCV, Deflated Sharpe Ratio, Probability of - Backtest Overfitting), data pipelines, execution venues, risk - framework, and regulatory posture. Source code and model weights - are proprietary and not included in this repository. -type: "misc" + Disuza Quantitative is a private, pre-deployment quantitative R&D initiative + building and validating rule-based systematic trading infrastructure. This + unreleased public-reference candidate distinguishes current, in-progress, and + target state. Forward-only market-data capture supports research collection; + it does not represent a live trading system, investment activity, investment + performance, legal registration, or regulatory authorization. authors: - name: "Disuza Quantitative" website: "https://disuza.com" - address: "Madrid, Spain" url: "https://github.com/DisuzaQuantitative/Disuza-Quantitative" repository-code: "https://github.com/DisuzaQuantitative/Disuza-Quantitative" -identifiers: - - type: other - value: "https://www.wikidata.org/wiki/Q139491356" - description: "Wikidata entity" keywords: - - "quantitative trading" - - "systematic trading" - - "algorithmic trading" - - "rule-based trading" - - "anti-overfit methodology" - - "CPCV" - - "deflated sharpe ratio" - - "probability of backtest overfitting" - - "digital assets" - - "us index futures" - - "risk management" - - "financial technology" + - "quantitative research" + - "research governance" + - "pre-deployment" + - "systematic research" + - "validation" + - "auditability" + - "public documentation" license: "CC-BY-4.0" -version: "3.1.0" -date-released: "2026-05-22" +version: "4.0.0" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b62ae26..7fd3382 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,64 +1,84 @@ # Contributing -Thank you for your interest in Disuza Quantitative. +Thank you for your interest in the Disuza Quantitative Public Technical +Reference. -## About this repository +## Repository purpose -This repository is a **living technical reference** for Disuza Quantitative's -architecture, methodology, and regulatory posture. It is maintained by the -firm and updated alongside production changes. It is licensed under -[Creative Commons Attribution 4.0 International (CC BY 4.0)](LICENSE), with -explicit carve-outs for trademarks, source code, and operational know-how. +This repository documents a private, pre-deployment quantitative R&D +initiative. It is a public documentation surface, not a live trading system, +investment product, performance record, or source-code distribution. -## Pull requests +[`PUBLIC_FACTS.yml`](PUBLIC_FACTS.yml) is the canonical machine-readable source +for public positioning and status definitions. -**We do not accept external pull requests against this documentation.** The -content here must stay consistent with the production system, which is not -publicly observable. Attempting to contribute documentation changes from -outside the firm creates a drift surface that we cannot verify, so we decline -such contributions as a matter of policy rather than quality. +## External pull requests -If you have submitted a PR in error, please convert it into an issue -(see below) and we will address it there. +We do not accept unsolicited external pull requests. Public descriptions must +be reconciled against information that is not publicly observable, so an +external contributor cannot independently establish that a proposed capability +statement is safe and accurate. -## Issues +Documentation clarifications and corrections to publicly observable facts are +welcome as issues. -We welcome issues in the following categories: +## Acceptable issues -- **Documentation clarification requests.** A section is unclear or - ambiguous — describe what you tried to learn and where the documentation - fell short. -- **Factual corrections.** A claim is inconsistent with a publicly - observable signal (for example, a broken link, or a statement that - contradicts our published [llms.txt](https://disuza.com/llms.txt)). -- **Questions about the public reference.** If you are trying to - understand Disuza's technology or posture and the existing - documentation does not answer, we are happy to respond. +- Broken links, rendering defects, spelling errors, or ambiguous wording. +- A mismatch between a document and `PUBLIC_FACTS.yml`. +- A missing or incorrect **CURRENT**, **IN PROGRESS**, or **TARGET** label. +- A statement that appears to imply deployment, performance, investment + activity, legal registration, or regulatory authorization. +- A security concern submitted through the process in + [`.github/SECURITY.md`](.github/SECURITY.md). -We will not respond in issues to: +Do not post credentials, private identifiers, unpublished research, security +details, or other sensitive material in a public issue. -- Requests for source code, model weights, datasets, or operational - specifics that are explicitly carved out of the public reference. -- Commercial proposals, partnership inquiries, or career discussions — - these belong at [contact@disuza.com](mailto:contact@disuza.com). -- General cryptocurrency market discussion not related to this - documentation. +## Maintainer publication rules -## Security +Every proposed documentation change must satisfy all of the following: -Please see [`SECURITY.md`](.github/SECURITY.md) for responsible disclosure -of security-relevant findings. +1. **Status-qualified** — capability statements use **CURRENT**, + **IN PROGRESS**, or **TARGET** with the meanings in `PUBLIC_FACTS.yml`. +2. **Evidence-bounded** — wording does not extend beyond publicly supportable + facts. +3. **Pre-deployment** — target designs are not presented as integrated, + deployed, connected to capital, or operating in markets. +4. **Claim-safe** — no returns, alpha, track-record, managed-account, custody, + investment-service, legal-registration, licensing, approval, or + authorization claim is introduced. +5. **Disclosure-safe** — no secrets, private IDs, detailed thresholds, + infrastructure coordinates, proprietary algorithms, or unpublished results + are included. +6. **Metadata-consistent** — a release updates `README.md`, + `PUBLIC_FACTS.yml`, `CHANGELOG.md`, `CITATION.cff`, and the organization + profile to the same version and date. +7. **Licence-consistent** — current public documentation remains CC BY 4.0, + while historical grants remain described accurately in `NOTICE.md`. -## Code of conduct +## Style -We expect all interactions in issues and other project spaces to be -professional and respectful. Harassment, spam, and off-topic or bad-faith -contributions will not be tolerated. +- Use plain English and define specialized terms. +- Separate facts from intended future state. +- Prefer the narrowest claim that the available evidence supports. +- Use repository-relative links for repository files. +- Do not use promotional, predictive, or performance-oriented language. + +## Licence of accepted material + +Material intentionally accepted into the current public documentation is +published under [CC BY 4.0](LICENSE), unless a file explicitly states +otherwise. By submitting material for inclusion, an authorized contributor +must have the right to provide it on those terms. + +Historical material remains subject to the notice shipped with its exact +version. See [`NOTICE.md`](NOTICE.md). ## Contact -All other inquiries: [contact@disuza.com](mailto:contact@disuza.com). +General inquiries: [contact@disuza.com](mailto:contact@disuza.com). --- -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* +Disuza Quantitative Public Technical Reference · v4.0.0 candidate · Unreleased · Last verified 2026-09-01 diff --git a/LICENSE b/LICENSE index 261eeb9..08e47ab 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,39 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ +Creative Commons Attribution 4.0 International - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION +SPDX-License-Identifier: CC-BY-4.0 - 1. Definitions. +The public documentation in this distribution is licensed under the +Creative Commons Attribution 4.0 International Public License. - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. +You may: - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. + - Share — copy and redistribute the material in any medium or format. + - Adapt — remix, transform, and build upon the material for any purpose, + including commercially. - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. +Under the following terms: - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. + - Attribution — You must give appropriate credit, provide a link to the + licence, and indicate if changes were made. You may do so in any + reasonable manner, but not in any way that suggests the licensor endorses + you or your use. + - No additional restrictions — You may not apply legal terms or + technological measures that legally restrict others from doing anything + the licence permits. - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. +No warranties are given. The licence may not provide all permissions necessary +for an intended use. Other rights, including privacy, publicity, moral, patent, +and trademark rights, may limit how the material may be used. - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. +The complete and controlling legal code is available at: - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). + https://creativecommons.org/licenses/by/4.0/legalcode - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. +The human-readable deed is available at: - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." + https://creativecommons.org/licenses/by/4.0/ - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +This file identifies the licence applied to the current distribution. It does +not revoke or replace rights previously granted for historical versions under +the licence notices shipped with those versions. See NOTICE.md for scope and +attribution information. diff --git a/NOTICE.md b/NOTICE.md new file mode 100644 index 0000000..0bd2ad7 --- /dev/null +++ b/NOTICE.md @@ -0,0 +1,50 @@ +# Licensing and Attribution Notice + +## Current distribution + +Version 4.0.0 of the Disuza Quantitative Public Technical Reference is an +unreleased candidate, last verified on 2026-09-01. No release date is claimed. + +Unless a file contains a different notice, original public documentation in +this distribution is offered under the +[Creative Commons Attribution 4.0 International Public License](LICENSE) +(`CC-BY-4.0`). + +A reasonable attribution is: + +> Disuza Quantitative, *Public Technical Reference*, unreleased version 4.0.0 candidate, +> , +> licensed under CC BY 4.0. Changes, if any, were made by the reuser. + +## Scope + +The licence applies only to material actually included in this public +distribution and only to rights the licensor is authorized to grant. + +This repository does not distribute or license production trading source code, +private datasets, model weights, credentials, secrets, proprietary algorithms, +or private operational material. + +Names, logos, trade names, service marks, and other brand identifiers are not +licensed as trademarks. CC BY 4.0 does not grant patent or trademark rights and +does not imply sponsorship, endorsement, legal registration, regulatory +authorization, or official status. + +Third-party names, links, badges, and referenced works remain subject to their +respective rights and terms. + +## Historical licence grants + +Some earlier commits or tagged versions were distributed with an Apache +License 2.0 notice. Rights validly granted under that notice remain available +for the exact historical material to which the notice applied. Version 4.0.0 +does not revoke those grants or retroactively relicense historical copies. + +To determine the terms for an earlier version, inspect the `LICENSE` and notice +files shipped with that exact commit or tag. + +## No endorsement or warranty + +Attribution must not suggest sponsorship, endorsement, legal status, or +regulatory approval. The material is provided without warranties, as described +in the applicable licence. diff --git a/PUBLIC_FACTS.yml b/PUBLIC_FACTS.yml new file mode 100644 index 0000000..9fdf390 --- /dev/null +++ b/PUBLIC_FACTS.yml @@ -0,0 +1,139 @@ +schema_version: 1 +document: + title: "Disuza Quantitative Public Technical Reference" + version: "4.0.0" + release_status: "unreleased" + last_verified: "2026-09-01" + canonical_repository: "https://github.com/DisuzaQuantitative/Disuza-Quantitative" + +initiative: + name: "Disuza Quantitative" + positioning: "Disuza Quantitative is a private, pre-deployment quantitative R&D initiative building and validating rule-based systematic trading infrastructure." + lifecycle: "pre-deployment" + operating_footprint: "Founder-led between Madrid, Spain, and Bizerte, Tunisia." + legal_registration_claim: "none" + regulatory_authorization_claim: "none" + +leadership: + model: "Two-founder private initiative." + co_founders: + - name: "Yasmine Bendhiab" + responsibility: "Business, legal, and administrative coordination; non-technical role." + location: "Madrid, Spain." + - name: "Fares Bendhiab" + responsibility: "Research architecture, quantitative engineering, and technical governance." + location: "Bizerte, Tunisia." + +status_vocabulary: + CURRENT: "Publicly supportable state at the document date." + "IN PROGRESS": "Work being designed, implemented, or evaluated; completion is not claimed." + TARGET: "Intended future state; not a statement of present capability." + +public_status: + CURRENT: + - "A private quantitative research and development initiative." + - "A public documentation and governance corpus." + - "Research tooling under controlled development." + - "Forward-only market-data capture and monitoring are operational for research data collection." + - "A bounded execution-engine contract is qualified on deterministic synthetic fixtures only." + "IN PROGRESS": + - "Validation controls and supporting research software." + - "Data, execution, risk, and operational abstractions." + - "Readiness evidence for future qualification decisions." + TARGET: + - "An auditable, deployment-ready systematic research and execution stack." + - "Promotion between lifecycle stages only after explicit qualification gates." + +capabilities: + CURRENT: + - "Python-based quantitative research tooling." + - "Rule-based strategy specification and evaluation." + - "Temporal data separation and point-in-time quality work." + - "Purged, embargoed, anchored walk-forward evaluation and Deflated Sharpe Ratio (DSR) on the current synthetic engine route." + - "Combinatorial Purged Cross-Validation (CPCV) and Probability of Backtest Overfitting (PBO) as programme methods only where applicable." + - "Hypothesis pre-registration, cumulative trial accounting, and reproducibility controls." + - "Cloud-supported batch research workflows." + - "Audit-oriented documentation and research governance." + "IN PROGRESS": + - "Stronger access-integrity and audit-evidence controls." + - "Data, risk, state, and execution abstractions." + - "Order-and-fill accounting and failure-handling controls." + - "Evidence packages for later paper-execution qualification." + TARGET: + - "An integrated, auditable systematic research and execution stack." + - "Qualified paper-execution and venue-adapter paths." + - "Reconciled runtime state and risk-reducing failure behaviour." + - "Explicit human promotion decisions between lifecycle stages." + +target_architecture: + status: "TARGET" + deployment: "not deployed" + components: + - "Governed research inputs." + - "Point-in-time dataset construction." + - "Rule-based candidate evaluation." + - "Validation and governance review." + - "Explicit promotion decision." + - "Paper-execution qualification." + - "Venue-adapter boundary." + - "Risk and state controls." + - "Order and fill reconciliation." + - "Audit evidence." + +research_scope: + core_markets: + - "BTC and ETH perpetual markets." + - "NQ and ES index-futures markets." + optional_research: + - "Optional CFD adaptations are evaluated as a separate research lane." + primary_horizon: "Approximately 30 minutes to 4 hours." + boundary: "Programme research scope only; not qualified engine coverage or current trading activity." + +research_data_capture: + status: "CURRENT" + scope: "Forward-only market-data capture and monitoring are operational for research data collection." + boundary: "They do not place orders, operate accounts, connect capital, or constitute a trading runtime." + +qualified_engine: + status: "CURRENT" + evidence: "A bounded execution-engine contract is qualified on deterministic synthetic fixtures only." + boundary: "It has not processed market data and does not qualify a strategy, an economic result, paper execution, live execution, or deployment." + scope_boundary: "Its narrow contract does not establish coverage of the programme research universe or design horizon." + +methodology: + primary_signal_policy: "Rule-based." + auxiliary_machine_learning: "Eligible only after the related hard-rule baseline qualifies out of sample." + public_methods: + - "Temporal separation." + - "Hypothesis pre-registration." + - "Cumulative trial accounting." + - "Purged, embargoed, anchored walk-forward evaluation and Deflated Sharpe Ratio (DSR) on the current synthetic engine route." + - "Combinatorial Purged Cross-Validation (CPCV) and Probability of Backtest Overfitting (PBO) as programme methods only where applicable." + - "Sanity checks and reproducibility controls." + limitation: "Research methods reduce avoidable error; they do not establish future performance." + +repository_scope: + included: + - "Public documentation." + - "High-level research, governance, and architecture descriptions." + - "Status-qualified descriptions of current, in-progress, and target work." + excluded: + - "Production trading source code." + - "Secrets, credentials, and private infrastructure identifiers." + - "Private datasets, model weights, and proprietary algorithms." + - "Unpublished research results and operational control thresholds." + +explicit_non_claims: + - "No live or paper trading, production trading platform, customer-facing trading service, order placement, account operation, custody, or capital-management activity is represented." + - "No historical or expected return, validated alpha, or investment-performance claim is made." + - "No investment service, investment advice, financial product, offer, or solicitation is made." + - "No company-registration or financial-services-licence claim, regulatory approval, or authorization is represented." + +licensing: + current_material: "CC-BY-4.0" + historical_grants: "Rights already granted under licences attached to earlier versions remain in effect for those exact versions." + notice: "NOTICE.md" + +contact: + website: "https://disuza.com" + email: "contact@disuza.com" diff --git a/README.md b/README.md index 1aa7483..0eea9a9 100644 --- a/README.md +++ b/README.md @@ -2,146 +2,169 @@ # Disuza Quantitative -### Systematic Crypto Trading Research Laboratory +### Public Technical Reference -**Madrid, Spain · Founded 2025 · Version 3** +Private pre-deployment quantitative R&D initiative -[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?style=flat&logo=python&logoColor=white)](https://python.org) -[![Google Cloud](https://img.shields.io/badge/Google_Cloud-Production-4285F4?style=flat&logo=googlecloud&logoColor=white)](https://cloud.google.com) -[![CC BY 4.0](https://img.shields.io/badge/License-CC_BY_4.0-lightgrey?style=flat)](LICENSE) -[![Wikidata](https://img.shields.io/badge/Wikidata-Q139491356-006699?style=flat&logo=wikidata&logoColor=white)](https://www.wikidata.org/wiki/Q139491356) -[![Last Commit](https://img.shields.io/github/last-commit/DisuzaQuantitative/Disuza-Quantitative?style=flat)](https://github.com/DisuzaQuantitative/Disuza-Quantitative/commits) +Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01 -**Living technical reference** — architecture, methodology, and regulatory posture. -Source code and model weights remain proprietary. +[![Pre-deployment R&D](https://img.shields.io/badge/status-Pre--deployment_R%26D-informational)](PUBLIC_FACTS.yml) +[![License: CC BY 4.0](https://img.shields.io/badge/license-CC_BY_4.0-lightgrey.svg)](LICENSE) +[![Last commit](https://img.shields.io/github/last-commit/DisuzaQuantitative/Disuza-Quantitative)](https://github.com/DisuzaQuantitative/Disuza-Quantitative/commits/main) -[Website](https://disuza.com) · [Guest Portal](https://disuza.com/guest) · [LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) · [LLM Context](https://disuza.com/llms.txt) · [FAQ](docs/faq.md) +[Website](https://disuza.com) · +[LinkedIn](https://www.linkedin.com/company/disuza-quantitative/) · +[Public facts](PUBLIC_FACTS.yml) · +[Documentation](docs/README.md) --- -> **Non-solicitation notice.** This repository is informational documentation only. -> Disuza Quantitative does not offer regulated investment services or solicit retail -> or professional investor capital. No statement in this repository constitutes an -> offer, invitation, or inducement to engage in any investment activity in any -> jurisdiction. Statements about regulatory alignment are expressions of internal -> posture, not representations of regulatory approval or licensed status. Before -> engaging with Disuza Quantitative in any capacity, consult local counsel. +> **Informational documentation only.** Nothing in this repository is +> investment advice, an offer, a solicitation, or a representation of legal +> registration, regulatory authorization, trading-system deployment, trading activity, +> or investment performance. ---- +## CURRENT — what Disuza Quantitative is + +Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. Its +present work concerns research governance, validation discipline, software +design, and the controlled development of a systematic research stack. + +This repository is the initiative's public documentation surface. It does not +contain a production trading platform, proprietary source code, model weights, +credentials, private datasets, or a performance record. -## What Disuza is - -Disuza Quantitative is a private quantitative trading research laboratory engineering -systematic execution algorithms for digital asset perpetual futures (BTC, ETH) and -US equity index futures (NQ, ES). The engine is a rule-based systematic engine with -a layered risk overlay that adjusts exposure in response to -short-horizon regime shifts; machine learning is restricted to auxiliary roles -(meta-labeling, dynamic position sizing, regime detection) per López de Prado's -framing — never as the primary signal generator. The platform runs on Google Cloud -and executes through prop-trading-programme APIs and self-custody perpetual -venues under trade-only permissions. - -## What Disuza is NOT - -- Not a high-frequency trading firm. -- Not a retail-facing signal-selling service. -- Not a public hedge fund — access is closed and by invitation. -- Not licensed at this time — operating in a pre-licensing phase, monitoring the - MiCA and FINMA regulatory landscapes as part of our pre-licensing preparation. - No statement herein constitutes a representation of regulatory compliance or - approval. - -## Architecture snapshot - -```mermaid -graph LR - A[Multi-source ingestion
exchange data · venue WS · macro · on-chain regime] -->|PIT pipelines| B[Feature store] - B --> C[Rule-based signal engine
+ layered risk overlay] - C --> D[Signal router] - D -->|Pub/Sub| E[Execution] - E --> F[Prop-trading-programme APIs] - E --> G[Self-custody perpetual venues] - D -.->|broker-truth reconciliation| F - D -.->|broker-truth reconciliation| G - style A fill:#f3f3f3,stroke:#333 - style C fill:#e8f4f8,stroke:#333 - style E fill:#f0e8f8,stroke:#333 -``` - -Full diagrams live in [`docs/diagrams/`](docs/diagrams/). Architecture walkthrough -in [`docs/architecture.md`](docs/architecture.md). - -## Explore the documentation - -| Section | What you'll find | +## Status vocabulary + +Every architecture or capability statement in this repository must use one of +these labels: + +| Label | Meaning | +| --- | --- | +| **CURRENT** | Publicly supportable state at the date shown in the document. | +| **IN PROGRESS** | Work is being designed, implemented, or evaluated; completion is not claimed. | +| **TARGET** | Intended future state; not a statement of present capability. | + +The machine-readable source for these definitions and the repository's current +positioning is [`PUBLIC_FACTS.yml`](PUBLIC_FACTS.yml). + +## Public status snapshot + +- **CURRENT** — a private quantitative R&D initiative, a documentation and + governance corpus, and research tooling under controlled development. +- **CURRENT** — forward-only market-data capture and monitoring are operational + for research data collection. They do not place orders, operate accounts, + connect capital, or constitute a trading runtime. +- **CURRENT** — a bounded execution-engine contract is qualified on + deterministic synthetic fixtures only. It has not processed market data and + does not qualify a strategy, an economic result, paper execution, live + execution, or deployment. +- **IN PROGRESS** — validation controls, data and execution abstractions, risk + controls, and their supporting software are being developed and evaluated. +- **TARGET** — an auditable, deployment-ready systematic research and execution + stack, subject to explicit qualification gates. + +Descriptions of a target architecture do not imply that its components are +integrated, deployed, connected to capital, or operating in markets. + +## Programme research scope and method + +- **CURRENT** — the programme research scope covers BTC and ETH perpetual + markets and NQ and ES index-futures markets. +- **CURRENT** — optional CFD adaptations are evaluated as a separate research + lane. +- **CURRENT** — the primary design horizon is approximately 30 minutes to + 4 hours. +- **CURRENT** — primary signal generation is rule-based. Machine learning may + be evaluated only in auxiliary roles and only after the related hard-rule + baseline qualifies out of sample. +- **CURRENT** — the current synthetic engine route uses purged, embargoed, + anchored walk-forward evaluation and Deflated Sharpe Ratio (DSR). +- **CURRENT** — Combinatorial Purged Cross-Validation (CPCV) and Probability of + Backtest Overfitting (PBO) are programme methods only where applicable; they + are not claimed for the current synthetic engine route. + +Programme research scope is not qualified engine coverage or current trading +activity. The narrow engine contract does not establish coverage of the +programme research universe or design horizon. + +These methods reduce avoidable research error. They do not establish economic +value or future performance. + +## Explicit non-claims + +The following explicit non-claims apply: + +- No live or paper trading, production trading platform, customer-facing + trading service, order placement, account operation, custody, or + capital-management activity is represented. +- No historical or expected return, validated alpha, or + investment-performance claim is made. +- No investment service, investment advice, financial product, offer, or + solicitation is made. +- No company-registration or financial-services-licence claim, regulatory + approval, or authorization is represented. + +Research methodology can reduce avoidable error; it cannot establish future +performance. + +## Documentation map + +| Section | Scope | | --- | --- | -| [Overview](docs/overview.md) | What Disuza is, the thesis, the regulatory posture | -| [Architecture](docs/architecture.md) | Data plane · compute plane · execution plane · persistence | -| [Data pipeline](docs/data-pipeline.md) | Multi-source ingestion with point-in-time guarantees | -| [Execution](docs/execution.md) | Venue classes, non-custodial execution, broker-truth reconciliation | -| [Risk framework](docs/risk.md) | Tiered drawdown posture, non-custodial guarantees, audit trail | -| [Regulatory](docs/regulatory.md) | MiCA and FINMA landscape, pre-licensing posture, disclosures | -| [Technology](docs/technology.md) | Language, frameworks, orchestration, cloud, observability | -| [Components](docs/components.md) | The services that make up the production platform | -| [Operations](docs/operations.md) | Deployment, monitoring, alerting, reliability posture | -| [Team](docs/team.md) | Yasmine Bendhiab and Fares Bendhiab | -| [Skills](docs/skills.md) | Technical competencies applied to the platform | -| [FAQ](docs/faq.md) | Questions about access, technology, regulation, and collaboration | - -## Team - -**Yasmine Bendhiab** — Co-Founder & CEO · Strategic Operations & Corporate Compliance -Madrid, Spain · [LinkedIn](https://www.linkedin.com/in/yasmine-bendhiab-22379319a/) - -**Fares Bendhiab** — Co-Founder & CTO · Lead Architect of the Quantitative Infrastructure -Bizerte, Tunisia · [LinkedIn](https://linkedin.com/in/fares-bendhiab-40866828a) · [GitHub](https://github.com/FaresDisusa) - -## Regulatory snapshot - -- **Jurisdiction:** Kingdom of Spain, registered entity in Madrid. -- **Phase:** Pre-licensing. -- **Monitoring:** MiCA (EU Markets in Crypto-Assets Regulation) and FINMA (Swiss - Financial Market Supervisory Authority) regulatory landscapes. -- **Simulated performance:** CFTC Rule 4.41 acknowledged. Any backtest results - referenced on the public guest portal are hypothetical historical simulations. -- **Custody model:** Non-custodial — credentials scoped to trade-only operations - across both execution classes. -- **Access model:** Closed-access, invitation-only. Not soliciting retail investors. - -Detail in [`docs/regulatory.md`](docs/regulatory.md). +| [Documentation index](docs/README.md) | Reading order and status conventions | +| [Public status](docs/status.md) | Current work, controls in progress, and target direction | +| [Overview](docs/overview.md) | Initiative scope and public boundaries | +| [Research methodology](docs/research-methodology.md) | Rule-based policy and anti-overfit controls | +| [Architecture](docs/architecture.md) | Current, in-progress, and target system views | +| [Components](docs/components.md) | Component responsibilities and status | +| [Data pipeline](docs/data-pipeline.md) | Data-quality and lineage design | +| [Execution](docs/execution.md) | Execution-control design, not live execution | +| [Risk](docs/risk.md) | Research and operational risk controls | +| [Operations](docs/operations.md) | Pre-deployment operational readiness | +| [Technology](docs/technology.md) | Tools used or evaluated in R&D | +| [Regulatory](docs/regulatory.md) | Public disclaimers and non-claims | +| [FAQ](docs/faq.md) | Short answers about scope and status | +| [Team](docs/team.md) | Public project roles | +| [Downstream alignment](docs/downstream-alignment-checklist.md) | Post-release checklist for surfaces excluded from v4.0.0 | + +## Repository boundaries + +The public repository intentionally stays at a documentation-safe level. It +must not include secrets, private identifiers, detailed control thresholds, +private infrastructure coordinates, proprietary algorithms, or unpublished +research results. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the publication +rules. ## Contact -All inquiries (general, partnerships, careers): **[contact@disuza.com](mailto:contact@disuza.com)** +General inquiries: [contact@disuza.com](mailto:contact@disuza.com). -## Documentation licence +## Licence -This documentation is released under -[Creative Commons Attribution 4.0 International (CC BY 4.0)](LICENSE) with -explicit carve-outs for trademarks, source code, model weights, and operational -know-how. See [`LICENSE`](LICENSE) for the full text and the no-endorsement -clause required for adaptations. +Unless a file says otherwise, the current public documentation is licensed +under [Creative Commons Attribution 4.0 International](LICENSE). Historical +licence grants remain valid for the exact material and versions to which they +were originally applied; see [`NOTICE.md`](NOTICE.md). ---
-*Disuza Quantitative is a closed-access research laboratory. This repository -contains architecture and methodology notes as a living public reference. Source -code, model weights, and operational know-how are proprietary.* +Disuza Quantitative · Public Technical Reference · v4.0.0 candidate -**© 2025-2026 Disuza Quantitative · CC BY 4.0** +Unreleased · Last verified: 2026-09-01
diff --git a/docs/README.md b/docs/README.md index 8b5a80e..4827f5a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,64 +1,80 @@ -# Disuza Quantitative — Documentation - -Welcome to the living technical reference. This documentation is versioned, -dated, and consistent with the machine-readable context files published at -[disuza.com/llms.txt](https://disuza.com/llms.txt) and -[disuza.com/llms-full.txt](https://disuza.com/llms-full.txt). - -## How to read this - -If you are a **prospect or partner doing due diligence**, start with: -1. [Overview](overview.md) — what Disuza is, the thesis, the positioning -2. [Regulatory](regulatory.md) — MiCA and FINMA landscape, pre-licensing posture -3. [Team](team.md) — founders and leadership - -If you are a **technical reader** (engineer, researcher, prospective partner -technical evaluator), start with: -1. [Architecture](architecture.md) — the system at a glance -2. [Data pipeline](data-pipeline.md) — ingestion and point-in-time guarantees -3. [Execution](execution.md) — venue classes and reconciliation -4. [Technology](technology.md) — stack and tooling - -If you are an **LLM or AI assistant** ingesting this for grounded retrieval, -every page carries a machine-readable `last_updated` marker and links back to -the canonical context files at disuza.com. - -## Sections - -| # | File | Purpose | -| --- | --- | --- | -| 1 | [`overview.md`](overview.md) | Company, thesis, positioning, what Disuza is and is NOT | -| 2 | [`architecture.md`](architecture.md) | Data plane, compute plane, execution plane, persistence | -| 3 | [`data-pipeline.md`](data-pipeline.md) | Multi-source ingestion with point-in-time guarantees | -| 4 | [`execution.md`](execution.md) | Venue classes, non-custodial execution, broker-truth reconciliation | -| 5 | [`risk.md`](risk.md) | Tiered drawdown posture, non-custodial guarantees, audit trail | -| 6 | [`regulatory.md`](regulatory.md) | MiCA and FINMA landscape monitoring, pre-licensing, disclosures, anti-overfit validation pipeline (CPCV / DSR / PBO per López de Prado) | -| 7 | [`technology.md`](technology.md) | Language, frameworks, orchestration, cloud, observability | -| 8 | [`components.md`](components.md) | The services that make up the production platform | -| 9 | [`operations.md`](operations.md) | Deployment, monitoring, alerting, reliability posture | -| 10 | [`team.md`](team.md) | Founders and leadership | -| 11 | [`skills.md`](skills.md) | Technical competencies applied to the platform | -| 12 | [`faq.md`](faq.md) | Frequently asked questions, verbatim-lookup style | - -## Diagrams - -Architecture diagrams are in [`diagrams/`](diagrams/) as Mermaid source files -that GitHub renders natively when viewing the linked pages. - -## What's NOT included - -- Trading strategies, alpha-generating signals, or feature engineering details. -- Model architecture specifics, weight distributions, hyperparameter values. -- Client data, trading records, real-time market data, or operational metrics. -- Source code, containers, or deployment manifests. -- Internal operational runbooks, incident postmortems, or on-call procedures. - -For the operational and internal dashboards, access is restricted to -authorised personnel at [disuza.com/dashboard](https://disuza.com/dashboard). +# Disuza Quantitative — Public Documentation ---- +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +**CURRENT:** Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. This +public reference separates verified current work from work in progress and +longer-term target architecture. + +Disuza Quantitative does not present a live trading platform, publish current +investment performance, or offer an investment service. + +Release-level status and non-claims are recorded in +[`PUBLIC_FACTS.yml`](../PUBLIC_FACTS.yml). + +## Status vocabulary + +Every capability statement in the v4 documentation uses one of these labels: + +- **CURRENT** — verified as part of the present research programme. +- **IN PROGRESS** — active work that is not yet qualified as complete. +- **TARGET** — intended future capability. It is not deployed, qualified, or + promised. + +Target architecture must never be read as current operating capability. + +## Start here + +| Page | Purpose | +| --- | --- | +| [`status.md`](status.md) | Current research stage, work in progress, and target direction | +| [`overview.md`](overview.md) | Initiative, scope, positioning, and leadership footprint | +| [`research-methodology.md`](research-methodology.md) | Research policy and anti-overfit controls | +| [`architecture.md`](architecture.md) | Current research foundation versus target system design | +| [`risk.md`](risk.md) | Current research-risk posture and target deployment controls | +| [`regulatory.md`](regulatory.md) | Non-solicitation and public-claim posture | +| [`faq.md`](faq.md) | Short answers to common questions | +| [`team.md`](team.md) | Founder responsibilities and deliberately limited biographies | +| [`skills.md`](skills.md) | Demonstrated and developing capabilities | +| [`downstream-alignment-checklist.md`](downstream-alignment-checklist.md) | Surfaces excluded from v4.0.0 that require later alignment | + +## CURRENT — programme research scope -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* -*Source of truth: [https://disuza.com/llms-full.txt](https://disuza.com/llms-full.txt)* +The core research scope covers BTC and ETH perpetual markets and NQ and ES +index-futures markets. Optional CFD research is evaluated as a separate lane. +The primary design horizon is approximately 30 minutes to 4 hours. + +This is a research scope, not a statement that these markets are currently +traded live. + +It is not qualified engine coverage. A bounded execution-engine contract is +qualified on deterministic synthetic fixtures only; it has not processed market +data and its narrow contract does not establish coverage of the programme +research universe or design horizon. + +Forward-only market-data capture and monitoring are operational for research +data collection. They do not place orders, operate accounts, connect capital, +or constitute a trading runtime. + +## What is not included + +The public reference excludes: + +- strategy rules, signals, features, and parameters; +- private source code and private research records; +- datasets, provider entitlements, and lineage identifiers; +- trial counts, research verdicts, and performance metrics; +- account, counterparty, credential, and infrastructure details; +- operational thresholds, runbooks, incident records, and security boundaries. + +## Publication rule + +If a public statement cannot be supported as current, it must be labelled +**IN PROGRESS** or **TARGET**. If the evidence is not suitable for public +release, the statement is omitted. + +--- - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/architecture.md b/docs/architecture.md index 9239344..3212a88 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,166 +1,195 @@ # Architecture -> High-level system architecture of the Disuza Quantitative platform at the -> abstraction level appropriate for public reference. Internal implementation -> details, model parameters, and operational cadences are not included. - -## Design philosophy - -The platform is built on four core principles: - -1. **Event-driven orchestration.** Workflows are triggered by a cloud-hosted - scheduler and mediated through a pub/sub event bus, with consumer-side - idempotency. There is no central dependency-tracked DAG orchestrator. -2. **Domain-driven separation.** Data ingestion, feature engineering, - inference, risk, and execution are independent services that communicate - through well-defined contracts. -3. **Fail-safe operations.** Every service is designed to fail gracefully. - Consumers tolerate at-least-once delivery via a processed-message ledger - and stable idempotency keys. State persists across restarts in Firestore - and BigQuery. -4. **Observability first.** Structured logging, custom metrics, heartbeat - watchdogs, and operator alerts are part of every service from day one. - -## Planes - -Disuza's architecture decomposes into three functional planes plus an -orchestration tier and persistence tier. - -### Data plane - -- Multi-source ingestion combining exchange market data (OHLCV + L2 order - book + trades + funding + open interest + liquidations), redundant - venue-direct WebSocket capture for forward-stream resilience, macro - context, and on-chain regime gating signals used strictly as L1-L2 - macro context (not as primary alpha source). -- Real-time and point-in-time feature pipelines with retroactive-revision - guardrails so that training and live inference see the same feature - distributions. -- Schema validation and last-known-good fallbacks prevent malformed or - missing data from poisoning downstream inference. - -Detail in [`data-pipeline.md`](data-pipeline.md). - -### Compute plane - -- **Rule-based signal engine** — the direction-agnostic core that produces - position decisions from the feature store, governed by a fixed parameter - set rather than a learned primary model. Machine learning, when used, is - confined to auxiliary roles (meta-labeling, dynamic position sizing, - regime detection) per López de Prado's framing. -- **Layered risk overlay** — modulates exposure when short-horizon signals - disagree with the primary stance, implementing counter-positioning - discipline rather than naïve directional betting. -- **Signal router** — combines engine outputs with risk-framework gates - before publishing to the execution plane. - -Internal model architecture, feature details, hold horizons, and signal -taxonomy are proprietary and not published. - -### Execution plane - -- **Venue adapters** — prop-trading-programme APIs (broker-specific - protocols, trade-only scope; including US equity index futures venues - for NQ and ES) and self-custody perpetual venues (trade-scoped API - wallets). -- **Order lifecycle manager** — place, monitor, reconcile, and close. -- **Broker-truth reconciliation** — the broker's own position and fill - history is the source of truth for PnL and account state. Reconstructed - PnL uses actual broker fills, not algorithmic estimates. - -Detail in [`execution.md`](execution.md). - -### Orchestration tier - -Cloud Scheduler is the clock. Pub/Sub is the event bus. Firestore is the -real-time state store. Consumer services use stable idempotency keys and a -processed-message ledger so that at-least-once delivery produces -exactly-once effects. - -### Persistence tier - -- **Firestore** for real-time state (open positions, account equity, kill - switches, execution status). -- **BigQuery** for historical analytics (trade ledger, equity curves, - per-trade attribution). -- **Cloud Storage** for model artefacts, feature snapshots, and cache - manifests. - -## High-level architecture diagram - -Full diagram in [`diagrams/high-level-architecture.mmd`](diagrams/high-level-architecture.mmd). -GitHub renders Mermaid natively. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +This page separates the present research foundation from work in progress and +the intended system design. The release-level definitions and non-claims in +[`PUBLIC_FACTS.yml`](../PUBLIC_FACTS.yml) govern every statement below. + +## Status vocabulary + +- **CURRENT** — publicly supportable at the date shown above. +- **IN PROGRESS** — being designed, implemented, or evaluated; completion is + not claimed. +- **TARGET** — intended future capability; it is not a statement of present + operation. + +## CURRENT — research foundation + +The current foundation is a private research environment, not an operating +trading platform. It supports: + +- rule-based strategy research; +- private Python-based research tooling; +- data acquisition and quality-control work; +- forward-only market-data capture and monitoring for research data collection; +- cloud-supported batch research workflows; +- statistical validation and reproducibility controls; +- audit-oriented research governance. + +The research universe covers BTC and ETH perpetual markets and NQ and ES +index-futures markets. Optional CFD adaptation is evaluated as a separate +research lane. The primary design horizon is approximately 30 minutes to +4 hours. + +This is programme research scope only, not qualified engine coverage or current +trading activity. A bounded execution-engine contract is qualified on +deterministic synthetic fixtures only. Its narrow contract does not establish +coverage of that research universe or design horizon. +It has not processed market data and does not qualify a strategy, an economic +result, paper execution, live execution, or deployment. + +Primary signal generation is rule-based. Machine learning may be evaluated +only in auxiliary research roles and only after the corresponding hard-rule +baseline qualifies out of sample. + +The operational data-capture surface is separate from the trading-system +lifecycle. It does not establish integrated runtime inference, deployed +execution, order placement, account operation, capital connectivity, or live +trading. + +## IN PROGRESS — controlled abstractions + +The programme is developing and evaluating high-level abstractions for: + +- point-in-time data preparation and quality controls; +- candidate evaluation and reproducibility evidence; +- risk, state, and execution boundaries; +- order and fill accounting; +- failure handling and operator-review evidence. + +These abstractions remain subject to verification. Their presence in design +material does not establish that a complete system exists or is ready for +deployment. + +## TARGET — design principles + +Any future qualified system is intended to preserve five boundaries: + +1. **Research before promotion.** A candidate advances only through explicit + evidence and a human decision. +2. **Rule-based primary logic.** Auxiliary ML cannot replace the hard-rule + baseline. +3. **Point-in-time integrity.** Evaluation inputs must reflect what would have + been available at the relevant decision time. +4. **Risk-reducing failure behaviour.** Missing or inconsistent evidence must + block promotion or new exposure. +5. **Reconciled state.** Any future execution record must be reconciled against + venue-reported orders and fills. + +## TARGET — target architecture — not deployed + +The sole architecture diagram for this release is embedded below. Everything +inside it is **TARGET** and **not deployed**. ```mermaid -graph TB - subgraph Orchestration - CS[Cloud Scheduler] - PS[Pub/Sub event bus] - FS[Firestore state] +--- +title: Target architecture - not deployed +--- +flowchart TB + subgraph TARGET["TARGET — Target architecture (not deployed)"] + direction TB + + subgraph RESEARCH["Research and validation"] + direction TB + INPUTS["Governed research inputs"] + PIT["Point-in-time dataset construction"] + RULES["Rule-based candidate evaluation"] + VALIDATE["Validation and governance review"] + PROMOTE{"Explicit promotion decision"} + AUX["Auxiliary ML candidate
after hard-rule qualification"] + + INPUTS --> PIT --> RULES --> VALIDATE --> PROMOTE + RULES -.->|"baseline qualifies first"| AUX + AUX -.-> VALIDATE + end + + subgraph QUALIFY["Execution qualification"] + direction LR + PAPER["Paper-execution qualification"] + ADAPTER["Venue-adapter boundary"] + PAPER --> ADAPTER + end + + subgraph CONTROL["Runtime controls"] + direction LR + RISK["Risk and state controls"] + RECON["Order and fill reconciliation"] + AUDIT["Audit evidence"] + RISK --> RECON --> AUDIT + end + + PROMOTE -->|"qualifies"| PAPER + ADAPTER --> RISK end +``` - subgraph "Data plane" - ING[Multi-source ingestion
exchange data · venue WS · macro · on-chain regime] - PIT[PIT feature pipelines] - FS_STORE[Feature store] - end +At a high level, the intended flow would be: - subgraph "Compute plane" - ML[Rule-based signal engine] - RISK[Layered risk overlay] - ROUTER[Signal router] - end +1. governed research inputs; +2. point-in-time dataset construction; +3. rule-based candidate evaluation; +4. validation and governance review; +5. an explicit promotion decision; +6. paper-execution qualification; +7. venue-adapter, risk, state, and reconciliation boundaries; +8. audit evidence for subsequent review. - subgraph "Execution plane" - ADAPT[Venue adapters] - LIFE[Order lifecycle manager] - RECON[Broker-truth reconciliation] - end +An auxiliary-ML path would begin only after the hard-rule baseline satisfies +its research qualification requirements. It would remain a separate candidate +and would not inherit the baseline's status. - CS --> ING - ING --> PIT - PIT --> FS_STORE - FS_STORE --> ML - ML --> RISK - RISK --> ROUTER - ROUTER --> PS - PS --> LIFE - LIFE --> ADAPT - ADAPT -.-> RECON - RECON -.-> FS -``` +## TARGET — data and research plane -## Communication patterns +The intended data and research plane would separate source acquisition, +point-in-time dataset construction, quality checks, feature computation, +candidate evaluation, and reproducibility evidence. A failure in required +evidence would stop the affected path. -- **Synchronous (REST):** dashboard-to-backend reads, configuration updates, - health checks, and authenticated client portal. -- **Asynchronous (Pub/Sub):** signal propagation between pipeline stages, - execution-event distribution, alert fan-out. -- **Scheduled (Cloud Scheduler):** data ingestion cycles, feature computation - kickoff, hedge-monitor sweeps, periodic calibration cycles. +This target description does not identify providers, private datasets, +internal lineage records, parameters, or research outcomes. -## Resilience +## TARGET — validation and promotion plane -| Scenario | Response | -| --- | --- | -| Data source temporarily unavailable | Retry with backoff, fall back to last-known-good cache, validated-schema gate | -| Execution venue unresponsive | Retry against the same venue with bounded attempts; broker-truth reconciliation ensures no phantom PnL if the engine's close request raced with a broker-side event | -| Pub/Sub duplicate delivery | Consumer-side processed-message ledger with stable idempotency keys | -| Model artefact load failure | Fallback to most-recent validated artefact; block new-open signals if no valid artefact is available | -| Equity drawdown exceeds tier | Automated per-account sizing gate halts new opens at that account; closes remain permitted to preserve capital | -| Operator intervention required | Global manual-override flag in Firestore; trading pauses at consumer read without redeploy | +The intended validation plane would apply frozen evaluation rules, +anti-overfit controls, reproducibility checks, and explicit review before any +candidate could move to a later lifecycle stage. -## Security posture +Research qualification, paper-execution qualification, and any later +deployment decision would remain separate decisions. Passing one would not +imply the next. -- Credentials in Google Cloud Secret Manager, never in code or repositories. -- Service accounts with least-privilege IAM per service. -- Non-custodial execution: credentials scoped to trade-only operations in - both execution classes. -- Immutable timestamped audit trail on every execution decision. -- Structured logs emitted to Cloud Logging. +## TARGET — runtime and execution plane ---- +A future runtime plane would separate signal decisions, risk decisions, state +transitions, venue adaptation, and order-and-fill reconciliation. Risk-reducing +actions would remain possible when new exposure is blocked. -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* +The target is compatible with venue-appropriate, non-custodial operation where +applicable. It is not a claim of current account access, order placement, +custody, or capital management. + +## TARGET — operational evidence + +A future qualified runtime would need structured evidence for: + +- configuration and artefact identity; +- decision provenance; +- state transitions; +- order and fill reconciliation; +- failures, recovery tests, and operator decisions. + +The public reference intentionally omits private infrastructure coordinates, +control values, runbooks, identities, credentials, and incident records. + +## Public architecture boundary + +This page is a status-qualified design reference. It does not publish source +code, strategy logic, provider entitlements, private interfaces, or evidence +packs. See [`status.md`](status.md), [`research-methodology.md`](research-methodology.md), +and [`risk.md`](risk.md) for the governing public context. + +--- - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/components.md b/docs/components.md index def5216..44bf4cb 100644 --- a/docs/components.md +++ b/docs/components.md @@ -1,163 +1,14 @@ -# Components +# Components — Moved in v4 -> The public-facing services that make up the Disuza Quantitative platform. -> Internal module structure and implementation details are operational and -> not included. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Service map +This legacy path remains as a compatibility stub for one major release. -| Service | Tier | Trigger | Purpose | -| --- | --- | --- | --- | -| Data collector | Data plane | Cloud Scheduler (periodic) | Multi-source ingestion, PIT snapshot, schema validation, cache-manifest lineage | -| Signal detector | Compute plane | Pub/Sub event + Cloud Scheduler safety-net | Feature fetch, rule-based signal evaluation, risk-framework gating, signal publication | -| Hedge monitor | Compute + execution plane | Cloud Scheduler (periodic) | Layered risk overlay, trailing-stop discipline, timeout enforcement, reconciliation sweep | -| Order executor | Execution plane | Pub/Sub event | Venue adapters, order lifecycle, broker-truth reconciliation on exits | -| Calibration job | Compute plane | Cloud Scheduler (periodic) | Periodic parameter calibration for the rule-based engine and auxiliary ML components, artefact versioning, active-artefact pointer update | -| Dashboard API | Access layer | HTTPS authenticated | Client portal endpoints for position and analytics reads | -| Public site | Presentation | Static hosting | Guest portal, landing, authenticated client UI | +- **CURRENT:** the research foundation is summarized in + [`status.md`](status.md). +- **IN PROGRESS:** controlled system abstractions are described in + [`architecture.md`](architecture.md#in-progress--controlled-abstractions). +- **TARGET:** future components appear only in + [`architecture.md`](architecture.md#target--target-architecture--not-deployed). -Each service is independently deployable, independently scaled, and -independently instrumented. - -## Data collector - -**Purpose.** Periodic multi-source ingestion into the point-in-time -feature pipeline. - -**Triggers.** Cloud Scheduler fires on the ingestion cadence. On boot, a -first cycle runs immediately to seed the cache. - -**Responsibilities.** - -- Fetch from each configured source class (exchange market data, - venue-direct WebSocket capture, macro context, on-chain regime - gating signals). -- Write a point-in-time snapshot of the raw data. -- Validate against the critical-feature schema; fall back to last-known- - good if validation fails. -- Produce a content-addressed manifest hash and a lineage row in - BigQuery for long-term audit. -- Publish a cycle-complete event on Pub/Sub. - -## Signal detector - -**Purpose.** Feature-based position decisions from the rule-based signal engine. - -**Triggers.** Primary trigger is the cycle-complete event from the data -collector. A Cloud Scheduler safety-net fires every few hours as a -fallback in case the primary trigger is missed. - -**Responsibilities.** - -- Resolve the active artefact from the Firestore pointer. -- Load the per-asset feature vector for the current bar. -- Evaluate the rule-based signal engine. -- Apply risk-framework gates (position caps, drawdown gates, - trading-enabled flag). -- Publish a signal event to the order executor. - -## Hedge monitor - -**Purpose.** Layered risk overlay, in-flight position discipline, and -reconciliation sweep. - -**Triggers.** Cloud Scheduler periodic cadence. Also exposes a manual -reconcile endpoint for operator use. - -**Responsibilities.** - -- Run the layered risk overlay to modulate exposure when short-horizon - signals disagree with the primary stance. -- Monitor trailing stops and enforce timeout discipline. -- Before every exit decision, verify the broker still holds the matching - position (per-exit broker-truth pre-check). -- Run a full reconciliation sweep on boot and on demand: compare - Firestore state against broker fills, reconstruct orphaned position - exits from real fill history. - -## Order executor - -**Purpose.** Venue-specific order placement, monitoring, and close. - -**Triggers.** Pub/Sub events from the signal detector and hedge monitor. - -**Responsibilities.** - -- Route orders to the right venue adapter based on the target account. -- Place orders with stable idempotency keys and client order identifiers. -- Monitor fills and produce structured execution events. -- On close, resolve the real exit price and fees from broker fills, - reconstruct PnL, and update Firestore state. -- Emit alerts on execution failures or unexpected broker states. - -## Calibration job - -**Purpose.** Periodic parameter calibration with artefact versioning. - -**Triggers.** Cloud Scheduler periodic cron. - -**Responsibilities.** - -- Assemble the calibration window from the PIT feature store. -- Recalibrate the rule-based signal engine's parameter set and the layered - risk overlay (and any auxiliary ML components used in restricted roles - per López de Prado's framing). -- Write artefacts to Cloud Storage under a versioned path. -- Update the Firestore pointer that the signal detector reads, flipping - the active artefact with a single atomic write (no redeploy required). -- Emit a calibration-complete event with validation metrics. - -## Dashboard API - -**Purpose.** Authenticated client portal endpoints. - -**Triggers.** HTTPS requests from the public site after authentication. - -**Responsibilities.** - -- Position reads (open positions, current equity, drawdown state). -- Historical analytics reads (trade ledger, equity curves). -- Configuration reads and limited writes (authorised personnel only). -- System-health summary endpoints. - -## Public site - -**Purpose.** The public presence at [disuza.com](https://disuza.com). Hosts -the landing page, the guest portal (public demo), LLM context files, and -— after authentication — the operator dashboard. - -**Responsibilities.** - -- Render marketing and reference content. -- Provide the guest portal with clearly labelled hypothetical-backtest - simulation data. -- Emit the machine-readable context files at `/llms.txt` and - `/llms-full.txt`, regenerated from a single source of truth on every - production build. -- Proxy authenticated requests to the dashboard API. - -## Inter-service contracts - -- **Event envelope.** Every Pub/Sub event carries: an `idempotency_key` - (stable across retries), a `source` identifier, a `ts` timestamp, and - a typed `payload`. -- **Consumer idempotency.** Before acting on an event, consumers check - a processed-message ledger keyed on `idempotency_key`. -- **State updates.** Firestore writes use optimistic concurrency with - version counters; conflicts trigger a bounded retry with backoff. -- **Failure propagation.** Unrecoverable errors emit a structured alert - on Telegram; recoverable errors retry with exponential backoff up to - a bounded attempt count before alerting. - -## What is NOT published - -Module-level file layouts, internal APIs, secret-handling patterns, -deploy scripts, runbooks, incident histories, and service-to-service -authentication details are operational and are not part of the public -reference. - ---- - -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +No separate component capability is claimed on this page. diff --git a/docs/data-pipeline.md b/docs/data-pipeline.md index c3f5584..e791a24 100644 --- a/docs/data-pipeline.md +++ b/docs/data-pipeline.md @@ -1,112 +1,17 @@ -# Data Pipeline +# Data Pipeline — Moved in v4 -> The data pipeline is the foundation layer of Disuza's engine. Its design -> priority is **determinism** — training and live inference must see the -> same features, at the same time-alignment, produced by the same code. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Sources +This legacy path remains as a compatibility stub for one major release. -Disuza's data pipeline draws from four source classes: +- **CURRENT:** the public research policy is in + [`research-methodology.md`](research-methodology.md). +- **IN PROGRESS:** data-quality abstractions are summarized in + [`architecture.md`](architecture.md#in-progress--controlled-abstractions). +- **TARGET:** the future data and research plane is described in + [`architecture.md`](architecture.md#target--data-and-research-plane). -- **Exchange market data.** OHLCV, full Level-2 order book, trade prints, - funding rates, open interest, and liquidation streams from public - exchange APIs across major venues. -- **Venue-direct WebSocket capture.** Redundant real-time microstructure - capture (mark price, funding cycles, liquidation events, open-interest - snapshots) for forward-stream resilience independent of any single - data vendor. -- **Macro context.** Cross-asset rates, volatility indices, and broader - market reference points that contextualise digital-asset behaviour. -- **On-chain regime gating.** L1-L2 macro regime context only (not a - primary alpha source); used to gate strategy activation in identified - macro regimes rather than as a feed of trade signals. - -Specific providers are not named in public documentation. Disuza uses -institutional-tier data providers under standard commercial licences. - -## Point-in-time (PIT) guarantees - -A core design principle: **a feature value at time T must not depend on -information that was unavailable at T**. This is non-trivial because many -providers retroactively revise historical values as more information -arrives. The pipeline addresses this with: - -- **Point-in-time snapshots.** Each ingestion cycle writes a snapshot of - the raw data as it existed at that moment. Historical snapshots are - immutable. -- **Retroactive-revision guardrails.** Providers that revise historical - data are detected and reconciled: the live feature pipeline uses the - as-of-time snapshot, not the latest revised value. -- **Deterministic replay.** A backtest started today on the same raw - snapshots produces the same features as the equivalent live run did at - the historical time. - -## Ingestion lifecycle - -```mermaid -graph LR - CLOCK[Cloud Scheduler clock] --> COLLECT[Data collector service] - COLLECT --> FETCH[Source adapters] - FETCH --> SNAP[Point-in-time snapshot] - SNAP --> VALIDATE[Schema validator] - VALIDATE -->|pass| CACHE[Raw cache - GCS] - VALIDATE -->|fail| LKG[Last-known-good fallback] - CACHE --> MANIFEST[Manifest hash + lineage] - MANIFEST --> PIT[PIT feature pipeline] - PIT --> FEATURES[Feature store] -``` - -Full diagram in [`diagrams/data-flow.mmd`](diagrams/data-flow.mmd). - -## Schema validation and LKG fallback - -Every ingestion cycle gates on a schema validator: - -- **Critical-feature check.** A small set of features that the engine - cannot operate without must be present and within expected distribution - bounds. -- **Stat-drift check.** If the distribution of critical features shifts - materially versus a recent baseline, the cycle is flagged and the - pipeline falls back to the last-known-good (LKG) schema until the shift - is acknowledged by an operator. -- **Fail-safe default.** If no LKG is available or the fallback itself - fails, the inference pipeline blocks new-open signals rather than - running on degraded data. - -## Cache lineage and provenance - -Every raw cache write is accompanied by: - -- A content-addressed manifest hash over the materialised parquet bytes. -- A cycle identifier tying the cache to the Cloud Scheduler invocation. -- A persisted row in a BigQuery lineage table for long-term audit. - -This is the substrate of **broker-truth reconciliation** (see -[`execution.md`](execution.md)): given a trade, the pipeline can -reproduce the exact feature vector that produced its signal. - -## Feature engineering - -The pipeline produces features in four categorical groupings: - -- Exchange microstructure (OHLCV-derived, order-book-derived, trade-derived). -- Derivatives flow (funding rates, open-interest dynamics, liquidation cascades). -- Macro regime context (cross-asset, volatility regime, on-chain L1-L2 gating). -- Venue-health features (redundant capture cross-checks). - -The exact feature list, feature count, and feature-engineering -implementations are proprietary and not disclosed. - -## Versioning - -Feature definitions are versioned. When a feature definition changes, the -pipeline produces a new feature column under a versioned name rather than -silently overwriting. Backtests and live inference against older model -artefacts continue to resolve against the feature-definition version the -artefact was trained on. - ---- - -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +Forward-only market-data capture and monitoring are operational for research +data collection. No integrated data-to-trading execution pipeline is claimed; +the capture surface does not place orders, operate accounts, connect capital, +or constitute a trading runtime. diff --git a/docs/diagrams/data-flow.mmd b/docs/diagrams/data-flow.mmd deleted file mode 100644 index 6ff1b74..0000000 --- a/docs/diagrams/data-flow.mmd +++ /dev/null @@ -1,43 +0,0 @@ -%% Disuza Quantitative — Data Flow (PIT pipelines) -%% Version 3.1 · 2026-05-22 - -graph LR - subgraph "Source classes" - S1[Exchange market data
OHLCV · L2 · trades · funding · OI] - S2[Venue-direct WebSocket
forward-stream redundancy] - S3[Macro context] - S4[On-chain regime gating
L1-L2 context only] - end - - CLOCK[Cloud Scheduler
ingestion cadence] - COLLECT[Data collector
Cloud Run service] - SNAP[Point-in-time
snapshot] - VALID{Schema
validator} - LKG[Last-known-good
fallback] - CACHE[(Raw cache
Cloud Storage)] - MANIFEST[Manifest hash
+ BigQuery lineage] - PIT[PIT feature pipeline
retroactive-revision guardrails] - FSTORE[(Feature store)] - INFER[Rule-based signal evaluation] - - CLOCK --> COLLECT - S1 --> COLLECT - S2 --> COLLECT - S3 --> COLLECT - S4 --> COLLECT - COLLECT --> SNAP - SNAP --> VALID - VALID -->|pass| CACHE - VALID -->|fail| LKG - LKG --> CACHE - CACHE --> MANIFEST - MANIFEST --> PIT - PIT --> FSTORE - FSTORE --> INFER - - classDef source fill:#fef8e7,stroke:#aa8800,stroke-width:1px - classDef store fill:#e8f8e8,stroke:#338833,stroke-width:1px - classDef validator fill:#f8e8e8,stroke:#883333,stroke-width:1px - class S1,S2,S3,S4 source - class CACHE,FSTORE store - class VALID,LKG validator diff --git a/docs/diagrams/execution-reconciliation.mmd b/docs/diagrams/execution-reconciliation.mmd deleted file mode 100644 index 1b72006..0000000 --- a/docs/diagrams/execution-reconciliation.mmd +++ /dev/null @@ -1,52 +0,0 @@ -%% Disuza Quantitative — Execution and Broker-truth Reconciliation -%% Version 3.1 · 2026-05-22 -%% -%% The platform's bookkeeping is always a reconstruction of the broker's -%% ledger. PnL comes from actual broker fills, never from algorithmic -%% candle-based estimates. - -graph TB - SIG[Signal event
from compute plane] - ROUTE[Signal router
risk gates] - PRECHECK{Broker pre-check
does position
still exist?} - PLACE[Place order
with idempotency key] - FILLS[Broker fills stream] - CLOSE[Close condition
trail · timeout · reversal] - POSTCHECK{Broker pre-check
on close} - EXIT[Publish close] - EXEC[Execute close
on broker] - REAL[Real fill
price + fee] - PNL[Reconstruct PnL
from actual fills] - STATE[(Firestore state
+ BigQuery ledger)] - ORPH{Orphan?
FS says open
broker is flat} - SWEEP[Reconciliation sweep
on boot + on demand] - HIST[Pull broker fill history
reconstruct real exit] - ALERT[Critical alert
Telegram] - - SIG --> ROUTE - ROUTE --> PRECHECK - PRECHECK -->|broker has position| PLACE - PRECHECK -->|broker flat| ORPH - PLACE --> FILLS - FILLS --> CLOSE - CLOSE --> POSTCHECK - POSTCHECK -->|broker has position| EXIT - POSTCHECK -->|broker flat| ORPH - EXIT --> EXEC - EXEC --> REAL - REAL --> PNL - PNL --> STATE - - SWEEP --> ORPH - ORPH -->|reconstruct| HIST - HIST --> PNL - ORPH --> ALERT - - classDef gate fill:#fff3cd,stroke:#aa6600,stroke-width:1.5px - classDef recon fill:#e8f4f8,stroke:#336699,stroke-width:1.5px - classDef state fill:#e8f8e8,stroke:#338833,stroke-width:1px - classDef alert fill:#f8e8e8,stroke:#883333,stroke-width:1.5px - class PRECHECK,POSTCHECK,ORPH gate - class SWEEP,HIST,RECON,PNL recon - class STATE state - class ALERT alert diff --git a/docs/diagrams/high-level-architecture.mmd b/docs/diagrams/high-level-architecture.mmd deleted file mode 100644 index 4ef94ee..0000000 --- a/docs/diagrams/high-level-architecture.mmd +++ /dev/null @@ -1,66 +0,0 @@ -%% Disuza Quantitative — High-level Architecture -%% Version 3.1 · 2026-05-22 -%% Render natively on GitHub. Paste into https://mermaid.live for interactive view. - -graph TB - subgraph Orchestration - CS[Cloud Scheduler
the clock] - PS[Pub/Sub
event bus] - FS[Firestore
real-time state] - end - - subgraph "Data plane" - ING[Multi-source ingestion
exchange · venue WS · macro · on-chain regime] - PIT[Point-in-time feature pipelines] - FST[Feature store
cache + lineage] - end - - subgraph "Compute plane" - ML[Rule-based signal engine] - RISK[Layered risk overlay] - ROUTER[Signal router
with risk gates] - end - - subgraph "Execution plane" - ADAPT[Venue adapters] - LIFE[Order lifecycle manager] - RECON[Broker-truth reconciliation] - end - - subgraph "Venue classes" - INST[Prop-trading-programme APIs
broker-specific protocols, trade-only scope] - SELF[Self-custody perpetual venues
trade-scoped API wallets] - end - - subgraph Persistence - SQL[(BigQuery
analytics)] - GCS[(Cloud Storage
artefacts + snapshots)] - end - - CS --> ING - ING --> PIT - PIT --> FST - FST --> ML - ML --> RISK - RISK --> ROUTER - ROUTER --> PS - PS --> LIFE - LIFE --> ADAPT - ADAPT --> INST - ADAPT --> SELF - INST -.->|fills| RECON - SELF -.->|fills| RECON - RECON --> FS - LIFE --> FS - ML --> GCS - FST --> GCS - RECON --> SQL - - classDef plane fill:#e8f4f8,stroke:#333,stroke-width:1px - classDef orch fill:#fff3cd,stroke:#333,stroke-width:1px - classDef venue fill:#f0e8f8,stroke:#333,stroke-width:1px - classDef persist fill:#f3f3f3,stroke:#666,stroke-width:1px,color:#555 - class ML,RISK,ROUTER plane - class CS,PS,FS orch - class INST,SELF venue - class SQL,GCS persist diff --git a/docs/downstream-alignment-checklist.md b/docs/downstream-alignment-checklist.md new file mode 100644 index 0000000..5d8478b --- /dev/null +++ b/docs/downstream-alignment-checklist.md @@ -0,0 +1,70 @@ +# Downstream Alignment Checklist + +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +This checklist is a separate follow-up scope. The unreleased version 4.0.0 +candidate changes none of the surfaces below. + +The canonical input for every later alignment is +[`PUBLIC_FACTS.yml`](../PUBLIC_FACTS.yml). No downstream surface may be updated +by copying unsupported claims from an older public page. + +## TARGET — release boundary + +- [ ] Confirm the public repository v4.0.0 has been squash-merged and released. +- [ ] Record the actual merge date and final public wording as the alignment + baseline. +- [ ] Keep website, social, and machine-readable changes in separate reviewed + change sets. +- [ ] Remove live, production, performance, investment-service, legal-status, + and regulatory-readiness claims unless separately evidenced and approved. +- [ ] Preserve **CURRENT**, **IN PROGRESS**, and **TARGET** distinctions. + +## TARGET — website and guest surface + +- [ ] Align `disuza.com` identity, lifecycle, markets, horizon, methodology, + capabilities, non-claims, contact, version, and date. +- [ ] Keep target architecture visibly labelled **TARGET — not deployed**. +- [ ] Remove or disable `/guest` promotion until its content and data contract + pass the same factual, privacy, legal, and link review. +- [ ] Verify navigation, Open Graph metadata, structured data, and legal footer. + +## TARGET — machine-readable website files + +- [ ] Align `llms.txt` with the exact canonical positioning and explicit + non-claims. +- [ ] Align `llms-full.txt` with the same status vocabulary and remove + superseded v3 claims. +- [ ] Confirm neither file exposes internal identifiers, results, datasets, + thresholds, infrastructure coordinates, counterparties, or private + repository information. + +## TARGET — external identity surfaces + +- [ ] Align this repository's GitHub **About** description, homepage preview, + and topics; remove stale cloud, production, legal-status, and + regulatory-readiness markers before claiming cross-surface alignment. +- [ ] Open a separate reviewed PR in the organization-level public `.github` + repository to synchronize its `profile/README.md` from the approved + `.github/profile/README.md` mirror in this release. +- [ ] Verify the public organization Overview after that profile PR merges. +- [ ] Align the LinkedIn organization description, location wording, website + preview, and capability claims. +- [ ] Review Wikidata statements independently; correct only facts supported by + reliable public sources and platform policy. +- [ ] Align page titles, descriptions, Open Graph fields, social cards, + canonical URLs, robots metadata, and structured SEO data. + +## TARGET — acceptance + +- [ ] Biography, contact, and licence wording match `PUBLIC_FACTS.yml` and + current source material. +- [ ] Every surface is checked against `PUBLIC_FACTS.yml`. +- [ ] Links, previews, and machine-readable metadata are verified after + publication. +- [ ] No downstream alignment is represented as part of repository v4.0.0. + +--- + +*Disuza Quantitative — downstream follow-up scope · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/execution.md b/docs/execution.md index 317eb22..fa265b1 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -1,149 +1,15 @@ -# Execution +# Execution — Moved in v4 -> The execution layer translates signal-layer decisions into broker orders, -> manages their lifecycle, and reconciles the firm's bookkeeping against -> the broker's source of truth. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Design principle: broker is source of truth +This legacy path remains as a compatibility stub for one major release. -Disuza's execution architecture rests on one operating principle: +- **CURRENT:** no deployed execution capability is represented; see + [`status.md`](status.md#no-performance-or-access-claim). +- **IN PROGRESS:** execution boundaries are summarized in + [`architecture.md`](architecture.md#in-progress--controlled-abstractions). +- **TARGET:** the future runtime and execution plane is described in + [`architecture.md`](architecture.md#target--runtime-and-execution-plane). -> **The broker's state — its open positions, its actual fills, its realised -> PnL — is always the source of truth. The firm's bookkeeping is a -> reconstruction of that state, not an authoritative system of record.** - -This principle is non-obvious and learned the hard way. The common -alternative — trusting the engine's internal estimate of a position's exit -price based on candle data — fails silently when brokers execute at -prices the engine cannot observe (stop-loss cascades, fast markets, -partial fills). Firms that rely on internal estimates accumulate silent -drift between their bookkeeping and the broker's ledger; when the drift -is discovered (often during audit or a large adverse event), the damage -is larger than it would have been if the firm had been reading the -broker's ledger directly the whole time. - -Disuza pulls the broker's own fill history on every exit decision and -reconstructs PnL from actual fills. - -## Venue classes - -Disuza executes across two venue classes, selected to fit different -capital and counterparty profiles. - -### Prop-trading-programme APIs - -- **Protocol:** broker-specific, varies by counterparty. -- **Scope:** trade-only. Withdrawal permissions are controlled by the - broker-issued credential scope, not by the firm. -- **Profile:** institutional prop-trading programmes covering both - digital asset perpetual futures venues and US equity index futures - venues (NQ, ES). Counterparty risk is allocated to the broker's - regulatory umbrella. - -### Self-custody perpetual venues - -- **Protocol:** authenticated REST. -- **Scope:** trade-scoped API wallets under a signer-separation pattern. - Withdrawal requires the root signer, which is offline; the trading - agent wallet can only place and close orders. -- **Profile:** direct self-custody with on-chain settlement. - -Specific venue names are not published as part of the public reference. - -## Order lifecycle - -```mermaid -graph TB - SIG[Signal from compute plane] - ROUTE[Signal router - risk gates] - PRECHECK[Broker pre-check
does position still exist?] - PLACE[Place order] - MONITOR[Monitor fills] - CLOSE[Close condition - trail/timeout/reversal] - RECON[Broker-truth reconciliation] - LEDGER[Reconstructed PnL from actual fills] - STATE[Firestore state update] - - SIG --> ROUTE - ROUTE --> PRECHECK - PRECHECK -->|broker has position| PLACE - PRECHECK -->|broker flat, orphan| RECON - PLACE --> MONITOR - MONITOR --> CLOSE - CLOSE --> RECON - RECON --> LEDGER - LEDGER --> STATE -``` - -Full diagram in [`diagrams/execution-reconciliation.mmd`](diagrams/execution-reconciliation.mmd). - -## Non-custodial posture - -In both venue classes, Disuza's execution credentials are scoped to -trade-only operations: - -- For prop-trading-programme APIs, the broker issues credentials with - trade permissions only; the account-level deposit and withdrawal - rights remain with the account holder. -- For self-custody venues, Disuza operates agent wallets with signer - separation: the trading agent can sign trade messages only; fund - movement requires the root signer, which is not online with the - trading system. - -This is a structural guarantee of the non-custodial posture: even a -compromise of the trading infrastructure cannot move client funds off -the account or wallet. - -## Reconciliation modes - -Reconciliation operates at two complementary cadences: - -### Reactive (per-exit) - -Before the execution layer publishes a close decision, it verifies the -broker still holds the matching position. If the broker is flat — because -a native stop was hit, or the position was closed manually, or the -counterparty cancelled — the execution layer does **not** produce a -bookkeeping close at the algorithmic exit price. Instead, it defers to -the next recovery sweep, which reconstructs the real exit from the -broker's fill history. - -### Recovery sweep - -On service boot and on demand, a full broker-versus-state comparison -runs. Orphan positions in either direction are handled: - -- **Firestore says open, broker is flat.** The platform pulls the - broker's fill history, identifies the close fill that matches the - orphaned position by coin / direction / size / timestamp, reconstructs - the real PnL (closedPnl minus fees), and updates Firestore with the - real exit data. A critical-severity alert is emitted so operators can - review. -- **Firestore says flat, broker has position.** The platform emits a - critical alert. It does **not** auto-close an unexpected broker - position, because the correct remediation depends on context that - cannot be inferred automatically. Operator review is required. - -## Idempotency - -Every execution-adjacent Pub/Sub message carries: - -- A stable `idempotency_key` derived from the position identifier and the - event type. Consumer handlers check a processed-message ledger before - acting so that at-least-once delivery produces exactly-once effects. -- A `client_order_id` that ties broker messages to the firm's internal - order identifier, enabling later cross-referencing in broker fill - history. - -## Execution venues at a glance - -| Venue class | Protocol | Scope | Fund-movement risk | -| --- | --- | --- | --- | -| Prop-trading-programme APIs | Broker-specific, varies by counterparty | Trade-only credentials issued by the broker | Held with the broker's regulatory umbrella | -| Self-custody perpetual venues | Authenticated REST | Trade-scoped agent wallet; root signer offline | Held in self-custody; trading key cannot move funds | - ---- - -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +No order placement, account operation, or capital connectivity is claimed on +this page. diff --git a/docs/faq.md b/docs/faq.md index 6058d89..b0614fd 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,212 +1,124 @@ # Frequently Asked Questions -> Verbatim-lookup FAQ. Each question is phrased as a prospect or LLM user -> would ask it. Answers open with a complete declarative sentence that -> restates the subject — the first sentence is what LLMs typically quote. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** ## What is Disuza Quantitative? -Disuza Quantitative is a private quantitative trading research laboratory -based in Madrid, Spain, founded in 2025 by Yasmine Bendhiab (Co-Founder & -CEO) and Fares Bendhiab (Co-Founder & CTO). Disuza engineers systematic -execution algorithms for digital asset perpetual futures and US equity -index futures, and operates in a pre-licensing phase. - -## Who founded Disuza Quantitative? - -Disuza Quantitative was co-founded in 2025 by Yasmine Bendhiab and Fares -Bendhiab. Yasmine is Co-Founder & CEO, focused on strategic operations and -corporate compliance, based in Madrid, Spain. Fares is Co-Founder & CTO, -lead architect of the quantitative infrastructure, based in Bizerte, -Tunisia. - -## Where is Disuza Quantitative based? - -Disuza Quantitative is based in Madrid, Kingdom of Spain. The firm is -registered and operationally present in Madrid. - -## Is Disuza Quantitative a hedge fund? - -No. Disuza Quantitative is a private quantitative trading research -laboratory, not a collective investment scheme. Disuza does not solicit -or manage public retail or professional investor capital and does not -hold itself out as an asset manager. - -## Is Disuza Quantitative licensed or regulated? - -Disuza Quantitative operates in a pre-licensing phase and is monitoring -the MiCA (EU) and FINMA (Swiss) regulatory landscapes as part of its -pre-licensing preparation. Disuza does not currently hold a -regulated-investment-services licence in any jurisdiction and does not -offer regulated investment services. Statements about regulatory -alignment describe internal posture, not representations of regulatory -approval. - -## Can I invest with Disuza Quantitative? - -No. Disuza Quantitative does not accept retail investment, does not -solicit investor capital, and does not operate as a publicly available -asset manager. Access to Disuza's live platform is closed and by -invitation only. - -## Can I buy signals from Disuza Quantitative? - -No. Disuza Quantitative does not sell signals, does not publish a trading -feed, and does not provide trading advice to third parties. - -## Is Disuza Quantitative a high-frequency trading firm? - -No. Disuza Quantitative operates on intraday to multi-day horizons, not -at microsecond latency. The engine's architecture is pipeline-driven -(Cloud Scheduler + Pub/Sub + Firestore event-driven orchestration), not -co-location-dependent. - -## What markets does Disuza Quantitative trade? - -Disuza Quantitative trades digital asset perpetual futures (primarily -BTC and ETH) and US equity index futures (NQ and ES). The execution -plane supports prop-trading-programme venues and self-custody perpetual -venues. - -## What is Disuza Quantitative's architecture? - -Disuza Quantitative's architecture is a rule-based systematic engine with -a layered risk overlay, running on Google Cloud. Machine learning is -restricted to auxiliary roles (meta-labeling, dynamic position sizing, -regime detection) per López de Prado's framing — never as the primary -signal generator. The stack uses Cloud Scheduler as the orchestration -clock, Pub/Sub as the event bus, Firestore for real-time state, -BigQuery for analytics, and Cloud Run for every stateless request or -event handler. -Multi-source ingestion (exchange market data including L2 order book and -derivatives flow, redundant venue-direct WebSocket capture, macro -context, and on-chain regime gating signals used strictly as L1-L2 -context) feeds point-in-time feature pipelines with retroactive-revision -guardrails. Execution is non-custodial across -prop-trading-programme APIs (broker-specific protocols) and self-custody -perpetual venues (trade-scoped API wallets). Detail in -[`architecture.md`](architecture.md). - -## What technologies does Disuza Quantitative use? - -Disuza Quantitative uses Python 3.12+ for the trading platform, Next.js -with TypeScript for the web surface, and Google Cloud (Cloud Run, Cloud -Scheduler, Pub/Sub, Firestore, BigQuery, Cloud Storage) for -infrastructure. The signal engine is rule-based, not ML-driven; machine -learning is used only in restricted auxiliary roles (meta-labeling, -dynamic position sizing, regime detection) with standard scientific -Python tooling. Detail in [`technology.md`](technology.md). - -## What backtest methodology does Disuza Quantitative use? - -Disuza Quantitative's research methodology follows López de Prado's -anti-overfit discipline: Combinatorial Purged Cross-Validation (CPCV), -Deflated Sharpe Ratio (DSR) with cumulative trial counter, and -Probability of Backtest Overfitting (PBO). Frozen temporal splits -(dev / validation / holdout / forward) are fixed per asset class before -any hypothesis is tested. Every strategy under evaluation has a -pre-registered hypothesis document, and every cited result has a -committed reproducibility script. Detailed validation thresholds are -operational and not part of the public reference. See -[`regulatory.md`](regulatory.md). - -## How does Disuza Quantitative handle risk? - -Disuza Quantitative operates a venue-appropriate, tiered drawdown -posture with automated per-account sizing gates that halt new opens when -an account's tier-specific threshold is exceeded. Closes are always -permitted to preserve capital. A global manual-override switch provides -operator-controlled incident-response capability. The bookkeeping layer -reconstructs realised PnL from actual broker fills, not from algorithmic -estimates, through broker-truth reconciliation. Detail in -[`risk.md`](risk.md). - -## What data sources does Disuza Quantitative use? - -Disuza Quantitative draws from four source classes: exchange market -data (OHLCV, L2 order book, trades, funding, open interest, and -liquidations) for primary alpha, redundant venue-direct WebSocket -capture for forward-stream resilience, macro context for cross-asset -regime classification, and on-chain regime gating signals (used strictly -as L1-L2 macro context, not as a primary alpha source). Specific -provider names are not published as part of the public reference. Detail in -[`data-pipeline.md`](data-pipeline.md). - -## What execution venues does Disuza Quantitative use? - -Disuza Quantitative executes across two venue classes: prop-trading- -programme APIs (broker-specific protocols, trade-only credential scope) -and self-custody perpetual venues (trade-scoped agent wallets with -signer separation). Specific counterparty names and execution protocols -are not published. Detail in [`execution.md`](execution.md). - -## Is Disuza Quantitative custodial? - -No. Disuza Quantitative is non-custodial across both execution classes. -For prop-trading-programme accounts, the broker holds capital and -issues Disuza trade-only credentials. For self-custody venues, Disuza -uses agent wallets under signer separation so the online trading key -cannot move funds; withdrawal requires the offline root signer. - -## How does Disuza Quantitative reconcile its bookkeeping with the broker? - -Disuza Quantitative treats the broker's own position and fill history -as the source of truth. Before every exit decision, the execution -layer verifies the broker still holds the matching position. On boot -and on operator demand, a full reconciliation sweep compares Firestore -state against broker fills; orphaned positions are closed in Firestore -using PnL reconstructed from the broker's actual fill history rather -than algorithmic estimates. - -## What is Disuza Quantitative's performance? - -Disuza Quantitative publishes a hypothetical historical backtest summary -on its public guest portal at [disuza.com/guest](https://disuza.com/guest). -All performance figures there are labelled as simulated historical -results with the standard past-performance-does-not-guarantee-future- -results disclaimer and CFTC Rule 4.41 framing. Disuza does not publish -live account performance. - -## Is Disuza Quantitative hiring? - -Disuza Quantitative is not currently hiring non-founder staff. Inquiries -may be sent to [contact@disuza.com](mailto:contact@disuza.com) and will -be retained for future reference. - -## Can I contribute to this repository? - -No, this repository is a curated living technical reference, not an open -collaboration project. We do not accept external pull requests to the -documentation. Issues may be opened for documentation clarification -requests or factual corrections. - -## Can I use this documentation under the CC BY 4.0 licence? - -Yes, you may share and adapt the documentation content under the terms -of Creative Commons Attribution 4.0 International, with explicit -carve-outs for trademarks, source code, model weights, and operational -know-how. See [`LICENSE`](../LICENSE) for full terms, including the -no-endorsement clause that applies to adaptations. - -## How do I contact Disuza Quantitative? - -Send an email to [contact@disuza.com](mailto:contact@disuza.com) for all -inquiries — general, partnerships, hiring, press, or collaboration. -Disuza does not maintain separate inboxes per category. - -## Where can I learn more? - -- [disuza.com](https://disuza.com) — primary website -- [disuza.com/guest](https://disuza.com/guest) — public guest portal -- [disuza.com/llms.txt](https://disuza.com/llms.txt) — concise LLM context file -- [disuza.com/llms-full.txt](https://disuza.com/llms-full.txt) — extended LLM context file -- [Wikidata Q139491356](https://www.wikidata.org/wiki/Q139491356) — entity record -- [LinkedIn company page](https://www.linkedin.com/company/disuza-quantitative/) -- This repository — living technical reference +**CURRENT:** Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. ---- +## Where is the initiative led? + +The initiative is led across Madrid, Spain, and Bizerte, Tunisia. + +## What is the current stage? + +- **CURRENT:** research and engineering. +- **IN PROGRESS:** stronger integrity, access, trial-accounting, and audit + controls. +- **TARGET:** qualified paper and live deployment after the required evidence + and approvals exist. + +## Is there a live trading platform? + +No live trading platform is represented. Forward-only market-data capture and +monitoring are operational for research data collection, but they do not place +orders, operate accounts, connect capital, or constitute a trading runtime. +Runtime inference, execution, state, and reconciliation belong to the target +deployment path and must be qualified before they can be described as current. + +## Does Disuza Quantitative publish current performance? + +No. This repository makes no current strategy-performance claim and does not +publish live account performance. + +## Can I invest or buy signals? + +No. Disuza Quantitative does not accept investment through this repository, +offer a public investment service, or sell trading signals. + +## What markets are researched? + +**CURRENT:** The core research scope covers BTC and ETH perpetual markets and +NQ and ES index-futures markets. Optional CFD adaptations are evaluated +separately. + +Research scope is not a statement of current live trading. + +It is programme research scope only, not qualified engine coverage. The narrow +engine contract does not establish coverage of every listed market or the +programme design horizon. + +## What is the primary holding horizon? + +**CURRENT:** The primary design horizon is approximately 30 minutes to 4 hours. +This is not a high-frequency, co-location-dependent programme. + +## Is the signal engine based on machine learning? + +**CURRENT:** Primary signal generation is rule-based, not machine-learning +based. + +**TARGET:** Machine learning may be researched only in auxiliary roles, such as +meta-labeling, dynamic position sizing, or regime detection, after the related +hard-rule baseline qualifies out of sample. -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* -*Source of truth: [https://disuza.com/llms-full.txt](https://disuza.com/llms-full.txt)* +## What research methodology is used? + +**CURRENT:** The current synthetic engine route uses purged, embargoed, anchored +walk-forward evaluation and Deflated Sharpe Ratio (DSR). Combinatorial Purged +Cross-Validation (CPCV) and Probability of Backtest Overfitting (PBO) are +programme methods only where applicable; they are not claimed for the current +synthetic engine route. + +These methods reduce overfitting risk; they do not guarantee performance. +See [`research-methodology.md`](research-methodology.md). + +## What technology is current? + +**CURRENT:** private Python-based research tooling, forward-only market-data +capture and monitoring, data and quality-control work, cloud-supported batch +workflows, and statistical governance. + +Specific runtime execution services are not presented as current. The broader +system design is described as a target in [`architecture.md`](architecture.md). + +## What engine evidence is current? + +**CURRENT:** A bounded execution-engine contract is qualified on deterministic +synthetic fixtures only. It has not processed market data and does not qualify a +strategy, an economic result, paper execution, live execution, or deployment. + +## Is the system non-custodial? + +Non-custodial operation is a **TARGET** design requirement where applicable. +It is not presented here as a current client relationship or a currently +deployed execution guarantee. + +## Is the source code open source? + +No. The trading and research source code is proprietary and maintained in +private repositories. This public repository contains a sanitized technical +reference, not the platform source. + +## Is Disuza Quantitative a regulated investment service? + +No investment service is offered through this repository. Any future service +or deployment model would require separate legal, regulatory, counterparty, +and operational review. + +## Can I contribute? + +This is a curated public reference. Factual-correction and documentation +clarification issues are welcome. The private trading source is not open for +public contribution. + +## How can I make contact? + +Email **[contact@disuza.com](mailto:contact@disuza.com)** for general +inquiries. + +--- - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/media/og-image.png b/docs/media/og-image.png index 2f8e68d..210f538 100644 Binary files a/docs/media/og-image.png and b/docs/media/og-image.png differ diff --git a/docs/operations.md b/docs/operations.md index f3a327a..e4171de 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -1,118 +1,16 @@ -# Operations +# Operations — Moved in v4 -> Deployment, monitoring, and reliability posture at the abstraction level -> appropriate for public reference. Operational cadences, alert thresholds, -> and runbook contents are internal and not included. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Deployment +This legacy path remains as a compatibility stub for one major release. -Services deploy independently through Cloud Build. The public website is -hosted on Firebase Hosting with automatic deploys on tagged releases. -Backend services deploy to Cloud Run from Artifact Registry with -version-tagged images. +- **CURRENT:** the initiative remains pre-deployment; see + [`status.md`](status.md). +- **IN PROGRESS:** control evidence is summarized in + [`risk.md`](risk.md#in-progress--stronger-control-evidence). +- **TARGET:** future operational evidence is described in + [`architecture.md`](architecture.md#target--operational-evidence). -Rollbacks are near-instantaneous: Cloud Run retains previous revisions, -and the Firestore active-artefact pointer can be flipped back to the -prior model version with a single write. Firebase Hosting retains -historical releases with a one-command rollback. - -## Monitoring - -The observability posture combines: - -- **Structured logs** from every service to Cloud Logging, queryable via - the Log Explorer. -- **Custom metrics** for per-service health (request rates, error - rates, latency distributions) and platform health (positions by - state, equity, drawdown). -- **Heartbeat watchdogs** — each service emits a periodic heartbeat. - Missing heartbeats beyond a bounded window alert operators. -- **Telegram** as the primary operator alert channel; email as - fallback for cold incidents. - -## Alerting posture - -The alert taxonomy distinguishes operational severity from business -impact: - -- **Critical:** trading-continuity issues (broker connectivity, kill - switch trips, unexpected broker state). Always page. -- **Warning:** recoverable degradation (source unavailable with LKG - fallback active, schema drift flagged). Notify without paging. -- **Info:** routine state transitions (deploys, calibration cycles, - reconciliation results). Log only. - -Alert thresholds, pager routing, and runbook-association are -operational details and not published. - -## Reliability posture - -- **Fault tolerance.** Exponential-backoff retries on transient - failures. Last-known-good fallbacks on data-source outages. -- **At-least-once delivery.** Pub/Sub guarantees at-least-once; consumers - produce exactly-once effects via a processed-message ledger keyed on - stable idempotency identifiers. -- **State recovery.** Services are stateless from a request perspective; - persistent state lives in Firestore and BigQuery. A service can restart - at any time and resume operation. -- **Broker-truth reconciliation.** The platform's bookkeeping is always - a reconstruction of the broker's ledger, not an authoritative record. - Drift is detected and corrected on every exit decision and in boot - sweeps. - -## Deployment practices - -- **Staged rollout** for code changes: tests in CI, build, staging verification, - then production. -- **Feature-flagged changes** for behavioural changes: a config flag in - Firestore can gate a new behaviour without requiring a redeploy. -- **Immutable artefacts.** Container images are tagged by commit SHA and - never overwritten. -- **Zero-downtime deploys** for request-handling services; model-artefact - rollovers happen atomically via the active-artefact pointer. - -## Change management - -Model-behaviour changes follow a more cautious process than code -changes: - -1. Train the candidate artefact offline. -2. Validate on a held-out backtest window. -3. Shadow-run against live data for a bounded period (predictions - logged without being acted upon). -4. Compare shadow predictions against live signals. -5. Flip the active-artefact pointer on operator approval. -6. Monitor live performance against the shadow baseline for a settling - period. - -Specific validation thresholds, shadow-run durations, and approval -criteria are operational and not part of the public reference. - -## Incident response - -Incidents are categorised by trading-continuity impact: - -- **P0 — trading halted.** The global `trading_enabled` flag is toggled - off; investigation begins immediately; scheduled communication to - affected account holders. -- **P1 — degraded execution.** Affected account or venue is - quarantined; trading continues elsewhere; investigation begins - immediately. -- **P2 — observability or reporting issue.** Fixed in the next - business-hours cycle. - -Runbooks, response-time commitments, and communication templates are -internal and not part of the public reference. - -## What is NOT published - -Specific operational cadences (ingestion rate, reconciliation frequency, -watchdog timeouts), alert thresholds, runbook contents, on-call rotation -details, incident histories, and internal tooling are not part of the -public reference. - ---- - -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +Forward-only research data capture and monitoring are operational. No trading +runtime, order placement, account operation, or capital connectivity is claimed +on this page. diff --git a/docs/overview.md b/docs/overview.md index 70ca268..44d3547 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,107 +1,99 @@ # Overview -## Company - -Disuza Quantitative is a private quantitative trading research laboratory -headquartered in Madrid, Spain. Founded in 2025 by Yasmine Bendhiab (Co-Founder -& CEO) and Fares Bendhiab (Co-Founder & CTO), Disuza operates as a -closed-access research environment engineering systematic execution algorithms -for digital asset perpetual futures (BTC, ETH) and US equity index futures -(NQ, ES). - -The firm operates proprietary capital and invitation-only partner accounts. It -is not accepting retail clients, not soliciting retail or professional investor -capital, and not offering regulated investment services at this time. - -## Thesis - -Human emotion is the largest persistent inefficiency in financial markets. -Disciplined rule-based systematic strategies can extract durable edge from -market microstructure — when paired with institutional-grade risk management -and rigorous execution discipline. - -Disuza's design stance is that the operational edge compounds from three -sources: - -1. **Data quality.** Deterministic point-in-time feature pipelines with - retroactive-revision guardrails ensure that training and live inference - see the same world. -2. **Risk discipline.** A layered risk overlay modulates exposure in response - to short-horizon regime shifts, rather than betting on a single direction. -3. **Execution fidelity.** Non-custodial execution with broker-truth - reconciliation — the broker's state is always the source of truth, and - reconstructed PnL uses actual fills, not algorithmic estimates. -4. **Methodology rigor.** Anti-overfit validation pipeline per López de - Prado (Combinatorial Purged Cross-Validation, Deflated Sharpe Ratio, - Probability of Backtest Overfitting) with pre-registered hypotheses - and a cumulative trial counter that adjusts significance thresholds - across the project lifetime. - -## What Disuza is - -- A private **research laboratory** — the primary output is systematic trading - infrastructure, not a product sold to retail. -- A **closed-access** operator — access to the live platform is by invitation - only, and participation is limited to proprietary capital plus authorised - partner accounts. -- A **methodology-transparent** organisation — architecture and posture are - published in this living reference; source code, model weights, and - operational know-how remain proprietary. - -## What Disuza is NOT - -- **Not a high-frequency trading firm.** The firm operates on intraday to - multi-day horizons, not at microsecond latency. -- **Not a retail-facing product** or signal-selling service. Disuza does not - offer subscription signals, does not accept retail investment, and does not - operate as a trading academy. -- **Not a public hedge fund.** The firm is not licensed as a collective - investment scheme in any jurisdiction and does not hold or manage - third-party capital as an asset manager. -- **Not a licensed investment firm.** The firm is in a pre-licensing phase - and monitors the MiCA and FINMA regulatory landscapes. Statements in this - repository about regulatory alignment are expressions of internal posture, - not representations of regulatory approval. - -## Regulatory posture (summary) - -- **Jurisdiction:** Kingdom of Spain, entity registered in Madrid. -- **Phase:** pre-licensing. -- **Framework monitoring:** MiCA (EU) and FINMA (Swiss). -- **Simulated performance disclosure:** CFTC Rule 4.41 acknowledged. All - performance figures on the public guest portal are hypothetical historical - simulations. -- **Client relationship model:** non-custodial. Credentials across both - execution classes are scoped to trade-only operations. -- **Solicitation posture:** closed-access, invitation-only. Disuza does not - solicit retail or professional investor capital. - -Detail in [`regulatory.md`](regulatory.md). - -## Technology posture (summary) - -- **Engine:** rule-based systematic engine with a layered risk overlay; machine learning restricted to auxiliary roles (meta-labeling, dynamic position sizing, regime detection) per López de Prado framing — never as the primary signal generator. -- **Data:** multi-source pipeline combining exchange market data (OHLCV + - L2 order book + trades + funding + open interest + liquidations), - redundant venue-direct WebSocket capture for forward-stream resilience, - macro context, and on-chain regime gating signals used strictly as - L1-L2 macro context, through point-in-time feature pipelines with - retroactive-revision guardrails. -- **Execution:** prop-trading-programme APIs (broker-specific protocols, - trade-only scope) and self-custody perpetual venues (trade-scoped API - wallets). -- **Cloud:** Google Cloud, event-driven orchestration, non-custodial execution - with broker-truth reconciliation. - -Detail in [`architecture.md`](architecture.md) and [`technology.md`](technology.md). +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +## CURRENT — initiative + +Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. It is +founder-led across Madrid, Spain, and Bizerte, Tunisia. + +Its present work is research and engineering: developing rule-based systematic +methods, testing their assumptions, strengthening research controls, and +building the foundations required for later qualification. + +Forward-only market-data capture and monitoring are operational for research +data collection. They do not place orders, operate accounts, connect capital, +or constitute a trading runtime. + +## CURRENT — programme research scope + +The core market scope is: + +- BTC and ETH perpetual markets; +- NQ and ES index-futures markets; +- optional CFD research as a separate adaptation lane. + +The primary design horizon is approximately 30 minutes to 4 hours. + +This scope describes what is researched. It does not state that these markets +are currently traded live. + +It is programme research scope only, not qualified engine coverage. A bounded +execution-engine contract is qualified on deterministic synthetic fixtures only; +it has not processed market data, and its narrow contract does not establish +coverage of the programme research universe or design horizon. + +## CURRENT — design position + +The programme is: + +- **rule-based first** — primary signals must come from explicit economic and + market rules; +- **methodology-led** — hypotheses, trial accounting, temporal separation, + reproducibility, and anti-overfit checks govern evaluation; +- **audit-oriented** — verified facts, judgment, and unknowns are kept + separate; +- **private by design** — source code, strategies, datasets, and operational + details are not published. + +Machine learning is limited to auxiliary research roles and only after a +hard-rule baseline qualifies out of sample. + +## IN PROGRESS — governance and integrity + +The research programme is strengthening controls around access, trial +accounting, reproducibility, and independent audit evidence. + +This is the current priority. The public reference therefore makes no current +strategy-performance claim and no trading-system deployment claim. + +## TARGET — future system + +The longer-term target is a qualified systematic trading system with: + +- controlled paper and live execution paths; +- venue-appropriate risk controls; +- reconciled order and fill accounting; +- non-custodial design where applicable; +- explicit human approval at promotion boundaries. + +These are target properties, not descriptions of a currently live platform. + +## What Disuza Quantitative is not + +Disuza Quantitative is not: + +- a public hedge fund; +- a retail signal service; +- a provider of investment services through this repository; +- an invitation to invest; +- a claim of live or future performance; +- a high-frequency co-location operation. + +## Leadership footprint + +The initiative is led across Madrid and Bizerte. Public documentation uses a +neutral organisational voice and does not expose private working arrangements. ## Contact -All inquiries — general, partnerships, careers: **[contact@disuza.com](mailto:contact@disuza.com)**. +General inquiries: **[contact@disuza.com](mailto:contact@disuza.com)** ---- +See [`status.md`](status.md) for the current public status and +[`research-methodology.md`](research-methodology.md) for the research policy. -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* -*Source of truth: [https://disuza.com/llms-full.txt](https://disuza.com/llms-full.txt)* +--- - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/regulatory.md b/docs/regulatory.md index 349bdf3..9228eac 100644 --- a/docs/regulatory.md +++ b/docs/regulatory.md @@ -1,147 +1,88 @@ -# Regulatory Posture - -> Disuza operates in a pre-licensing phase. The statements below describe -> internal posture and monitoring; they do not constitute representations of -> regulatory approval or licensed status. - -## Jurisdiction - -Disuza Quantitative is a private entity registered in Madrid, Kingdom of -Spain. Operational activity is conducted from that jurisdiction. Documentation -is released under Creative Commons Attribution 4.0 International (see -[`LICENSE`](../LICENSE)), with explicit carve-outs for trademarks, source code, -and operational know-how. - -## Phase - -The firm operates in a **pre-licensing** phase. It does not hold a -regulated-investment-services licence in any jurisdiction, does not market -investment services to retail clients, and does not solicit retail or -professional investor capital. - -## Framework monitoring - -Disuza tracks two regulatory landscapes as part of its pre-licensing -preparation: - -- **MiCA** — EU Markets in Crypto-Assets Regulation. Relevant provisions - include the authorisation regime for Crypto-Asset Service Providers - (CASPs), the conduct-of-business requirements for client-facing - services, and the prudential requirements for entities that hold - client assets or execute client orders. -- **FINMA** — Swiss Financial Market Supervisory Authority. Relevant - guidance includes the CASP-adjacent categorisations under FinIA and - FinSA, and the cross-border provisioning rules for services offered - into Switzerland. - -These statements reflect internal posture — understanding of the -landscape and preparation for eventual licensing. They do **not** -constitute representations of compliance, authorisation, or approval -by any supervisory authority. - -## Counterparty relationships - -Disuza's execution counterparties — prop-trading programmes and -self-custody perpetual venues — operate under their own regulatory -umbrellas in their own jurisdictions. Disuza's trading activity through -those counterparties is conducted as the counterparty's authorised trader, -under the counterparty's terms, and does not transfer regulatory -responsibility to Disuza. - -## Performance claims and simulated results - -Any backtest results referenced on the public guest portal at -[disuza.com/guest](https://disuza.com/guest) are **hypothetical historical -simulations** and do not represent actual trading outcomes. Disuza -acknowledges **CFTC Rule 4.41** regarding simulated performance: - -> "HYPOTHETICAL OR SIMULATED PERFORMANCE RESULTS HAVE CERTAIN INHERENT -> LIMITATIONS. UNLIKE AN ACTUAL PERFORMANCE RECORD, SIMULATED RESULTS DO -> NOT REPRESENT ACTUAL TRADING. ALSO, SINCE THE TRADES HAVE NOT ACTUALLY -> BEEN EXECUTED, THE RESULTS MAY HAVE UNDER- OR OVER-COMPENSATED FOR THE -> IMPACT, IF ANY, OF CERTAIN MARKET FACTORS, SUCH AS LACK OF LIQUIDITY. -> SIMULATED TRADING PROGRAMS IN GENERAL ARE ALSO SUBJECT TO THE FACT THAT -> THEY ARE DESIGNED WITH THE BENEFIT OF HINDSIGHT. NO REPRESENTATION IS -> BEING MADE THAT ANY ACCOUNT WILL OR IS LIKELY TO ACHIEVE PROFITS OR -> LOSSES SIMILAR TO THOSE SHOWN." - -Public performance figures are framed with a **past performance does not -guarantee future results** disclaimer surfaced at the point of -presentation, not only in a separate modal. - -## Backtest methodology (high-level) - -At a level appropriate for public reference: - -- Out-of-sample validation on held-out windows that the model has not - seen during training. -- Point-in-time feature snapshots so the backtest sees the same data the - live engine would have seen at the same historical moment. -- Conservative standard-error estimation for monthly return and - risk-adjusted-return metrics. -- Deterministic replay: the same raw snapshots reproduce the same - backtest output end-to-end. - -Detailed backtest parameters, validation windows, and metric definitions -are operational and not part of the public reference. - -## Anti-overfit validation pipeline - -Disuza's research methodology follows the discipline outlined in Marcos -López de Prado's work on multiple-testing and out-of-sample robustness: - -- **Combinatorial Purged Cross-Validation (CPCV)** — preserves the - temporal structure of financial data while extracting many distinct - out-of-sample paths from a single dataset, controlling for the leakage - between adjacent train and test folds. -- **Deflated Sharpe Ratio (DSR)** — adjusts the in-sample Sharpe estimate - for the number of trials conducted on the dataset; the cumulative trial - counter is preserved across the project lifetime. -- **Probability of Backtest Overfitting (PBO)** — quantifies the - probability that the strategy ranked best in-sample will underperform - out-of-sample. -- **Frozen temporal splits per asset class** — dev / validation / holdout - / forward windows are fixed before any hypothesis is tested; the - holdout and forward sets are never touched until validation gates pass. -- **Pre-registered hypotheses** — every strategy under evaluation has a - registered hypothesis document committed before experimentation begins. -- **Reproducibility script per validated result** — every cited backtest - number has a corresponding `reproduce_NNN.py` committed alongside. - -Detailed validation thresholds (DSR minimums, PBO ceilings, CPCV -parameters) are operational and not part of the public reference. - -## Custody model - -Disuza's relationship with any counterparty is structurally -non-custodial: - -- For prop-trading-programme accounts, the prop firm holds the - capital and issues Disuza trade-only credentials. -- For self-custody venues, Disuza uses agent wallets under signer - separation: the online trading key cannot move funds; withdrawal - requires an offline root signer. - -Disuza does not at any time hold, pool, or otherwise have discretionary -access to client funds beyond trade-placement authority. - -## Non-solicitation posture - -Disuza does not solicit retail investor capital, does not market -investment services to the public in any jurisdiction, and does not -operate as a Collective Investment Scheme under any regulatory framework. -Access to Disuza's live platform is closed and by invitation only. +# Regulatory and Public-Claim Posture + +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +This page is informational. It is not legal advice, an offer, a solicitation, +or a representation of regulatory approval. + +## CURRENT — research initiative + +Disuza Quantitative is a private, pre-deployment research initiative led +across Madrid, Spain, and Bizerte, Tunisia. + +It does not currently offer an investment service through this repository, +accept investor capital through this repository, or provide public trading +signals. + +## CURRENT — non-solicitation + +Nothing in this repository is: + +- an offer or invitation to invest; +- a recommendation to buy or sell an instrument; +- a promise of access to a trading platform; +- a performance forecast; +- a representation of licensed or approved status. + +Anyone evaluating a future relationship must obtain independent legal, +regulatory, tax, and financial advice in the relevant jurisdiction. + +## CURRENT — performance claims + +Version 4 makes no current strategy-performance claim. + +Research methods, architecture, or historical experimentation must not be +interpreted as evidence of current or future returns. No representation is +made that any account will achieve a profit or avoid a loss. + +Any future public performance material would require: + +- a defined and verified evidence source; +- clear separation of simulated and live results; +- methodology and limitation disclosures; +- review under the rules applicable to the audience and jurisdiction; +- an explicit publication decision. + +## CURRENT — research methodology disclosure + +The public methodology description is limited to governance principles: +rule-based primary research, temporal separation, pre-registration, cumulative +trial accounting, purged and embargoed anchored walk-forward evaluation, DSR, +sanity checks, and reproducibility. CPCV and PBO remain programme methods only +where applicable and are not claimed for the current synthetic engine route. + +This disclosure does not publish a strategy, a result, or a regulatory +assurance. + +## IN PROGRESS — control strengthening + +Research integrity, access, trial-accounting, and audit controls are being +strengthened. + +The public consequence is conservative: no current result is described as a +deployment qualification while this work remains in progress. + +## TARGET — future relationships + +Potential future direct, programme-based, paper, or live activity would require +separate qualification and legal review. A target execution or custody design +does not create a current client relationship or service. + +## Privacy and counterparties + +This public reference does not identify private accounts, counterparties, +credential structures, operational jurisdictions, or legal arrangements. +Those facts are disclosed only when necessary, authorised, and appropriate +for the recipient. ## Document status -This documentation is informational only. Statements about regulatory -alignment describe internal posture and monitoring activity; they do not -constitute representations of regulatory compliance, authorisation, or -approval. Before engaging with Disuza Quantitative in any capacity, -consult local counsel. +This posture was last verified on 2026-09-01 for the unreleased v4.0.0 public +documentation candidate. Laws, regulatory interpretations, and business +circumstances can change; this page must be reviewed before any materially +different public claim is made. --- -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/research-methodology.md b/docs/research-methodology.md new file mode 100644 index 0000000..06c369a --- /dev/null +++ b/docs/research-methodology.md @@ -0,0 +1,107 @@ +# Research Methodology + +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +This page describes the public research policy at a high level. It does not +publish strategy logic, datasets, thresholds, trial counts, or results. + +## CURRENT — rule-based primary research + +Primary signal generation is rule-based. A research hypothesis must define a +mechanism, inputs, decision rules, failure conditions, and evaluation path +before it can be treated as a candidate for testing. + +Machine learning is not used as a primary signal generator. + +## CURRENT — conditional auxiliary machine learning + +Machine learning may be considered only for auxiliary roles such as: + +- meta-labeling; +- dynamic position sizing; +- regime detection. + +An auxiliary ML component is eligible for research only after the corresponding +hard-rule baseline has qualified out of sample. It must then be evaluated as a +separate, trial-accounted hypothesis against that baseline. + +This policy prevents a flexible model from replacing an unproven economic +mechanism. + +## CURRENT — bounded synthetic engine evidence + +A bounded execution-engine contract is qualified on deterministic synthetic +fixtures only. It has not processed market data and does not qualify a strategy, +an economic result, paper execution, live execution, or deployment. + +The contract is deliberately narrower than the programme research scope. It +does not establish coverage of the programme research universe or design +horizon. + +## CURRENT — route-specific anti-overfit design + +The research design uses: + +- temporal separation across development, validation, holdout, and forward + partitions; +- hypothesis pre-registration before governed out-of-sample evaluation; +- purged, embargoed, anchored walk-forward evaluation and Deflated Sharpe Ratio + (DSR) on the current synthetic engine route; +- Combinatorial Purged Cross-Validation (CPCV) and Probability of Backtest + Overfitting (PBO) as programme methods only where applicable; +- cumulative trial accounting; +- sanity checks and reproducibility controls, including deterministic artefacts + and checks before a result can be interpreted. + +CPCV and PBO are not claimed for the current synthetic engine route. Their use +depends on an evaluation geometry for which they are applicable. + +These methods reduce avoidable overfitting risk. They do not guarantee that a +strategy has economic value or will perform in the future. + +## CURRENT — separation of claims + +Research records distinguish: + +- verified facts; +- research judgment; +- unknowns; +- target capabilities. + +A failed or inconclusive research result is not rewritten as success. A target +architecture is not evidence of current operation. + +## IN PROGRESS — stronger research controls + +Controls around research access, trial accounting, failure handling, and +independent audit evidence are being strengthened. + +The public implication is intentionally narrow: no current strategy result is +presented here as a deployment qualification or a current performance claim. + +## TARGET — qualification before deployment + +A future deployment candidate would need to pass, in order: + +1. frozen research and evaluation rules; +2. statistical and reproducibility checks; +3. synthetic execution and accounting checks; +4. paper-trading review; +5. an explicit human decision to proceed. + +Passing one stage would not imply that later stages are complete. + +## What remains private + +The following remain private: + +- strategy identities, parameters, and feature definitions; +- temporal split dates and dataset identifiers; +- trial budgets, counters, and statistical thresholds; +- research outcomes and performance measurements; +- audit evidence, internal reviews, and qualification packs. + +--- + +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/risk.md b/docs/risk.md index 17ce571..b1ae497 100644 --- a/docs/risk.md +++ b/docs/risk.md @@ -1,114 +1,83 @@ -# Risk Framework +# Risk and Research Governance -> Disuza's risk framework operates at multiple tiers and is tightly coupled -> to the execution layer, not a separate after-the-fact check. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Principles +This page separates current research controls from target deployment controls. +It does not publish account thresholds, strategy parameters, or operating +runbooks. -1. **Capital preservation is the first objective.** Return-seeking is - subordinate to downside control. -2. **Venue-appropriate posture.** Drawdown and sizing parameters are - calibrated per account class, because prop-trading-programme APIs - and self-custody venues carry different risk profiles and counterparty - assumptions. -3. **Closes are always permitted.** Risk gates may block new opens; - they never block a close. Whatever the state, the platform must be - able to reduce exposure. -4. **Non-custodial by construction.** Risk to client funds is structurally - bounded by trade-only credential scoping, not by policy discipline. +## CURRENT — research-risk principles -## Tiers of risk control +The current programme follows these principles: -### Pre-trade +1. **Evidence before promotion.** A research candidate does not advance + because it is plausible or attractive. +2. **Fail closed.** Missing or inconsistent evidence blocks a claim rather + than being filled with an optimistic assumption. +3. **Temporal separation.** Governed out-of-sample evaluation is separated + from development. +4. **Cumulative trial accounting.** Repeated testing changes the evidentiary + bar and must be counted. +5. **Reproducibility.** A result must be tied to deterministic inputs, + code, and checks before it can be interpreted. +6. **No current performance claim.** Research infrastructure is not evidence + of a qualified strategy. -Before any order leaves the execution layer: +## CURRENT — capital posture -- **Position gating.** Only one directional position per asset per account - at any time; size and exposure ceilings are enforced against current - account equity. -- **Drawdown gate.** An account whose current drawdown exceeds its - tier-specific flat threshold has its new-open sizing set to zero. Closes - are unaffected. -- **Trading-enabled check.** A global manual-override flag in Firestore - can pause new opens firm-wide without requiring a redeploy. This is an - operator-controlled incident-response lever, not an automated circuit. +This public reference represents no current account operation, +investor-capital acceptance, trade placement, or live risk-control surface. -### In-trade +Capital preservation is a design priority for future qualification, not a +claim that live capital controls are currently deployed. -While a position is open: +## IN PROGRESS — stronger control evidence -- **Trailing-stop discipline.** Positions carry a trail that ratchets on - favourable moves and triggers exit when broken. -- **Timeout discipline.** Every position has a maximum hold time; an - unreached stop-or-target at timeout produces an exit at market. -- **Broker-truth reconciliation.** Before every exit publication, the - execution layer verifies the broker still holds the position; orphaned - positions are reconciled from broker fills rather than closed at an - algorithmic estimate. +The programme is strengthening: -### Post-trade +- access and authorization evidence; +- trial-accounting integrity; +- failure and recovery tests; +- independent audit evidence; +- consistency between policy, implementation, and verification. -After exit: +No internal incident detail, control threshold, or qualification evidence is +published here. -- **Real-PnL reconstruction.** Realised PnL is taken from actual broker - fills minus actual fees, never from algorithmic estimates. -- **Equity-state update.** Per-account running equity is updated with the - reconstructed PnL. Drawdown re-computes against the peak-to-trough - definition appropriate for the account tier. -- **Audit trail.** Every execution decision — open, monitor, close, - reconciliation — produces a timestamped immutable log entry. +## TARGET — deployment risk controls -## Account tiering +A future qualified deployment path is intended to include: -Accounts are grouped into tiers based on counterparty class and capital -profile: +- pre-trade exposure and account checks; +- venue-appropriate drawdown controls; +- controls that allow risk reduction even when new exposure is blocked; +- position timeout and exit discipline; +- order and fill reconciliation; +- operator intervention controls; +- structured audit evidence; +- non-custodial credential design where applicable. -- **Prop-programme tier.** Prop-trading-programme accounts operating - under the prop firm's own drawdown rules. Tier parameters are - conservative to preserve the programme. -- **Self-custody tier.** Self-custody perpetual accounts with proprietary - capital. Tier parameters align with the firm's internal - capital-preservation mandate. +Each item is a **TARGET** capability until independently qualified. This list +is not a statement that a production risk system exists today. -Exact tier parameters are not published and are calibrated against -historical backtest characteristics. +## Promotion boundaries -## Kill switches +A future candidate would move through separate research, synthetic execution, +paper, and live decisions. Evidence from one boundary would not automatically +qualify the next. -Two mechanisms that share a name but serve different purposes: +## What remains private -### Automated per-account flat gate +The following are not published: -When an account's current drawdown exceeds its tier-specific flat -threshold, its new-open sizing multiplier is set to zero. The pre-trade -gate then skips new opens for that account. Closes continue to be -permitted so the account can recover exposure. - -### Global manual-override - -An operator can toggle the global `trading_enabled` flag off in Firestore -to halt new opens firm-wide. This is an incident-response mechanism, not -an automated circuit. Like the per-account gate, it blocks new opens only; -closes remain permitted. - -## Audit and observability - -- Every execution decision emits a structured log line with the full - context required to reconstruct the decision. -- Heartbeat watchdogs detect stalled services; a missing heartbeat after - a bounded window alerts operators. -- Structured logs ship to Cloud Logging; alerts route through Telegram - to the operator channel. - -## What is NOT published - -Specific drawdown thresholds, sizing multipliers, trailing-stop -percentages, timeout durations, account tier memberships, and operator -playbooks are operational controls and are not part of the public -reference. +- drawdown, sizing, stop, timeout, or alert thresholds; +- account tiers and venue mappings; +- kill-switch logic and test packs; +- credentials, principals, and custody boundaries; +- incident history and recovery procedures; +- research verdicts, metrics, and trial counts. --- -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/skills.md b/docs/skills.md index 37f2f64..1a212e0 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -1,94 +1,54 @@ -# Skills Applied +# Capabilities -> Technical competencies applied in building and operating the Disuza -> Quantitative platform. This is not a recruiting surface — Disuza is not -> hiring — but the skills inventory is useful for evaluating the firm's -> technical depth. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Systematic strategy design +Capability labels describe the initiative's public research status. They are +not credentials, performance claims, or evidence of trading-system deployment. -- Rule-based systematic engine design and serving -- Feature engineering across time-series and cross-sectional signals -- Walk-forward validation and out-of-sample evaluation discipline -- Drift detection, monitoring, and artefact versioning -- Rolling calibration pipelines with active-artefact pointer updates -- Auxiliary ML in restricted roles only (meta-labeling, dynamic position sizing, regime detection) per López de Prado's framing — never as the primary signal generator +## CURRENT — demonstrated in the research programme -## Financial engineering +- Python-based quantitative research tooling; +- rule-based strategy specification and evaluation; +- temporal data separation and point-in-time quality work; +- purged, embargoed, anchored walk-forward evaluation and Deflated Sharpe Ratio + (DSR) on the current synthetic engine route; +- Combinatorial Purged Cross-Validation (CPCV) and Probability of Backtest + Overfitting (PBO) as programme methods only where applicable; +- hypothesis pre-registration, cumulative trial accounting, and + reproducibility controls; +- cloud-supported batch research workflows; +- forward-only market-data capture and monitoring for research data collection; +- a bounded execution-engine contract qualified on deterministic synthetic + fixtures only; +- audit-oriented documentation and research governance. -- Systematic trading system design -- Position sizing, risk gating, drawdown-driven kill switches -- Broker-truth reconciliation and fill-history-based PnL reconstruction -- Non-custodial execution patterns (trade-only credential scoping, - signer separation) -- Regulatory-landscape literacy: MiCA, FINMA, CFTC Rule 4.41 -- Anti-overfit validation pipeline (CPCV + DSR + PBO per López de Prado) -- Pre-registered hypothesis discipline with reproducibility scripts -- Frozen temporal-split methodology (dev / validation / holdout / forward) +These capabilities support private R&D only. -## Cloud infrastructure +The data-capture surface does not place orders, operate accounts, connect +capital, or constitute a trading runtime. The engine evidence has not processed +market data and does not qualify a strategy, an economic result, paper +execution, live execution, or deployment. -- Google Cloud Platform native operator -- Cloud Run, Cloud Run Jobs, Cloud Build, Cloud Scheduler -- Pub/Sub event-driven orchestration at production scale -- Firestore real-time state with optimistic concurrency -- BigQuery for analytics, Cloud Storage for artefacts -- Artifact Registry for versioned container images -- Secret Manager for credential management -- Identity and Access Management with least-privilege service accounts +## IN PROGRESS — under development -## Backend engineering +- stronger access-integrity and audit-evidence controls; +- data, risk, state, and execution abstractions; +- order-and-fill accounting and failure-handling controls; +- evidence packages for later paper-execution qualification. -- Python 3.12+ production-grade services -- FastAPI for authenticated REST endpoints -- Pydantic for data validation -- asyncio for concurrent I/O -- Structured logging, heartbeat watchdogs, custom metrics -- Immutable timestamped audit trails +Work listed here is not claimed as complete or deployment-ready. -## Frontend engineering +## TARGET — not deployed -- Next.js 16 App Router with static export -- React 19 with hooks and modern component patterns -- TypeScript 5 across the frontend surface -- Tailwind CSS for styling -- Framer Motion for interactions -- Firebase Hosting for static-export deployment +- an integrated, auditable systematic research and execution stack; +- qualified paper-execution and venue-adapter paths; +- reconciled runtime state and risk-reducing failure behaviour; +- explicit human promotion decisions between lifecycle stages. -## Data engineering - -- Point-in-time feature pipelines -- Retroactive-revision guardrails -- Schema validation with last-known-good fallback -- Content-addressed manifest hashes for provenance -- BigQuery lineage tables for long-term audit - -## DevOps - -- Containerised services (Docker) -- CI/CD through Cloud Build -- Branch-protected main; staging verification; production deploy -- Zero-downtime deploys with revision retention for instant rollback -- Feature-flagged behaviour changes through Firestore - -## Protocols and venues - -- Prop-trading-programme API integration (broker-specific protocols, trade-only scope) -- REST API client engineering for self-custody perpetual venues -- Order lifecycle management with stable idempotency keys -- Consumer-side exactly-once effects over at-least-once delivery - -## Documentation and observability - -- Single-source-of-truth for public content regenerated at build time -- Structured commit history with conventional-commit prefixes -- Living technical reference (this repository) maintained alongside - production changes -- IP-safety pre-commit verification to prevent leakage of proprietary - terms into public surfaces +The target list is directional. It is not a promise of availability or future +performance. --- -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/status.md b/docs/status.md new file mode 100644 index 0000000..ed6b8fa --- /dev/null +++ b/docs/status.md @@ -0,0 +1,98 @@ +# Public Research Status + +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** + +This page applies the release-level vocabulary and non-claims recorded in +[`PUBLIC_FACTS.yml`](../PUBLIC_FACTS.yml). + +**CURRENT:** Disuza Quantitative is a private, pre-deployment quantitative R&D initiative +building and validating rule-based systematic trading infrastructure. + +## Snapshot + +| Area | Status | Public statement | +| --- | --- | --- | +| Programme stage | **CURRENT** | Pre-deployment research and engineering | +| Programme research scope | **CURRENT** | BTC/ETH perpetuals, NQ/ES futures, optional CFD research | +| Programme design horizon | **CURRENT** | Approximately 30 minutes to 4 hours | +| Primary signal policy | **CURRENT** | Rule-based | +| Machine learning | **CURRENT** | Auxiliary only after hard-rule out-of-sample qualification | +| Research data capture | **CURRENT** | Forward-only market-data capture and monitoring are operational; no order placement or account operation | +| Engine evidence | **CURRENT** | Bounded contract on deterministic synthetic fixtures only; no market data or performance qualification | +| Research controls | **IN PROGRESS** | Integrity and audit controls are being strengthened | +| Live trading platform | **TARGET** | Not currently claimed as deployed or qualified | +| Current performance | **CURRENT** | No current performance claim | +| Investment service | **CURRENT** | None offered | + +## CURRENT — research foundation + +The initiative is founder-led between Madrid, Spain, and Bizerte, Tunisia. + +The current programme includes: + +- rule-based strategy research; +- private research and engineering tooling; +- data acquisition and quality-control work; +- forward-only market-data capture and monitoring for research data collection; +- cloud-supported batch research workflows; +- statistical validation and reproducibility controls; +- audit-oriented research governance. + +These capabilities support research. They do not establish a production +trading platform. + +The operational data-capture surface is separate from the trading-system +lifecycle. It does not place orders, operate accounts, connect capital, or +constitute a trading runtime. + +A bounded execution-engine contract is qualified on deterministic synthetic +fixtures only. It has not processed market data and does not qualify a strategy, +an economic result, paper execution, live execution, or deployment. + +## IN PROGRESS — control strengthening + +The programme is strengthening the controls that govern research access, +trial accounting, reproducibility, and audit evidence. + +During this work, public documentation does not present a strategy as +qualified for deployment and does not make a current performance claim. +Completion requires evidence, not a documentation update. + +## TARGET — qualified deployment path + +Longer-term targets include: + +- paper-trading qualification; +- venue-specific execution qualification; +- runtime risk and state controls; +- reconciled order and fill accounting; +- carefully governed direct or programme-based deployment. + +These are target capabilities. They are not statements of current operation, +availability, or future results. + +## Programme scope boundaries + +The core research universe is: + +- BTC and ETH perpetual markets; +- NQ and ES index-futures markets; +- optional CFD adaptations evaluated separately. + +The primary design horizon is approximately 30 minutes to 4 hours. Research +scope may change through documented internal decisions, but public status is +updated only after those decisions are verified and safe to disclose. + +This is programme research scope only, not qualified engine coverage or current +trading activity. The narrow engine contract does not establish coverage of the +programme research universe or design horizon. + +## No performance or access claim + +This public reference makes no claim of current strategy performance, public +platform access, investor-capital acceptance, or an investment service. + +--- + +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/team.md b/docs/team.md index 4e7febe..2e569bb 100644 --- a/docs/team.md +++ b/docs/team.md @@ -1,84 +1,35 @@ # Team -Disuza Quantitative is a two-founder firm. Both co-founders hold operational -and strategic responsibility; the firm does not currently employ non-founder -staff. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Yasmine Bendhiab — Co-Founder & CEO +Disuza Quantitative is a two-founder private R&D initiative led between +Madrid, Spain, and Bizerte, Tunisia. These biographies are intentionally +limited to public responsibilities and location. -Yasmine leads Disuza's strategic operations, regulatory alignment, and -corporate governance. She is based in **Madrid, Spain**. +## CURRENT — Yasmine Bendhiab, Co-Founder -**Focus:** Strategic Operations · Corporate Compliance · Regulatory Alignment +- **Location:** Madrid, Spain. +- **Responsibilities:** business, legal, and administrative coordination. This + is a non-technical role. -**Background.** Data engineer with multi-year distributed data engineering -experience across AWS, PySpark, and ML infrastructure. Currently Data -Engineer at Ryanair (Madrid). Previously Data Engineer at Zonexos (Canada) -and Machine Learning Researcher at Caire (Germany). +## CURRENT — Fares Bendhiab, Co-Founder -**Education.** +- **Location:** Bizerte, Tunisia. +- **Responsibilities:** research architecture, quantitative engineering, and + technical governance. -- Diplôme d'Ingénieur en Informatique — École Nationale des Sciences de - l'Informatique (ENSI), 2022. -- Mathematics & Computer Science — Institut Préparatoire aux Études - d'Ingénieur de Bizerte (IPEIB), 2019. -- Machine Learning Specialization — Stanford Online, 2023. +## Biography boundary -**Expertise.** - -- Distributed data engineering -- Machine learning pipelines -- Corporate compliance and governance -- Regulatory-landscape monitoring (MiCA, FINMA) -- Strategic operations and FinTech context - -**Links.** - -- LinkedIn: [linkedin.com/in/yasmine-bendhiab-22379319a](https://www.linkedin.com/in/yasmine-bendhiab-22379319a/) - ---- - -## Fares Bendhiab — Co-Founder & CTO - -Fares is the lead architect of Disuza's quantitative infrastructure. He -is based in **Bizerte, Tunisia**. - -**Focus:** Systems Architecture · Quantitative Trading Infrastructure · -Computational Biology - -**Background.** Systems architect focused on autonomous trading -infrastructure and computational biology. Architects Disuza's end-to-end -quantitative engine from data ingestion through execution on distributed -cloud architecture. Research interests span market-adaptive execution, -systematic trading pipelines, and pharmacogenomics. - -**Expertise.** - -- Distributed systems architecture -- Quantitative trading infrastructure -- Machine learning pipelines and event-driven orchestration -- Prop-trading-programme API execution and venue integration -- Cloud-native Python engineering on Google Cloud - -**Links.** - -- LinkedIn: [linkedin.com/in/fares-bendhiab-40866828a](https://linkedin.com/in/fares-bendhiab-40866828a) -- GitHub: [github.com/FaresDisusa](https://github.com/FaresDisusa) - ---- +Employer history, education, certifications, regulatory expertise, and claims +of deployed-platform experience are omitted from this release. Any change to +the names, responsibilities, locations, or public contact in this page must be +checked against `PUBLIC_FACTS.yml` and current source material. ## Contact -For inquiries directed at either founder, please use -**[contact@disuza.com](mailto:contact@disuza.com)**. Inbound messages are -triaged to the appropriate founder. - -Disuza does not currently maintain a separate press, investor-relations, -or careers inbox. All inquiries — general, partnerships, hiring — flow -through the single contact address. +General inquiries: [contact@disuza.com](mailto:contact@disuza.com). --- -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +*Disuza Quantitative — Public Technical Reference · Version 4.0.0 candidate · +Unreleased · Last verified 2026-09-01* diff --git a/docs/technology.md b/docs/technology.md index 3777baa..91e4a48 100644 --- a/docs/technology.md +++ b/docs/technology.md @@ -1,133 +1,14 @@ -# Technology +# Technology — Moved in v4 -> The technology stack at the abstraction level appropriate for public -> reference. Library-level details, container images, and service configuration -> are operational and not included. +> **Version 4.0.0 candidate · Unreleased · Last verified 2026-09-01** -## Language and runtime +This legacy path remains as a compatibility stub for one major release. -- **Primary language:** Python 3.12+. Data processing, feature engineering, - ML inference, execution logic, and service glue. -- **Frontend:** TypeScript 5 with Next.js 16 App Router, React 19, Tailwind - CSS. -- **Infrastructure-as-code surface:** standard shell tooling plus Google - Cloud native CLIs. +- **CURRENT:** publicly supportable research tooling is summarized in + [`status.md`](status.md#current--research-foundation). +- **IN PROGRESS:** technology-neutral abstractions are described in + [`architecture.md`](architecture.md#in-progress--controlled-abstractions). +- **TARGET:** the intended system design is explicitly not deployed; see + [`architecture.md`](architecture.md#target--target-architecture--not-deployed). -## Engine and calibration - -- **Engine:** rule-based systematic engine with a layered risk overlay. - Machine learning is restricted to auxiliary roles (meta-labeling, dynamic - position sizing, regime detection) per López de Prado's framing — never - as the primary signal generator. -- **Tooling:** standard scientific Python tooling for the rule-based engine - and risk overlay; ML libraries used only within the restricted auxiliary - roles. -- **Serving:** containerised on Cloud Run, warm-cached per instance. -- **Calibration:** Google Cloud; artefacts persisted to Cloud Storage; - active artefact selection via a Firestore pointer that can be rolled - forward without a redeploy. - -Specific engine parameters, feature counts, and calibration cadences are -proprietary and not published. - -## Orchestration and state - -Disuza's orchestration is **event-driven**, not DAG-driven: - -- **Cloud Scheduler** — the clock. Kicks off ingestion, safety-net - inference runs, hedge-monitor sweeps, and calibration cycles on cron - schedules. -- **Pub/Sub** — the event bus. Pipelines communicate by publishing and - consuming topics. Consumers implement idempotency via a processed-message - ledger and stable idempotency keys. -- **Firestore** — real-time state. Open positions, account equity, - kill-switch flags, and configuration pointers live here. Clients read - near-real-time; writes are transactional where consistency matters. -- **BigQuery** — historical analytics. Trade ledger, equity curves, - per-trade attribution, metrics history. -- **Cloud Storage** — model artefacts, feature snapshots, raw data cache. -- **Artifact Registry** — versioned Docker images for every service. - -## Compute - -- **Cloud Run services** for every stateless request or event handler: - data collection, inference, hedging and monitoring, execution, - dashboard API. -- **Cloud Run jobs** for bounded batch workloads such as periodic - calibration. -- Auto-scaling with warm-cache-friendly concurrency settings. - -## Observability - -- **Structured logging** from every service to Cloud Logging. -- **Custom metrics** surfaced via Cloud Monitoring. -- **Heartbeat watchdogs** per service — a missing heartbeat after a - bounded window alerts operators. -- **Telegram** is the operator alert channel for high-severity events - (kill-switch trips, orphan detection, deploy outcomes). Email is the - fallback. - -| Concern | Tool | -| --- | --- | -| Log aggregation | Cloud Logging | -| Metrics and dashboards | Cloud Monitoring | -| Error reporting | Cloud Error Reporting | -| Trace (limited) | Cloud Trace | -| Operator alerts | Telegram primary, email fallback | -| Incident memory | Internal runbooks (not public) | - -## Security - -- Credentials in **Google Cloud Secret Manager**. No credentials in code, - container images, or repositories. -- Service accounts with **least-privilege IAM** per service. -- **Trade-only credential scoping** on every execution path — no - service account holds withdrawal or fund-movement permissions. -- **Immutable timestamped audit trail** for every execution decision. -- TLS 1.3 on every request path. - -## CI/CD - -- **Cloud Build** for container builds and deployments. -- **Artifact Registry** for versioned image storage. -- **Firebase Hosting** for the public website with automatic deploys on - tagged releases. -- Static type checks and linting on every commit; production-build - verification on every merge. - -## Data providers (class-level) - -- Exchange market data (OHLCV, L2 order book, trades, funding, open - interest, liquidations) from public exchange APIs. -- Redundant venue-direct WebSocket capture for forward-stream resilience. -- Macro context from standard financial data sources. -- On-chain regime gating signals from institutional-tier data providers - (used strictly as L1-L2 macro context, not as primary alpha). - -Specific vendor names are not published as part of the public reference. - -## Frontend - -- **Next.js 16** App Router with static export for the public site. -- **React 19** functional components with hooks. -- **Tailwind CSS** for styling. -- **Framer Motion** for interactions. -- **Firebase Hosting** for deployment; CDN-edged globally. - -## Development practices - -- Type hints across the Python surface; strict TypeScript on the - frontend. -- Structured commit history with conventional-commit-style prefixes - (`feat`, `fix`, `chore`, `docs`, `refactor`). -- Single-source-of-truth for published facts via a `facts.ts` export on - the website side, regenerating `llms.txt` and `llms-full.txt` on every - production build to prevent drift. -- IP-safety pre-commit grep to prevent leakage of proprietary terms into - public surfaces. - ---- - -*Disuza Quantitative — Living Technical Reference · Version 3.1 · Last Updated: 2026-05-22* - - +No additional technology capability is claimed on this page. diff --git a/scripts/check_public_surface.py b/scripts/check_public_surface.py new file mode 100644 index 0000000..ed405d7 --- /dev/null +++ b/scripts/check_public_surface.py @@ -0,0 +1,984 @@ +#!/usr/bin/env python3 +"""Fail closed on public-documentation drift and unsafe disclosures. + +The checker intentionally uses only the Python standard library so contributors +can run it before installing any documentation tooling. Full CFF, Markdown, +external-link, Mermaid, and secret validation run as separate CI steps. +""" + +from __future__ import annotations + +import datetime as dt +import html +import re +import sys +import unicodedata +from dataclasses import dataclass +from pathlib import Path +from urllib.parse import unquote +from zoneinfo import ZoneInfo + + +ROOT = Path(__file__).resolve().parents[1] +EXPECTED_VERSION = "4.0.0" +DOCUMENT_TIMEZONE = ZoneInfo("Africa/Tunis") +FACTS_PATH = ROOT / "PUBLIC_FACTS.yml" +CHANGELOG_PATH = ROOT / "CHANGELOG.md" +TEXT_SUFFIXES = { + ".cff", + ".json", + ".jsonc", + ".md", + ".mmd", + ".py", + ".sh", + ".toml", + ".txt", + ".yaml", + ".yml", +} +STATUS_LABELS = {"CURRENT", "IN PROGRESS", "TARGET"} + + +@dataclass(frozen=True, order=True) +class Issue: + path: str + line: int + code: str + message: str + + +issues: list[Issue] = [] + + +def relative(path: Path) -> str: + return path.relative_to(ROOT).as_posix() + + +def add_issue(path: Path, line: int, code: str, message: str) -> None: + issues.append(Issue(relative(path), line, code, message)) + + +def line_number(text: str, offset: int) -> int: + return text.count("\n", 0, offset) + 1 + + +def public_text_files() -> list[Path]: + result: list[Path] = [] + for path in ROOT.rglob("*"): + if not path.is_file(): + continue + if path.name != "LICENSE" and path.suffix.lower() not in TEXT_SUFFIXES: + continue + if any(part in {".git", "node_modules"} for part in path.parts): + continue + result.append(path) + return sorted(result) + + +def strip_yaml_scalar(value: str) -> str: + value = value.strip() + if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}: + value = value[1:-1] + return value + + +def normalized_whitespace(value: str) -> str: + return " ".join(value.split()).casefold() + + +def normalized_claim(value: str) -> str: + return re.sub(r"[^a-z0-9]+", " ", value.casefold()).strip() + + +def simple_yaml_scalars(path: Path) -> dict[str, str]: + """Read scalar mappings from the conservative YAML subset used here.""" + + scalars: dict[str, str] = {} + stack: list[tuple[int, str]] = [] + key_pattern = re.compile( + r"""^(\s*)(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+)):(?:\s*(.*))?$""" + ) + + for raw_line in path.read_text(encoding="utf-8").splitlines(): + if not raw_line.strip() or raw_line.lstrip().startswith(("#", "- ")): + continue + match = key_pattern.match(raw_line) + if not match: + continue + + indent = len(match.group(1)) + key = match.group(2) or match.group(3) or match.group(4) + value = (match.group(5) or "").strip() + while stack and stack[-1][0] >= indent: + stack.pop() + dotted = ".".join([item[1] for item in stack] + [key]) + + if value: + scalars[dotted] = strip_yaml_scalar(value) + else: + stack.append((indent, key)) + + return scalars + + +def simple_yaml_lists(path: Path) -> dict[str, list[str]]: + """Read list items from the conservative YAML subset used here.""" + + lists: dict[str, list[str]] = {} + stack: list[tuple[int, str]] = [] + key_pattern = re.compile( + r"""^(\s*)(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+)):(?:\s*(.*))?$""" + ) + item_pattern = re.compile(r"^(\s*)-\s+(.+?)\s*$") + + for raw_line in path.read_text(encoding="utf-8").splitlines(): + if not raw_line.strip() or raw_line.lstrip().startswith("#"): + continue + + key_match = key_pattern.match(raw_line) + if key_match: + indent = len(key_match.group(1)) + key = key_match.group(2) or key_match.group(3) or key_match.group(4) + value = (key_match.group(5) or "").strip() + while stack and stack[-1][0] >= indent: + stack.pop() + if not value: + stack.append((indent, key)) + continue + + item_match = item_pattern.match(raw_line) + if not item_match or not stack: + continue + indent = len(item_match.group(1)) + while stack and stack[-1][0] >= indent: + stack.pop() + if not stack: + continue + dotted = ".".join(item[1] for item in stack) + lists.setdefault(dotted, []).append(strip_yaml_scalar(item_match.group(2))) + + return lists + + +def require_file(path: Path) -> bool: + if path.is_file(): + return True + add_issue(path, 1, "missing-file", "required public-release file is missing") + return False + + +def check_facts() -> tuple[str, str, dict[str, str], dict[str, list[str]]]: + if not require_file(FACTS_PATH): + return EXPECTED_VERSION, "", {}, {} + + facts = simple_yaml_scalars(FACTS_PATH) + fact_lists = simple_yaml_lists(FACTS_PATH) + required = { + "document.version", + "document.release_status", + "document.last_verified", + "document.canonical_repository", + "initiative.name", + "initiative.positioning", + "initiative.lifecycle", + "status_vocabulary.CURRENT", + "status_vocabulary.IN PROGRESS", + "status_vocabulary.TARGET", + "research_scope.boundary", + "research_data_capture.status", + "research_data_capture.scope", + "research_data_capture.boundary", + "qualified_engine.status", + "qualified_engine.evidence", + "qualified_engine.boundary", + "qualified_engine.scope_boundary", + "licensing.current_material", + "contact.email", + } + for key in sorted(required - facts.keys()): + add_issue(FACTS_PATH, 1, "facts-field", f"missing scalar field: {key}") + + required_lists = { + "public_status.CURRENT", + "public_status.IN PROGRESS", + "public_status.TARGET", + "capabilities.CURRENT", + "capabilities.IN PROGRESS", + "capabilities.TARGET", + "target_architecture.components", + "research_scope.core_markets", + "research_scope.optional_research", + "methodology.public_methods", + "repository_scope.included", + "repository_scope.excluded", + "explicit_non_claims", + } + for key in sorted(required_lists): + if not fact_lists.get(key): + add_issue(FACTS_PATH, 1, "facts-list", f"missing or empty list: {key}") + + if facts.get("target_architecture.status") != "TARGET": + add_issue( + FACTS_PATH, + 1, + "facts-architecture", + "target_architecture.status must be TARGET", + ) + if facts.get("target_architecture.deployment") != "not deployed": + add_issue( + FACTS_PATH, + 1, + "facts-architecture", + "target_architecture.deployment must be not deployed", + ) + + version = facts.get("document.version", "") + release_status = facts.get("document.release_status", "") + last_verified = facts.get("document.last_verified", "") + + if version != EXPECTED_VERSION: + add_issue( + FACTS_PATH, + 1, + "facts-version", + f"document.version must be {EXPECTED_VERSION}", + ) + + if release_status != "unreleased": + add_issue( + FACTS_PATH, + 1, + "facts-release-status", + "document.release_status must remain unreleased until publication", + ) + + try: + parsed_date = dt.date.fromisoformat(last_verified) + except ValueError: + add_issue( + FACTS_PATH, + 1, + "facts-date", + "document.last_verified must be an ISO date", + ) + else: + # The document date follows the maintainer's Tunis civil day. GitHub + # runners use UTC and can therefore still be on the preceding date. + document_today = dt.datetime.now(DOCUMENT_TIMEZONE).date() + if parsed_date > document_today: + add_issue( + FACTS_PATH, + 1, + "facts-date", + "document.last_verified cannot be in the future in Africa/Tunis", + ) + + actual_statuses = { + key.removeprefix("status_vocabulary.") + for key in facts + if key.startswith("status_vocabulary.") + } + if actual_statuses != STATUS_LABELS: + add_issue( + FACTS_PATH, + 1, + "facts-statuses", + "status_vocabulary must contain only CURRENT, IN PROGRESS, and TARGET", + ) + + return version, last_verified, facts, fact_lists + + +def check_candidate_markers(version: str, last_verified: str) -> None: + marker_paths = [ + ROOT / "README.md", + ROOT / "CONTRIBUTING.md", + ROOT / ".github" / "profile" / "README.md", + *sorted((ROOT / "docs").glob("*.md")), + ] + for path in marker_paths: + if not require_file(path): + continue + text = path.read_text(encoding="utf-8") + if version and version not in text: + add_issue(path, 1, "candidate-version", "v4 candidate marker is missing") + if last_verified and last_verified not in text: + add_issue(path, 1, "verification-date", "last-verified marker is missing") + + old_markers = ( + ("legacy-version", re.compile(r"(?i)\bv?3\.1(?:\.0)?\b")), + ("legacy-date", re.compile(r"\b2026-05-" r"22\b")), + ) + for path in public_text_files(): + if path == CHANGELOG_PATH: + continue + text = path.read_text(encoding="utf-8") + for code, pattern in old_markers: + for match in pattern.finditer(text): + add_issue( + path, + line_number(text, match.start()), + code, + "legacy release marker is allowed only in CHANGELOG.md", + ) + + +def check_fact_consistency( + version: str, + facts: dict[str, str], + fact_lists: dict[str, list[str]], +) -> None: + name = facts.get("initiative.name", "") + positioning = facts.get("initiative.positioning", "") + lifecycle = facts.get("initiative.lifecycle", "") + email = facts.get("contact.email", "") + canonical_repository = facts.get("document.canonical_repository", "") + + for path in ( + ROOT / "README.md", + ROOT / ".github" / "profile" / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "faq.md", + ): + if not path.is_file(): + continue + text = path.read_text(encoding="utf-8") + for value, label in ((name, "initiative name"), (lifecycle, "lifecycle")): + if value and value.casefold() not in text.casefold(): + add_issue(path, 1, "facts-consistency", f"missing {label} from PUBLIC_FACTS.yml") + if positioning and normalized_whitespace(positioning) not in normalized_whitespace(text): + add_issue( + path, + 1, + "facts-consistency", + "canonical positioning must match PUBLIC_FACTS.yml verbatim", + ) + + for path in (ROOT / "README.md", ROOT / ".github" / "profile" / "README.md"): + if path.is_file() and email: + text = path.read_text(encoding="utf-8") + if email.casefold() not in text.casefold(): + add_issue(path, 1, "facts-consistency", "missing public contact email") + + cff_path = ROOT / "CITATION.cff" + if not require_file(cff_path): + return + cff = simple_yaml_scalars(cff_path) + required_cff = { + "cff-version", + "message", + "title", + "url", + "license", + "version", + } + for key in sorted(required_cff - cff.keys()): + add_issue(cff_path, 1, "cff-field", f"missing top-level CFF field: {key}") + + expected_cff = { + "cff-version": "1.2.0", + "version": version, + "license": facts.get("licensing.current_material", ""), + "url": canonical_repository, + } + for key, expected in expected_cff.items(): + if expected and cff.get(key) != expected: + add_issue(cff_path, 1, "cff-consistency", f"{key} must match PUBLIC_FACTS.yml") + + if facts.get("document.release_status") == "unreleased" and "date-released" in cff: + add_issue( + cff_path, + 1, + "cff-unreleased", + "date-released must be absent while the candidate is unreleased", + ) + + cff_text = cff_path.read_text(encoding="utf-8") + if name and name.casefold() not in cff_text.casefold(): + add_issue(cff_path, 1, "cff-consistency", "initiative name is missing") + if positioning and normalized_whitespace(positioning) not in normalized_whitespace(cff_text): + add_issue( + cff_path, + 1, + "cff-consistency", + "canonical positioning must match PUBLIC_FACTS.yml verbatim", + ) + if not re.search(r"(?m)^\s*-\s+name:\s*\S", cff_text): + add_issue(cff_path, 1, "cff-authors", "at least one named author is required") + + projections = { + "capabilities.CURRENT": [ROOT / "docs" / "skills.md"], + "capabilities.IN PROGRESS": [ROOT / "docs" / "skills.md"], + "capabilities.TARGET": [ROOT / "docs" / "skills.md"], + "target_architecture.components": [ROOT / "docs" / "architecture.md"], + "research_scope.core_markets": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "faq.md", + ], + "research_scope.optional_research": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "faq.md", + ], + "methodology.public_methods": [ + ROOT / "README.md", + ROOT / "docs" / "research-methodology.md", + ], + "explicit_non_claims": [ROOT / "README.md"], + } + for key, paths in projections.items(): + corpus = normalized_claim( + "\n".join( + path.read_text(encoding="utf-8") for path in paths if path.is_file() + ) + ) + for item in fact_lists.get(key, []): + if normalized_claim(item) not in corpus: + add_issue( + FACTS_PATH, + 1, + "facts-projection", + f"{key} item is not projected into its canonical public page: {item}", + ) + + scalar_projections = { + "research_scope.boundary": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "overview.md", + ], + "research_data_capture.scope": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "architecture.md", + ROOT / "docs" / "faq.md", + ], + "research_data_capture.boundary": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "architecture.md", + ROOT / "docs" / "faq.md", + ], + "qualified_engine.evidence": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "research-methodology.md", + ROOT / "docs" / "faq.md", + ], + "qualified_engine.boundary": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "research-methodology.md", + ROOT / "docs" / "faq.md", + ], + "qualified_engine.scope_boundary": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "research-methodology.md", + ROOT / "docs" / "overview.md", + ], + "research_scope.primary_horizon": [ + ROOT / "README.md", + ROOT / "docs" / "status.md", + ROOT / "docs" / "faq.md", + ], + "methodology.primary_signal_policy": [ + ROOT / "README.md", + ROOT / "docs" / "research-methodology.md", + ROOT / "docs" / "faq.md", + ], + } + for key, paths in scalar_projections.items(): + expected = facts.get(key, "") + corpus = normalized_claim( + "\n".join( + path.read_text(encoding="utf-8") for path in paths if path.is_file() + ) + ) + if expected and normalized_claim(expected) not in corpus: + add_issue( + FACTS_PATH, + 1, + "facts-projection", + f"{key} is not projected into its canonical public page", + ) + + +FORBIDDEN_RULES = ( + ( + "internal-id", + re.compile(r"(?i)\b(?:D|S|H)(?:[_-]?\d{2,})\b"), + "internal research or decision identifier", + ), + ( + "internal-gate", + re.compile(r"(?i)\bgate\s*\d+\b"), + "internal gate identifier", + ), + ( + "private-key", + re.compile(r"-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----"), + "private-key material", + ), + ( + "credential-value", + re.compile( + r"""(?ix) + \b(?:api[_ -]?key|access[_ -]?token|password|private[_ -]?key|secret) + \b\s*[:=]\s*["']?[A-Za-z0-9_./+=-]{8,} + """ + ), + "credential-like assignment", + ), + ( + "cloud-role", + re.compile( + r"(?i)\b(?:roles/[a-z][\w.]+|service" + r"Account:\S+|\bI" + r"AM\b)" + ), + "private authorization detail", + ), + ( + "service-account", + re.compile(r"(?i)\bservice" r"\s+accounts?\b"), + "private runtime identity detail", + ), + ( + "storage-locator", + re.compile(r"(?i)\b(?:gs|s3)://\S+"), + "private storage locator", + ), + ( + "cloud-region", + re.compile( + r"(?i)\b(?:asia|australia|europe|me|northamerica|southamerica|us)-" + r"(?:central|east|west|north|south|northeast|southeast)\d\b" + ), + "specific infrastructure region", + ), + ( + "private-path", + re.compile(r"(?i)(? None: + for path in public_text_files(): + text = path.read_text(encoding="utf-8") + for code, pattern, message in FORBIDDEN_RULES: + for match in pattern.finditer(text): + add_issue(path, line_number(text, match.start()), code, message) + + +def github_heading_anchors(text: str) -> set[str]: + anchors: set[str] = set() + duplicates: dict[str, int] = {} + in_fence = False + + for line in text.splitlines(): + if re.match(r"^\s*(```|~~~)", line): + in_fence = not in_fence + continue + if in_fence: + continue + + explicit = re.search(r"""]+>", "", heading) + heading = re.sub(r"[`*_~]", "", heading).strip().casefold() + + characters: list[str] = [] + for char in heading: + category = unicodedata.category(char) + if char in {"-", "_"} or char.isspace() or not category.startswith(("P", "S")): + characters.append(char) + base = re.sub(r"\s", "-", "".join(characters)).strip("-") + number = duplicates.get(base, 0) + duplicates[base] = number + 1 + anchors.add(base if number == 0 else f"{base}-{number}") + + return anchors + + +def markdown_links(path: Path) -> list[tuple[int, str]]: + links: list[tuple[int, str]] = [] + pattern = re.compile( + r"""!?\[[^\]]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^)]*)?\)""" + ) + in_fence = False + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + if re.match(r"^\s*(```|~~~)", line): + in_fence = not in_fence + continue + if in_fence: + continue + for match in pattern.finditer(line): + links.append((number, match.group(1) or match.group(2))) + return links + + +def check_relative_links() -> None: + anchor_cache: dict[Path, set[str]] = {} + markdown_paths = [ + path + for path in public_text_files() + if path.suffix.lower() == ".md" and path != CHANGELOG_PATH + ] + + for source in markdown_paths: + for number, raw_destination in markdown_links(source): + destination = html.unescape(raw_destination).strip() + if re.match(r"^[A-Za-z][A-Za-z0-9+.-]*:", destination): + continue + if destination.startswith("//"): + continue + + file_part, separator, anchor = destination.partition("#") + file_part = unquote(file_part.split("?", 1)[0]) + if file_part.startswith("/"): + add_issue( + source, + number, + "absolute-link", + "repository links must be relative", + ) + continue + + target = source if not file_part else (source.parent / file_part).resolve() + try: + target.relative_to(ROOT) + except ValueError: + add_issue(source, number, "escaping-link", "relative link escapes repository") + continue + + if file_part and not target.is_file(): + add_issue(source, number, "broken-link", "relative link target does not exist") + continue + + if separator and anchor: + if target.suffix.lower() != ".md": + add_issue( + source, + number, + "invalid-anchor", + "anchors may target Markdown files only", + ) + continue + if target not in anchor_cache: + anchor_cache[target] = github_heading_anchors( + target.read_text(encoding="utf-8") + ) + if unquote(anchor).casefold() not in anchor_cache[target]: + add_issue(source, number, "broken-anchor", "Markdown anchor does not exist") + + +CAPABILITY_VERBS = re.compile( + r"(?i)\b(?:builds?|building|develops?|deploys?|delivers?|executes?|" + r"generates?|hosts?|includes?|integrates?|implements?|maintains?|manages?|" + r"monitors?|operates?|places?|processes?|provides?|publishes?|" + r"reconciles?|routes?|runs?|serves?|stores?|supports?|uses?|" + r"validates?|validating)\b" +) +NON_CURRENT_CONTEXT = re.compile( + r"(?i)\b(?:being|no|not|never|without|would|will|may|might|could|must|" + r"intended|future|planned|targets?|doesn't|cannot|documentation|statement)\b" +) +DEPLOYMENT_TERMS = re.compile(r"(?i)\b(?:deployed|live|production)\b") +INSTRUCTION_BULLET = re.compile( + r"^\s*(?:[-*+]\s+|\d+[.)]\s+)" + r"(?:align|check|confirm|do|keep|prefer|record|remove|separate|use|verify)\b", + re.I, +) + + +def status_in_text(text: str) -> str | None: + found = {label for label in STATUS_LABELS if re.search(rf"\b{label}\b", text)} + return next(iter(found)) if len(found) == 1 else None + + +def check_present_capability_claims() -> None: + claim_paths = [ + path + for path in public_text_files() + if path.suffix.lower() == ".md" and path != CHANGELOG_PATH + ] + + for path in claim_paths: + if not path.is_file(): + continue + section_status: dict[int, str | None] = {} + in_fence = False + in_html_comment = False + paragraph_status: str | None = None + paragraph_non_current = False + + for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1): + if in_html_comment: + if "-->" in line: + in_html_comment = False + continue + if "" not in line.split("