Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion reviewer/CONTROLLER.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,10 @@ COMMENT/ACK writes and whole-document reconciliation. The [native discovery
reader](GITHUB-DISCOVERY.md) collects request/removal provenance, owner commands
and live base revisions with an explicitly supplied read transport. It commits
complete discovery before returning Current so cancellation reaches the local
dispatch fence. Actual App consistency remains unqualified. There is no polling
dispatch fence. [Snapshot evidence](SNAPSHOT-EVIDENCE.md) collects a bounded
merge-base diff from trusted immutable Git objects, verifies inline anchors
against their blobs and retains authoritative omissions through review/recovery.
Actual App consistency remains unqualified. There is no polling
daemon, production launcher, credential acquisition, installation flow or activation command. The retired SFL runtime
remains frozen. Live acceptance is tracked in [#173](https://github.com/hemsoft-dev/set-it-free-loop/issues/173),
[#174](https://github.com/hemsoft-dev/set-it-free-loop/issues/174) and
Expand Down
5 changes: 5 additions & 0 deletions reviewer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,11 @@ limitations, never evidence of clean code. Candidate hooks and instructions are
inert data. The reader must run as a separate identity outside the provider
worker, without provider/GitHub credentials.

[Snapshot evidence](SNAPSHOT-EVIDENCE.md) builds the trusted changed-path packet
and diff-line map without checkout or fetching. It binds both to the exact
SQLite-admitted packet and carries controller-observed omissions into reader
coverage, fake review, recovery and rendering.

`AuthStore` on Linux/macOS serializes trusted local state updates and per-phase
profile leases with a cross-process lock. A durable profile journal survives
controller loss, blocks stale seed reuse and commits returned credentials only
Expand Down
93 changes: 93 additions & 0 deletions reviewer/SNAPSHOT-EVIDENCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Immutable snapshot evidence

`CaptureSnapshotEvidence` prepares a bounded evidence packet from an explicitly
supplied trusted `GitStore` and admitted snapshot. It reads committed objects;
it never checks out candidate code, fetches history, loads a provider profile or
starts a reviewer. Repository and fork provenance still come from qualified
discovery and object acquisition. A local object with a matching hash does not
attest installation permissions or which repository supplied it.

Capture requires all three revisions to be commits and the captured merge base
to be the unique merge base of the base tip and head. Missing or ambiguous
history defers the entire capture. The comparison is merge-base to head, even
when an independently advanced base tip has the same tree as head.

Git produces the NUL-delimited raw inventory with full object IDs and renames
disabled. A rename appears as deletion and addition. Modes, status, object IDs,
paths and cardinality are validated. Unsafe paths or incomplete inventories
defer capture. Both SHA-1 and SHA-256 object formats are supported. Packet data
includes every changed path, mode, old/new object identity and status within the
128-file cap. No truncated inventory is admitted.

Regular text blobs and patches share finite bounds. Symlinks, submodules,
binaries, non-UTF-8 objects, unavailable blobs and source/patch size omissions
retain explicit path-specific coverage. Missing commits are not treated as
ordinary blob omissions. There is a two-MiB aggregate blob read budget, a two-MiB
per-command output cap, a 64-KiB JSON packet cap and a one-minute overall capture
deadline. A complete inventory and its coverage must fit; otherwise capture
fails. Patch omission can leave room for later small files. An omitted patch
never supplies inline anchors.

Fixed Git flags disable external diff drivers, text conversion, rename
detection, color, replacement objects and lazy fetch. `--ignore-submodules=none` overrides candidate `.gitmodules` and repository ignore settings. Git receives no inherited
user environment or global/system configuration. The explicitly selected Git
binary and object repository configuration remain trusted. Their provisioning
must stay outside candidate source. No shell is used by capture.

Each hunk's context, additions, deletions, counts, coordinates, unchanged gaps
and EOF newline markers are checked against the actual old/new blobs. Metadata
and function labels do not select paths or lines. Only verified right-side
context/addition lines become inline anchors. Source-valid findings elsewhere
remain summary findings under the existing renderer.

## Bind the admitted packet

Use the job returned by `Admit`, including on an idempotent retry:

```go
capture, err := CaptureSnapshotEvidence(ctx, trustedGit, snapshot)
// Handle err before admission.
job, err := store.Admit(ctx, scope, requestID, release, capture.Packet(), now)
// Handle err before binding.
bound, err := capture.Bind(job)
// Handle err before providing a reader or publication anchors.
engine.Reader = bound.Reader
// After stopped-worker execution:
intent, err := publisher.PrepareEvidence(ctx, outcome, bound)
```

`Bind` requires the exact admitted snapshot and packet plus a valid job. If a
retry returns a previously stored packet and a fresh capture differs, binding
fails. Recovery must reproduce the original captured packet or retain explicit
uncertainty; it cannot silently replace its omissions or source input. A bound
reader uses the job's configured limits and rejects a different snapshot.
Paths and coverage accessors return copies. Inline maps stay private; use `bound.Render` or `Publisher.PrepareEvidence` so publication revalidates the complete admitted job hash. The low-level map-taking renderer/publisher remain transport test seams and reject captured snapshot packets.

Supply an independently budgeted bound reader to each adapter as well as the
engine's citation-verification factory. Search skips unreadable paths with recorded coverage and still stops on cancellation or budget exhaustion. Source receipts combine unique controller-owned reasons per allowed path, reserving space for global denial/exhaustion facts. Unknown attempted paths are sanitized rather than stored as source inventory. Initial controller coverage is retained
when the in-process source broker forks the adapter's reader. It consumes no
model read budget. Citation validation and the engine's existing authoritative
coverage merge preserve these omissions even if the model reports none. The
managed source role still requires its separate identity/containment boundary;
this collector does not qualify that boundary.

## Offline evidence and remaining runtime work

Tests create real commits and exercise the installed Git producer, including
both object formats, quoted/Unicode paths, deletion, no-newline text, renames,
symlinks, submodules and binaries. Working-tree changes, hooks, configured
external/textconv drivers and inherited Git environment canaries cannot alter
the packet or execute during capture. A local inert promisor trap first proves
that missing objects would trigger fetching without the controls, then proves
capture records an omission without invoking that trap. No network is used.

Hostile parser fixtures reject forged source, coordinates, counts, hidden edits,
missing newline markers, duplicate paths and partial inventories. The durable
integration test admits this actual Git packet into SQLite, runs four fake
provider phases, recovers completed work without another provider call and
renders authoritative omissions despite empty model coverage declarations.

This is a library prerequisite for #176. Private polling/backoff, qualified
object acquisition, token attestation, runtime composition and packaging remain
required. It does not install an App, enable Actions, activate the retired
controller or qualify live subscription use.
8 changes: 7 additions & 1 deletion reviewer/publication.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,13 @@ func redactDocument(doc Document, secrets []string) Document {
return doc
}
func (p Publisher) Prepare(ctx context.Context, out Outcome, diff map[string]map[int]bool) (WriteIntent, error) {
doc, err := Render(out, diff)
if snapshotEvidencePacket(out.Job.Packet) {
return WriteIntent{}, ErrFenced
}
return p.prepare(ctx, out, diff)
}
func (p Publisher) prepare(ctx context.Context, out Outcome, diff map[string]map[int]bool) (WriteIntent, error) {
doc, err := renderOutcome(out, diff)
if err != nil {
return WriteIntent{}, err
}
Expand Down
38 changes: 28 additions & 10 deletions reviewer/reader.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,15 @@ type ReadRecord struct {
}

type Reader struct {
mu sync.Mutex
store ObjectStore
snapshot Snapshot
paths map[string]bool
limits Limits
calls, used int
reads []ReadRecord
coverage []Coverage
mu sync.Mutex
store ObjectStore
snapshot Snapshot
paths map[string]bool
limits Limits
calls, used int
reads []ReadRecord
coverage []Coverage
initialCoverage []Coverage
}

func validPath(p string) bool {
Expand Down Expand Up @@ -80,7 +81,7 @@ func (r *Reader) Read(ctx context.Context, revision, p string) (string, error) {
defer r.mu.Unlock()
fail := func(reason string) (string, error) {
loggedPath := p
if !validPath(loggedPath) {
if !validPath(loggedPath) || !r.paths[loggedPath] {
loggedPath = ""
}
if len(r.coverage) < 256 {
Expand Down Expand Up @@ -121,9 +122,15 @@ func (r *Reader) Read(ctx context.Context, revision, p string) (string, error) {
}

func (r *Reader) Search(ctx context.Context, revision, needle string, maxResults int) ([]Anchor, error) {
if err := ctx.Err(); err != nil {
return nil, err
}
if needle == "" || len(needle) > 256 || strings.ContainsAny(needle, "\r\n") || maxResults < 1 || maxResults > 100 {
return nil, errors.New("invalid bounded search")
}
if revision != r.snapshot.Head && revision != r.snapshot.Base && revision != r.snapshot.MergeBase {
return nil, errors.New("revision outside job snapshot")
}
paths := make([]string, 0, len(r.paths))
for p := range r.paths {
paths = append(paths, p)
Expand All @@ -133,7 +140,18 @@ func (r *Reader) Search(ctx context.Context, revision, needle string, maxResults
for _, p := range paths {
text, err := r.Read(ctx, revision, p)
if err != nil {
return matches, err
if ctx.Err() != nil {
return matches, ctx.Err()
}
r.mu.Lock()
exhausted := r.calls >= r.limits.ReaderCalls || r.used >= r.limits.ReaderBytes
r.mu.Unlock()
if exhausted {
return matches, err
}
// Unreadable material retains its authoritative omission. One binary,
// deleted or oversized path must not disable later text matches.
continue
}
for i, line := range strings.Split(text, "\n") {
if strings.Contains(line, needle) {
Expand Down
7 changes: 7 additions & 0 deletions reviewer/render.go
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,13 @@ func sourceURL(snapshot Snapshot, a Anchor) string {
// findings outside the diff stay in the summary. Incomplete jobs never expose
// substantive partial findings, even if prior phases succeeded.
func Render(out Outcome, diffLines map[string]map[int]bool) (Document, error) {
if snapshotEvidencePacket(out.Job.Packet) {
return Document{}, ErrFenced
}
return renderOutcome(out, diffLines)
}

func renderOutcome(out Outcome, diffLines map[string]map[int]bool) (Document, error) {
doc := Document{Inline: []InlineComment{}}
if err := out.Job.Validate(); err != nil {
return doc, err
Expand Down
Loading