115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# Phase 0.9B observer result contract
|
|
|
|
Status: **HOST CONTRACT ONLY — NO TARGET IMPLEMENTATION**.
|
|
|
|
This contract defines how a future observer result would be represented after
|
|
startup, exit and output gates are separately proven. It does not establish
|
|
those capabilities and does not authorize transfer or execution.
|
|
|
|
## Framing
|
|
|
|
The preferred representation is bounded JSON Lines because every entry can be
|
|
validated independently and a final entry can mark truncation or failure.
|
|
Whether JSON Lines is feasible without unacceptable target dependencies
|
|
remains unproven.
|
|
|
|
Every future entry must contain:
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"observer_build_id": "offline-bound identifier",
|
|
"observation_id": "unique bounded identifier",
|
|
"category": "firmware",
|
|
"source": "exact source identity",
|
|
"raw_value": null,
|
|
"raw_error": "UNSUPPORTED_OR_UNPROVEN",
|
|
"normalized_value": null,
|
|
"confidence": "UNPROVEN",
|
|
"persistent_mutation_performed": false,
|
|
"retry_performed": false,
|
|
"monotonic_offset_ms": null,
|
|
"truncation": false,
|
|
"fail_closed": true
|
|
}
|
|
```
|
|
|
|
Allowed confidence values are `OBSERVED`, `PARTIAL`, `UNSUPPORTED`,
|
|
`UNPROVEN`, `CONFLICT`, and `ERROR`.
|
|
|
|
`raw_value` and `raw_error` are mutually exclusive. A normalized value may be
|
|
present only when it cannot hide a raw discrepancy. The raw values from two
|
|
firmware sources are always returned separately.
|
|
|
|
## Fixed limits
|
|
|
|
No target constants are selected while the build is blocked. A future
|
|
observation plan must bind all of these to finite positive values:
|
|
|
|
- maximum complete output bytes;
|
|
- maximum entry bytes;
|
|
- maximum path bytes;
|
|
- maximum observations;
|
|
- maximum objects;
|
|
- maximum processes;
|
|
- maximum services;
|
|
- maximum listeners;
|
|
- maximum errors; and
|
|
- maximum monotonic runtime.
|
|
|
|
An exceeded limit produces one final bounded error when the output channel
|
|
still works, sets `truncation=true` and `fail_closed=true`, performs no retry,
|
|
and exits through the proven termination path.
|
|
|
|
## Per-category rules
|
|
|
|
| Category | Success evidence | Required failure form |
|
|
|---|---|---|
|
|
| observer identity | offline manifest identity repeated unchanged | `UNPROVEN` if runtime self-binding is not available |
|
|
| firmware | two separately sourced raw values and exact comparison | `UNPROVEN` for a missing source; `CONFLICT` for mismatch |
|
|
| mount | only fields with exact ABI evidence | `UNSUPPORTED` for unproven layouts or semantics |
|
|
| object metadata | literal authorized path, no-follow open, stable pre/post same-object metadata | explicit symlink, path, object-ID or size error |
|
|
| SHA-256 | exact planned size, complete bounded read, stable post-read object | short read, read error, drift or hash mismatch |
|
|
| rollback object | same rules plus a distinct available identity from live | backup missing or same-object conflict |
|
|
| processes/services | bounded read-only snapshot with exact structures | `UNSUPPORTED` when service mapping is incomplete |
|
|
| listeners | bounded read-only snapshot with exact owner mapping | `UNSUPPORTED` when API or ownership is unproven |
|
|
| autoload | minimal fields from complete authoritative sources | missing source, parse error or incomplete-source `UNPROVEN` |
|
|
|
|
No file content unrelated to the minimal autoload/retry decision may be
|
|
returned. Secrets and full configuration contents are excluded.
|
|
|
|
## Filesystem contract
|
|
|
|
A future target may read an object only when its compiled and audited path is:
|
|
|
|
```text
|
|
authorized literal path
|
|
-> open read-only + no-follow + close-on-exec
|
|
-> fstat same descriptor
|
|
-> validate regular object and planned size
|
|
-> one bounded read stream
|
|
-> fstat same descriptor
|
|
-> compare identity and size
|
|
-> no-follow path metadata comparison
|
|
-> close
|
|
```
|
|
|
|
If no-follow is not source- and artifact-proven, the result is
|
|
`PATH_SYMLINK_SAFETY_UNPROVEN` and the object is not hashed. No path is
|
|
hardcoded by Phase 0.9B. The default observation plan contains no paths.
|
|
|
|
Reads may affect atime, caches, audit records, counters or scheduling. Those
|
|
volatile or unknown effects must be reported; this contract does not call them
|
|
absent and does not authorize persistent writes.
|
|
|
|
## Terminal behavior
|
|
|
|
Every future path, including output failure, deadline, unsupported query,
|
|
parse error, read error, limit exhaustion and conflict, must reach the proven
|
|
termination path. No retry, sleep-and-retry, callback, background thread,
|
|
listener, process signal, service action or subprocess may occur.
|
|
|
|
The host-only model in `tests/phase09b_observer_model.py` exercises these
|
|
contract decisions without filesystem or network I/O. It is a guardrail, not
|
|
PS5 code or hardware evidence.
|