27: named sources, adapters, and normalized outcomes by AmaraNecib · Pull Request #42 · AmaraNecib/mizan

AmaraNecib · 2026-07-19T11:54:39Z

Summary

Introduce the adapter and named-source boundary that lets Mizan consume facts from any host data source. Add the normalized source outcomes needed by later source plans.

Changes

Core (@mizan/core)

ResolveContext: New interface with required principalId, evaluation now timestamp, and optional CancellationSignal
CancellationSignal: Runtime-neutral AbortSignal mirror (no DOM types)
registerPlan(): Register named source plans on the Mizan instance
Plan-scoped evaluation: forPrincipal(principalId, planName?) — with plan, only referenced sources are resolved; without plan, all sources (backward compatible)
SourceRegistry extended with get() and has() for plan validation

Memory Adapter (@mizan/memory)

Updated resolve() to accept ResolveContext (requires principalId + now)

Tests

42 core tests (+12 new): plan registration, plan-scoped resolution, custom source replacement, context enrichment, adapter-as-fact-provider contract
16 memory tests (updated for new context shape)

Acceptance criteria coverage

Criterion	Status
Adapter can register one or more focused named authorization sources	✅
Source receives trusted authorization context, evaluation time, and cancellation signal	✅
Source can return facts, miss, or unavailable with freshness metadata	✅ (pre-existing)
Complete empty fact set is distinguishable from miss and unavailable	✅ (pre-existing)
Malformed source output is rejected as a contract error	✅ (pre-existing)
Named plan can resolve one source and feed normalized facts into existing evaluator	✅
Custom source can replace memory source without changing decision semantics	✅
Tests prove adapters provide facts and Mizan remains the final decision maker	✅

Refs #27

Verification

Typecheck passes (bun run typecheck)
All tests pass (bun run test — 58 pass, 0 fail)
Build succeeds (bun run build)
Pre-commit hooks pass (typecheck + test)
Pre-push hooks pass (typecheck + test + build)
Pre-Push Self-Review (code-review skill) — no actionable findings

Summary by CodeRabbit

New Features
- Added plan-scoped authorization evaluation so decisions consider only sources configured for the selected plan.
- Added plan registration to enable scoped evaluation with validation for duplicate plan names and invalid source references.
- Introduced an evaluation context for fact resolution, including principalId, an now timestamp, and optional cancellation signaling.
Bug Fixes
- Ensured resolvers receive the full evaluation context (principalId and a valid now).
- Confirmed the core remains responsible for final allow/deny decisions, not adapters.
Tests
- Expanded coverage for plan scoping, required/optional source behavior, and outcome payload shape.

- Enrich SourceResolver.resolve() context with ResolveContext (required principalId, evaluation now timestamp, optional CancellationSignal) - Add registerPlan() to Mizan instance for named source plans - Add plan-scoped evaluation via forPrincipal(principalId, planName) — resolves only sources referenced by the plan - Keep default forPrincipal() resolving all sources (backward compatible) - Add CancellationSignal interface (runtime-neutral AbortSignal mirror) - Update MemoryAdapter to accept the new ResolveContext - Tests: plan registration, plan-scoped resolution, custom source replacement, context enrichment, adapter-as-fact-provider contract Refs #27

AmaraNecib · 2026-07-19T11:55:03Z

@coderabbitai review

coderabbitai · 2026-07-19T11:55:13Z

✅ Action performed

Review finished.

coderabbitai · 2026-07-19T11:55:16Z

📝 Walkthrough

Walkthrough

Changes

Core plan-scoped evaluation

Layer / File(s)	Summary
Resolver context and fact collection `packages/core/src/index.ts`, `packages/core/__tests__/decision.test.ts`	Resolvers now receive `principalId`, `now`, and optional `signal`; fact collection validates plans, resolves configured sources, and performs decisions from returned facts.
Plan registration and evaluation API `packages/core/src/index.ts`, `packages/core/__tests__/decision.test.ts`	`Mizan` registers named plans and supports plan-scoped or all-source principal evaluation, with tests for duplicate, missing, and unknown sources and plans.
Memory adapter context integration `packages/memory/src/index.ts`, `packages/memory/__tests__/*`	The memory adapter uses `ResolveContext`, forwards it through registration, and updates resolution tests to provide `now`.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant Mizan
  participant PrincipalEvaluator
  participant SourceResolver
  Caller->>Mizan: registerPlan(name, plan)
  Caller->>Mizan: forPrincipal(principalId, planName)
  Mizan->>PrincipalEvaluator: create evaluator with planName
  PrincipalEvaluator->>SourceResolver: resolve({ principalId, now })
  SourceResolver-->>PrincipalEvaluator: SourceOutcome facts
  PrincipalEvaluator-->>Caller: authorization result

