# Agentic invocation, grants and handoff: source review

Status: **38 pinned probes pass; the three source corrections are applied**. The
[application record](../authoring/agentic-source-application.json) binds these
changes together with the [recovery corrections](agentic-run-recovery-review.md)
and execution additions. Historical proposal tests use commit `7167e08ce5`;
live-content tests independently check application. No guide acceptance,
source-unit assignment, browser review or normal-speed listening is claimed.

Source pin: `1ceae52c7896a59ac74a4429d410f3218f0b91c6`. The probes execute the
complete unmodified `invocation/invocation.ts`, `grants/resolver.ts` and
`handoff/handoff-protocol.ts` modules from `libs/oshun/agentic-studio/src`. They
use controlled records, no network, credentials, storage or model. Deliberately
malformed inputs expose missing local validation; they are not evidence that an
authenticated deployment accepts those inputs or that the broader capability
broker can be bypassed.

The existing invocation, grants, handoff and portfolio-broker Vitest suites also
pass: **64 tests across four files**, one worker, no file parallelism. The
tracked package matches the source pin. Those suites include controlled broker
rejection of mismatched actor, tenant, purpose, resource, action, trust zones
and risk. They are not a complete runtime, service or release gate.

## Three corrections

| Slide              | Existing overstatement                                                                                                   | Prepared correction                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agents-preflight` | A passing preflight is presented as a launch guarantee with required consent and a declared source set.                  | Explain the supplied-entry, set-membership, numeric-range and null checks, and the trusted policy/source/consent work outside them.                |
| `agents-grants`    | Renewal requires a new identity; returning cascade events can sound like enforced delivery and termination.              | Explain caller-supplied renewal fields, future-dated expiry events and the distinction between simple selection and the actual broker.             |
| `agents-handoff`   | General authority and cycle language obscures the optional re-entry flag, omitted modifiers and local-return accounting. | Distinguish trace checks from stage-DAG validation, supplied-value comparisons from schema/approval, and returned numbers from atomic reservation. |

[The proposed replacements](agentic-authority-corrections.json) bind each
current assembled slide hash. The four dry authoring tests check those hashes,
all six drafts' disjoint IDs and joint catalog membership, existing table/column
render contracts, source resolution and paragraph speech plans. They do not
measure fit or produce delivered HTML, PDFs or audio.

Visual thesis: preserve the cream, ink and terracotta reading plane; make the
boundary of each check easy to compare, without portraying a supplied record as
a seal of authorization.

Content plan: compare the four preflight obligations, retain the five exact
grant-specificity rows, then distinguish history, authority and budget in the
handoff. Put detailed examples and caller obligations in explanatory paragraphs.
Keep one clear takeaway per slide.

Interaction thesis: retain navigation, source disclosure and
reduced-motion-aware transitions. The comparison tables and independent handoff
columns must convey their meaning in static HTML and PDF. No new motion, chrome
or decorative imagery is required. This is not an accepted visual benchmark;
actual embedded, compact, mobile and page-fit PDF review remains required after
application.

## Preflight: validate supplied declarations, then establish their authority

`validatePreflight` returns an error array in this order:

1. Each supplied required consent whose confirmation time is exactly `null`.
2. Each supplied trigger scope absent from the supplied entitlement set.
3. An invalid cost range.
4. An invalid latency range.
5. A non-null evidence requirement combined with a null source reference.

Cost/latency ranges require finite bounds, nonnegative low values and high
values at least as large as low values. Zero and equal endpoints are valid. This
is range validation, not measured provider accuracy or budget admission.

The consent loop cannot discover an omitted policy requirement. A missing entry
or `required: false` does not produce a required-consent error; non-null future,
negative and nonfinite timestamps pass this check. It does not identify who
confirmed, validate the seven typed keys at runtime or establish current
consent. Likewise, the entitlement set and trigger's required scopes are inputs,
not server authority that this helper resolves.

The source-set check is literal null logic. A blank string or an unresolved
identifier passes; a null evidence requirement permits a null source reference.
Tone, persona, output and actor/tenant identity are recorded fields, not
resolved or authenticated here. A UI, consent store, source resolver and
executor must establish the real workflow. These probes do not test the adjacent
run-card, output-review and notification interfaces; their existing unit suite
is separate supporting evidence, not a customer-flow acceptance claim.

## Grant selection is not the whole capability boundary

The simple resolver selects matching agent/tool/scope references, then removes
non-null revocations and expirations at or before the supplied clock. Scope
priorities are 100, 80, 60, 40 and 20 for run, pipeline instance, session, user
and tenant respectively. Newest grant time breaks equal-priority ties; an exact
tie retains the first supplied record.

Selection has some important interpretation boundaries:

- A revoked narrow grant can fall back to a broader live grant. Revoking one
  candidate is not necessarily a denial of the requested operation.
- When no candidate is live, **any** revoked match produces
  `all-matches-revoked`, even if other matches are only expired. The label is
  not a literal classification of every record.
- A future grant time is not rejected, and a future non-null revocation time is
  treated as revoked now, not scheduled for later.
- A per-run record has no independent tenant or actor field. Its scope match
  compares the run ID. The resolver does not enforce the returned free-form
  capability modifiers and retains the original record reference.
- `recheckQueuedRunAtDispatch` simply re-resolves supplied inputs and returns a
  decision/time. Calling it, using a trustworthy clock and enforcing the result
  are dispatcher responsibilities.

This does **not** describe the whole deployed authorization mechanism.
`PortfolioCapabilityBroker.matchingGrants` first filters exact actor, tenant,
purpose, resource, action, source/target trust and risk along with agent/tool.
`authorizeUse` calls the simple resolver on that filtered set, then evaluates
additional trust-promotion, secret, sandbox, network and credential boundaries.
The pinned BFF `runs-route.ts` calls `runGovernedToolPlan` with a broker and
server-owned tool policy. These relationships were inspected in source, not
exercised as authenticated HTTP requests by this review.

The broker has its own grant lifecycle and checks. Its existing controlled test
suite passes, including actor/tenant mismatch rejections. Do not infer that the
simple resolver's deliberately incomplete input shape bypasses those checks.
Full governed-orchestrator, broker, HTTP route, persistence, transport and
deployment teaching still needs dedicated review. In particular, the current
`agents-admission` explanation remains pending that deeper audit.

## Revocation and renewal: distinguish an event from its effect

`emitRevocationCascade` walks supplied active-run records breadth-first from
matching grant users through their parent/child links. A visited-ID set prevents
cycling. It does not validate tenant-consistent ancestry, mutate runs, publish
events or stop workers. Multiple direct users start at depth zero; the reported
depth is relative to the supplied affected-root walk, not always the absolute
run-tree depth.

`emitExpiryCascade` includes unrevoked grants expiring at or before the end of a
supplied horizon, including earlier expirations. It constructs events stamped
with each grant's expiry. For a grant expiring at 1,030, observed at 1,000 with
a 60-second horizon, the event exists while `resolveGrant` still considers the
grant live. The original record's revocation field remains null. A consumer must
distinguish warning/scheduling from actual expiry enforcement.

`renewGrant` checks nonblank rationale and audit-ID strings, then copies
supplied replacement ID/time/expiry fields and clears revocation. The same ID or
a blank ID can succeed; neither uniqueness nor a recorded audit event nor a
valid future expiry is established. This function is not the broker's operator
approval workflow. The authority owner must validate and persist a legitimate
renewal.

## Handoff: local validation versus execution

`validateDispatch` checks a supplied ancestor-agent trace, depth, tool subset,
fanout, modifiers and budget in that order. It is not `validatePlanDag`, which
checks the separately declared stage graph. `allowCycle: true` bypasses the
ancestor re-entry check; no approved-operator record is an input to this helper.
The default cap is five, and `trace.length >= cap` rejects. Nonfinite overrides
can bypass the comparison. The source comment describes approval at the root;
that policy must be established outside this function.

Tool membership is a subset check. Fanout is only a greater-than comparison, not
validation of a finite nonnegative integer. Modifier comparison visits only the
child's keys: numeric `<=`, boolean narrowing, exact strings, array `includes`
membership and recursive object entries. Omitted parent restrictions are
accepted and not merged back. Negative numeric limits may compare narrower
without being valid for the tool. Array object members use reference equality,
not deep equality. The application must define missing-value semantics and
validate its actual modifier schema.

Child budgets, by contrast, explicitly require finite positive amounts and a
finite nonnegative parent remainder large enough to contain them. Equal child
and remaining amounts are accepted. `deductDispatchBudget` returns a new parent
value; two calls using the same original 100-unit remainder and a 40-unit child
both return 60. This controlled repeated-call example is not a concurrent store
test. Actual dispatch needs atomic reservation and persistence.

Reconciliation returns unused funds or an overshoot report, not an account
credit or process stop. Invalid observed usage becomes a synthetic one-unit
overshoot for ordinary bounded amounts; negative usage becomes zero. An explicit
supplied terminal state is retained even with an overshoot. Approval helpers
compare role strings and return an initial state; audit constructors do not
validate matching dispatch/report identities or persist their records.
Attribution copies the supplied trace, including duplicates, rather than
verifying ancestry or writing an artifact.

## Learning outcomes and remaining evidence

The following documentation units remain **unassigned**. This review records
mechanisms and necessary corrections, not a claim that all details of each unit
are already taught by the three overview slides.

| Unit ID                    | Source section                        | Further teaching/evidence                                                                         |
| -------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `18fe712ab75e601a86b04e25` | Invocation declaration                | Trace trusted policy and consent/source resolution into actual UI and dispatch.                   |
| `4751dea35b2663258aa234ac` | Scope specificity                     | Predict fallback and tied selection; distinguish lifecycle policy from resolver inputs.           |
| `80dcf69dc7c135eaf39262bd` | Revocation, expiry and cascade        | Distinguish returned records, event delivery, current expiry and legitimate renewal.              |
| `e82138df511ec8e8b335b8e6` | Grants and resolver companion section | Connect the simple selector to broker and governed execution, without conflating their contracts. |
| `78b292b078993e5890a85354` | Handoff protocol                      | Work through validated inheritance, approval, reservation, execution, reconciliation and audit.   |

Prepared reader tasks are to predict a blank-source declaration result, select
among revoked run/live tenant grants, interpret a future-dated expiry event, and
decide what must happen after a 40-unit local deduction. Use neutral prompts and
version-bound actual reader sessions after the slides are rendered. No
participant answers, measured comprehension or accepted benchmark exists here.

After the active narration queue becomes stable, revalidate and deliberately
apply these three patches together with the disjoint recovery corrections.
Refresh source citations and affected inventory inputs, regenerate all six
changed tracks, and run full applicable source, standalone/embedded,
table/columns, actual-audio and PDF checks. Review actual-size visuals and
natural-speed narration; teach any missing source detail before adding reviewed
assignments. Preserve every original 177-baseline track without an exception:
`agentic-studio-failure` was not current in that baseline. This corrects the
original review's mistaken membership claim without rewriting its receipt.
