# swayamcodes/twin architecture

> Architecture diagram of the GitHub repository swayamcodes/twin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swayamcodes/twin
- Repository: https://github.com/swayamcodes/twin

## Overview

This TypeScript monorepo provides an isolated workspace runner (“twin”) and scenario-based evaluation tools. The main workflow runs a scenario in a disposable, guarded copy, captures workspace and tool evidence, validates that evidence, and produces oracle and score results; comparison and Markdown-report modules provide additional evaluation outputs. The graph includes the principal capture, contract, and scoring stages alongside the core runtime. Some subsystem connections are based on SOURCE INDEX references rather than shown call sites; unsampled details are not inferred as extra edges.

Main entry points: [`packages/core/src/twin.ts`](https://github.com/swayamcodes/twin/blob/main/packages/core/src/twin.ts) (Twin Lifecycle), [`packages/scenarios/src/s12-score-producer.ts`](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s12-score-producer.ts) (S12 Scoring), [`packages/scenarios/src/runner.ts`](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/runner.ts) (Scenario Runner), [`packages/scenarios/src/s6-score-producer.ts`](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s6-score-producer.ts) (S6 Scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command Line"]
  node_cli["CLI<br/>[index.ts]"]
end

subgraph group_core["Twin Runtime"]
  node_twin["Twin Lifecycle<br/>[twin.ts]"]
  node_safety["Root Safety<br/>[safety.ts]"]
  node_copy["Workspace Copy<br/>[copy.ts]"]
  node_run["Command Runner<br/>[run.ts]"]
  node_manifest["Manifest Capture<br/>[manifest.ts]"]
  node_git["Git Classification"]
  node_watch["Watch Capture<br/>[watch.ts]"]
  node_receipt["Run Receipt<br/>[receipt.ts]"]
end

subgraph group_scenario["Scenario Evaluation"]
  node_scenario_defs["Scenario Definitions<br/>[scenarios.ts]"]
  node_fixture["Fixture Setup<br/>[fixture.ts]"]
  node_runner["Scenario Runner<br/>[runner.ts]"]
  node_comparison["Comparison Runner"]
end

subgraph group_capture["Evidence Capture"]
  node_artifact["Artifact Capture<br/>[artifact.ts]"]
  node_records["Evidence Records<br/>[records.ts]"]
  node_attempt_capture["Attempt Capture"]
end

subgraph group_contracts["Evidence Contracts"]
  node_evidence_schema["Evidence Schemas"]
  node_evidence_validation["Evidence Validation"]
  node_attempt_schema["Attempt Protocol"]
  node_attempt_validation["Attempt Validation"]
  node_evidence_refs["Evidence References<br/>[evidence-refs.ts]"]
  node_oracle_schema["Oracle Schema<br/>[oracle-schema.ts]"]
end

subgraph group_outputs["Evaluation Outputs"]
  node_oracle["Oracle Evaluation<br/>[oracle.ts]"]
  node_s12_score["S12 Scoring"]
  node_s6_score["S6 Scoring"]
  node_s813_score["S8–S13 Scoring"]
  node_score_schema["Score Contracts<br/>[score-schema.ts]"]
  node_report["Markdown Report<br/>[markdown-report.ts]"]
end

node_user(("User"))

node_user -->|"invokes"| node_cli
node_cli -->|"uses runtime"| node_twin
node_twin -->|"allocates roots"| node_safety
node_twin -->|"copies workspace"| node_copy
node_twin -->|"runs command"| node_run
node_twin -.->|"captures manifest"| node_manifest
node_twin -.->|"captures git state"| node_git
node_twin -.->|"captures watches"| node_watch
node_twin -.->|"records receipt"| node_receipt
node_runner -->|"uses fixtures"| node_fixture
node_runner -->|"loads scenarios"| node_scenario_defs
node_comparison -->|"uses scenarios"| node_scenario_defs
node_comparison -->|"uses runtime"| node_twin
node_comparison -->|"uses fixtures"| node_fixture
node_artifact -->|"builds records"| node_records
node_artifact -->|"uses protocol schema"| node_attempt_schema
node_attempt_capture -->|"uses records"| node_records
node_attempt_capture -->|"uses evidence schema"| node_evidence_schema
node_attempt_capture -->|"validates attempt"| node_attempt_validation
node_attempt_validation -->|"validates evidence"| node_evidence_validation
node_attempt_validation -->|"hashes references"| node_evidence_refs
node_evidence_validation -->|"checks schema"| node_evidence_schema
node_evidence_schema -->|"uses reference types"| node_evidence_refs
node_attempt_schema -->|"uses oracle schema"| node_oracle_schema
node_oracle -->|"resolves references"| node_evidence_refs
node_oracle -->|"produces oracle result"| node_oracle_schema
node_s12_score -->|"uses scenario runs"| node_runner
node_s12_score -->|"uses oracle results"| node_oracle
node_s12_score -->|"captures artifacts"| node_artifact
node_s12_score -->|"captures attempts"| node_attempt_capture
node_s12_score -->|"uses score schema"| node_score_schema
node_s6_score -->|"uses scenario runs"| node_runner
node_s6_score -->|"uses oracle results"| node_oracle
node_s6_score -->|"captures artifacts"| node_artifact
node_s6_score -->|"uses score schema"| node_score_schema
node_s813_score -->|"uses scenario runs"| node_runner
node_s813_score -->|"uses scenarios"| node_scenario_defs
node_report -.->|"reports comparisons"| node_comparison

click node_cli "https://github.com/swayamcodes/twin/blob/main/packages/cli/src/index.ts"
click node_twin "https://github.com/swayamcodes/twin/blob/main/packages/core/src/twin.ts"
click node_safety "https://github.com/swayamcodes/twin/blob/main/packages/core/src/safety.ts"
click node_copy "https://github.com/swayamcodes/twin/blob/main/packages/core/src/copy.ts"
click node_run "https://github.com/swayamcodes/twin/blob/main/packages/core/src/run.ts"
click node_manifest "https://github.com/swayamcodes/twin/blob/main/packages/core/src/manifest.ts"
click node_git "https://github.com/swayamcodes/twin/blob/main/packages/core/src/git-classification.ts"
click node_watch "https://github.com/swayamcodes/twin/blob/main/packages/core/src/watch.ts"
click node_receipt "https://github.com/swayamcodes/twin/blob/main/packages/core/src/receipt.ts"
click node_scenario_defs "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/scenarios.ts"
click node_fixture "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/fixture.ts"
click node_runner "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/runner.ts"
click node_comparison "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/comparison-runner.ts"
click node_artifact "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/artifact.ts"
click node_records "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/records.ts"
click node_attempt_capture "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/twin-s12-attempt.ts"
click node_evidence_schema "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/normalized-evidence-schema.ts"
click node_evidence_validation "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/normalized-evidence-validation.ts"
click node_attempt_schema "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/attempt-protocol-schema.ts"
click node_attempt_validation "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/attempt-protocol-validation.ts"
click node_evidence_refs "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/evidence-refs.ts"
click node_oracle_schema "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/oracle-schema.ts"
click node_oracle "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/oracle.ts"
click node_s12_score "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s12-score-producer.ts"
click node_s6_score "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s6-score-producer.ts"
click node_s813_score "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s8-s13-score-producer.ts"
click node_score_schema "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/score-schema.ts"
click node_report "https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/markdown-report.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_twin,node_safety,node_copy,node_run,node_manifest,node_git,node_watch,node_receipt toneAmber
class node_scenario_defs,node_fixture,node_runner,node_comparison toneMint
class node_artifact,node_records,node_attempt_capture toneRose
class node_evidence_schema,node_evidence_validation,node_attempt_schema,node_attempt_validation,node_evidence_refs,node_oracle_schema toneIndigo
class node_oracle,node_s12_score,node_s6_score,node_s813_score,node_score_schema,node_report toneTeal
```

## Components

### Command Line

- [CLI](https://github.com/swayamcodes/twin/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`

### Twin Runtime

- [Twin Lifecycle](https://github.com/swayamcodes/twin/blob/main/packages/core/src/twin.ts): `packages/core/src/twin.ts`
- [Root Safety](https://github.com/swayamcodes/twin/blob/main/packages/core/src/safety.ts): `packages/core/src/safety.ts`
- [Workspace Copy](https://github.com/swayamcodes/twin/blob/main/packages/core/src/copy.ts): `packages/core/src/copy.ts`
- [Command Runner](https://github.com/swayamcodes/twin/blob/main/packages/core/src/run.ts): `packages/core/src/run.ts`
- [Manifest Capture](https://github.com/swayamcodes/twin/blob/main/packages/core/src/manifest.ts): `packages/core/src/manifest.ts`
- [Git Classification](https://github.com/swayamcodes/twin/blob/main/packages/core/src/git-classification.ts): `packages/core/src/git-classification.ts`
- [Watch Capture](https://github.com/swayamcodes/twin/blob/main/packages/core/src/watch.ts): `packages/core/src/watch.ts`
- [Run Receipt](https://github.com/swayamcodes/twin/blob/main/packages/core/src/receipt.ts): `packages/core/src/receipt.ts`

### Scenario Evaluation

- [Scenario Definitions](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/scenarios.ts): `packages/scenarios/src/scenarios.ts`
- [Fixture Setup](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/fixture.ts): `packages/scenarios/src/fixture.ts`
- [Scenario Runner](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/runner.ts): `packages/scenarios/src/runner.ts`
- [Comparison Runner](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/comparison-runner.ts): `packages/scenarios/src/comparison-runner.ts`

### Evidence Capture

- [Artifact Capture](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/artifact.ts): `packages/scenarios/src/capture/artifact.ts`
- [Evidence Records](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/records.ts): `packages/scenarios/src/capture/records.ts`
- [Attempt Capture](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/capture/twin-s12-attempt.ts): `packages/scenarios/src/capture/twin-s12-attempt.ts`

### Evidence Contracts

- [Evidence Schemas](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/normalized-evidence-schema.ts): `packages/scenarios/src/contract/normalized-evidence-schema.ts`
- [Evidence Validation](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/normalized-evidence-validation.ts): `packages/scenarios/src/contract/normalized-evidence-validation.ts`
- [Attempt Protocol](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/attempt-protocol-schema.ts): `packages/scenarios/src/contract/attempt-protocol-schema.ts`
- [Attempt Validation](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/attempt-protocol-validation.ts): `packages/scenarios/src/contract/attempt-protocol-validation.ts`
- [Evidence References](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/evidence-refs.ts): `packages/scenarios/src/contract/evidence-refs.ts`
- [Oracle Schema](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/oracle-schema.ts): `packages/scenarios/src/contract/oracle-schema.ts`

### Evaluation Outputs

- [Oracle Evaluation](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/oracle.ts): `packages/scenarios/src/oracle.ts`
- [S12 Scoring](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s12-score-producer.ts): `packages/scenarios/src/s12-score-producer.ts`
- [S6 Scoring](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s6-score-producer.ts): `packages/scenarios/src/s6-score-producer.ts`
- [S8–S13 Scoring](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/s8-s13-score-producer.ts): `packages/scenarios/src/s8-s13-score-producer.ts`
- [Score Contracts](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/contract/score-schema.ts): `packages/scenarios/src/contract/score-schema.ts`
- [Markdown Report](https://github.com/swayamcodes/twin/blob/main/packages/scenarios/src/markdown-report.ts): `packages/scenarios/src/markdown-report.ts`

### Other components

- **User**

## Connections

- User → CLI: invokes
- CLI → Twin Lifecycle: uses runtime (evidence: `packages/cli/src/index.ts`)
- Twin Lifecycle → Root Safety: allocates roots (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Workspace Copy: copies workspace (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Command Runner: runs command (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Manifest Capture: captures manifest (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Git Classification: captures git state (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Watch Capture: captures watches (evidence: `packages/core/src/twin.ts`)
- Twin Lifecycle → Run Receipt: records receipt (evidence: `packages/core/src/twin.ts`)
- Scenario Runner → Fixture Setup: uses fixtures (evidence: `packages/scenarios/src/runner.ts`)
- Scenario Runner → Scenario Definitions: loads scenarios (evidence: `packages/scenarios/src/runner.ts`)
- Comparison Runner → Scenario Definitions: uses scenarios (evidence: `packages/scenarios/src/comparison-runner.ts`)
- Comparison Runner → Twin Lifecycle: uses runtime (evidence: `packages/scenarios/src/comparison-runner.ts`)
- Comparison Runner → Fixture Setup: uses fixtures (evidence: `packages/scenarios/src/comparison-runner.ts`)
- Artifact Capture → Evidence Records: builds records (evidence: `packages/scenarios/src/capture/artifact.ts`)
- Artifact Capture → Attempt Protocol: uses protocol schema (evidence: `packages/scenarios/src/capture/artifact.ts`)
- Attempt Capture → Evidence Records: uses records (evidence: `packages/scenarios/src/capture/twin-s12-attempt.ts`)
- Attempt Capture → Evidence Schemas: uses evidence schema (evidence: `packages/scenarios/src/capture/twin-s12-attempt.ts`)
- Attempt Capture → Attempt Validation: validates attempt (evidence: `packages/scenarios/src/capture/twin-s12-attempt.ts`)
- Attempt Validation → Evidence Validation: validates evidence (evidence: `packages/scenarios/src/contract/attempt-protocol-validation.ts`)
- Attempt Validation → Evidence References: hashes references (evidence: `packages/scenarios/src/contract/attempt-protocol-validation.ts`)
- Evidence Validation → Evidence Schemas: checks schema (evidence: `packages/scenarios/src/contract/normalized-evidence-validation.ts`)
- Evidence Schemas → Evidence References: uses reference types (evidence: `packages/scenarios/src/contract/normalized-evidence-schema.ts`)
- Attempt Protocol → Oracle Schema: uses oracle schema (evidence: `packages/scenarios/src/contract/attempt-protocol-schema.ts`)
- Oracle Evaluation → Evidence References: resolves references (evidence: `packages/scenarios/src/oracle.ts`)
- Oracle Evaluation → Oracle Schema: produces oracle result (evidence: `packages/scenarios/src/oracle.ts`)
- S12 Scoring → Scenario Runner: uses scenario runs (evidence: `packages/scenarios/src/s12-score-producer.ts`)
- S12 Scoring → Oracle Evaluation: uses oracle results (evidence: `packages/scenarios/src/s12-score-producer.ts`)
- S12 Scoring → Artifact Capture: captures artifacts (evidence: `packages/scenarios/src/s12-score-producer.ts`)
- S12 Scoring → Attempt Capture: captures attempts (evidence: `packages/scenarios/src/s12-score-producer.ts`)
- S12 Scoring → Score Contracts: uses score schema (evidence: `packages/scenarios/src/s12-score-producer.ts`)
- S6 Scoring → Scenario Runner: uses scenario runs (evidence: `packages/scenarios/src/s6-score-producer.ts`)
- S6 Scoring → Oracle Evaluation: uses oracle results (evidence: `packages/scenarios/src/s6-score-producer.ts`)
- S6 Scoring → Artifact Capture: captures artifacts (evidence: `packages/scenarios/src/s6-score-producer.ts`)
- S6 Scoring → Score Contracts: uses score schema (evidence: `packages/scenarios/src/s6-score-producer.ts`)
- S8–S13 Scoring → Scenario Runner: uses scenario runs (evidence: `packages/scenarios/src/s8-s13-score-producer.ts`)
- S8–S13 Scoring → Scenario Definitions: uses scenarios (evidence: `packages/scenarios/src/s8-s13-score-producer.ts`)
- Markdown Report → Comparison Runner: reports comparisons