[EPIC][expert] Write / edit / create expert: symbolic target resolution, typed changes, preimage safety, and model fallback #415

New issue

Open

opened 2026-09-08 01:29:21 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 01:29:21 +00:00

Owner

Parent: #376
Depends on: #377, #380
Integrates with: #379, #382, #355, #93/#99 freshness

Goal

Add the canonical Write Expert responsible for reasoning about and producing typed edit/2 and create/2 actions while preserving exact target/preimage identity, source knowledge freshness, Frozen Spec obligations and canonical authority/effect semantics.

The Write Expert owns the reasoning and payload-production layer. It does not receive ambient filesystem authority and it does not bypass the existing write/effect boundary.

This preserves #355 / D6-11:

edit/2   -> Write Expert reasoning -> typed edit action -> canonical write/effect path
create/2 -> Write Expert reasoning -> typed create action -> canonical write/effect path

delete/1 -> plan-native deterministic op, NOT Write Expert
index/1  -> plan-native deterministic op, NOT Write Expert
run/1    -> plan-native deterministic op, NOT Write Expert

Responsibilities

consume exact Frozen Spec obligations relevant to the requested change;
ask Project Knowledge Expert for current symbol/source/span/provenance data;
ask Git Expert for current worktree/head/preimage constraints where relevant;
determine the smallest safe change set;
prefer deterministic structural transforms when a transformation is mechanically derivable;
construct typed edit/create payloads as inert data;
attach expected source hash/generation/preimage to mutations;
validate target confinement/schema before effect admission;
after admitted writes, trigger/require source freshness update through existing source-update/index mechanisms;
return changed-artifact evidence for Verify/Review;
never self-certify that the change satisfies the SPEC.

Deterministic-first editing

Use symbolic/structural transforms where possible, for example:

exact replacement bound to a source span/hash;
rename driven by symbol/reference facts;
add/remove normalized import/reference where language adapter can express it safely;
constrained config/data updates;
AST/CST-aware transformations when a validated generic adapter exists;
template expansion with closed typed slots.

These paths use zero model calls.

Model fallback

For genuinely generative code/text changes that cannot be derived mechanically, the expert may explicitly invoke a model fallback.

The fallback receives bounded relevant context/spec/evidence and returns candidate typed change data, not authority and not trusted code execution.

Required path:

symbolic edit reasoning cannot produce sufficient payload
  -> explicit fallback(reason)
  -> model call (metered normally)
  -> candidate edit/create payload
  -> schema/target/preimage validation
  -> canonical effect admission
  -> observe actual result

Only the model call is metered. The Write Expert invocation itself remains free.

Preimage / concurrent-change safety

Every mutation should bind to expected current state where possible:

file identity
source generation
content hash / expected preimage
source span / symbol ref when applicable
repository head/worktree evidence when applicable

If authoritative bytes/state changed after planning, return a structured stale/conflict outcome and re-resolve/replan rather than clobber.

Multi-file writes

Support a typed change set with explicit dependencies and atomicity/partial-failure semantics appropriate to the existing effect/tool layer.

Do not publish a supposedly current Project KB from half-completed intermediate state. Compose with #219/#99 dirty/coalescing/freshness work.

Cooperation

Project Knowledge Expert resolves targets and impact.
Git Expert supplies repository/preimage state.
Planner Expert defines change goals/dependencies.
Verify Expert independently verifies resulting state.
Repair Expert may request a revised change after verification failure.
Review Expert inspects the resulting diff/evidence adversarially.

Acceptance

Deterministic span-bound edit fixture completes with zero model calls.
Symbol rename fixture updates all required references using current project facts without a model where the adapter supports it.
edit/2 and create/2 route to Write Expert through #377/#379.
delete/1, run/1, index/1, sync_remote/1 cannot route to Write Expert.
Stale expected hash/preimage rejects before mutation.
Capability/authority denial rejects before underlying write dispatch.
Expert registration/selection never grants write authority.
Successful write produces observable result and causes source knowledge to become dirty/refreshed before current verification.
Multi-file partial failure cannot masquerade as complete success.
Explicit model fallback is traceable/metered, and its candidate output must pass the same schema/preimage checks as deterministic output.
Model output cannot widen capabilities or select arbitrary filesystem targets outside validated project scope.
Write Expert never marks the Frozen Spec satisfied itself.

Non-goals

No ambient filesystem access in expert logic.
No delete/run/index/sync implementation here.
No self-verification or Frozen Spec mutation.
No concrete AgentProlog product filesystem tool implementation in core.

Refs #376 #377 #379 #380 #382 #355 #93 #99 #141

