15 KiB
15 KiB
Audit Decision Register
Status
Complete. This document inventories the conclusions of Narratio's three maintainability audit passes and records their final disposition. It is a traceability register, not an implementation plan and not an additional audit.
The source audits are:
- the contract-preserving Maintainability Audit;
- the contract-relaxing Contract Simplification Audit; and
- the Reusable Library Extraction Audit.
The detailed File Operations Simplification roadmap supplies the approved filesystem rationale and policy that refine the audit findings. The consolidated Refactoring Roadmap is the controlling inventory of adopted work for the upcoming refactor.
Dispositions
- Immediate action: approved work included in
refactoring.md. - Constraint: a rule governing immediate work, but not a separate code change by itself.
- Superseded: a later approved decision replaces the earlier recommendation.
- Conditional: reconsider only when a stated future trigger occurs.
- Deferred: deliberately outside the upcoming refactor.
- No action: already satisfied, unsubstantiated, retained as-is, or merely an observation.
An immediate action can also carry a constraint. When findings overlap, the
contract audit controls product semantics, fileops.md resolves the detailed
filesystem policy, and the library audit controls extraction decisions. The
resulting immediate work is consolidated in refactoring.md.
Pass 1 — Contract-Preserving Maintainability Audit
All identifiers in this table refer to sections of audit.md.
| ID | Subject | Final disposition | Controlling decision and destination |
|---|---|---|---|
| H01 | Repository footprint | No action | Size alone was not a defect. |
| H02 | Trusted-environment threat model | Immediate action and constraint | Adopt the trusted, group-owned workspace model in fileops.md; retain secret handling and confined destructive scope. See refactoring.md, Filesystem. |
| H03 | Production-code concentration | No action | Do not split packages merely because they are large. |
| H04 | Production files over 1,000 lines | Immediate action | Decompose only the identified runner, analyze, configuration, publish, and previous-cache seams. See the corresponding refactoring.md workstreams. |
| H05 | Application, stage, and artifact interaction | Constraint | Preserve current package ownership and dependency direction. |
| H06 | Confined filesystem and directory promotion | Immediate action | Replace the broad subsystem under fileops.md; delete custom directory promotion. See Filesystem. |
| H07 | Test code larger than production | Immediate action | Remove tests only with retired contracts, consolidate focused fixtures, and replace mutable app globals as affected code is refactored. See Quality and testability. |
| H08 | Repository tests and vet | Constraint | Keep repository-wide tests and vet as required refactoring validation. |
| H09 | Acyclic package dependencies | Constraint | Preserve the existing acyclic dependency direction; no reorganization is required. |
| H10 | Localized complexity | Constraint | Limit work to audited hotspots and immediate collaborators. |
| H11 | Small dependency surface | Constraint | Add dependencies only where an adopted finding demonstrates net value. |
| H12 | Documentation ownership | Immediate action and constraint | Update canonical owners with each behavior change and avoid parallel narratives. See Quality and documentation. |
| H13 | Coverage by volume | Immediate action | Add risk-focused restore and transition coverage; do not preserve or target a test-line or coverage ratio. |
| H14 | Cohesion of app, stage, and config | Immediate action and constraint | Keep packages intact while introducing private lifecycle, transaction, and validation-domain seams. |
| H15 | Natural modules in large files | Immediate action | Use the audited internal seams for runner, analyze, configuration, publish, and current previous-cache logic. |
| H16 | Duplication in stages and adapters | No action | Do not introduce base-stage or base-adapter abstractions; keep tool contracts local. |
| H17 | Durable versus implementation-coupled tests | Immediate action | Preserve behavior tests, delete mechanism tests for retired contracts, use invocation-scoped dependencies, and improve large structural diffs selectively. |
| H18 | Invariant discoverability | Immediate action | Correct filesystem documentation and restore behavior; retain transaction-order comments near runner and publish ownership. |
| H19 | Go baseline upgrade | Immediate action, revised to Go 1.26 | The audit proposed Go 1.27, but the approved implementation baseline is Go 1.26: it provides os.Process.WithHandle, while os.Root.RemoveAll was already available in Go 1.25. Upgrade the module, CI/release images, module state, and release documentation in one bounded change. See Platform modernization. |
| H20 | os.Root confinement |
Immediate action | Use os.Root only for genuinely root-scoped cleanup and restore; use ordinary filesystem operations elsewhere. See Filesystem. |
| H21 | Narratio-owned durability and policy | Superseded in part; immediate action | fileops.md retains atomic visibility, limits, modes, validated downloads, destructive scope, and secret protection while retiring stronger guarantees. |
| H22 | os.Process.WithHandle |
Immediate action | Adopt after the Go baseline upgrade while preserving Windows Job Object lifecycle. See Platform modernization. |
| H23 | slices and maps |
Immediate opportunistic action | Apply only in touched code where semantics are identical; no bulk rewrite. See Quality and testability. |
| H24 | errgroup for transcription |
Immediate action | Replace the manual worker pool while preserving cancellation, qualified errors, and deterministic aggregation. See Platform modernization. |
| H25 | go-cmp in tests |
Immediate opportunistic action | Use for selected large structural comparisons only. See Quality and testability. |
| H26 | Adopt gofrs/flock |
No action | Retain the small existing platform lock primitives. |
| H27 | Adopt Cobra | Deferred | Reconsider only after demonstrated command/help/flag inheritance costs. |
| H28 | Generic configuration framework | No action | Retain typed strict decoding, composition, defaults, and semantic validation. |
| H29 | Generic atomic-file package | Immediate action with constraint | Keep a small local helper unless focused research finds a maintained dependency that removes more code while meeting platform and mode needs. See Filesystem. |
| H30 | Provider-neutral object storage | No action | The narrow internal storage ports already satisfy the requirement. |
| H31 | Retry or backoff package | No action | Retain the explicit WhisperX policy and provider-owned AWS retries. |
| H32 | UUID or ULID package | No action | Retain the existing readable cryptographically random run ID. |
| H33 | Generic subprocess framework | Superseded in part | The library audit retains the code internally now, requires local mechanism/policy separation, and makes external extraction conditional. See Platform modernization and L01. |
| H34 | executePlan |
Immediate action | Decompose around invocation preparation, collaborator composition, one-stage transition, and finalization while keeping lock and persistence ordering explicit. See Runner lifecycle. |
| H35 | Shared planning/execution transition model | Immediate action | Introduce only the shared pure pre-execution decision and small identical transition helpers. See Runner lifecycle. |
| H36 | analyzeStage.Run |
Superseded in part; immediate action | Contract Finding C03 removes invocation projections. Use a session-only execution accumulator or equivalent private state under the checkpointing model. See Analyze recovery. |
| H37 | executeAnalyzeArtifact |
Immediate action | Split preparation, adapter invocation, validated materialization, and evidence construction under one transaction owner. See Analyze recovery. |
| H38 | config/validate.go |
Superseded in part; immediate action | Split by semantic domain, but C06 removes exact validation order and full prose as compatibility requirements. See Configuration. |
| H39 | validateScriptorium |
Immediate action | Separate declaration/output, dependency/input, and variable validation; retain deterministic semantics without promising diagnostic choreography. |
| H40 | validateNotarius |
Immediate action | Separate reference binding from output-lane normalization and collision checks. |
| H41 | validateAudita |
Immediate mechanical action | Move it with its adapter-validation domain but do not decompose the function. |
| H42 | Composition-envelope splitting | Immediate action | Separate shape decoding, cross-field semantics, and root metadata removal while preserving useful source-aware conflict diagnostics. |
| H43 | previouscache.Resolve |
Superseded | C01 requires complete removal of legacy candidate probing rather than isolation. Simplify the remaining canonical path as part of the compatibility purge. |
| H44 | stage/publish.go |
Immediate action | Decompose internal concerns while retaining one publish transaction; C05 controls the new lock and carry-forward semantics. See Remote publication. |
| H45 | fileops/directory.go |
Immediate action | Delete directory promotion and replace it with validated same-workspace Notarius rename. See Filesystem. |
| H46 | Restore classification | Immediate correctness action | Classify leaf and ancestor symlinks as non-regular conflicts inside a root-scoped restore design. See Filesystem. |
| H47 | Manifest analyze-state validation | No action | Retain the cohesive state-model owner; only trivial clone cleanup is permitted when touched. |
| H48 | Preliminary priority order | Constraint | Use as dependency guidance for implementation planning; it creates no separate deliverable. |
Pass 2 — Contract Simplification Audit
All identifiers in this table refer to findings of
contract-audit.md. These approved decisions control any
conflicting recommendation from the first pass.
| ID | Subject | Final disposition | Destination |
|---|---|---|---|
| C01 | Deprecated compatibility | Immediate action | Purge all named legacy configuration, party/player, remote-state, previous-cache, extraction, analyze, and manifest compatibility paths. See Canonical contracts. |
| C02 | Structured run manifests | Immediate action | Eliminate the run-manifest schema and lifecycle; keep the session manifest as the sole local progress authority. See Manifest authority. |
| C03 | Analyze recovery | Immediate action | Checkpoint each successful artifact in dependency order, retain valid successes across later failure, and resume failed, stale, or missing work. See Analyze recovery. |
| C04 | Cleanup hidden inside publish | Immediate action | Add cleanup as the final idempotent pipeline stage and remove post-publish cleanup obligations. See Cleanup stage. |
| C05 | Shared mutable remote locks | Immediate action | Replace the central/static lock model with per-source remote lock objects and carry prior locked declarations into new commits. See Remote publication. |
| C06 | Configuration diagnostic contracts | Immediate action and constraint | Preserve strict deterministic semantics and useful source-aware errors while retiring exact validation order, wording, punctuation, formatting, and incidental provenance. See Configuration. |
The contract audit also records that the combined work remains eligible for a minor release because the compatibility surfaces were already deprecated and removable. Release execution is outside this refactoring roadmap.
Pass 3 — Reusable Library Extraction Audit
Identifiers refer to library-audit.md. Candidate 5 is
expanded into its separately evaluated helper groups, and the audit's explicit
non-candidates are listed so the register is complete.
| ID | Candidate | Final disposition | Controlling decision and destination |
|---|---|---|---|
| L01 | Cross-platform subprocess supervision | Conditional extraction; immediate internal cleanup | Keep internal until a real second consumer, overlapping multi-platform contract, alternative review, clean API, and maintainer exist. Separate process mechanism from Narratio policy locally and remove unrelated file writers. See Platform modernization. |
| L02 | Hardened FileOps | Immediate simplification; no extraction | Follow fileops.md; version control preserves reusable algorithms without making Narratio consume rejected guarantees. |
| L03 | YAML composition and provenance | No extraction | Keep Narratio's configuration DSL internal. Dependency evaluation for low-level node mechanics is distinct and not required now. |
| L04 | Immutable remote commit protocol | No extraction | Keep the domain protocol internal; evaluate established content-addressed specifications only if interoperable cross-application snapshots become a real requirement. |
| L05a | Path-safety helpers | No extraction; opportunistic local action | Keep small and internal; use standard-library path primitives only where semantics match exactly. |
| L05b | Bounded I/O and streaming redaction | No extraction | Retain adapter limits, secret policy, and errors in Narratio. |
| L05c | Atomic file replacement | No extraction; immediate local action | Use the small local or established implementation selected under H29 and fileops.md. |
| L05d | Object-store ports, file locks, IDs, and DAG helpers | No extraction | Keep the narrow ports and domain algorithms internal. |
| L06 | Release automation | No action | Keep repository-local; reconsider a standalone tool or template only after materially identical scripts drift across repositories. |
| L07 | Artifact source and destination policy | No extraction | Domain ownership is the source of its value. |
| L08 | Manifest and durable state validation | No extraction | Keep state schemas and validation with Narratio. |
| L09 | Stage ordering, selection, invalidation, resume, and force | No extraction | Keep pipeline lifecycle semantics with Narratio. |
| L10 | Analyze checkpoint and dependency recovery | No extraction | Implement C03 as Narratio domain behavior. |
| L11 | Cleanup and remote lock policy | No extraction | Implement C04 and C05 as Narratio operational policy. |
| L12 | External tool and storage adapters | No extraction | Keep integration-specific requests, validation, and errors local. |
| L13 | Configuration validation, party resolution, and artifact-family expansion | No extraction | Keep product configuration rules internal. |
Completeness and Routing Summary
Every audited hypothesis or candidate is represented above. Only entries marked
Immediate action or Immediate opportunistic action produce scope in
refactoring.md. Constraints govern that work without
creating independent implementation tasks. Superseded, conditional, deferred,
and no-action entries remain here for traceability and are intentionally absent
from the actionable roadmap except where a boundary must be stated to prevent
scope creep.
The consolidation adds no hypothesis or feature that was not identified by an
audit. A future implementation plan should derive its stages from
refactoring.md, use this register to verify completeness, and return to the
source audits only when it needs the supporting analysis behind a decision.