docs(adr): define selective CEL acquisition and harness admission by ifireball · Pull Request #8694 · fullsend-ai/fullsend

ifireball · 2026-10-22T08:24:36Z

Summary

Record three decisions for entity-source CEL: acquire only data that can affect the predicate (ADR 0147), reuse verified actor roles for a bounded period (ADR 0148), and apply each selected harness's human admission minimum to the prompting event, decision-relevant entity facts, and Fullsend-controlled model records (ADR 0151).

The platform keeps a non-waivable triage-level floor. The harness role selects the run credential identity and supplies a compatibility default for human admission: triage and review default to triage; every other role, including custom roles, defaults to write. A trusted top-level human_min_role or an ADR 0112 guarded overlay may set triage, write, maintain, or admin. Token scopes and privilege_levels do not infer the human threshold. Trigger CEL may narrow routing after the platform gate.

Review focus

The same resolved minimum applies separately to event actors, actor-originated facts that could make entity CEL actionable, and each Fullsend-controlled model-bound record at its fresh exposure checkpoint. A prompting actor or CEL match does not authorize another record.
An overlay setting human_min_role may use only verified trusted facts available before that harness's actor gate. Role-dependent guards require the future versioned verified-effective-role CEL input; raw event.actor.role and label grants cannot choose the minimum. The ordered overlay result, guard evidence, and effective minimum are pinned across dispatch and run. ADR 0112's trusted-field check establishes dependencies; reviewers still need to check which truth value selects a lower threshold (for example, an author can choose a fork).
A human label addition supplies an exact, provider-proven triage grant for its accepted transition and proven projection. At a triage minimum, that projection remains eligible while the same accepted label state is proven, even if the labeler's later role changes. A higher-minimum harness needs the labeler's current verified effective role. Bot label handoffs and registered-bot authorization remain separate. The grant never fabricates a verified actor role or admits model records.
An explicit human_min_role: triage on a write-capable harness deliberately permits triage actors and records to guide it while its minted capabilities stay the same. That is a reviewed harness policy choice, not an inference from token capabilities.
The registry and local harness policy come from a trusted immutable revision (the target/base commit for change proposals), with hash-verified remote layers. Dispatch binds the composed policy identity, overlay outcome, and effective minimum to the run handoff; run verifies the same policy before using credentials or content. Actor-role caches hold verified roles, not per-harness pass decisions; each harness reapplies its own minimum.

Other changes

ADR 0147 defines selective acquisition, UNKNOWN progression, durable retry or rediscovery, bound-run rechecks, and decision-relevant audit evidence. Raw monotone state can conservatively defer a run without authorizing every historical updater.
ADR 0148 permits scoped actor-role reuse for entity CEL, with an absolute five-minute cap, known-change invalidation, and rechecks after cache-dependent false decisions. Event and model-bound checks remain fresh.
Authorization Contract v2 defines the gates, narrow label grants, overlay selection order, and audit evidence. Accepted ADRs receive short status cross-references; architecture and related problem documents reflect the target decision.

This PR changes design documents only. Authorization v1 already specifies triage for observation and write for mutation. The GitHub bash routes implement the built-in thresholds, and #8727 now applies the harness role-derived defaults in Go CEL dispatch for ordinary human events before trigger CEL. The human_min_role field is target-only until the loader validates and enforces it, including explicit empty values, base composition, guarded overlays, and rejection in deprecated forge: blocks. Current dispatch and run do not share the verified overlay context or policy-identity handoff required by this target contract. Versioned CEL inputs must expose verified effective roles and label-grant provenance separately; the normalized-entity and snapshot v2 contracts are prerequisites for the target entity and model paths. Snapshot v1 retains its historical threshold.

Related issues

Related to #8421. #8420 tracks the normalized-entity schema and partial-data contract required before implementation.

Testing

CI=1 make lint passed on the staged documentation changes.
git diff --check origin/main...HEAD passed.
Tests not applicable: documentation only.

Checklist

PR title follows Conventional Commits.
Commits have one DCO sign-off and agent attribution.
I wrote this contribution myself and can explain all changes in it.

qodo-code-review · 2026-10-22T08:25:20Z

PR Summary by Qodo

Define selective entity CEL evaluation and bounded actor-role reuse

📝 Documentation 🕐 40+ Minutes

