docs(#6407): adopt deterministic entity context staging - #7080
Conversation
Record a runner-owned, filtered entity snapshot that is available before the pre-script and exposed through predictable paths outside the repository clone. Signed-off-by: Barak Korren <bkorren@redhat.com> Assisted-by: Codex (gpt-5.6-sol)
PR Summary by QodoDocument deterministic filtered entity-context staging
AI Description
Diagram
High-Level Assessment
Files changed (4)
|
|
🤖 Finished Review · ✅ Success · Started 1:08 PM UTC · Completed 1:26 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.09 |
Site previewPreview: https://3e27f827-site.fullsend-ai.workers.dev Commit: |
Code Review by Qodo
1. Identical inputs produce different trees
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| `index.json` is the authoritative, versioned manifest. It identifies the forge, | ||
| repository, entity kind and ID, snapshot time/revision, schema version, and an | ||
| ordered entry for every staged file with source ID and URL, author, timestamps, | ||
| media type, byte count, SHA-256 digest, and filtering/truncation status. |
There was a problem hiding this comment.
1. Implementers can diverge on snapshots 📜 Skill insight ⚙ Maintainability
The Decision section of ADR 0107 embeds the authoritative v1 directory tree, exact paths, field-level index.json schema, ordering, metadata, and digest behavior instead of linking to a versioned artifact under docs/normative/. When runner, forge-adapter, and sandbox implementations adopt this prose independently, they have no machine-checkable conformance target for schemas or canonical serialization and can diverge.
Agent Prompt
## Issue description
Move the detailed entity-context directory and manifest contract into a versioned normative specification, and update ADR 0107 to link to it rather than defining the contract inline.
## Issue Context
Create an appropriate artifact such as `docs/normative/entity-context/v1/README.md`. Preserve and formalize the complete directory layout, schemas, canonical serialization and ordering, path-safe stable-ID encoding, filtering status values, field-level `index.json` contents, metadata, digest coverage, and compatibility rules there, while keeping ADR 0107 focused on the architectural decision and rationale.
## Fix Focus Areas
- docs/ADRs/0107-deterministic-filtered-entity-context-staging.md[56-85]
- docs/ADRs/0015-normative-specifications-directory.md[39-55]
- docs/normative[1-1]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| `index.json` is the authoritative, versioned manifest. It identifies the forge, | ||
| repository, entity kind and ID, snapshot time/revision, schema version, and an | ||
| ordered entry for every staged file with source ID and URL, author, timestamps, | ||
| media type, byte count, SHA-256 digest, and filtering/truncation status. |
There was a problem hiding this comment.
2. Identical inputs produce different trees 🐞 Bug ≡ Correctness
index.json must include the snapshot time while the ADR also promises byte-identical trees for identical forge responses. Fetching the same response at different times changes that required timestamp, so the central determinism guarantee fails unless time is derived canonically or excluded from the tree.
Agent Prompt
## Issue description
Reconcile the required snapshot timestamp with the guarantee that identical forge responses produce byte-identical context trees.
## Issue Context
Define a canonical source for the timestamp, weaken the guarantee to exclude acquisition metadata, or separate non-deterministic run metadata from the deterministic snapshot.
## Fix Focus Areas
- docs/ADRs/0107-deterministic-filtered-entity-context-staging.md[78-85]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| The snapshot is written outside the repository clone. Host-side pre- and | ||
| post-scripts receive `FULLSEND_CONTEXT_DIR` pointing to | ||
| `<run-dir>/context`; inside the sandbox the same variable points to | ||
| `/sandbox/workspace/context`. Fullsend uploads that directory after sandbox |
There was a problem hiding this comment.
3. Private forge data enters run artifacts 🐞 Bug ⛨ Security
The decision stores bodies, comments, reviews, diffs, and logs beneath <run-dir>/context without requiring deletion or exclusion from retained artifacts. Private-entity runs therefore leave filtered but still confidential content in a directory the repository documents as artifact-uploaded, reaching artifact retention whenever the run directory is collected.
Agent Prompt
## Issue description
Define the lifecycle and retention boundary for staged entity context containing private forge data.
## Issue Context
Require cleanup after the last authorized host consumer, specify behavior on failures and cancellation, and either exclude context from run artifacts or define explicit access-controlled retention. Preserve diagnostics without retaining full private bodies and logs unnecessarily.
## Fix Focus Areas
- docs/ADRs/0107-deterministic-filtered-entity-context-staging.md[48-75]
- docs/ADRs/0107-deterministic-filtered-entity-context-staging.md[94-100]
- docs/ADRs/0017-credential-isolation-for-sandboxed-agents.md[102-104]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
Risk Assessment: moderate (2/5) DetailsDocs-only ADR addition with no source or CI changes; score elevated slightly above low by docs/architecture.md being a high-churn, multi-author file that creates merge-conflict risk. |
ReviewFindingsMedium
Next steps:
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
| media type, byte count, SHA-256 digest, and filtering/truncation status. | ||
| `summary.md` is a generated navigation aid containing bounded metadata and | ||
| links, not a second copy of bodies. Collections and files that do not apply are | ||
| omitted. Entries use canonical ordering and zero-padded ordinals plus |
There was a problem hiding this comment.
[medium] internal-consistency
(a) The determinism claim "identical forge responses produce byte-identical trees" (line 85) is potentially contradicted by the "snapshot time/revision" field in index.json (line 79). If "snapshot time" is derived from the runner's wall clock rather than from forge response data, two assemblies of the same forge data at different times would produce different index.json files, breaking the byte-identical guarantee. The ADR does not clarify the source. (b) The text on line 84 states "Entries use canonical ordering and zero-padded ordinals plus forge-stable IDs" without qualification, but the directory tree (lines 65-75) shows ordinal prefixes only on comments and reviews, not on checks. The discrepancy between the general statement and the selective application in the diagram is real.
Suggested fix: Clarify whether "snapshot time" is derived from forge response data (preserving determinism) or from the runner clock (excluded from the byte-identical guarantee). Clarify that ordinal prefixes apply to flat-file collections (comments, reviews) but not to per-entity subdirectories (checks), or align the diagram with the text.
1 participant
Summary
FULLSEND_CONTEXT_DIR, outside the repository cloneRationale
Issue #6407 identifies repeated ad-hoc forge calls as non-deterministic and token-intensive. This ADR records the architecture for collecting the handled issue or change proposal once, filtering untrusted content before agent consumption, and sharing the resulting snapshot across scripts and runtimes.
This is the design decision for #6407; implementation and token-cost measurement remain follow-up work, so this PR does not close the issue.
Verification
make lintRelates to #6407.