feat(core): enhanced result object .report() + source discriminator (ADR 0019)#343
Merged
rejifald merged 1 commit intoJun 29, 2026
Conversation
…ADR 0019)
Add the run-diagnostics surface ADR 0016 held the line against, plus the
`source` discriminator (folds in two of 0016's four deferrals).
- `Inspection<T>` gains `source: 'live' | 'cache' | 'stream'` — the
interpretant of `raw` (why it is/isn't null). It lands on the minimal
object (not the report) because it explains an Inspection field; revises
0016's guess that source belonged on the enhanced object.
- new `.report()` -> `RunReport<T> extends Inspection<T>` adding `attempts`,
`timing { ms, waited? }`, the redacted `config`, and the `cache` outcome.
`.inspect()` stays the minimal "raw + drift" probe.
Built entirely from the existing event spine — `attempts`/`done.ms`/
`Σ progress.waitedMs`/the `phase:'cache'` detail — so NO new engine events
(per-attempt latency is deferred). A shared `drainRun` feeds both consumers;
`source` precedence is stream > cache > live. `config` is the already-redacted
`__config`, never `__rawConfig`. Never throws.
Flips ADR 0019 to Accepted.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
rejifald
added a commit
that referenced
this pull request
Jun 29, 2026
#343 merged into this branch added the .report() instance method but the generated playground-completions.generated.ts was not re-run, so the verify gate's `git diff --exit-code` on the generated file failed. Pure regeneration via `pnpm --filter @stitchapi/docs gen:completions`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
rejifald
added a commit
that referenced
this pull request
Jun 30, 2026
…DR 0019) (#342) Lands two ADR 0016 deferrals (ADR 0019's #343 was stacked into this branch, so both ship together): - ADR 0018: opt-in InspectOptions.redact (default off) scrubs secret-named fields from .inspect()'s raw via redactSecretsDeep; isSecretQueryKey → isSecretKey (alias kept). A safe-sharing convenience, never a leak guarantee. - ADR 0019: .report() → RunReport<T> extends Inspection<T> (attempts, timing, redacted config, cache outcome) + the 'source' discriminator on Inspection. Built off the existing event spine; no new engine events. Bundle budget raised 23.55→23.95 / 19.0→19.45 KB (both attach to the core Stitch surface, ~0.45 KB); advertised whole-entry size ~23→~24 kB. Resolves main's P5 (value→data) / P17 (waited/elapsed de-suffix) renames. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements ADR 0019 (flipped to Accepted in this PR). Third of three stacked implementation PRs for ADR 0016's deferrals; supersedes the docs-only #337.
What & why
Adds the run-diagnostics surface ADR 0016 deliberately held the line against, and folds in the
sourcediscriminator (two of 0016's four deferrals).Inspection<T>gainssource: 'live' | 'cache' | 'stream'— the interpretant ofraw(why it is/isn't null). It lands on the minimal object, not the report, because it explains an existing Inspection field — revising 0016's guess thatsourcebelonged on the enhanced object.'cache'/'stream'are structural nulls;'live'means a request ran..report()→RunReport<T> extends Inspection<T>addingattempts,timing { ms, waited? }, the redactedconfig, and thecacheoutcome..inspect()stays the minimal "raw + drift" probe;RunReportis "how did this run go?".Plumbing audit (the heart of the ADR)
Everything is derived from the existing event spine —
attempts,done.ms,Σ progress.waitedMs, thephase:'cache'detail — so no new engine events. A shareddrainRunfeeds both.inspect()and.report();sourceprecedence is stream > cache > live. Per-attempt latency is deliberately deferred (the spine has no per-attempt request spans).Privacy
configis the already-redacted__config, never__rawConfig;rawstays non-enumerable and inherits 0018'sredact. v1 echoes the static redacted config (per-call input overrides not reflected) — the fallback the ADR permits.Verification
Pre-commit gate green (format, lint, monorepo typecheck).
packages/coretests: 1108 passed, incl. 10 new.report()/sourcetests. Noengine.tschanges.🤖 Generated with Claude Code