# citum-migrate

`citum-migrate` is a standalone, best-effort migration tool and library for
turning a CSL 1.0 style (`.csl`) into a Citum style (`.yaml`). It is separate
from the primary `citum` CLI.

The migration pipeline is now output-driven first:

1. Extract global options from CSL XML.
   - Includes processing/disambiguation extraction and citation-sort mapping.
   - Emits citation/bibliography contributor overrides when et-al thresholds differ by scope.
2. Resolve citation and bibliography templates from inferred output artifacts.
3. Fall back to XML template compilation only when template artifacts are missing or rejected.

This keeps option extraction deterministic while scaling template migration to large style corpora.

When the target style is already known in the repo as a profile or journal
wrapper, `citum-migrate` now derives that lineage from current repo truth and
may emit `extends:`-based wrapper output instead of flattening everything into a
standalone style. Unknown or unresolved styles still fall back to standalone
output.

Migration output is now planned explicitly. The default CLI still writes one
style document to stdout, but lineage analysis classifies the target as either a
standalone style or an existing wrapper over a checked-in parent. Future
embedded-root workflows must opt into multi-artifact output and prove the
resolved public wrapper matches the intended effective style before writing the
hidden root plus wrapper pair. See
`docs/specs/EMBEDDED_ROOT_WRAPPER_MIGRATION.md`.

## CLI Usage

```bash
citum-migrate [STYLE.csl] [options]
```

Example:

```bash
citum-migrate styles-legacy/apa.csl > styles/apa.yaml
```

Run `citum-migrate --help` for the full option reference.

## Options

- `--template-source auto|hand|inferred|xml`
- `--live-infer-backend auto|embedded|node`
- `--template-dir <path>`
- `--min-template-confidence <0.0..1.0>`
- `--debug-variable <name>`
- `--emit-evidence <path>`
- `--family-candidate off|auto|<style-id>`
- `--minimize-wrapper`

### `--template-source`

- `auto` (default): hand-authored → inferred cache/live → XML fallback
- `hand`: hand-authored only → XML fallback
- `inferred`: inferred cache only → XML fallback
- `xml`: XML templates only

`inferred` mode is cache-only and never runs live Node/citeproc-js inference.

### `--live-infer-backend`

- `auto` (default): embedded JS runtime first, then Node subprocess fallback
- `embedded`: embedded JS runtime only
- `node`: legacy Node subprocess only

This flag only applies when `--template-source auto` needs live inference after
cache lookup. Cache hits still win first.

### `--emit-evidence`

Write a machine-readable migration evidence JSON sidecar to the given path.
Useful for auditing template selection decisions and compression outcomes.

### `--family-candidate`

Controls whether a discovered parent style is promoted into the lineage:

- Omitted (default): preserve standalone output; no promotion attempted.
- `off`: explicitly disable promotion even if a candidate is available.
- `auto`: promote whatever the lineage resolver discovered via reverse
  template-link scan.
- `<style-id>`: force the given canonical ID as the family-candidate parent.

### `--minimize-wrapper`

When `--family-candidate` promotes a parent, emit only the minimal wrapper
form (`info:` + `extends:`) instead of the full diff. Used by the
evidence-driven compression harness to derive output-driven minima.

### What "hand-authored" means

In this README, `hand-authored` means a checked-in Citum style YAML file created
manually (human or agent-assisted), not generated by `citum-migrate` or
`infer-template.js`.

Path convention:

- `examples/<style-name>-style.yaml`

`citum-migrate` reads citation and bibliography templates from that file when
available. Resolution is section-level:

- if the hand-authored file contains only bibliography template data, citation
  can still come from inferred cache (or XML fallback)
- if it contains both sections, both are used

## Template Resolution Order

In `auto` mode:

1. `examples/<style-name>-style.yaml` (hand-authored template sections)
2. `templates/inferred/<style-name>.bibliography.json`
3. `templates/inferred/<style-name>.citation.json`
4. Legacy cache compatibility: `templates/inferred/<style-name>.json` (bibliography)
5. Live inference via embedded JS runtime (auto mode default)
6. Live inference via `scripts/infer-template.js` Node fallback (auto mode only)
7. XML template compiler fallback

## Embedded Runtime Bundle

The embedded runtime bundle is committed at:

- `crates/citum-migrate/js/embedded-template-runtime.js`

Regenerate it after changing the host-neutral inference core or citeproc bundle:

```bash
node scripts/build-embedded-template-runtime.js
```

## Precompile Once, Migrate in Rust

For large-scale migration, precompute inferred templates once, then run Rust migrations without citeproc-js:

```bash
# 1) Precompute inferred template cache for all parent styles
./scripts/batch-infer.sh

# 2) Or precompute selected styles
./scripts/batch-infer.sh --styles "apa elsevier-harvard ieee"

# 3) Migrate using cache-only inferred mode (no live Node inference)
citum-migrate styles-legacy/apa.csl --template-source inferred
```

## Cache Artifact Format

Section-keyed cache files:

- `templates/inferred/STYLE_NAME.bibliography.json`
- `templates/inferred/STYLE_NAME.citation.json`

Each file is produced by:

```bash
node scripts/infer-template.js styles-legacy/STYLE_NAME.csl --section=bibliography --fragment
node scripts/infer-template.js styles-legacy/STYLE_NAME.csl --section=citation --fragment
```

Fragment shape:

```json
{
  "meta": {
    "style": "apa",
    "confidence": 0.85,
    "delimiter": ". ",
    "entrySuffix": ".",
    "wrap": "parentheses"
  },
  "bibliography": {
    "template": []
  }
}
```

`citation` artifacts use the same shape with a `citation` section key.

## Confidence Gate

`--min-template-confidence` rejects inferred fragments below threshold before use.

Example:

```bash
citum-migrate styles-legacy/apa.csl \
  --template-source auto \
  --min-template-confidence 0.80
```

When rejected, migration falls back to XML template compilation for that section.

## Fidelity Expectations

`citum-migrate` does not guarantee perfect output equivalence for every legacy
style without review. Current expectations:

- Inferred templates are primarily used to raise bibliography fidelity.
- Citation fidelity is protected by guardrails and section-level XML fallback.
- Note styles can still require manual review/tuning more often than
  author-date and numeric styles.

Use oracle validation for style-level acceptance:

```bash
node scripts/oracle.js styles-legacy/your-style.csl --json
```

## Notes

- Output is written to stdout; redirect to a file as needed.
- Options extraction remains XML-based by design.
- Template inference is output-driven to avoid procedural CSL template translation bottlenecks.
