Skip to content

feat(dtogen): generate MutableClone for DTO-backed views - #2795

Merged
jbeda merged 1 commit into
mainfrom
impl/dto-view-mutable-clone
Nov 16, 2026
Merged

jbeda merged 1 commit into
mainfrom
impl/dto-view-mutable-clone

Conversation

@jbeda

@jbeda jbeda commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Generate concrete MutableClone() methods for DTO-backed views whose explicitly declared DTO owner selects clone; delegate detachment to the existing DTO Clone() method.
  • Preserve zero values, optional/present-empty data, exact payloads, selected-subtree copying, and the boundary between DTO identity and private enclosing view scope.
  • Roll out to existing session and fixture views. Replace the DTO-exporting RecordView.Format() with MutableClone() and migrate callers; keep schema-label Format() accessors.
  • Document the contract and generation requirements; refresh generated artifacts and API snapshots.

This supplies a prerequisite for #2793. It does not implement or close that PR's instruction-contract follow-ups, import its modelrequest/UserContextPrefix types, rename instructions, change contribution slots/provenance, or add the resume example or production integration.

Verification

  • Executable generator fixtures: capability/closure selection, handwritten overrides, collisions, bootstrap/freshness/artifact protections, nested detachment, optional containers, repeated clones, context-bearing views, and leaf-only allocation.
  • Session Submit/Load tests: retained content, independent clones, scope boundary, selected-subtree copying, borrowed navigation, and zero views.
  • task test
  • task lint
  • task test:race
  • task docs
  • task generate:data:check
  • task api:check
  • go run ./cmd/mecademo (tool call, permission ask/approval, and final result)

Independent Spec, Standards, Test adequacy, Architecture, Library reuse, and Duplication reviews completed. The test reviewer found two important assertion gaps; both were fixed and independently rechecked. No open findings.

API compatibility

No wire or stored-data changes; no wire major/feature identifier changes or upgrade sequencing required. Generated methods are additive Go APIs. Removing RecordView.Format() is an explicitly operator-approved Go source break within the isolated kernel experiment: callers use MutableClone() instead. RecordView retains its handwritten materialized-record implementation; DTO-backed views use generated methods. No production entry points change.

Implementation plan

Approved plan, including the Format-export amendment.

Generate MutableClone for views backed by an explicitly declared Clone owner, retaining zero, payload ownership, and enclosing-scope boundaries. Roll out existing views and replace the legacy RecordView.Format export with MutableClone.

Co-authored-by: Mecatl <noreply@mecatl.dev>
@jbeda

jbeda commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Approved implementation plan

  • Slug: dto-view-mutable-clone
  • Source: .scratch/dto-view-mutable-clone/plan.md (local provenance, not a remote link)
  • Branch: impl/dto-view-mutable-clone
  • Baseline: refs/heads/main at 67bd65151d7850fa11bd77f030f30429c89962b8
  • Updated: 2026-11-16T00:12:57Z
  • Plan SHA-256: 5dbe12d7682567feda7f178506324e89771dcfb42b6a7ad72dfb7abdeabe7e71
  • Amendment: the operator explicitly added removal and caller migration of DTO-exporting Format methods. This supersedes the original request to keep handwritten exports unchanged.

Generated DTO view mutable clones

Scope and contract

Implement concrete view.MutableClone() operations on current main, independently of PR #2793, in /home/jbeda/src/mecatl-2. Do not modify, switch, reset, or otherwise disturb /home/jbeda/src/mecatl-4 or its parked PR.

  • Return the concrete backing DTO, deeply detached through its owner's existing Clone() capability.
  • A zero view returns a zero DTO without invoking Clone.
  • Preserve optional presence, present-empty values, ordering, exact bytes, and all DTO payload fields, including fields omitted from view getters.
  • Copy only the selected subtree, never unrelated enclosing/sibling payloads.
  • Export DTO payload and DTO identity fields, not the private enclosing scope or identity retained by the view. Existing scope/authoring validation remains authoritative.
  • Mutating one result cannot affect views, snapshots, or other clones. Borrowed getters and leaf Copy retain their contracts.
  • Keep operations concrete; introduce neither a generic mutable-view interface nor mutable retained aliases.

Generation policy

Generate MutableClone automatically for selected view handles whose backing DTO belongs to an explicit owner declaration's named closure and whose owner selects clone, including existing declared handwritten overrides. Other views remain inspection-only. A method named Clone alone never establishes ownership. Do not add a new flag or select additional owner capabilities implicitly.

Supply the same explicit owner metadata to load-only bootstrap and final generation. Preserve per-module GOWORK=off, no owner execution, deterministic artifacts, closure rendering and typechecking before installation, and marked regular-file protections. Reject collisions with handwritten view methods/fields and untagged DTO getters.

Approved amendment: replace DTO export Format

Remove existing view Format methods that export detached DTOs and migrate their callers to MutableClone. Current main has one: RecordView.Format. Keep its implementation handwritten because it owns materialized-record backing rather than the generator's value *DTO layout; do not restructure backing just to generate it. Rename the matching fixture-record helper and migrate tests. Retain OpaqueProviderDataView.Format() string, which reads a schema label rather than exporting a DTO.

Tasks and intended verification

  1. Implement generator eligibility, method emission, and bootstrap support with executable fixture tests.
  2. Roll out applicable existing views through task generate:data, migrate the approved Format export/callers, and refresh API snapshots through task api:update.
  3. Document ownership, zero behavior, scope boundary, and generation requirements in the generator guide and generated comments.
  4. Test zero views; nested mutable slices/pointers/maps/bytes; optional and present-empty storage; exact retained content and independent clones; selected-subtree allocation; context-bearing views; unchanged borrowed navigation/leaf copying; capability selection/collisions; bootstrap and artifact protections. Execute generated output, not only source-text assertions. Exercise Submit and storage-backed Load.
  5. Run focused generator/runtime checks, generation/API freshness, task test, task lint, task test:race, task docs, and the offline demo. Full test outer timeout: 1800 seconds. Other full gates: 600 seconds.
  6. Independently review Spec, Standards, Test adequacy, and applicable Domain axes against fixed point 67bd65151d7850fa11bd77f030f30429c89962b8; fix concrete findings and recheck affected tests/review scopes.
  7. Commit with Co-authored-by: Mecatl <noreply@mecatl.dev>, push impl/dto-view-mutable-clone, and open a separate PR. Do not merge.

Exclusions and compatibility

Exclude #2793's modelrequest/UserContextPrefix types, RootInstructions/UserInstructions renames, InstructionBlock contribution slots/provenance, session-resume example, production integration, session cloning, and unrelated refactors. This PR supplies a prerequisite for #2793; it does not implement or close its instruction-contract follow-ups.

API compatibility: no wire or stored-data changes, hence no wire major/feature change or upgrade sequencing. Generated methods are additive Go APIs. Removing RecordView.Format is an explicitly approved Go source break within the isolated kernel experiment; callers migrate to MutableClone. No experimental-kernel changelog bookkeeping is required.

No unresolved design decisions. Gate results and review outcomes are reported separately from these verification intentions.

@jbeda
jbeda enabled auto-merge (squash) November 16, 2026 00:29
@jbeda
jbeda merged commit 89a9f42 into main Nov 16, 2026
46 checks passed
@jbeda
jbeda deleted the impl/dto-view-mutable-clone branch November 16, 2026 00:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant