refactor(api): narrow the published surface

[bmanquen]

• Remove ensureFreshToken from the auth context. getAccessToken runs the identical leeway-gated single-flight refresh and reports whether it worked, so the side-effect-only variant was strictly less useful. HighlightQueueDrainHost derives the drain's internal DrainAuth.ensureFreshToken from it; drain.ts is unchanged.
• Stop exporting SignOutGuardAuth. It only named useSignOutGuard's parameter, which structural inference already covers.
• Stop exporting isValidHighlightHex and KnownAuthPermission.
• Update AGENTS.md, ADR 0016, the READMEs, and the changeset.

None of these shipped — all are new on this branch inside unreleased minors, so no changeset entry is needed for the removals.

Greptile Summary

This PR narrows the unreleased public API while preserving the queue drain’s internal refresh interface.

• Removes ensureFreshToken, KnownAuthPermission, isValidHighlightHex, and SignOutGuardAuth from their public surfaces.
• Adapts the highlight queue drain to use getAccessToken() internally.
• Keeps highlight hex validation private to the UI swatch implementation.
• Updates tests, documentation, ADR guidance, and release notes to match.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete changed-code defect identified.

The narrowed symbols were confined to unreleased branch work, and the replacement queue-drain adapter preserves the prior refresh behavior while the private hex validator remains equivalent to core’s validation contract.

Important Files Changed

Filename	Overview
packages/core/src/auth/auth-context.tsx	Removes the redundant side-effect-only token refresh method while retaining the result-bearing accessor.
packages/core/src/auth/auth-provider.tsx	Stops publishing ensureFreshToken through the auth context without changing the underlying refresh implementation.
packages/core/src/highlights/highlight-queue-drain-host.tsx	Derives the drain’s internal refresh callback from getAccessToken with behavior equivalent to the removed method.
packages/core/src/index.ts	Removes unreleased helper and permission-type exports from the core package entry point.
packages/ui/src/lib/verse-action-swatches.ts	Internalizes the six-digit highlight-hex predicate with semantics matching core validation.
packages/ui/src/index.ts	Removes the internal structural auth parameter type from the UI package surface.
packages/ui/src/native/use-sign-out-guard.ts	Keeps the sign-out guard parameter type private while preserving structural type inference for callers.

_{Reviews (1): Last reviewed commit: "refactor(api): narrow the published surf..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Auth (PKCE OAuth, token storage, refresh)
• Knowledge Base — Core Provider Initialization
• Knowledge Base — Build, Versioning, and Release Tooling

[cameronapak]

Standards

No hard AGENTS violations. The four names are off the public barrels. Docs and the changeset drop those names. No extra changeset is needed. The names did not ship.

Judgement (Fowler smells):

• Middle Man (justified). HighlightQueueDrainHost wraps getAccessToken in a void ensureFreshToken. DrainAuth still wants () => Promise<void>. drain.ts stays unchanged.
• Duplicated Code. isValidHighlightHex is copied into verse-action-swatches.ts. The public core export is gone. A deep import is blocked. The hex rule can drift.
• Divergent Change. The PR title is "narrow the published surface". The READMEs also add offline, onHighlightError, refreshHighlights, and sign-out tutorials.

Spec

The spec asks for four un-exports, then a docs update:

• Remove ensureFreshToken from the auth context.
• Stop the export of SignOutGuardAuth, isValidHighlightHex, and KnownAuthPermission.
• Update AGENTS.md, ADR 0016, the READMEs, and the changeset.
• Do not add a changeset entry for the removals. The names did not ship.

public barrels
|-- core/index.ts
|   - ensureFreshToken      # also off AuthContextValue
|   - isValidHighlightHex
|   - KnownAuthPermission
`-- ui/index.ts + native/index.ts
    - SignOutGuardAuth

still internal
|-- DrainAuth.ensureFreshToken   # void wrapper over getAccessToken
|-- highlights/isValidHighlightHex
`-- types.KnownAuthPermission

(a) Missing / partial: none.

The four names are off the public barrels. AuthContextValue no longer defines ensureFreshToken. The drain host derives a void wrapper from getAccessToken. drain.ts is unchanged. SignOutGuardAuth is file-local. isValidHighlightHex stays internal. KnownAuthPermission stays behind AuthPermission.

(b) Scope creep: the spec asked the docs to show the four un-exports. This PR also adds consumer tutorials that are not those four names (offline / queued, onHighlightError, refreshHighlights, useHighlightPermissionFlow). The code change is in scope. The docs and changeset are a highlights-feature dump.

(c) Implemented but wrong: none. The drain wrapper discards AccessTokenResult as specified. getAccessToken still owns the leeway-gated single-flight refresh.

---

Standards: 0 hard, 3 judgement (worst: Duplicated Code on the hex helper). Spec: 0 missing/wrong, 1 scope-creep (worst: README tutorials outside the four removals).

Code Reviewer bot, sent on behalf of Cam.

[cameronapak]

nitpick (non-blocking): This hex check is a copy of the helper in paint-projection.ts.

The public export is gone, so a deep import is blocked. If the hex rule changes, these two copies can drift.

Code Reviewer bot, sent on behalf of Cam.

[bmanquen]

This is a trade off, do we want this to be publicly accessible as part of the public API or would we rather keep both helpers?

I dont think this function should change much if at all.

[cameronapak]

note (non-blocking): The spec asked the docs to show the four un-exports.

This section (and the later sign-out / refresh tutorials) is extra consumer surface. The text is accurate. It is a second job in this PR.

Code Reviewer bot, sent on behalf of Cam.