[FLO-OBS-01] Define the suite observability, privacy, and stream contract

[szmyty]

Parent: #14
Suite roadmap: #11

Outcome

Define the normative observability profile shared by flow, aniflow, optiflow, and renderflow before adding more instrumentation or choosing a shared package.

The profile must make operational logs, metrics, traces, progress, typed diagnostics, versioned command results, and durable run evidence visibly distinct while giving participating processes a consistent correlation vocabulary.

Scope

• Inventory current logging, progress, diagnostics, stdout/stderr, configuration, and run/evidence behavior in all four repositories at pinned revisions.
• Define canonical signal purposes:
  • logs for bounded operational detail;
  • metrics for aggregate health and performance;
  • traces/spans for causal and latency relationships;
  • progress events for user-visible lifecycle;
  • typed results/diagnostics for automation;
  • durable manifests/evidence for accepted state.
• Define standard resource and correlation fields, including product, version, command, operation, run, stage, provider, capability, artifact role, validation, outcome, and duration.
• Classify fields as stable, provisional, local-only, exportable, sensitive, high-cardinality, or prohibited.
• Define stable event naming, severity mapping, span hierarchy, metric names/units, histogram guidance, attribute budgets, sampling expectations, and clock semantics.
• Define human, JSON Lines, file, and OpenTelemetry projections without turning human formatting into a public contract.
• Define CLI/configuration precedence for verbosity, filters, format, color, sinks, and export. Environment-based configuration must be documented and must not leak into deterministic identity.
• Specify stdout/stderr ownership for human and machine modes, including parse errors, help/version, progress, panics, and exporter diagnostics.
• Specify redaction at source plus defense-in-depth filtering for secrets, environment values, authorization material, source content, prompts, captions, argv, and paths.
• Define offline/no-export default behavior, explicit opt-in, retention expectations, and failure behavior for unavailable collectors.
• Define which OpenTelemetry semantic conventions are adopted, extended, or deliberately avoided.
• Define cross-process context propagation boundaries and the allowlist required before trace context reaches a child process.
• Document how telemetry correlates with but never establishes domain evidence, validation, completion, provenance, or checkpoint reuse.
• Evaluate ADR impact. Create a proposed ADR only where the profile introduces a durable suite decision not already governed by accepted architecture.

Required artifacts

• Suite observability profile and signal-boundary documentation.
• Event/span/metric/attribute registry with privacy and cardinality classifications.
• CLI/configuration behavior matrix.
• stdout/stderr mode matrix.
• Redaction and data-handling threat model.
• OpenTelemetry mapping and propagation proposal.
• Conformance test plan reusable by later issues.
• Current-state inventory with exact repository revisions and known gaps.

Acceptance criteria

• Every signal has one named purpose and cannot be mistaken for authoritative run evidence.
• Machine stdout remains one versioned command result with no logs, progress, color, or banner.
• Library callers retain control of subscribers/exporters.
• Default operation performs no telemetry network access.
• Prohibited fields and high-cardinality metric labels are explicit and testable.
• Trace context cannot reach arbitrary configured providers implicitly.
• Exporter failure, buffering, flush, shutdown, and backpressure semantics are defined.
• Deterministic plans, cache keys, provider locks, compatibility fingerprints, and artifact digests exclude all telemetry-only state.
• Human/non-interactive/accessibility behavior is specified without relying on color or decoration.
• The proposed conformance matrix covers human, JSON, redirected, non-TTY, no-color, offline, collector-unavailable, and cancellation paths.
• Architecture and terminology agree across the suite documents this issue changes.

Explicit non-goals

• Selecting or creating a shared crate/repository.
• Instrumenting production code.
• Enabling export.
• Defining a hosted backend.
• Replacing existing holon result, diagnostic, event, or evidence schemas.
• Recording media or other user content.
• CLI branding artwork.

Roadmap-Track: FLO-OBS