interface import: scaffold an interface block from a bound object

[scottypate]

Resolves #18. Stacked on #19 — base is virtual-cells-binding-model, not main. Review that one first.

The change to what was asked for

#18 asked for imported types and descriptions. This emits types only.

Copying warehouse prose into cell.yaml is the rot the issue complains about. Automating the copy makes rot cheap rather than fixing it. The asymmetry that matters:

• Types are safe to copy — verify checks them against the warehouse on every run, so divergence is caught.
• Descriptions are not — no check exists, so a copy goes stale silently.

The warehouse's prose already rides observed.source_descriptions (shipped in #19), live and unrottable. An author writes a local description: only when they mean something different from the warehouse — which is authorship, not transcription.

Usage

datamk interface import -p prod --bind gold_customer --as qfai_customer

  - name: qfai_customer
    version: 1.0.0
    bind: gold_customer
    # description:                 # what ONE ROW means — yours to write
    grain: []                      # columns that make a row unique
    schema:
      customer_id: string
      credits_balance: decimal
      credits_history:
        type: unmapped             # no datamk name for STRUCT(...) —
                                   # choose one, or drop the column
    contract: experimental

stdout by default; --write splices into the interface: block by byte range rather than round-tripping through serde_yaml, which would destroy the teaching comments. Refuses an existing entry without --force. YAML to stdout, everything else to stderr, so piping is safe.

Decisions worth review

• type: unmapped rather than dropping the column. verify only checks that declared columns exist, so a dropped column ships as a silent hole in the contract. unmapped fails the existing type check, so it cannot ship by accident.
• No unit: inference. No warehouse carries it, and guessing USD from a column name is the failure that field exists to prevent.
• grain: [] and no export description. Both are judgment, not transcription.
• contract: supported now means the meaning is available — a local description or one on the bound source — rather than restated locally, which would force the copy back in. Note the consequence: an export can claim supported on the strength of prose that lives entirely upstream, so the ratchet's guarantee now depends on a comment nobody in this repo controls.

Verification

657 tests, 0 failures. fmt and clippy clean at -D warnings.

The inverse type mappings are siblings of the existing forward predicates, never edits to them — each pinned by an offline round-trip test asserting every declared name they emit satisfies the forward check. Unmappable types (STRUCT, ARRAY, GEOGRAPHY, BLOB) have explicit coverage. All default CI, no credentials.

🤖 Generated with Claude Code