Prioritize convenient debug representations

This commit is contained in:
2026-11-19 19:07:57 +00:00
parent 5618adea8e
commit d9e1d1e4a7

View File

@@ -647,10 +647,11 @@ retains the bookkeeping boundary; U9 still owns concrete durable record choices.
**Discussion / decision:** Controls, native capture hooks, lifecycle, failure
policy, and optional diagnostics agreed. Use `--debug` for native verbosity and
durable capture with `/tmp/notarius-debug` as the default root. Operator-owned
data handling and recording each fact once are agreed. Replace the summary/trace
hierarchy with a compact run index, configuration/composition snapshots, and
operation records; maintain a `latest` symlink at the debug root. Capture depth
and concrete serialized fields remain under discussion. Implementation is pending.
data handling and convenient diagnostic representation are agreed. Replace the
summary/trace hierarchy with a compact run index, configuration and composition
snapshots, and operation records; maintain a `latest` symlink at the debug root. Convenience
guides capture depth; the precise inventory and serialized fields remain under
discussion. Implementation is pending.
### Shared Debug Control With Conditional Capture
@@ -712,8 +713,9 @@ copied execution summaries, synthetic call identities, and duplicate terminal
reporting. Keep callbacks lightweight and synchronize shared capture state:
callbacks are synchronous, can overlap across operations, and `OnPrepared` runs
while admission is held. Retain needed details and persist them at normal
operation boundaries rather than buffering an entire pipeline or repeatedly
writing every accumulated conversation prefix.
operation boundaries without requiring an entire pipeline's content in memory.
Native snapshots may repeat conversation prefixes when that is the convenient
representation; do not introduce a custom delta format merely to remove them.
Capture only available evidence. Preparation/admission failures may have no
`OnPrepared` notification; observer events have metadata, not response bodies;
@@ -806,9 +808,17 @@ status zero alone does not establish that a check passed.
### Selected Bundle Organization
**Agreed principle:** Record each fact once and reference it where needed. Use
shared application outcome facts and native execution evidence rather than
parallel summary/trace accounting or repeated snapshots.
**Guiding principle:** Capture the most convenient debug representation. Optimize
for straightforward capture and useful inspection, rather than maximum
conciseness, completeness, or deduplication. Native values, complete snapshots,
and self-contained operation records are appropriate even when fields or content
repeat.
"Record each fact once and reference it where needed" remains a practical
guideline for avoiding independently maintained decisions and accounting, not a
strict storage constraint. Use shared application outcome facts and native
execution evidence. Repeating that evidence in useful representations does not
require another source of truth or justify custom compression/reconstruction.
Organize the bundle around the run and its operations, replacing `summary/` and
`trace/` as separate categories. Use a compact overview for navigation and keep
@@ -838,28 +848,30 @@ exact serialized fields remain implementation choices:
| Resolved pipeline | Describe selected steps, lanes, modules, validators, and reference relationships. |
| Operation records | Connect diagnostic evidence with its stage, chunk, lane, or validator. |
The overview is an index rather than a second execution ledger. Its terminal
facts come from the same application outcome used for the CLI report, and it
references detailed records instead of duplicating requests, responses, findings,
or error history. Capture configuration and resolved composition once when
available. Use native execution IDs with application scope to connect records.
The overview provides navigation, with terminal facts drawn from the same
application outcome used for the CLI report. Reference detailed records where
useful; include convenient summary fields without maintaining a second execution
ledger. Configuration and resolved composition normally need one snapshot each.
Use native execution IDs with application scope to connect records.
Reused work has a checkpoint/reuse decision and reference, not a fabricated model
execution.
Retain enough available context to investigate a run that fails before publishing
output. Do not depend entirely on a successful output manifest or automatically
copy every original input and published artifact. Select a conversation
representation that avoids repeatedly saving the complete accumulated history
after each turn or maintaining an independent competing transcript.
copy every original input and published artifact. Prefer the native conversation
representation when convenient, including complete per-turn snapshots if those
are easier to capture and inspect. Do not build a competing transcript model or
deduplication system to eliminate repeated history.
### Open Discussion: Capture Depth
The organization is selected; precise evidence and granularity remain open:
The organization and emphasis on convenience are selected; precise evidence
and granularity remain open. Capture readily available, useful evidence without
making exhaustive reconstruction or every provider attempt a prerequisite:
- Which prepared request details, outputs, intermediate artifacts, validation
decisions, and correction content to retain.
- How to represent conversation history without repeated prefixes while using
PromptKit's native evidence.
- Which native conversation snapshots make troubleshooting most convenient.
- How much failed-run context to retain independently, and when references to
existing inputs, checkpoints, or published artifacts suffice.
- Which desired evidence is available through native public hooks and which