# Metadata Exporter Spec

## Purpose

Downstream environments already carry real business metadata and real drift.
Applying a newly built final pack directly onto that live state can fail for
reasons that are hard to inspect from pack sources alone.

This exporter gives us a comparison baseline:

```text
live DB metadata -> exported pack snapshot -> diff vs final pack
```

## First milestone

Implement a Python exporter that emits a directory shaped like:

```text
<output>/
  metadata/
    _System_Object.json
    _System_Field.json
    _System_RecordType.json
    _System_ValidationRule.json
    _System_PageLayout.json
    _System_Permission.json
    _System_ObjectFieldMapping.json
    _System_ReportType.json
    _System_Relationship.json
    FlowDefinition.json
```

The first milestone does not need final-pack fidelity.
It needs:

1. deterministic output
2. valid JSON
3. stable file paths
4. enough shape to support meaningful metadata diffing

## Input model

Use one explicit DB connection input:

1. `--dsn`

Format:

```text
mysql://user:pass@tcp(host:port)/db?tls=true
```

The first version may also support env fallback later, but the CLI should keep
the DB input explicit.

## Data ownership

The exporter is intended to read metadata-layer state, not business rows.

Target layers:

1. installed object/field metadata
2. record types
3. validation rules
4. list-field defaults
5. related-list defaults
6. permission metadata
7. layout / flow metadata later

Do not export:

1. end-user record data
2. logs
3. runtime cache rows
4. deploy-state noise

## Canonicalization rules

Every JSON file should be emitted with:

1. UTF-8
2. trailing newline
3. `indent=2`
4. `sort_keys=True` where key order is not semantically constrained

Lists should be sorted deterministically by business key whenever possible.

## Transport rule

The exporter implementation should be Python.
If the current environment has no Python MySQL driver, it may call the system
`mysql` or `mariadb` client via Python `subprocess`, but the export logic must
remain Python-owned.

## Incremental roadmap

1. v1: ✓
   - tool skeleton
   - deterministic output directory
   - raw metadata-table export
2. v2: ✓
   - map exported raw metadata into component-shaped files (`--mode pack`)
   - outputs object specs plus record types / validation / permissions / report types / layouts
3. v3: ✓
   - add `compare.py` for pack diff helpers
   - supports `--left` and `--right` export directories
   - outputs text or JSON diff report
4. v4:
   - add optional component-specific transforms
   - expand flow coverage from `FlowDefinition` projection to full `FlowVersion` payload when needed
5. later:
   - evaluate whether a generic form belongs upstream