# Fulpack Test Fixtures

This directory contains reproducible test fixtures for the fulpack archive module. All fixtures are script-generated to ensure consistency across implementations (gofulmen, pyfulmen, tsfulmen).

## Fixture Inventory

| Fixture               | Size      | Purpose                                   | Format |
| --------------------- | --------- | ----------------------------------------- | ------ |
| `basic.tar`           | 21.5 KB   | Uncompressed tar with binary+text content | tar    |
| `basic.tar.gz`        | 847 bytes | Compressed tar archive                    | tar.gz |
| `nested.zip`          | 3.4 KB    | 3-level directory nesting                 | zip    |
| `pathological.tar.gz` | 1.3 KB    | Security test cases (malicious paths)     | tar.gz |

## Documentation

Each fixture has a corresponding `.txt` file documenting:

- **Purpose**: What the fixture tests
- **Structure**: File/directory layout
- **Expected Behavior**: Pass/fail conditions for operations
- **Test Coverage**: Specific scenarios enabled

**Examples**:

- `basic.tar.txt` - Documents the `basic.tar` fixture
- `pathological.tar.gz.txt` - Documents the `pathological.tar.gz` fixture

## Generation

All fixtures are generated by `scripts/generate-fulpack-fixtures.ts` to ensure:

- **Reproducibility**: Anyone can regenerate identical fixtures
- **Size Governance**: Programmatic enforcement of limits
- **Fresh Content**: No coupling between fixtures
- **Cross-Language Parity**: Synced to Python/TypeScript wrappers

**Regenerate all fixtures**:

```bash
bun run scripts/generate-fulpack-fixtures.ts
```

**Regenerate specific fixture**:

```bash
bun run scripts/generate-fulpack-fixtures.ts --fixture basic.tar
```

## Size Governance

Fixtures must stay small to avoid bloating the repository:

- **Compressed archives** (tar.gz, zip, gzip): ≤10 KB
- **Uncompressed tar**: ≤25 KB (tar has 512-byte block padding overhead)
- **Pathological/security fixtures**: ≤50 KB

The generator enforces these limits programmatically and will fail if exceeded.

## Fixture Details

### basic.tar (21.5 KB)

**Purpose**: Test uncompressed tar format with binary and text data.

**Contents**:

- `README.md` - Text file (~600 bytes)
- `config.json` - Text file (~100 bytes)
- `metadata.txt` - Text file (~120 bytes)
- `data/sample.txt` - Text file (~100 bytes)
- `data/tiny.png` - Binary file (~100 bytes, PNG-like blob)

**Tests**:

- Tar format operations (create, extract, scan)
- `compression_ratio = 1.0` (no compression)
- Binary data integrity
- Fastest operations (no compression overhead)

**Rationale**: Crucible v0.2.12 added `ArchiveFormat.TAR` as fourth standard format. This fixture enables testing tar-specific behavior distinct from tar.gz.

---

### basic.tar.gz (847 bytes)

**Purpose**: Test standard compressed tar archive operations.

**Contents**: Same 5-file structure as basic.tar, but compressed.

**Tests**:

- Standard tar.gz operations
- Compression ratio (~3:1 for text)
- Directory nesting (subdir/)

---

### nested.zip (3.4 KB)

**Purpose**: Test deep directory nesting and path handling.

**Contents**:

```
root.txt
level1/
  file1.txt
  level2/
    file2.txt
    level3/
      file3.txt
      deep.txt
```

**Tests**:

- 3-level directory nesting
- Zip format operations
- Path normalization

---

### pathological.tar.gz (1.3 KB)

**Purpose**: Test security protections against malicious archives.

**Contents** (simulated security test cases):

- Path traversal: `../../../etc/passwd`
- Absolute paths: `/etc/passwd`, `/root/.ssh/id_rsa`
- Symlink escapes targeting outside bounds

**Expected Behavior**:

- `scan()`: MUST list all entries (including malicious paths, per standard)
- `verify()`: MUST return `valid=false` with `PATH_TRAVERSAL` and `ABSOLUTE_PATH` errors
- `extract()`: MUST fail with security errors before writing files
- Telemetry: `fulpack.security.violations_total` metric incremented

**⚠️ Note**: This fixture contains simulated malicious content for testing purposes only.

## Cross-Language Parity

These fixtures are synced to language wrappers via `make sync-to-lang`:

- **gofulmen**: Embeds from root `config/` (no sync needed)
- **pyfulmen**: `lang/python/config/library/fulpack/fixtures/`
- **tsfulmen**: `lang/typescript/config/library/fulpack/fixtures/`

All implementations must produce identical results when processing these fixtures.

## References

- **Fulpack Specification**: `docs/standards/library/modules/fulpack.md`
- **Generator Script**: `scripts/generate-fulpack-fixtures.ts`
- **Crucible v0.2.12**: Added tar format support
- **Crucible v0.2.13**: Added fixture generator and documentation
