Media, revisions, observability, and administration

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

The phase narrative below is dated. Actual opt-in native inspection/transformation, quarantine and idle-worker monitoring now exist, with Q03 scanner hardening. See native operations and scanner guide. Broad hostile video, production feed, outer escaped-child, selected-host and human qualification remain open.

Current supplemental implementation (2026-10-19): see the native operations guide for the new strict video inspector, FFmpeg processor, process-group runner, private quarantine/ClamAV adapter and independent idle-worker watchdog. Their local native tests now run in an explicitly approved finite Docker profile; this supersedes the older absence statements below only for that tested scope. They remain opt-in and do not qualify deployment or original release gates.

Native/scanner disablement and manual handling records actual missing versions/sandbox proof, private retention/quarantine limitations and denied/failed/unknown outcomes. No optional native processing or scanner is enabled by the documentation.

Phase 7 adds reusable mechanics without supplying application records, public routes, native media executables, telemetry accounts, alert recipients, or an enabled administration area. Every subsystem is opt-in and explicitly composed by the consuming application.

Current Major stabilization (2026-10-17): see the disabled media qualification profile and scanner contract/actual accessibility limits. The ffprobe adapter now canonicalizes local input and separates it from switches while restricting protocols to local files. Six local media tests and seven actual-PHP-upload/scanner-contract tests pass; no real FFmpeg, ffprobe, antivirus or durable quarantine qualification is claimed.

Media ownership and flow

src/Media/ separates four responsibilities:

• MediaTypeDetector performs a bounded signature check for MP4, QuickTime, and WebM containers.
• MediaProbe returns normalized metadata through a replaceable adapter. FfprobeMediaProbe accepts a configured absolute executable, passes an argument vector to MediaToolRunner without a shell, limits time/output, discards raw stderr, and parses only selected JSON fields.
• MediaPolicy applies exact MIME/codec allowlists and byte, dimension, duration, and audio requirements. Missing metadata fails closed when a corresponding bound is configured.
• MediaIntakeService persists an accepted/rejected MediaRecord through an application-selected store. MediaLifecycleService moves accepted work forward with optimistic revisions and opaque derivative references.

Source filesystem paths are never persisted in MediaRecord; applications provide an opaque sourceReference. Oversized input is rejected before a probe is invoked. Detection/probe disagreement is an error rather than a fallback. UnavailableMediaProbe and UnavailableMediaProcessor are safe defaults, while fakes permit deterministic application tests.

NativeMediaToolRunner is an infrastructure boundary, not a claim that an executable is installed, patched, sandboxed, or safe for hostile input. The application/deployment must configure a canonical absolute path and apply OS resource controls. No real FFmpeg/ffprobe/ImageMagick run occurred during this phase. Native probe/transcode behavior, hostile fixtures, decompression bombs, process isolation, antivirus/content scanning, output validation, and shared durable media stores remain TO VERIFY.

Revision history

src/Revision/ supplies application-neutral snapshot history:

• Revision validates a bounded JSON-compatible payload and links canonical SHA-256 checksums to the previous revision;
• RevisionStore requires atomic append against an expected current version;
• InMemoryRevisionStore is for tests/examples;
• FileRevisionStore uses private per-aggregate locks and atomic replacement for a single host, and verifies the complete chain whenever it reads;
• RevisionDiffer returns added/removed/changed JSON-pointer paths, never the underlying values;
• RevisionManager::restore() appends old content as a new revision instead of deleting or rewriting history.

Applications own authorization, payload classification, schema evolution, transactions with the canonical aggregate, retention, audit, and user-facing conflict handling. A revision history is not a security/business audit ledger. Multi-node/database stores must preserve compare-and-append atomically and are not included.

Observability boundaries

src/Observability/ keeps diagnostic data bounded before it crosses an adapter:

• MetricPoint permits counters, gauges, and durations with a maximum of ten pre-enumerated low-cardinality labels; identity/request/path/URL labels are rejected;
• ErrorGrouper derives its digest from throwable class plus stable component and operation codes, while excluding messages, traces, arguments, bodies, and secret-bearing context keys;
• HealthRegistry freezes after first use and aggregates the existing HealthCheck contract into separate liveness/readiness reports; thrown details become health.exception;
• AlertManager applies bounded process-local cooldown deduplication before a validated alert reaches an AlertSink.

The included in-memory sinks are deterministic test/local-diagnostic adapters. They are neither durable nor shared. A production application must choose its metrics/error/alert backends, retention, access, sampling, cardinality budget, delivery/retry policy, and shared deduplication. Synchronous health checks cannot be preempted by the registry, so each check must enforce its own timeout and remain non-destructive.

Optional administration starter

src/Administration/ provides a frozen registry and presentation model, not an administrative runtime. Every AdminRoute always declares authentication and an application ability. Mutation declarations are rejected unless they require both recent authentication and CSRF, and mutations cannot be emitted as navigation links. An approval threshold can be declared for application service enforcement.

The accessible native-PHP example is skeleton/resources/views/admin/index.php. It is intentionally absent from the route file and bootstrap. Before an application enables it, the application must enforce authentication, ability/object authorization, recent authentication, CSRF, approvals, transaction ownership, and audit at their real middleware/service boundaries. Registry metadata is reviewable configuration; it does not perform any of those checks.

Local verification and limits

Deterministic tests cover strict probe parsing through a fake runner, media policy/lifecycle conflict behavior, revision append/reload/tamper/conflict and restore, safe metric/error/health/alert behavior, admin security declarations, escaping, accessibility landmarks, and default route absence.

Still TO VERIFY:

• final stable PHP >=8.5.11 <8.6.0 hosted execution for any deliberately enabled native adapters (local CLI fakes are not native-tool proof);
• native media tools against malformed and hostile fixtures under OS limits;
• database/shared media and revision stores under concurrent writers;
• real metrics, error, and alert backends plus delivery failure behavior;
• browser/assistive-technology accessibility automation for an application that deliberately enables the administration starter.

Editorial provenance

Source: docs/MEDIA_REVISIONS_AND_OBSERVABILITY.md. Source SHA-256: 59630229a5d78dcc10085ab222c4d7fcec54cd5aa6a9b30a13923e3ed0e60870.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.