AI Description

• Adopt progressive entity-data acquisition so CEL checks need not read unrelated history.
• Permit provider-verified actor-role reuse for entity CEL, capped at five minutes.
• Version the authorization contract while keeping entity-source CEL disabled pending a partial-data
 contract.

Diagram

graph TD
  A["Event or poll"] --> B["Origin gate"] --> C["Selective plan"] --> D["Authorized facts"] --> E{"CEL result"}
  E -- "true" --> F["Bound recheck"] --> G["Sandbox launch"]
  H["Role cache"] --> D
  E -- "UNKNOWN: acquire" --> C
  E -- "false: reconcile" --> A
  F -- "inconclusive: retry" --> C

High-Level Assessment

The following are alternative approaches to this PR:

1. Require complete entity history before CEL

➕ Simpler completeness reasoning and full-history audit reconstruction.
➖ Reads, authorizes, and audits unrelated records even for state-only or short-circuiting predicates.

2. Refresh actor roles on every check

➕ Recognizes provider-side permission changes at the next check.
➖ Repeats lookups across progressive iterations, poll cycles, and bound runs.

Recommendation: The proposed combination is appropriate for reducing provider load while explicitly bounding uncertainty and stale-role risk. Keep entity-source CEL disabled until the normalized-entity contract can express partial data, source coverage, and concurrency; retain fresh event-admission and model-bound gates.

Files changed (12) +1061 / -18

Documentation (12) +1061 / -18

config.tsExpose normative specifications in the docs sidebar +5/-0

Expose normative specifications in the docs sidebar
• Adds a sidebar section that discovers documents under docs/normative, making the versioned authorization contracts easier to find.
docs/.vitepress/config.ts

0063-polling-based-work-discovery.mdClarify retry requirements for entity-source handoffs +5/-0

Clarify retry requirements for entity-source handoffs
• Links ADR 0147's durable retry or proven rediscovery requirement while preserving the legacy reconstructed-event lastCheck rule.
docs/ADRs/0063-polling-based-work-discovery.md

0098-entity-first-harness-evaluation.mdMark entity-evaluation guarantees partially superseded +10/-1

Mark entity-evaluation guarantees partially superseded
• Identifies the full-history, audit-roster, and per-evaluation role-refresh rules revised by ADRs 0147 and 0148. Clarifies that trusted-origin, event-actor, and model-bound gates remain required.
docs/ADRs/0098-entity-first-harness-evaluation.md

0144-reuse-poll-and-entity-bound-run-processes.mdDistinguish retained process rules from revised check rules +7/-0

Distinguish retained process rules from revised check rules
• Marks complete-entity due checks, full-history audits, and per-check role refresh as partially superseded without changing lifecycle, scheduling, or model-bound authorization rules.
docs/ADRs/0144-reuse-poll-and-entity-bound-run-processes.md

0147-evaluate-entity-cel-over-selectively-acquired-data.mdAdopt selective, progressive entity CEL acquisition +159/-0

Adopt selective, progressive entity CEL acquisition

• Defines conservative dependency planning, partial-data UNKNOWN semantics, coverage proofs, actor-gated facts, and provisional poll-to-run handoffs with retry guarantees. Replaces full-history audit rosters with bounded decision evidence and keeps entity-source CEL disabled pending a normalized-entity contract.

docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md

0148-reuse-verified-actor-roles-for-entity-cel.mdAdopt bounded reuse of verified CEL actor roles +120/-0

Adopt bounded reuse of verified CEL actor roles

• Permits scoped provider-verified role reuse across checks and processes with an absolute five-minute maximum, known-change invalidation, and rechecks after cache-dependent false results. Preserves fresh event and model-bound authorization, and documents the possible stale-grant sandbox-launch window.

docs/ADRs/0148-reuse-verified-actor-roles-for-entity-cel.md

architecture.mdAlign architecture and observability guidance with the ADRs +33/-15

Align architecture and observability guidance with the ADRs

• Replaces full-history entity-check guidance with selective acquisition, coverage-aware outcomes, bounded role reuse, and decision-focused audit evidence. Clarifies the remaining normalized-entity contract prerequisite.

docs/architecture.md

README.mdIdentify v1 as the retained dispatch contract +9/-1

