Skip to main content

ICW-E6S07T111-Specification: FR-078 Comprehensive Install Event-Contract Logging Quality

Task: E6:S07:T111
Related FR: FR-078
Host Task: T111-comprehensive-install-event-contract-logging-and-feedback-quality.md
Created: 2026-04-09

Executive Summary​

Define a strict install event contract so every install step and sub-step can be reconstructed as intent -> action -> result, with deterministic correlation and redaction-safe payloads suitable for high-quality forensic analysis.

Problem Statement​

Current install logging is helpful but mostly run/phase oriented, which can leave ambiguity around why decisions were made, what exact operation executed, and what concrete outcome followed. This limits root-cause precision and slows quality hardening.

T111 addresses this by defining contract-level telemetry completeness and deterministic event linkage.

Scope​

In scope:

  • Event schema and invariants for intent, action, and result.
  • Step/sub-step completeness across CLI and framework-specific installers.
  • Deterministic correlation fields and timeline reconstruction rules.
  • Failure-boundary behavior (partial failure still emits complete prior history).
  • Redaction and secret-safety constraints.
  • Backward-compatible coexistence with current text logging behavior.

Out of scope:

  • Transport/submission path policy and workflow governance.
  • Maintainer ingestion endpoints and submission lifecycle operations.
  • User-account identity and external trust/auth flows.

Functional Invariants​

  1. Triad completeness invariant
    Each emitted step event must include structured intent, action, and result sections (required fields enforced by schema/tests).

  2. Deterministic correlation invariant
    Events must include stable correlation keys (install_run_id, step_id, parent/child relation) so multi-component runs can be reconstructed deterministically.

  3. Coverage invariant
    All major install phases and required sub-steps in CLI + framework installers must emit contract-compliant events.

  4. Decision transparency invariant
    Branch and decision points (mode/backend/fallback/retry/skip) must be represented with explicit rationale fields.

  5. Outcome normalization invariant
    result must normalize status, exit code, duration, validation outcomes, and error class for comparable analysis.

  6. Failure-boundary invariant
    On step failure, historical events remain complete up to boundary; terminal event must encode failure state and boundary metadata.

  7. Redaction invariant
    Known secret-bearing fields and error text paths must pass redaction checks prior to persistence.

Ordering Contract (Instrumentation Rollout)​

  1. Define canonical schema + required fields.
  2. Add emitter adapters in CLI install orchestrator.
  3. Extend framework installer hooks to emit compatible events.
  4. Add validators/tests for required field completeness and joinability.
  5. Reconcile docs and examples with finalized contract.

This order prevents partial adoption from creating schema drift.

Requirement Mapping (T111 AC)​

  • AC1: Every step/sub-step reconstructable as intent -> action -> result.
  • AC2: Correlation metadata enables deterministic timeline reconstruction.
  • AC3: Missing mandatory fields are blocked by tests/validators.
  • AC4: Result payloads are normalized and comparable.
  • AC5: Local artifacts contain enough detail for reproduction and triage.
  • AC6: Redaction constraints validated by tests.

Non-Functional Constraints​

  • Performance: Contract logging overhead must remain bounded and monitored.
  • Compatibility: Existing text logs remain supported during migration.
  • Operability: Diagnostics remain concise and actionable.
  • Determinism: Identical runs under same inputs should produce structurally consistent event graphs.

Edge Cases and Boundaries​

  • Installer emits nested sub-steps without explicit parent linkage.
  • Retry loops produce duplicate semantic steps with different attempts.
  • Fallback path triggers after backend or validation failure.
  • Framework script logs without full context unless adapter bridges are present.
  • Unexpected stderr includes sensitive fragments requiring redaction.

Boundary policy:

  • Prefer explicit event representation over inferred reconstruction.
  • Fail fast on schema-required-field absence in test mode.
  • Never persist raw secret-bearing payloads.

Acceptance Assertions​

  • Planning artifact defines explicit, testable checks for all ACs.
  • Scope boundary with submission/governance workstream (FR-079/T112) is explicit.
  • Host task and planning artifacts are bidirectionally aligned for implementation handoff.