Possibly related PRs

AmaraNecib/mizan#37: Establishes the core and memory adapter resolver surfaces updated by this ResolveContext change.
AmaraNecib/mizan#40: Provides the core authorization decision engine extended with resolver context and plan-scoped evaluation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is clearly related to the PR’s main themes: named sources/plans, adapter integration, and normalized outcomes.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/27-named-sources

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

AmaraNecib · 2026-07-19T11:55:52Z

@coderabbitai review

coderabbitai · 2026-07-19T11:56:06Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T11:58:40Z

@coderabbitai review

coderabbitai · 2026-07-19T11:58:53Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T12:01:33Z

@coderabbitai review

coderabbitai · 2026-07-19T12:01:45Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T12:07:23Z

@coderabbitai review

coderabbitai · 2026-07-19T12:07:28Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T12:18:05Z

@coderabbitai review

coderabbitai · 2026-07-19T12:18:26Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T12:34:10Z

@coderabbitai review

coderabbitai · 2026-07-19T12:34:17Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T12:36:10Z

@coderabbitai review

coderabbitai · 2026-07-19T12:36:29Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T13:33:58Z

@coderabbitai review

coderabbitai · 2026-07-19T13:34:09Z

✅ Action performed

Review finished.

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/index.ts`:
- Around line 33-57: The declared CancellationSignal and ResolveContext.signal
are not wired into the evaluation pipeline. Either add an end-to-end signal
parameter through decide(), can(), forPrincipal(), and collectFacts() so it is
populated when constructing ResolveContext, or update the documentation to
explicitly state cancellation is not yet supported; do not expose the signal as
an active capability while callers cannot provide it.
- Around line 300-328: Update collectFacts plan-source resolution to inspect
each SourcePlanEntry.required value; skip missing resolvers for optional
entries, while continuing to throw the existing error for missing required
sources and retaining normal registration for found sources.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5c2a6c06-d8ba-47b3-911c-4215b10e0fbe

📥 Commits

Reviewing files that changed from the base of the PR and between 327a634 and 3b7bf9d.

📒 Files selected for processing (5)

packages/core/__tests__/decision.test.ts
packages/core/src/index.ts
packages/memory/__tests__/decision.test.ts
packages/memory/__tests__/smoke.test.ts
packages/memory/src/index.ts

…urcePlanEntry.required

AmaraNecib · 2026-07-19T13:49:53Z

@coderabbitai review

coderabbitai · 2026-07-19T13:50:00Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T16:46:35Z

@coderabbitai review

coderabbitai · 2026-07-19T16:46:40Z

✅ Action performed

Review finished.

AmaraNecib · 2026-07-19T22:42:01Z

@coderabbitai review

coderabbitai · 2026-07-19T22:42:06Z

✅ Action performed

Review finished.

AmaraNecib marked this pull request as ready for review July 19, 2026 11:55

chore: minor comment fix to force CodeRabbit re-review

3b7bf9d

coderabbitai Bot reviewed Jul 19, 2026

View reviewed changes

Comment thread packages/core/src/index.ts

Comment thread packages/core/src/index.ts

fix: address CodeRabbit findings — document signal deferral, honor So…

ae56220

…urcePlanEntry.required

AmaraNecib merged commit e37d507 into develop Jul 19, 2026
2 checks passed

coderabbitai Bot mentioned this pull request Jul 19, 2026

26: temporal and scoped authorization facts #44

Merged

Conversation

AmaraNecib commented Jul 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Core (@mizan/core)

Memory Adapter (@mizan/memory)

Tests

Acceptance criteria coverage

Verification

Summary by CodeRabbit

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

Uh oh!

coderabbitai Bot commented Jul 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

AmaraNecib commented Jul 19, 2026

AmaraNecib commented Jul 19, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading

coderabbitai Bot commented Jul 19, 2026 •

edited

Loading