feat(karta): consumer Workload interface with shape-blind pod mutation

[AviadHayumi]

implements #341 - the consumer front door, designed so it cannot corrupt any definition in the shipped catalog.

what this adds

pkg/karta - one small interface:

w, _ := karta.New(definition, obj)      // eager validation: definition, gvk, suspend actions
wt, _ := w.Tree(ctx)                    // read everything (depth-first Instances() iterator added)

err = w.UpdatePodTemplate(ctx, "worker", karta.PodPatch{   // typed, compile safe
    SchedulerName: ptr.To("kai-scheduler"),
})
err = w.UpdatePodTemplate(ctx, "worker", karta.Patch{      // raw, any routable field
    "spec": map[string]any{"tolerations": []any{map[string]any{"key": "gpu", "operator": "Exists"}}},
})

w.Components()                          // per component: writable pod fields, suspendable
obj, _ = w.Object()                     // deep copy, ready to apply

the mutation design

• one verb, two doors: UpdatePodTemplate takes a PodTemplateUpdate - the typed PodPatch or a raw Patch map. the typed patch compiles into the raw form, so ONE router serves both and the typed fields cannot drift from what the engine routes.
• the raw patch is validated against a partial corev1.PodTemplateSpec - k8s itself is the schema, a typo like spec.labels fails before anything runs. metadata is restricted to labels and annotations in v1.
• merge rules: maps merge, scalars replace, lists replace as a whole - except spec.containers, which merges by container name. one unnamed containers entry means the sole container, and on fragmented shapes it routes image and resources to their own definition paths. null never deletes in v1, every offending path listed at once.
• a field is writable only when its jq path can be assigned directly. the catalog sweep: 283 paths, 232 writable; the 51 rejected are exactly the read-only projections and formulas (NIMCache's {requests: ...}, KServe's select-pipe containerPath, every // 1). those return a typed unsupported error before any jq runs.
• each set field becomes an individual jq leaf assignment, so unknown sibling fields survive and definitions where podSpecPath and metadataPath point at the same object (KServe's transformer) are safe by construction.
• WithInstances validates every physical route against instanceIdPath, so per-instance targeting works on any shape whose paths iterate with the ids - fragmented included.
• mutations run on a deep copy kept only on full success - on any error the object is unchanged.
• capability errors carry logical view paths (spec.tolerations, metadata.labels) in one *UnsupportedFieldsError, classifiable with errors.Is(err, karta.ErrNotSupported).
• scale stays read-only in v1: replicasPath in the catalog carries formulas and literals. extension path documented in add a small karta.Workload interface - one clear front door for consumers #341.

how it is verified

• a catalog conformance gate walks every definition in docs/catalog: every writable field applied to a synthetic object built from the definition's own paths, with canaries proving only the named leaves changed.
• a parity spec replays every recorded real-cluster state (test/e2e/recorded_data) through both eras: extraction byte-identical everywhere; mutation changed zero unintended leaves. the old typed path destroyed core Pod recordings outright (whole-object replacement, status lost) - recorded in the spec as evidence.
• make check green, 32 specs, lint 0 issues.

performance

measured on a 1MB workload: one typed field 8.5ms, ten raw scalar fields 1.4ms. the engine skips the defensive json round-trip when data is already json-primitive (NewPrimitiveRunner). numbers canonicalize to float64 (documented on Object()); integers above 2^53 are not supported - pre-existing engine behavior, now stated.

the jq engine moves under internal/ (breaking, deliberate)

pkg/jq -> internal/jq. leaving the evaluator importable lets a consumer bypass every capability check the front door enforces. with internal/ the compiler owns the boundary: consumers get pkg/karta (and pkg/resource as the power api), nothing else compiles. all in-repo importers moved; nested modules under github.com/run-ai/karta/ still build (go's internal rule is prefix based). external pkg/jq importers break at compile time - that is the point, shout if anyone depends on it today.

also

• pkg/karta/kartatest: a recording fake that validates every update through karta.ValidatePodTemplateUpdate - the exact code path production runs, so the fake cannot drift from it.
• tree.Instances(): depth-first (component, instance) iterator.
• the quickstart consumes the front door end to end on JobSet and LeaderWorkerSet.
• read-side normalization (PodView) is deferred: normalized PodView: shape-blind pod reads to match the shape-blind mutation api #344.

size: +1598 logic, +1141 tests, +16 docs (the internal/ move is rename-detected, ~0).