Identify v1 as the retained dispatch contract
• Links to v2 and explains which future entity-evaluation and audit requirements it supersedes. States that existing event-backed dispatch continues using v1 until migration.
docs/normative/authorization/v1/README.md

README.mdSpecify Authorization Contract v2 +703/-0

Specify Authorization Contract v2

• Defines normative rules for selective acquisition, coverage, actor attribution, UNKNOWN outcomes, durable handoffs, bounded audit evidence, and scoped actor-role caching. Preserves separate event-actor and model-bound gates and documents migration and versioning boundaries.

docs/normative/authorization/v2/README.md

agent-architecture.mdLink entity-centric architecture to the new decisions +4/-0

Link entity-centric architecture to the new decisions
• Adds references to progressive entity acquisition and bounded verified-role sharing in the entity-trigger discussion.
docs/problems/agent-architecture.md

agent-infrastructure.mdQualify role sharing across repeated entity checks +1/-1

Qualify role sharing across repeated entity checks
• Connects resident process reuse to ADR 0148's bounded actor-role lifetime.
docs/problems/agent-infrastructure.md

operational-observability.mdConnect entity-trigger audits to bounded evidence +5/-0

Connect entity-trigger audits to bounded evidence
• References decision-relevant provenance and source-coverage evidence, including the age of shared actor-role results used for CEL.
docs/problems/operational-observability.md

fullsend-ai-review · 2026-10-22T08:26:36Z

🤖 Finished Review · ✅ Success · Started 8:26 AM UTC · Completed 8:48 AM UTC

Commit: 5006524 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $3.18

qodo-code-review · 2026-10-22T08:30:07Z

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (1)

1. Disabled entity checks look available 📜 Skill insight ≡ Correctness

Description

The added documentation describes entity-source CEL as disabled or not yet implemented without the
required > **Planned:** callout or an issue link. Readers of the ADR and normative contract
therefore cannot distinguish this future behavior from current functionality, and the same omission
appears in the v2 entity-evaluation section.

Code

docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md[R135-136]
+Entity-source CEL remains disabled until a versioned normalized-entity
+contract defines partial data, coverage, and concurrency semantics.

Relevance

● Weak
Similar planned-feature callout findings in normative and user docs were rejected by authors.
PR-#6083
PR-#8275
PR-#6035

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The compliance rule requires every mention of a not-yet-implemented feature to use a `>
**Planned:**` blockquote with a relevant issue link. The new ADR explicitly says entity-source CEL
remains disabled until a future contract exists, while the v2 contract states that the path is not
yet implemented; neither changed section uses that callout or provides an issue link.

docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md[132-136]
docs/normative/authorization/v2/README.md[285-300]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new documentation mentions that entity-source CEL is disabled until the normalized-entity contract exists, but it does not use the required planned-feature callout or link to the relevant issue. Similar future-state wording appears in the Authorization Contract v2 entity-evaluation section.

## Fix Focus Areas
- docs/ADRs/0147-evaluate-entity-cel-over-selectively-acquired-data.md[135-136]
- docs/normative/authorization/v2/README.md[294-300]

## Recommended Fix
Rewrite each not-yet-implemented feature reference as a `> **Planned:**` blockquote and include a link to the relevant tracking issue, such as #8420 for the normalized-entity and partial-data contract. Ensure the wording clearly distinguishes planned behavior from currently implemented functionality.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Dismiss ↗ | View ↗

Context sources

✅ Tickets: 🎫 Clarify entity-source discovery requirements for ADR 0098 🎫 Specify normalized entity v1 for ADR 0098

✅ Compliance rules (platform): 95 rules

✅ Skills: 5 invoked

writing-user-docs

writing-adrs

check-patch-coverage

cutting-releases

adr-corner

✅ Cross-repo context — repo relationships

Explored: repo: fullsend-ai/experiments (sha: 09c2dbc2) — View relationship

Explored: repo: fullsend-ai/agents (sha: a41950c1) — View relationship

Review mode: Auto: ⚖️ Balanced: Security-sensitive normative contract with broad cross-document authorization implications.

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

github-actions · 2026-10-22T08:30:32Z

Site preview

Preview: https://bfeca1e0-site.fullsend-ai.workers.dev

Commit: 9fc06a2c6e0403511853634e78964e78b2fe359c

codecov · 2026-10-22T08:39:05Z