| 1 | package tool |
| 2 | |
| 3 | import ( |
| 4 | "context" |
| 5 | "encoding/json" |
| 6 | ) |
| 7 | |
| 8 | // EvidenceTargetInfo is a writer's declaration of the content it is about to |
| 9 | // replace, resolved through the writer's own path, overlay, encoding, |
| 10 | // uniqueness, and interval checks. Hashes are the current content's per-line |
| 11 | // SHA-256 digests for Ranges, concatenated in range order; they contain no |
| 12 | // source text. |
| 13 | type EvidenceTargetInfo struct { |
| 14 | Path string |
| 15 | Snapshot string |
| 16 | SourceTextDigest string |
| 17 | // Absent binds create to a confirmed missing source, so a raced creation |
| 18 | // cannot be overwritten using a preflight that saw no file. |
| 19 | Absent bool |
| 20 | // PreservesContent requires a host-captured source identity but no text |
| 21 | // coverage. A byte-preserving move must continue to support binary files. |
| 22 | PreservesContent bool |
| 23 | // WholeFile marks a requirement that covers the file's entire current |
| 24 | // content, so paged evidence may be stitched only within one snapshot. |
| 25 | WholeFile bool |
| 26 | Ranges []ReadRange |
| 27 | Hashes []string |
| 28 | } |
| 29 | |
| 30 | type expectedWriteSourceKey struct{} |
| 31 | |
| 32 | // WithExpectedWriteSource carries the preflight source to the actual writer. |
| 33 | // The writer checks it after opening its source, closing the gate/execute gap. |
| 34 | func WithExpectedWriteSource(ctx context.Context, source EvidenceTargetInfo) context.Context { |
| 35 | return context.WithValue(ctx, expectedWriteSourceKey{}, source) |
| 36 | } |
| 37 | func ExpectedWriteSource(ctx context.Context) (EvidenceTargetInfo, bool) { |
| 38 | info, ok := ctx.Value(expectedWriteSourceKey{}).(EvidenceTargetInfo) |
| 39 | return info, ok |
| 40 | } |
| 41 | |
| 42 | // EvidenceDeclarer is an optional writer capability. The host asks the real |
| 43 | // writer what evidence it needs instead of trusting a model-reported write |
| 44 | // scope, and re-resolves the target through the same code path the write uses. |
| 45 | // An error means the writer's own validation should own the user-visible result. |
| 46 | type EvidenceDeclarer interface { |
| 47 | DeclareEvidenceTarget(ctx context.Context, args json.RawMessage) (EvidenceTargetInfo, error) |
| 48 | } |
| 49 |