pollinate

Pollinate

Overview

Analyze a source feature, map it to target project conventions, and generate a design document for porting. Delegates implementation to the standard /plan → /execute pipeline, and verification to /pollinate-verify.

Announce: "I'm analyzing the source feature for cross-codebase porting."

Arguments

<source-path-or-url> <feature> [--rigor critical]

• <source>: Local filesystem path or GitHub/git URL
• <feature>: Function name, module name, or natural language description
• --rigor critical: Flag specific chunks for elevated verification (property-based testing, extra adversarial iterations)

Process

Before Starting

# Check tracking tool availability
BEADS_AVAILABLE=false
DECIDUOUS_AVAILABLE=false

# Check both tool installation AND project initialization
command -v bd >/dev/null 2>&1 && ls .beads/beads.db 2>/dev/null && BEADS_AVAILABLE=true
command -v deciduous >/dev/null 2>&1 && ls .deciduous/ 2>/dev/null && DECIDUOUS_AVAILABLE=true

# Graceful degradation note:
# If neither tool is available: skip all tracking commands (bd, deciduous) throughout this skill.
# The analysis and design doc generation work identically — only tracking calls are skipped.
# If only one is available: use whichever is available, skip the other.

# Create epic for feature extraction (if beads available)
[ "$BEADS_AVAILABLE" = true ] && bd create "Pollinate: Extract <feature> from <source>" -t epic -p 2

