Local AI Toolkit

Responsibility map for incremental changes

Русская версия

This completes the boundary review in #624, against 78b7da480634313ff97b96b0eb1fbe5ecd32aecc. The six files below remain production entry points. Their length is not a reason to move code. A further extraction needs a concrete behavior change, a named caller and a test of the observable guarantee it must preserve.

Current ownership and small-change boundaries

Entry point Responsibilities now Boundary for a small change
InstallerWizardViewModel Page/selection state, review and consent, dispatch of installation/recovery actions, progress and recorded results. Keep UI state and consent in the wizard. Finish/recovery wording already consumes immutable facts through InstallerRunMessages. A new execution coordinator is justified only when an actual run/recovery change needs it; pass the approved plan and return events/results, rather than giving presentation authority to execute effects.
CodeSearchSyncCommand Repository gate, base/worktree planning, semantics then corpus embedding, progress, drift checks, publication and cleanup. Keep one orchestration owner and gate lifetime. Planning identifies a specific tree; phase execution produces artifacts for that identity; publication validates and exposes completed artifacts. WorktreeGenerationPublications already owns the epoch-bound early pointer. Move a phase only with a concrete change requiring that seam.
DurableQueue Admission/deduplication and sequence allocation, durable state and leases, validated request payloads, recovery, archive/quarantine and retention. Metadata, payload validation and retention are distinct responsibilities inside one mutex transaction. The request cache is scoped to the current mutex lease. A helper must receive that scope or validated values; it must not acquire an independent lock or cache payloads across operations. State-only polling must remain state-only.
BrokerModelInstaller Trusted request snapshot, signed catalog validation, active-version lease, launcher commands, status/pull/preflight protocol validation, progress and accurate partial outcomes. Existing trust/active-version/process interfaces are seams, not public trust bypasses. A new protocol field may justify a narrow parser/validator; it must return facts to the batch owner, which retains trust lifetime, cancellation and the distinction between attempted, completed and indeterminate effects.
InstallationLayoutLease Protected Windows layout acquisition, retained directory/file handles and identity/ACL evidence, version temporaries/publication, launcher backup/retention and owned cleanup. No additional extraction is selected. For a concrete publication/backup defect, isolate only the affected operation while the lease keeps its handles and evidence alive. A helper must not replace handle-relative operations with a path check followed by an unprotected operation.
IndexBuilder File partition/reuse, symbol-aware chunking, base/overlay assembly, broker embedding batches, checkpoint resume, adaptive limits, backend recovery and build progress. No additional extraction is selected. A measured assembly, retry or checkpoint defect may justify one private plan/phase helper. Preserve hashes, chunker identity, model/dimension/context and ordering in its inputs. Writing an index does not grant that helper authority to publish the repository generation.

The last two decisions are deliberately conditional: #624 does not authorize a standalone rewrite of security or indexing code. There is no new abstraction without a consumer, persistent queue cache, storage migration or public API change in this documentation change.

Responsibility Owning issue and delivered change What stays with that owner
Installer execution versus result presentation #615, PR #671 The wizard supplies recorded facts; re-rendering after a language change does not execute installation or rewrite the journal. Cancellation/effect truth remains #589, with outcome presentation in #604.
Sync planning, phases and publication #620, PR #676 Requested-worktree readiness and full maintenance are separate outcomes. Old global readers remain valid until all required worktrees are prepared. Do not create a duplicate sync refactor task.
Queue metadata, payload and retention #621, PR #677 Reuse is bounded to one mutex lease; the next operation validates disk payloads again. Retention remains in the same serialization boundary. The measured improvement does not require splitting the entire class.
Index/query performance #619 Query-vector identity, timing and retrieval quality remain that issue’s work. Do not move IndexBuilder as a substitute for measuring the query path.

This map closes the coordination work in #624. It neither reopens completed issues nor declares the remaining performance or live installer acceptance work complete.

Guarantees to preserve

Installer and model execution. Consent precedes effects. Journal/result facts determine what completed, failed or remains unknown; formatting cannot change those facts or rollback eligibility. The model batch keeps verified package, launcher and active-version evidence throughout execution, matches catalog/model/context in command responses, preflights installed models and never silently relaxes residency. Existing guards include wizard tests and model installer tests.

Sync and indexing. The repository gate precedes shared-state writes and owns the whole publication transaction. Semantics and corpus must describe the same generation/tree/dirty state. A changed worktree cannot publish stale artifacts; an early worktree pointer is valid only for its recorded global-pointer epoch. Cancellation/failure must preserve readable published generations and completed checkpoints. Keep base/overlay model dimensions, chunker identity and normalization consistent, including unchanged-file reuse. Existing guards include active publication, pointer epochs and retention, embedding resume, backend recovery and adaptive batching.

Queue. A shared mutex protects sequencing, deduplication, request/state consistency, lease transitions and recovery. Validated payloads do not outlive that lease, including exceptional exits. A same-length/backdated replacement must be checked on the next operation; invalid records are quarantined. Preserve durable JSON contracts and archive/retention semantics. QueueRequestSnapshotTests checks these cache boundaries; the retained measurement and real-process contention probe covers the measured change.

Protected installation layout. Keep canonical identity, ACL/reparse validation and retained handle lifetime coupled to the operation. Revalidate before committing/publishing; rollback/cleanup removes only owned changes. A path string is not a substitute for retained evidence. Package installer tests include unsafe-existing-ACL refusal without mutation; shared-root tests cover permitted existing layout state. These are regression anchors, not proof of every possible filesystem race.

Acceptance of the next small PR

  1. Name the issue, caller and observable scenario requiring the boundary. Keep one responsibility change per PR and preserve the existing entry point unless the issue requires a contract change.
  2. For changed behavior, reproduce the failure first. For an extraction, retain existing observable tests and add a test only for an uncovered guarantee. Do not test a new helper merely because it exists, or assert a machine-speed threshold.
  3. Carry lock/lease lifetime, cancellation, ownership and publication authority across the boundary explicitly. Preserve JSON contracts and untrusted-content markers. Compare results on the existing corpus before accepting an optimization.
  4. Run the full solution before opening the PR: dotnet test LocalAi.slnx --configuration Release --max-parallel-test-modules 1 --timeout 20m. Record totals and reasons for skips. Unit/fixture checks do not establish live DPI, accessibility or installation acceptance.

For this map, implementation and test anchors were checked against the cited baseline. No production code or tests were changed. The PR records the full-suite result and verifies local document links. No model-performance or cloud-token-savings claim is made.