How swayamcodes/twin works
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: twin.ts Twin Lifecycle · s12-score-producer.ts S12 Scoring · runner.ts Scenario Runner · s6-score-producer.ts S6 Scoring
Components 29
Command Line
- CLI
packages/cli/src/index.ts
Twin Runtime
- Twin Lifecycle
packages/core/src/twin.ts - Root Safety
packages/core/src/safety.ts - Workspace Copy
packages/core/src/copy.ts - Command Runner
packages/core/src/run.ts - Manifest Capture
packages/core/src/manifest.ts - Git Classification
packages/core/src/git-classification.ts - Watch Capture
packages/core/src/watch.ts - Run Receipt
packages/core/src/receipt.ts
Scenario Evaluation
- Scenario Definitions
packages/scenarios/src/scenarios.ts - Fixture Setup
packages/scenarios/src/fixture.ts - Scenario Runner
packages/scenarios/src/runner.ts - Comparison Runner
packages/scenarios/src/comparison-runner.ts
Evidence Capture
- Artifact Capture
packages/scenarios/src/capture/artifact.ts - Evidence Records
packages/scenarios/src/capture/records.ts - Attempt Capture
packages/scenarios/src/capture/twin-s12-attempt.ts
Evidence Contracts
- Evidence Schemas
packages/scenarios/src/contract/normalized-evidence-schema.ts - Evidence Validation
packages/scenarios/src/contract/normalized-evidence-validation.ts - Attempt Protocol
packages/scenarios/src/contract/attempt-protocol-schema.ts - Attempt Validation
packages/scenarios/src/contract/attempt-protocol-validation.ts - Evidence References
packages/scenarios/src/contract/evidence-refs.ts - Oracle Schema
packages/scenarios/src/contract/oracle-schema.ts
Evaluation Outputs
- Oracle Evaluation
packages/scenarios/src/oracle.ts - S12 Scoring
packages/scenarios/src/s12-score-producer.ts - S6 Scoring
packages/scenarios/src/s6-score-producer.ts - S8–S13 Scoring
packages/scenarios/src/s8-s13-score-producer.ts - Score Contracts
packages/scenarios/src/contract/score-schema.ts - Markdown Report
packages/scenarios/src/markdown-report.ts
Other components
- User
Connections 38
- User → CLI: invokes
- CLI → Twin Lifecycle: uses runtime
packages/cli/src/index.ts - Twin Lifecycle → Root Safety: allocates roots
packages/core/src/twin.ts - Twin Lifecycle → Workspace Copy: copies workspace
packages/core/src/twin.ts - Twin Lifecycle → Command Runner: runs command
packages/core/src/twin.ts - Twin Lifecycle → Manifest Capture: captures manifest
packages/core/src/twin.ts - Twin Lifecycle → Git Classification: captures git state
packages/core/src/twin.ts - Twin Lifecycle → Watch Capture: captures watches
packages/core/src/twin.ts - Twin Lifecycle → Run Receipt: records receipt
packages/core/src/twin.ts - Scenario Runner → Fixture Setup: uses fixtures
packages/scenarios/src/runner.ts - Scenario Runner → Scenario Definitions: loads scenarios
packages/scenarios/src/runner.ts - Comparison Runner → Scenario Definitions: uses scenarios
packages/scenarios/src/comparison-runner.ts - Comparison Runner → Twin Lifecycle: uses runtime
packages/scenarios/src/comparison-runner.ts - Comparison Runner → Fixture Setup: uses fixtures
packages/scenarios/src/comparison-runner.ts - Artifact Capture → Evidence Records: builds records
packages/scenarios/src/capture/artifact.ts - Artifact Capture → Attempt Protocol: uses protocol schema
packages/scenarios/src/capture/artifact.ts - Attempt Capture → Evidence Records: uses records
packages/scenarios/src/capture/twin-s12-attempt.ts - Attempt Capture → Evidence Schemas: uses evidence schema
packages/scenarios/src/capture/twin-s12-attempt.ts - Attempt Capture → Attempt Validation: validates attempt
packages/scenarios/src/capture/twin-s12-attempt.ts - Attempt Validation → Evidence Validation: validates evidence
packages/scenarios/src/contract/attempt-protocol-validation.ts - Attempt Validation → Evidence References: hashes references
packages/scenarios/src/contract/attempt-protocol-validation.ts - Evidence Validation → Evidence Schemas: checks schema
packages/scenarios/src/contract/normalized-evidence-validation.ts - Evidence Schemas → Evidence References: uses reference types
packages/scenarios/src/contract/normalized-evidence-schema.ts - Attempt Protocol → Oracle Schema: uses oracle schema
packages/scenarios/src/contract/attempt-protocol-schema.ts - Oracle Evaluation → Evidence References: resolves references
packages/scenarios/src/oracle.ts - Oracle Evaluation → Oracle Schema: produces oracle result
packages/scenarios/src/oracle.ts - S12 Scoring → Scenario Runner: uses scenario runs
packages/scenarios/src/s12-score-producer.ts - S12 Scoring → Oracle Evaluation: uses oracle results
packages/scenarios/src/s12-score-producer.ts - S12 Scoring → Artifact Capture: captures artifacts
packages/scenarios/src/s12-score-producer.ts - S12 Scoring → Attempt Capture: captures attempts
packages/scenarios/src/s12-score-producer.ts - S12 Scoring → Score Contracts: uses score schema
packages/scenarios/src/s12-score-producer.ts - S6 Scoring → Scenario Runner: uses scenario runs
packages/scenarios/src/s6-score-producer.ts - S6 Scoring → Oracle Evaluation: uses oracle results
packages/scenarios/src/s6-score-producer.ts - S6 Scoring → Artifact Capture: captures artifacts
packages/scenarios/src/s6-score-producer.ts - S6 Scoring → Score Contracts: uses score schema
packages/scenarios/src/s6-score-producer.ts - S8–S13 Scoring → Scenario Runner: uses scenario runs
packages/scenarios/src/s8-s13-score-producer.ts - S8–S13 Scoring → Scenario Definitions: uses scenarios
packages/scenarios/src/s8-s13-score-producer.ts - Markdown Report → Comparison Runner: reports comparisons