Parent: #376 Depends on: #377, #380 Integrates with: #379, #382, #355, #93/#99 freshness ## Goal Add the canonical **Write Expert** responsible for reasoning about and producing typed `edit/2` and `create/2` actions while preserving exact target/preimage identity, source knowledge freshness, Frozen Spec obligations and canonical authority/effect semantics. The Write Expert owns the **reasoning and payload-production layer**. It does not receive ambient filesystem authority and it does not bypass the existing write/effect boundary. This preserves #355 / D6-11: ```text edit/2 -> Write Expert reasoning -> typed edit action -> canonical write/effect path create/2 -> Write Expert reasoning -> typed create action -> canonical write/effect path delete/1 -> plan-native deterministic op, NOT Write Expert index/1 -> plan-native deterministic op, NOT Write Expert run/1 -> plan-native deterministic op, NOT Write Expert ``` ## Responsibilities - consume exact Frozen Spec obligations relevant to the requested change; - ask Project Knowledge Expert for current symbol/source/span/provenance data; - ask Git Expert for current worktree/head/preimage constraints where relevant; - determine the smallest safe change set; - prefer deterministic structural transforms when a transformation is mechanically derivable; - construct typed edit/create payloads as inert data; - attach expected source hash/generation/preimage to mutations; - validate target confinement/schema before effect admission; - after admitted writes, trigger/require source freshness update through existing source-update/index mechanisms; - return changed-artifact evidence for Verify/Review; - never self-certify that the change satisfies the SPEC. ## Deterministic-first editing Use symbolic/structural transforms where possible, for example: - exact replacement bound to a source span/hash; - rename driven by symbol/reference facts; - add/remove normalized import/reference where language adapter can express it safely; - constrained config/data updates; - AST/CST-aware transformations when a validated generic adapter exists; - template expansion with closed typed slots. These paths use zero model calls. ## Model fallback For genuinely generative code/text changes that cannot be derived mechanically, the expert may explicitly invoke a model fallback. The fallback receives bounded relevant context/spec/evidence and returns **candidate typed change data**, not authority and not trusted code execution. Required path: ```text symbolic edit reasoning cannot produce sufficient payload -> explicit fallback(reason) -> model call (metered normally) -> candidate edit/create payload -> schema/target/preimage validation -> canonical effect admission -> observe actual result ``` Only the model call is metered. The Write Expert invocation itself remains free. ## Preimage / concurrent-change safety Every mutation should bind to expected current state where possible: ```text file identity source generation content hash / expected preimage source span / symbol ref when applicable repository head/worktree evidence when applicable ``` If authoritative bytes/state changed after planning, return a structured stale/conflict outcome and re-resolve/replan rather than clobber. ## Multi-file writes Support a typed change set with explicit dependencies and atomicity/partial-failure semantics appropriate to the existing effect/tool layer. Do not publish a supposedly current Project KB from half-completed intermediate state. Compose with #219/#99 dirty/coalescing/freshness work. ## Cooperation - **Project Knowledge Expert** resolves targets and impact. - **Git Expert** supplies repository/preimage state. - **Planner Expert** defines change goals/dependencies. - **Verify Expert** independently verifies resulting state. - **Repair Expert** may request a revised change after verification failure. - **Review Expert** inspects the resulting diff/evidence adversarially. ## Acceptance - [ ] Deterministic span-bound edit fixture completes with zero model calls. - [ ] Symbol rename fixture updates all required references using current project facts without a model where the adapter supports it. - [ ] `edit/2` and `create/2` route to Write Expert through #377/#379. - [ ] `delete/1`, `run/1`, `index/1`, `sync_remote/1` cannot route to Write Expert. - [ ] Stale expected hash/preimage rejects before mutation. - [ ] Capability/authority denial rejects before underlying write dispatch. - [ ] Expert registration/selection never grants write authority. - [ ] Successful write produces observable result and causes source knowledge to become dirty/refreshed before current verification. - [ ] Multi-file partial failure cannot masquerade as complete success. - [ ] Explicit model fallback is traceable/metered, and its candidate output must pass the same schema/preimage checks as deterministic output. - [ ] Model output cannot widen capabilities or select arbitrary filesystem targets outside validated project scope. - [ ] Write Expert never marks the Frozen Spec satisfied itself. ## Non-goals - No ambient filesystem access in expert logic. - No delete/run/index/sync implementation here. - No self-verification or Frozen Spec mutation. - No concrete AgentProlog product filesystem tool implementation in core. Refs #376 #377 #379 #380 #382 #355 #93 #99 #141