# Log goal with verbatim prompt (if deciduous available)
[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add goal "Port <feature> from <source> to this codebase" -c 80

During Source Acquisition

Step 1: Parse Arguments

Detect source type and extract feature identifier:

Source Type Detection:

• Starts with /, ~, or . → local filesystem path
• Starts with https://github.com, git@, or ends with .git → remote URL
• Otherwise → ask user via AskUserQuestion: "Is '' a local path or GitHub URL?"

Accepted Feature Identifiers:

• Function name (e.g., fetch_user, getUserData)
• Module name (e.g., auth, payment_processor)
• Natural language description (e.g., "the user authentication flow")

Optional flag:

• --rigor critical → mark extracted chunks for elevated verification (property-based testing, adversarial iterations)

Step 2: Acquire Source & Extract Feature

For Local Paths: Dispatch ed3d-research-agents:codebase-investigator with:

Your task: Extract a feature from the source codebase and return its complete dependency graph.

Input:
- Source path: <SOURCE_PATH>
- Feature identifier: <FEATURE_ID> (could be function name, module name, or natural language description)

Output: Structured response with these sections:

1. **Feature Location**
   - File path(s)
   - Line range (if applicable)
   - Programming language

2. **Feature Code**
   - Complete implementation (all non-library code)
   - Any inline documentation

3. **Direct Dependencies**
   - Imported functions/classes from same codebase
   - Parameters and their types
   - Return type

4. **Transitive Dependency Graph**
   - For each direct dependency, recursively trace its dependencies
   - Stop when reaching: standard library, third-party package, or circular reference
   - Format: Tree structure showing dependency depth

5. **External Dependencies**
   - Third-party libraries/frameworks used
   - Version constraints (if specified)
   - License types

6. **Line Count**
   - Total lines of feature code (including dependencies in same codebase)

CRITICAL INSTRUCTIONS:
- Accept function name, module name, or natural language description as feature identifier
- For natural language: search code comments, docstrings, and file structure to infer intent
- Trace recursively until hitting standard library or third-party package boundaries
- Report the complete transitive graph, not just direct imports
- If the feature is not found, ask clarifying questions about its name or location

For Remote URLs: Dispatch ed3d-research-agents:remote-code-researcher with:

Your task: Clone a GitHub repository, extract a feature, and return its complete dependency graph.

Input:
- Repository URL: <REMOTE_URL>
- Feature identifier: <FEATURE_ID>

Output: Structured response with these sections:

1. **Feature Location**
   - File path(s)
   - Line range (if applicable)
   - Programming language

2. **Feature Code**
   - Complete implementation (all non-library code)
   - Any inline documentation

3. **Direct Dependencies**
   - Imported functions/classes from same codebase
   - Parameters and their types
   - Return type

4. **Transitive Dependency Graph**
   - For each direct dependency, recursively trace its dependencies
   - Stop when reaching: standard library, third-party package, or circular reference
   - Format: Tree structure showing dependency depth

5. **External Dependencies**
   - Third-party libraries/frameworks used
   - Version constraints (if specified)
   - License types

6. **Line Count**
   - Total lines of feature code (including dependencies in same codebase)

7. **Clone Path**
   - The path where you cloned the repository (will be needed for later verification)

CRITICAL INSTRUCTIONS:
- Accept function name, module name, or natural language description as feature identifier
- For natural language: search code comments, docstrings, and file structure to infer intent
- Trace recursively until hitting standard library or third-party package boundaries
- Report the complete transitive graph, not just direct imports
- If the feature is not found, ask clarifying questions about its name or location
- After cloning to a temporary location, output the clone path so we can persist it for later use.

After agent returns, capture the source path:

• Local paths: Record as SOURCE_PATH = <original-path>
• Remote clones: Record as SOURCE_PATH = <clone-path> (from agent response)

Store SOURCE_PATH in a variable for later use in design doc generation.

Important for remote clones: When generating the design doc in Phase 4, include in "Additional Considerations": "Source cloned to <SOURCE_PATH>. Do not delete until /pollinate-verify completes."

Step 3: Chunk Decomposition & Deciduous Logging

If feature ≤100 lines, skip to deciduous logging.

If feature >100 lines:

1. Analyze the dependency graph for natural decomposition boundaries:

   • Separate concerns (e.g., validation logic vs. API calls)
   • Independent subfeatures that could be implemented separately
   • Cohesive modules within the feature

2. Present chunk table to user via AskUserQuestion:

The extracted feature is <N> lines and has complex dependencies.

Suggested decomposition:

| Chunk | Lines | Dependencies | Notes |
|-------|-------|--------------|-------|
| <name1> | <L> | <deps> | <desc> |
| <name2> | <L> | <deps> | <desc> |
| ... | | | |

Choose one:
- "Use suggested chunks" → proceed with decomposition
- "Extract as monolithic feature" → treat entire feature as one unit
- "Custom chunks: <chunk1>, <chunk2>, ..." → specify your own

3. Log deciduous decisions (final action in Step 3, if deciduous available):

Log the extraction result:

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add action "Extracted <feature> from <source>: <N> lines, <M> dependencies" -c 85

If feature >100 lines and chunking was performed, also log the decomposition decision:

If user chose monolithic:

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Kept <feature> as monolithic unit: <N> lines, <M> dependencies" -c 80

If user chose suggested chunks:

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Decomposed <feature> into <K> chunks: <chunk-names>" -c 80

If user specified custom chunks:

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Decomposed <feature> into custom chunks: <custom-names>" -c 80

These logs capture the source analysis decisions for audit trail and future reference (only when deciduous is available).

Step 4: Target Convention Analysis

Dispatch ed3d-research-agents:codebase-investigator against the current (target) project to extract conventions:

Your task: Analyze the target project's conventions and patterns.

Input:
- Current project path: . (current working directory)

Output: Structured response with these sections:

1. **Project Overview**
   - Primary programming language(s)
   - Runtime/framework (Node.js, Python 3.x, Java, etc.)
   - Package manager (npm, pip, cargo, maven, etc.)

2. **Naming Conventions**
   - Variable/function naming style (snake_case, camelCase, PascalCase)
   - File naming patterns
   - Class/type naming patterns

3. **Code Organization**
   - Import/require patterns
   - Module structure
   - Folder organization

4. **Error Handling**
   - Exception/error types used
   - Error handling patterns (try-catch, Result types, error returns, etc.)
   - Logging approach

5. **Asynchronous Patterns**
   - async/await, promises, callbacks, or channels
   - Concurrency primitives used
   - Streaming vs buffering patterns

6. **Testing Framework & Patterns**
   - Test framework used (pytest, Jest, Go testing, etc.)
   - Test file location convention
   - Mocking approach (mocks, stubs, fixtures, etc.)

7. **Configuration & Dependency Management**
   - How external dependencies are declared (package.json, requirements.txt, Cargo.toml, etc.)
   - Currently installed dependencies relevant to the ported feature
   - Version pinning strategy

CRITICAL INSTRUCTIONS:
- Provide concrete examples from the actual codebase
- List all dependencies installed in the project
- Focus on patterns that would affect feature porting

For cross-language ports: Additionally dispatch ed3d-research-agents:combined-researcher to research idiomatic equivalents:

Your task: Research language-idiomatic patterns for cross-language feature porting.

Input:
- Source language: <SOURCE_LANGUAGE> (from Step 2)
- Target language: <TARGET_LANGUAGE> (detected from Step 4 codebase-investigator)
- Feature type: <FEATURE_TYPE> (e.g., async I/O, data validation, ORM usage, etc.)

Output: For each source pattern identified, provide:

1. **Pattern Name & Source Example**
   - The pattern as used in <SOURCE_LANGUAGE>
   - Concrete code snippet from the extracted feature

2. **Target Language Idiomatic Equivalent**
   - How this pattern is typically expressed in <TARGET_LANGUAGE>
   - Current best practice (as of 2026)
   - Trade-offs vs source approach

3. **Library/Framework Recommendations**
   - Idiomatic library/framework in target language
   - Whether it's already installed in the target project
   - Version requirements

Examples to research:
- Async I/O: asyncio (Python) → async/await or Tokio (Rust)?
- Error handling: Exceptions (Python) → Result types (Rust)?
- Data structures: dict (Python) → HashMap (Rust)?
- Testing: pytest (Python) → Go testing or custom framework?

CRITICAL INSTRUCTIONS:
- Focus on patterns actually present in the extracted feature
- Prioritize idiomatic approaches over literal translations
- Include performance/maintainability implications

After agents return, build two comparison tables and present to user:

Convention Mapping Table:

Present this table in text format:

| Aspect | Source | Target | Adaptation Notes |
|--------|--------|--------|-----------------|
| Language | <source-lang> | <target-lang> | |
| Naming | <source-style> | <target-style> | Use target style: <example> |
| Error Handling | <source-error> | <target-error> | Map <source> exceptions to <target> errors |
| Async Model | <source-async> | <target-async> | Use target async/await pattern |
| Testing | <source-test> | <target-test> | Target uses <framework> with <mocking> |
| ... | ... | ... | ... |

Dependency Mapping Table:

Present this table in text format:

| Source Dependency | Version | Target Equivalent | Status | User Decision? |
|------------------|---------|------------------|--------|---------------|
| <source-dep> | <ver> | <target-equiv> | already-installed | No |
| <source-dep> | <ver> | <target-equiv> | not-installed | Yes |
| <source-dep> | <ver> | None (implement inline) | — | Yes |
| ... | | | | |

Key decision markers:

• "already-installed" → No user decision needed, use equivalent as-is
• "not-installed" → Present as dependency swap option in Step 5
• "None (implement inline)" → Feature can be ported inline without external dep

Log deciduous decisions and LEARNED comments after building tables (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add action "Analyzed target project conventions: <N> conventions identified, <M> dependencies mapped" -c 85

If cross-language port: also log (if deciduous available)

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add action "Researched cross-language idiom equivalents: <patterns>" -c 85

Record target analysis learnings in beads epic (if beads available):

# For each convention discovered, add a LEARNED comment
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: Target uses <pattern> for <aspect>"

# Examples:
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: Target uses camelCase for function names (vs source snake_case)"
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: Target uses async/await pattern for async operations"
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: Target uses Jest for testing with mocked external calls"

These comments capture the target conventions discovered, creating a reusable reference for future porting efforts.

Step 5: User Decision Points

Surface trade-off decisions to the user in three categories. Use AskUserQuestion for each decision.

1. Dependency Swaps

For each dependency in the Dependency Mapping Table where source and target differ (not already-installed), present options:

AskUserQuestion (singleSelect):

Dependency Swap: <source-dep>

The source feature uses <source-dep> (<source-version>).
Target project equivalent: <target-equiv>

Behavioral difference (if any):
<desc of how target equiv differs, performance/accuracy implications>

Choose one:
- "Use target equivalent <target-equiv>" (Recommended) → Maps all source usages to target equiv
- "Port <source-dep> inline" → Minimal adaptation of source dep logic within ported feature
- "Skip this functionality" → Omit the <source-dep> feature entirely

Log each decision (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Dep swap: <source-dep> → <target-equiv> because <rationale>" -c 85

Or if skipped (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Dep swap: <source-dep> skipped because <rationale>" -c 85

2. Architectural Adaptations

For each architectural style difference identified in Convention Mapping Table, present options:

AskUserQuestion (singleSelect):

Architecture: <pattern-name>

Source uses: <source-style> (e.g., global state, dependency injection, service locator)
Target project uses: <target-style>

Performance/Accuracy implications:
- Target style: <implications>
- Source style kept: <implications>
- Hybrid approach: <implications>

Choose one:
- "Adapt to target style <target-style>" (Recommended) → Refactor feature to match target patterns
- "Keep source style" → Maintain source approach, add adapter layer if needed
- "Hybrid approach" → Selective adaptation of <components> to target style

Log each decision (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Architecture: adapted <pattern> to target style because <rationale>" -c 85

Or if kept source or hybrid (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Architecture: <pattern> kept source style because <rationale>" -c 85

3. Rigor Flagging (Conditional)

Only prompt if --rigor critical was NOT passed globally.

AskUserQuestion (multiSelect):

Rigor Flagging

For larger features or complex ports, you can flag individual chunks for elevated verification
(property-based testing, extra adversarial iterations, 10x more test cases).

Chunks from this feature:
- Chunk 1: <name> (<L> lines)
- Chunk 2: <name> (<L> lines)
- Chunk 3: <name> (<L> lines)
- ... (or "All chunks") ...

Flag chunks for critical rigor (select zero or more):
- [  ] Chunk 1: <name>
- [  ] Chunk 2: <name>
- [  ] Chunk 3: <name>
- [  ] All chunks

Log the decision (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Rigor: chunks <list> flagged critical because <rationale>" -c 80

If no chunks flagged (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add decision "Rigor: standard verification applied to all chunks" -c 80

Summary Log After All Decisions

After all three decision categories, log a summary action (if deciduous available):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add action "User decisions captured: <N> dependency swaps, <M> architectural adaptations, rigor flagged for <chunks>" -c 85

Record mapping decisions as LEARNED comments in beads epic (if beads available):

For each dependency swap decision:

[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: <source-dep> maps to <target-dep> in <target-lang> because <rationale>"

For each architectural adaptation decision:

[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: <source-pattern> adapts to <target-pattern> — <performance/accuracy tradeoff>"

Examples:

[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: requests (Python) maps to axios (JavaScript) because it's the idiomatically preferred HTTP library"
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: exception handling adapts to Promise rejection pattern — similar semantics, different syntax"
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "LEARNED: dictionary iteration adapts to Object.entries — functionally equivalent with minor performance characteristics"

These comments capture the mapping decisions and their rationale, making the adaptation choices visible in the epic for future reference.

This completes the target convention analysis and user decision phase. The decisions feed into the design document generation (Phase 6).

Step 6: Generate Design Document

Generate a design document that synthesizes all analysis into a structured plan for implementation and verification.

Design Document Location:

Create docs/design-plans/YYYY-MM-DD-pollinate-<feature-slug>.md where:

• YYYY-MM-DD is today's date
• <feature-slug> is a slugified version of the feature name (e.g., "gle-constraints" for "GLE Constraints")

Design Document Structure:

The design document must contain these sections in order:

1. Summary

Brief overview of what is being ported and why:

## Summary

Porting <feature-name> from <source-location> to <target-project>.

**Source:** <source-path-or-url>
**Target:** This project
**Rationale:** <why this feature is valuable>
**Feature Description:** <what it does>

2. Source Feature

Complete information from Step 2:

## Source Feature

**Location:** <file-paths>
**Language:** <source-language>
**Lines of Code:** <N> (including transitive dependencies)

**Complete Implementation:**

<code blocks showing the entire feature and all non-library dependencies>

**Direct Dependencies:**
- <dependency-1>: <description and type>
- <dependency-2>: <description and type>
- ...

**Transitive Dependency Graph:**

<ASCII tree showing full dependency depth>

**External Dependencies:**
- <lib-1> (version <ver>): <purpose>
- <lib-2> (version <ver>): <purpose>
- ...

3. Convention Mapping Table

Directly embed the convention mapping table from Step 4:

## Convention Mapping

| Aspect | Source | Target | Adaptation | Rationale |
|--------|--------|--------|-----------|-----------|
| Language | <source-lang> | <target-lang> | | |
| Naming | <source-style> | <target-style> | Use target style: <example> | Target codebase uniformly uses <target-style> for consistency |
| Error Handling | <source-error> | <target-error> | Map <source> exceptions to <target> errors | Target uses <pattern> for error handling throughout; aligns with project conventions |
| Async Model | <source-async> | <target-async> | Use target async/await pattern | <reason for async choice> |
| Testing | <source-test> | <target-test> | Target uses <framework> with <mocking> | Aligns with existing test infrastructure and team expertise |
| ... | ... | ... | ... | ... |

Rationale Column: Each row must explain WHY the adaptation is made. This transforms the mapping table from a "what" document to a "what and why" document, making the port a learning experience for anyone reading the design doc.

4. Dependency Mapping Table

Directly embed the dependency mapping table from Step 4, including user decisions from Step 5:

## Dependency Mapping

| Source Dependency | Version | Target Equivalent | Status | User Decision |
|------------------|---------|------------------|--------|---------------|
| <source-dep> | <ver> | <target-equiv> | already-installed | Use as-is |
| <source-dep> | <ver> | <target-equiv> | not-installed | <decision-from-step-5> |
| ... | | | | |

5. Architectural Adaptations

Document all user decisions from Step 5 with rationale:

## Architectural Adaptations

### Adaptation 1: <pattern-name>

**Decision:** <choice-from-step-5>

**Rationale:** <why-this-choice>

**Implementation Plan:** <how-to-implement-the-adaptation>

### Adaptation 2: ...

6. Acceptance Criteria

Generate behavioral equivalence criteria based on the feature's behavior and chunk boundaries:

## Acceptance Criteria

For **all chunks**, the ported feature must:
- [ ] Execute identical inputs through source and target, comparing outputs
- [ ] Produce behaviorally equivalent results (or document acceptable differences with rationale)
- [ ] Include differential tests validating outputs match

For **chunks flagged --rigor critical** (if any):
- [ ] Execute property-based testing (100+ random test cases per property)
- [ ] Document property invariants and their correctness proof
- [ ] Include adversarial test cases specifically designed to stress the adaptation boundaries

Examples of acceptable differences:
- Error message text (behavior is equivalent)
- Internal execution time (within 2x of source, if documented)
- Memory layout (same functional output)

7. Implementation Phases

Create one phase per chunk (or one phase if monolithic).

<!-- START_PHASE_1 -->
### Phase 1: <chunk-name>

**Chunk Description:** <what-this-chunk-does>

**Source Code Reference:**

<complete source code of this chunk>

**Differential Test Requirements:**

Write differential tests that run identical inputs through both source and target implementations, comparing outputs.

**For same-language ports (source and target in same language):**
Use the direct import pattern from Appendix: Differential Testing Patterns → Same-Language Differential Testing Pattern.
- Import both source and target implementations in test file
- Run identical test cases through both
- Assert outputs match (with tolerance for floats)
- See appendix for pytest example and key points

**For cross-language ports (source and target in different languages):**
Use the test vector pattern from Appendix: Differential Testing Patterns → Cross-Language Differential Testing Pattern (Test Vectors).
- Phase 1: Generate test vectors from source (JSON format)
- Phase 2: Validate vectors against target
- Use language-pair bridging strategy from appendix table
- See appendix for Python/JavaScript example and key points

**For all ports:**
Document acceptable differences with rationale using the template from Appendix: Differential Testing Patterns → Acceptable Difference Documentation.
- Every difference must have explicit rationale
- Pre-populate differences approved by user during Step 5
- Mark differences as "Approved by" only after confirmation

**Commit Message Format:**

When implementing this chunk, use:

feat(pollinate):

Ported from: Behavioral equivalence:

**Implementation Notes:**
- <architectural-decision>
- <dependency-swap-details>
- <error-handling-approach>
- <async-pattern-details>

<!-- END_PHASE_1 -->

<!-- START_PHASE_FINAL -->
### Final Verification Phase

After all implementation is complete, run this command to verify behavioral equivalence across the entire ported feature:

\`\`\`bash
/pollinate-verify --source <SOURCE_PATH> --task <beads-epic-id>
\`\`\`

The `/pollinate-verify` skill runs a three-layer verification strategy:
1. **Layer 1: Differential Testing** — Runs all differential test vectors and compares outputs
2. **Layer 2: Adversarial Hardening** — Generates edge-case inputs targeting language-specific divergence points
3. **Layer 3: Standard Verify** — Runs standard project verification (tests, linting, code review)

**Do NOT run standard `/verify`.** Use `/pollinate-verify` instead.

<!-- END_PHASE_FINAL -->

## Additional Considerations

**Source Availability:**

Source code is at: `<SOURCE_PATH>`

Source cloned to `<SOURCE_PATH>`. Do not delete until `/pollinate-verify` completes.

**Cross-Language Porting Considerations** (if applicable):

[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add action "Generated design doc: docs/design-plans/YYYY-MM-DD-pollinate-<feature-slug>.md" -c 90

git add docs/design-plans/YYYY-MM-DD-pollinate-<feature-slug>.md
git commit -m "docs: pollinate design for <feature> from <source>"

# Log outcome with verbatim summary (if deciduous available)
[ "$DECIDUOUS_AVAILABLE" = true ] && deciduous add outcome "Pollination analysis complete: <feature> from <source> mapped to <N> phases with <M> dependencies"

# Update beads epic to done (if beads available)
[ "$BEADS_AVAILABLE" = true ] && bd update <epic-id> --status done

# Add comment with design doc link (if beads available)
[ "$BEADS_AVAILABLE" = true ] && bd comment <epic-id> "Design: docs/design-plans/YYYY-MM-DD-pollinate-<feature-slug>.md"

/workflow-commands:plan @docs/design-plans/YYYY-MM-DD-pollinate-<feature-slug>.md .

/clear

import sys
import pytest

# Import source implementation
sys.path.insert(0, '<SOURCE_PATH>')
from source_module import source_feature

# Import target (ported) implementation
from target_module import target_feature

class TestDifferentialEquivalence:
    """Test that source and target implementations produce identical outputs."""

    def test_basic_case(self):
        """Test basic happy path."""
        input_data = {"key": "value", "count": 42}
        source_result = source_feature(input_data)
        target_result = target_feature(input_data)
        assert source_result == target_result

    def test_edge_case_empty_input(self):
        """Test with empty/minimal input."""
        source_result = source_feature({})
        target_result = target_feature({})
        assert source_result == target_result

    def test_edge_case_large_values(self):
        """Test with large input values."""
        input_data = {"count": 999999999}
        source_result = source_feature(input_data)
        target_result = target_feature(input_data)
        assert source_result == target_result

    def test_float_tolerance(self):
        """Test floating-point outputs with tolerance."""
        input_data = {"value": 3.14159}
        source_result = source_feature(input_data)
        target_result = target_feature(input_data)
        # Use approximate equality for floats
        assert abs(source_result - target_result) < 1e-10

    def test_error_case_invalid_input(self):
        """Test error handling with invalid input."""
        with pytest.raises(ValueError):
            source_feature(None)
        with pytest.raises(ValueError):
            target_feature(None)

# generate_vectors.py
import json
import sys

sys.path.insert(0, '<SOURCE_PATH>')
from source_module import source_feature

def generate_test_vectors():
    """Generate test vectors by running source implementation."""
    vectors = []

    test_cases = [
        {"name": "basic_case", "input": {"key": "value", "count": 42}},
        {"name": "empty_input", "input": {}},
        {"name": "large_values", "input": {"count": 999999999}},
        {"name": "string_data", "input": {"text": "hello world"}},
    ]

    for case in test_cases:
        try:
            output = source_feature(case["input"])
            vectors.append({
                "name": case["name"],
                "input": case["input"],
                "expected_output": output,
                "tolerance": {"float": 1e-10}
            })
        except Exception as e:
            vectors.append({
                "name": case["name"],
                "input": case["input"],
                "expected_error": str(e),
                "error_type": type(e).__name__
            })

    with open("test_vectors.json", "w") as f:
        json.dump({"test_vectors": vectors}, f, indent=2)

    print(f"Generated {len(vectors)} test vectors in test_vectors.json")

if __name__ == "__main__":
    generate_test_vectors()

// validate_vectors.js (Node.js example)
const fs = require("fs");
const targetFeature = require("./target_module").targetFeature;

function validateTestVectors() {
  const data = JSON.parse(fs.readFileSync("test_vectors.json", "utf8"));
  const vectors = data.test_vectors;

  let passed = 0;
  let failed = 0;

  for (const vector of vectors) {
    try {
      const result = targetFeature(vector.input);

      if ("expected_output" in vector) {
        // Compare output
        if (JSON.stringify(result) === JSON.stringify(vector.expected_output)) {
          console.log(`✓ ${vector.name}`);
          passed++;
        } else {
          console.log(`✗ ${vector.name}: output mismatch`);
          console.log(`  Expected: ${JSON.stringify(vector.expected_output)}`);
          console.log(`  Got:      ${JSON.stringify(result)}`);
          failed++;
        }
      }
    } catch (e) {
      if ("expected_error" in vector) {
        console.log(`✓ ${vector.name} (expected error)`);
        passed++;
      } else {
        console.log(`✗ ${vector.name}: unexpected error: ${e.message}`);
        failed++;
      }
    }
  }

  console.log(`\nResults: ${passed} passed, ${failed} failed`);
  process.exit(failed > 0 ? 1 : 0);
}

validateTestVectors();

{
  "test_vectors": [
    {
      "name": "descriptive_case_name",
      "input": { "key": "value", "count": 42 },
      "expected_output": { "result": "computed_value" },
      "tolerance": { "float": 1e-10 }
    },
    {
      "name": "error_case",
      "input": null,
      "expected_error": "ValueError",
      "error_type": "ValueError"
    },
    {
      "name": "large_values",
      "input": { "count": 999999999 },
      "expected_output": { "result": "large_computed_value" },
      "tolerance": {}
    }
  ]
}

## Known Acceptable Differences

| Difference | Source Behavior | Target Behavior | Rationale | Approved By |
|-----------|----------------|-----------------|-----------|------------|
| Float precision | 1e-15 tolerance | 1e-12 tolerance | Target uses f32 for performance; approved as sufficient for use case | User (2026-03-26) |
| Sort stability | Stable sort (guaranteed) | Unstable sort | Rust's default sort is unstable; docs verify correctness unchanged | Architecture review |
| Error message text | "Invalid key: 'foo'" | "Invalid key: foo" | Target omits quotes for brevity; behavior identical | User acceptance |
| Execution time | ~100ms | ~200ms | Cross-language overhead acceptable per requirements | Performance review |
| Memory layout | Pointer-based | Value-based | Internal structure differs; external API identical | Implementation team |