# 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.