From b7430f17cb39aa0974b513336589dc64af8e5c61 Mon Sep 17 00:00:00 2001 From: Simon Axelsson Date: Wed, 16 Sep 2026 15:33:05 +0200 Subject: [PATCH] docs: establish canonical c0py reconstruction masterplan --- docs/MASTERPLAN.md | 143 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/MASTERPLAN.md diff --git a/docs/MASTERPLAN.md b/docs/MASTERPLAN.md new file mode 100644 index 0000000..e282548 --- /dev/null +++ b/docs/MASTERPLAN.md @@ -0,0 +1,143 @@ +# C0PY Masterplan — Canonical Web Product Reconstruction Engine + +**Status:** canonical +**Owner:** C0PY +**Rule:** this document and the C0PY IR contracts are the single source of truth for web/product capture and reconstruction across SIAX. + +## Mission + +C0PY turns an observed web product into an evidence-backed digital twin specification that can be reconstructed, verified and repaired autonomously. The system must cover visual fidelity, responsive behavior, assets, interactions, workflows, network contracts, motion, accessibility and product topology. + +## Non-negotiable architecture + +```text +Source product + -> discovery + -> deterministic capture + -> semantic exploration + -> Canonical Evidence Graph / IR + -> frozen reconstruction specs + -> builder adapters + -> preview deployment + -> multidimensional verification + -> repair loop + -> production candidate +``` + +No crawler, AI builder or upstream project owns the truth. The Canonical IR owns the truth. + +## Canonical layers + +1. **Discovery** — routes, sitemaps, links, navigation, semantic workflow discovery. +2. **Capture** — Playwright + CDP as primary runtime; DOM, CSSOM, computed styles, accessibility tree, screenshots, storage, network, WebSocket/SSE, canvas/media and performance. +3. **Evidence** — every assertion stores source, method, capture context, confidence and provenance. +4. **Product model** — entities, relationships, capabilities, permissions, workflows and state machines inferred from observed behavior. +5. **Specification** — deterministic page/component/workflow contracts generated from the evidence graph. +6. **Reconstruction** — adapters for v0, Lovable, Codex and generic agents. Builders consume specs; they do not inspect the source as authority. +7. **Verification** — geometry, typography, color, assets, routes, state, interaction, workflow, network, motion, accessibility and runtime health. +8. **Repair** — failures become typed root-cause work items and are repaired iteratively. + +## Primary technology decisions + +- Browser runtime: Playwright. +- Deep browser instrumentation: Chrome DevTools Protocol. +- Crawl orchestration: Crawlee-compatible request graph. +- Session/event replay: rrweb adapter. +- Semantic exploration: Browser Use / Browser Harness adapters. +- Visual comparison: pixelmatch-compatible deterministic diff plus computed-style root cause analysis. +- Optional WebGL forensics: Spector.js adapter. +- Optional archival: SingleFile and Browsertrix only behind process/service adapters due to copyleft boundaries. +- Output target: clean SIAX architecture, normally Next.js + React + TypeScript, regardless of source framework. + +## Upstream capability policy + +Every borrowed idea or implementation MUST be classified as one of: + +- `CORE` — implemented and owned inside C0PY. +- `DEPENDENCY` — consumed as a package/library. +- `CHERRY_PICK` — imported/adapted source with exact provenance and license notice. +- `ADAPTER` — isolated integration behind a C0PY contract. +- `REIMPLEMENT` — behavior/specification reproduced without copying source. +- `REFERENCE_ONLY` — studied, never included in runtime. +- `DROP` — rejected duplicate or lower-value implementation. + +See `docs/UPSTREAM-CAPABILITY-MATRIX.md`. + +## Canonical package topology + +```text +packages/ + types/ canonical shared contracts + c0py-core/ + discovery/ + capture/ + evidence/ + provenance/ + product-model/ + specification/ + verification/ + repair/ + adapters/ +``` + +As implementation grows, high-cohesion modules may graduate into their own workspace packages, but they must continue to consume the same IR contracts. + +## Evidence model + +Evidence confidence MUST use explicit semantics: + +- `measured`: deterministic machine measurement. +- `observed`: directly observed behavior/state. +- `inferred`: reasoned from evidence, not directly visible. +- `declared`: supplied by an authorized configuration/specification. +- `unknown`: insufficient evidence. + +`invented` is prohibited in clone mode. Adapt/blend mode may create new design/product choices, but they must be marked as synthetic and never confused with source evidence. + +## Operating modes + +- **clone** — maximize observable fidelity; no creative substitutions without an explicit evidence gap. +- **adapt** — preserve approved product semantics while transforming brand/design/technology. +- **blend** — combine explicitly selected capabilities/patterns from multiple references into a new product; every source lineage remains traceable. + +## Quality gates + +A single visual score is forbidden as the release criterion. C0PY uses a fidelity vector: + +- geometry +- typography +- colors +- assets +- responsive states +- route coverage +- interaction/state coverage +- workflow coverage +- network-contract parity +- motion parity +- accessibility semantics +- console/runtime health +- production build health + +Critical routes, contracted workflows and required interaction states must reach 100% coverage before a clone can be marked complete. Visual tolerances are profile-specific and recorded in the manifest. + +## Cross-repo rule + +Other SIAX repositories may consume C0PY capabilities, evidence and generated specs, but MUST NOT fork a parallel capture ontology, fidelity model or reconstruction masterplan. Cross-repo integrations point back to C0PY contracts/versioned schemas. + +## Delivery order + +1. Canonical IR + provenance. +2. Playwright/CDP capture. +3. route topology and deterministic extraction. +4. HAR/network evidence and authenticated capture profiles. +5. interaction/state delta engine. +6. rrweb replay/event timeline. +7. semantic workflow discovery adapters. +8. design-system extraction. +9. media/motion/WebGL adapters. +10. specification generator. +11. reconstruction adapters. +12. multidimensional QA. +13. autonomous repair loop. +14. clone/adapt/blend orchestration. +15. MCP/API contracts and fleet automations.