porting-extract

name	porting-extract
description	Phase 2 extraction skill for library porting. Use when user wants to extract the API surface from an original library, create conformance packet fixtures, or write oracle scripts. This is the most critical phase - it establishes the behavioral contract that the port must match.

Library Porting - Phase 2: Extract

The most critical phase. Establishes the behavioral contract through oracle testing.

Purpose

Extract behavioral essence from original library through oracle testing:

• Run original library with known inputs
• Capture outputs as JSON fixtures
• Document edge cases and invariants
• Never read or copy source code

Workflow

Step 1: Write Oracle Script

The oracle is a Python script that runs operations on the original library and returns results:

#!/usr/bin/env python3
# oracle/your_lib_oracle.py
import json
import sys

# Example for pandas:
import pandas as pd

while line := sys.stdin.readline():
    req = json.loads(line)
    op = req["operation"]
    inputs = req["inputs"]
    
    if op == "series_add":
        left = pd.Series(inputs["left"]["values"], index=inputs["left"]["index"])
        right = pd.Series(inputs["right"]["values"], index=inputs["right"]["index"])
        result = left.add(right)
        print(json.dumps({
            "status": "ok",
            "result": {
                "index": result.index.tolist(),
                "values": result.values.tolist()
            }
        }))

Step 2: Test Oracle

# Test oracle with sample input
echo '{"operation": "series_add", "inputs": {"left": {"index": ["a","b"], "values": [1,2]}, "right": {"index": ["a","b"], "values": [3,4]}}}' | python3 oracle/your_lib_oracle.py

Step 3: Generate Fixtures

Use scripts/update_conformance_template.py or create manually:

# Generate fixtures for an operation
python3 scripts/update_conformance_template.py --operation series_add --mode strict

# Or create manually - fixture format:
cat > fixtures/packets/myproj_p2c_001_basic_strict.json << 'EOF'
{
  "packet_id": "MYPROJ-P2C-001",
  "case_id": "series_add_basic",
  "mode": "strict",
  "operation": "series_add",
  "left": {
    "index": [{"kind": "utf8", "value": "a"}, {"kind": "utf8", "value": "b"}],
    "values": [{"kind": "int64", "value": 1}, {"kind": "int64", "value": 2}]
  },
  "right": {
    "index": [{"kind": "utf8", "value": "a"}, {"kind": "utf8", "value": "b"}],
    "values": [{"kind": "int64", "value": 3}, {"kind": "int64", "value": 4}]
  },
  "expected_series": {
    "index": [{"kind": "utf8", "value": "a"}, {"kind": "utf8", "value": "b"}],
    "values": [{"kind": "int64", "value": 4}, {"kind": "int64", "value": 6}]
  }
}
EOF

Step 4: Extract ALL Operations

For each operation family, enumerate all methods:

# List all public methods of pandas
python3 -c "
import pandas as pd
methods = [m for m in dir(pd) if not m.startswith('_')]
for m in methods:
    print(m)
"

Operation Families to Extract

Family	Examples
arithmetic	add, sub, mul, div, mod, pow
comparison	eq, ne, lt, gt, le, ge
aggregation	sum, mean, std, var, min, max
indexing	getitem, setitem, where, mask
alignment	align, reindex, fillna
groupby	groupby, transform, aggregate
io	read_csv, to_csv, read_json, to_json
datetime	to_datetime, strftime, resample

Edge Cases to Document

For each operation, test:

• Empty inputs (empty series, empty dataframe)
• NaN propagation (NaN + number = NaN)
• Null/None handling
• dtype coercion (int + float = float)
• Index misalignment
• Duplicate labels
• Shape mismatches
• Type mismatches

Fixture Naming

{project}_{phase}{component}_{sequence}_{case_id}_{mode}.json

Example: myproj_p2c_001_duplicate_labels_strict.json
- myproj: project prefix
- p2c: Phase 2C (Conformance)
- 001: Sequence number
- duplicate_labels: Case identifier
- strict: Mode (strict or hardened)

Output

After Phase 2:

• 1000+ conformance packet fixtures in fixtures/packets/
• Oracle script that runs original library
• Edge case documentation
• Invariants and failure modes catalogued