@adrkit/evaluator 0.1.0

package/dist/keys.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @adrkit/evaluator — canonical key helpers.
+ *
+ * The compact assertion key and the canonical target key are the two identity
+ * strings that keep the report byte-stable and collision-safe (data-model §4/§5).
+ * Both are pure string functions.
+ */
+import type { Adr, Assertion } from '@adrkit/core';
+import type { AssertionKey, CanonicalTargetId, CanonicalTargetKey } from './types.js';
+/** Compact standard `JSON.stringify([log ?? "", path, id])` — no added whitespace. */
+export declare function makeAssertionKey(log: string | undefined, path: string, id: string): AssertionKey;
+/** The canonical assertion key for one assertion declared on one record. */
+export declare function assertionKeyForAssertion(record: Adr, assertion: Assertion): AssertionKey;
+/**
+ * A key is canonical iff parsing it yields exactly three strings AND the original
+ * key is byte-equal to the compact re-serialization. Whitespace-padded or otherwise
+ * noncanonical spellings are rejected, never normalized.
+ */
+export declare function isCanonicalAssertionKey(key: string): boolean;
+/** Parse a canonical assertion key back into its three string components. */
+export declare function parseAssertionKey(key: string): {
+    readonly log: string;
+    readonly path: string;
+    readonly id: string;
+} | undefined;
+/** Stable `${kind}:${id}` serialization used for equality/intersection/ordering. */
+export declare function canonicalTargetKey(id: CanonicalTargetId): CanonicalTargetKey;

package/dist/pass0.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @adrkit/evaluator — Pass 0 orchestrator.
+ *
+ * Pure, total function of `input` (FR-006): same input ⇒ same typed input error or
+ * byte-identical report + patch. It performs NO clock/network/db/filesystem access,
+ * mutates nothing, imports no adapter/model, and routes without approving or
+ * persisting anything. Missing backing degrades to inert, never a thrown error or a
+ * fabricated pass/fail.
+ *
+ * Behaviour is built up across the user stories: the schema-invalid short-circuit and
+ * the input-contract branch (T021), the structural rules (US1), the externally-backed
+ * rules (US3), routing (US4), and patch projection (US5).
+ */
+import type { Pass0Evaluation, Pass0Input } from './types.js';
+/**
+ * Evaluate a proposal under Pass 0. Total: returns either a typed input-contract error
+ * (no report/patch) or an evaluated `{ report, patch }`.
+ */
+export declare function evaluatePass0(input: Pass0Input): Pass0Evaluation;

package/dist/patch/project.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @adrkit/evaluator — schema-compatible patch projection (§9, R8/R12, T052).
+ *
+ * Projects the eleven rule results down to the committed four-field
+ * `DeterministicFinding` shape — VIOLATIONS ONLY (rule failures at their fixed
+ * severity) — plus `escalate` and existing-enum `escalationReasons` in fixed trigger
+ * order. It strips every operational-only field (reason codes, canonical target ids,
+ * source refs, snapshot ids, candidate/related refs, recordPath, lower-level evidence):
+ * that richness stays on `Pass0Report`. `adr` is copied only when it validates strictly
+ * as a core `AdrRef`, so a filesystem path can never be reinterpreted as an ADR
+ * reference. The evaluator RETURNS the patch; it never writes any record, review state,
+ * database, or index.
+ */
+import { type DeterministicFinding } from '@adrkit/core';
+import type { EvaluationPatch, Pass0Report, RuleResult } from '../types.js';
+/** A rule result is a violation iff it failed at its fixed severity. */
+export declare function isViolation(result: RuleResult): boolean;
+/** Project one violating rule result into the committed DeterministicFinding shape. */
+export declare function projectFinding(result: RuleResult): DeterministicFinding;
+export declare function projectPatch(report: Pass0Report): EvaluationPatch;

package/dist/report/aggregate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @adrkit/evaluator — deterministic finding aggregation (T026, C11).
+ *
+ * A rule may make several observations but yields exactly one aggregate `RuleResult`.
+ * Status precedence is `fail > inert > pass`; `not-evaluated` is set only by the
+ * orchestrator (schema-invalid or `assertions-pass` after a compile failure). The
+ * aggregate `reason` is the first code, in the rule's fixed catalog precedence, among
+ * the winning-status sub-findings — so mixed fail/inert fixtures are byte-stable
+ * rather than discovery-order dependent. All sub-findings are retained and sorted by
+ * the stable secondary comparator.
+ */
+import { type ReasonCode, type RuleId } from '../catalog.js';
+import type { RuleEvidence, RuleFinding, RuleResult } from '../types.js';
+/** One underlying observation a rule makes; aggregated into a single RuleResult. */
+export interface SubResult {
+    readonly status: 'pass' | 'fail' | 'inert';
+    readonly reason: ReasonCode;
+    readonly finding?: RuleFinding;
+}
+/** Aggregate one rule's sub-results into its single RuleResult (findings sorted). */
+export declare function aggregate(rule: RuleId, subs: readonly SubResult[], evidence?: RuleEvidence): RuleResult;

package/dist/report/assemble.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @adrkit/evaluator — report assembly.
+ *
+ * Places the eleven RuleResults in fixed rubric order, appends the routing decision
+ * (never a twelfth rule), and computes `outcome`. Secondary finding ordering and
+ * canonical byte serialization are added in US2 (T027/T028).
+ */
+import { type RuleId } from '../catalog.js';
+import type { Pass0Report, RoutingDecision, RuleResult } from '../types.js';
+/** `returned` iff any rule failed at `error` severity; otherwise `ok`. */
+export declare function computeOutcome(results: readonly RuleResult[]): 'ok' | 'returned';
+/**
+ * Assemble the report from a rule→result map. Exactly eleven results are emitted in
+ * fixed rubric order (C11); a missing rule is a programming error.
+ */
+export declare function assembleReport(proposalPath: string, resultsByRule: ReadonlyMap<RuleId, RuleResult>, routing: RoutingDecision): Pass0Report;

package/dist/report/order.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @adrkit/evaluator — deterministic ordering (R11).
+ *
+ * Stable secondary comparators for `RuleFinding`s within a rule and for the patch's
+ * `deterministicFindings`. Precedence (data-model §5/§7): candidate `AdrRef`, related
+ * `AdrRef`, matcher/assertion key, canonical target key, `recordPath`, `field`,
+ * `message`. `RuleFinding.adr` is strictly an `AdrRef`; a path never enters this order
+ * as `adr`. The eleven rule results keep fixed rubric order and routing keeps trigger
+ * order — those arrays are never sorted.
+ */
+import { type RuleId } from '../catalog.js';
+import type { CanonicalTargetId, RuleFinding } from '../types.js';
+/** Stable secondary comparator for RuleFindings within a single rule. */
+export declare function compareRuleFindings(a: RuleFinding, b: RuleFinding): number;
+export declare function sortRuleFindings(findings: readonly RuleFinding[]): RuleFinding[];
+/** Index of a rule in the fixed rubric order (for assembly). */
+export declare function ruleIndex(rule: RuleId): number;
+/** Comparator for a set-like array of canonical target ids (evidence). */
+export declare function compareCanonicalTargetIds(a: CanonicalTargetId, b: CanonicalTargetId): number;

package/dist/report/serialize.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @adrkit/evaluator — canonical serialization (T028, R11).
+ *
+ * Produces byte-reproducible `report` and `patch` bytes. Serialization is a hand-written
+ * ITERATIVE emitter (no recursion, no `JSON.stringify` key reordering) so that:
+ *   - object keys are emitted in strict code-unit order — including integer-like keys
+ *     (`{"2":..,"10":..}` ⇒ `{"10":..,"2":..}`), which `JSON.stringify` would reorder
+ *     numerically (finding #7);
+ *   - EVERY own JSON key is retained and emitted, including `__proto__`/`constructor`
+ *     smuggled through a null-prototype parse (finding #1); and
+ *   - hostile deep input cannot overflow the stack (finding #5) — the emitter uses an
+ *     explicit work stack, and untrusted data is depth/node-bounded by `withinJsonLimits`
+ *     before it ever reaches here.
+ *
+ * The deterministic payload carries NO timestamp, run id, or duration — caller
+ * `runMetadata` lives in the envelope, outside these bytes (FR-005).
+ */
+import type { EvaluationPatch, Pass0Report } from '../types.js';
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * Canonical JSON string with keys in code-unit order. `pretty` matches
+ * `JSON.stringify(x, null, 2)` formatting exactly (2-space indent, `": "`, LF).
+ */
+export declare function canonicalStringify(root: unknown, pretty?: boolean): string;
+/**
+ * Canonical JS structure with keys recursively sorted (code unit) — used for structural
+ * equality comparisons and CLI envelope building, NOT for byte emission. Output objects
+ * are null-prototype so a smuggled `__proto__` own key is retained rather than dropped.
+ */
+export declare function canonicalize(value: unknown): Json;
+/** Canonical JSON bytes: code-unit-sorted keys, 2-space indent, single trailing LF. */
+export declare function canonicalBytes(value: unknown): string;
+export declare function serializeReport(report: Pass0Report): string;
+export declare function serializePatch(patch: EvaluationPatch): string;
+export interface CanonicalArtifacts {
+    readonly report: string;
+    readonly patch: string;
+}
+export declare function serializeArtifacts(report: Pass0Report, patch: EvaluationPatch): CanonicalArtifacts;
+export {};

package/dist/routing/accepted-assertion.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @adrkit/evaluator — accepted-ADR assertion routing evidence (T048, C4).
+ *
+ * The `contradicts-accepted-adr` trigger is proven when the proposal canonically
+ * overlaps an accepted ADR (rule 6) AND an assertion on that overlapping accepted ADR
+ * FAILS against the supplied proposed / current-HEAD input. Unlike `scope-hierarchy`,
+ * this does NOT require org scope, domain applicability, or a base-green transition —
+ * only the proposed-side failure. Pure; reuses the same engine registry.
+ */
+import type { RuleContext } from '../rules/context.js';
+import type { CanonicalTargetKey } from '../types.js';
+export declare function contradictsAcceptedAdr(ctx: RuleContext, proposalTargetKeys: ReadonlySet<CanonicalTargetKey>): boolean;

package/dist/routing/route.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @adrkit/evaluator — escalation routing (T046, R10/C4/C7).
+ *
+ * A declarative OR over the eight deterministically-proven Pass 0 triggers, computed
+ * AFTER the eleven rule results (never a twelfth rule). Each trigger emits an ordered
+ * proven/not-proven evidence status; missing optional evidence is "not-proven", never a
+ * fabricated escalation. When escalation is proven, a single active human is resolved
+ * (deciders -> CODEOWNERS -> catalog); otherwise the target is `not-required`.
+ */
+import type { RuleContext } from '../rules/context.js';
+import type { RecordTargetResolution } from '../targets/canonical.js';
+import type { RoutingDecision, TriggerEvidenceStatus } from '../types.js';
+/** All eight triggers as `not-proven`, in fixed order (used for schema-invalid reports). */
+export declare function allNotProven(): readonly TriggerEvidenceStatus[];
+/** The deterministic non-escalated routing decision (schema-invalid short-circuit). */
+export declare function notRequiredRouting(): RoutingDecision;
+/** Evaluate the eight triggers and resolve the target if escalation is proven. */
+export declare function computeRouting(ctx: RuleContext, proposalTargets: RecordTargetResolution, contradictsAccepted: boolean): RoutingDecision;

package/dist/routing/target.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @adrkit/evaluator — named-human routing target (T047, R9/C7).
+ *
+ * Resolves a single active human in fixed source order: (1) proposal `deciders`, (2)
+ * CODEOWNERS owners for the proposal's resolved paths, (3) catalog owners for its
+ * resolved entities. Exact source-local ordering: deciders in declaration order; unique
+ * paths sorted by canonical path key, each taking the LAST matching CODEOWNERS rule's
+ * owners in declaration order; unique entities sorted by canonical target key, each
+ * appending catalog owners in snapshot order. Candidates are stable-deduplicated at
+ * first occurrence (never globally identity-sorted). A missing/inactive direct human is
+ * skipped; the first team that does not resolve to exactly one active human is an
+ * ambiguity barrier that immediately yields `unresolved`.
+ */
+import type { IdentityIndex } from '../identity/directory.js';
+import type { CanonicalTargetId, IdentityDirectorySnapshot, PrincipalRef, RouteTarget } from '../types.js';
+/**
+ * Resolve the escalation target. Called only when escalation is proven; a non-escalated
+ * run uses `route.target.not-required` at the routing layer.
+ */
+export declare function resolveRouteTarget(index: IdentityIndex, deciders: readonly PrincipalRef[], directory: IdentityDirectorySnapshot, resolvedPaths: readonly string[], resolvedEntities: readonly CanonicalTargetId[]): RouteTarget;

package/dist/rules/affects-overlap.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @adrkit/evaluator — rule 6: affects-overlap (warn).
+ *
+ * Finite canonical-target-key intersection of the proposal with each ACCEPTED ADR,
+ * computed once per (proposal, accepted-ADR) pair (R4). Primary precedence (§3.1):
+ * any non-empty intersection ⇒ warn (`accepted-intersection`); otherwise no accepted
+ * ADRs ⇒ pass (`no-accepted-corpus`); otherwise absent required pair backing ⇒ inert
+ * (`backing-absent`); otherwise a fully evaluated accepted corpus with no intersection
+ * ⇒ pass (`none`).
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateAffectsOverlap(ctx: RuleContext): RuleResult;

package/dist/rules/affects-resolvable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @adrkit/evaluator — rule 5: affects-resolvable (warn).
+ *
+ * Validates EACH proposal matcher independently, not only the union (finding #2): a
+ * matcher that resolves to real targets cannot mask another positive matcher with
+ * present backing that resolves to ZERO. ADR-0009 semantics are preserved — negation
+ * subtracts, and a different-repo qualifier contributes no local match. Per positive
+ * matcher: ≥1 resolved id ⇒ pass; present backing + zero ids ⇒ warn (`zero-targets`);
+ * a missing inventory (`backing-absent`) or resolver (`resolver-absent`) ⇒ inert. A
+ * negation-only record resolves to the empty set ⇒ warn. No affects ⇒ trivially pass.
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateAffectsResolvable(ctx: RuleContext): RuleResult;

package/dist/rules/assertions-compile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @adrkit/evaluator — rule 8: assertions-compile (error).
+ *
+ * Each assertion declares exactly one source and the approved engine profile validates
+ * it. Neither/both source ⇒ error; a failed source/artifact validation ⇒ error; a
+ * missing engine, resolved file content, or compiled artifact ⇒ inert; no assertions ⇒
+ * pass (`none`). Consumes the shared per-evaluation assertion outcomes so each assertion
+ * is compiled/validated exactly once (R7). One aggregate result.
+ */
+import type { AssertionOutcomes } from '../assertions/evaluate.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateAssertionsCompile(outcomes: AssertionOutcomes): RuleResult;

package/dist/rules/assertions-pass.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @adrkit/evaluator — rule 9: assertions-pass (warn).
+ *
+ * Evaluates each compiled assertion against its resolved input. A false result or a
+ * deterministic engine evaluation error ⇒ warn; a missing engine/input ⇒ inert; no
+ * assertions ⇒ pass (`none`). A compile FAILURE makes this whole rule
+ * `not-evaluated.prereq-failed` — enforced by the orchestrator, which only calls this
+ * rule when assertions-compile did not fail. Consumes the shared per-evaluation
+ * outcomes (one compile per assertion). One aggregate result.
+ */
+import type { AssertionOutcomes } from '../assertions/evaluate.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateAssertionsPass(outcomes: AssertionOutcomes): RuleResult;

package/dist/rules/context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @adrkit/evaluator — per-rule evaluation context.
+ *
+ * Assembled once by the orchestrator after `schema-valid` passes. Rules read only
+ * from this immutable context; none performs I/O.
+ */
+import type { Adr } from '@adrkit/core';
+import type { Pass0Input, ProposalResolution } from '../types.js';
+export interface RuleContext {
+    readonly input: Pass0Input;
+    /** The typed proposal (schema-valid passed). */
+    readonly proposed: Adr;
+    readonly resolution: ProposalResolution;
+    /** Full corpus records, INCLUDING the candidate (data-model §2). */
+    readonly corpusRecords: readonly Adr[];
+    /** Accepted ADRs in the corpus, EXCLUDING the candidate. */
+    readonly acceptedRecords: readonly Adr[];
+    readonly evaluationDate: string;
+}
+/** Records in the corpus that are accepted and are not the candidate proposal. */
+export declare function acceptedRecordsExcludingCandidate(records: readonly Adr[], proposalPath: string): readonly Adr[];

package/dist/rules/decider-resolvable.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @adrkit/evaluator — rule 10: decider-resolvable (warn).
+ *
+ * Every declared proposal decider must resolve through the immutable identity
+ * directory to exactly one active principal (R9). None declared, a zero match, or an
+ * ambiguous match is a warn; an absent directory is inert. Exactly one aggregate result.
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateDeciderResolvable(ctx: RuleContext): RuleResult;

package/dist/rules/expiry-sane.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/evaluator — rule 11: expiry-sane (info).
+ *
+ * `reviewBy` is compared to the caller-supplied `evaluationDate` — NO clock is read.
+ * Absent `reviewBy`, or one strictly after the evaluation date, passes; a `reviewBy`
+ * on or before the evaluation date is `info` (`past-or-equal`). Both are ISO `YYYY-MM-DD`
+ * strings, which compare correctly lexicographically.
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateExpirySane(ctx: RuleContext): RuleResult;

package/dist/rules/id-unique.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/evaluator — rule 2: id-unique (error).
+ *
+ * Identity is scoped by `[record.log ?? "", id]` over the candidate-inclusive corpus
+ * plus optional federated-log snapshots (T018). A duplicate of the candidate's key
+ * fails (`id-unique.collision`); equal ids in different named logs pass. Exactly one
+ * aggregate result is emitted (C11).
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateIdUnique(ctx: RuleContext): RuleResult;

package/dist/rules/kernel.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @adrkit/evaluator — rule kernel (result builders).
+ *
+ * Re-exports the canonical aggregation (`report/aggregate.ts`) and provides the small
+ * result builders rules use for clean pass / inert / not-evaluated outcomes. Keeping a
+ * single `aggregate` implementation avoids drift between rules and report assembly.
+ */
+import { type ReasonCode, type RuleId } from '../catalog.js';
+import type { RuleFinding, RuleResult } from '../types.js';
+export { aggregate, type SubResult } from '../report/aggregate.js';
+/** A clean pass with no sub-findings, using the rule's `.ok` reason by default. */
+export declare function passResult(rule: RuleId, reason?: ReasonCode): RuleResult;
+/** An inert (degraded) result — backing absent, never a violation. */
+export declare function inertResult(rule: RuleId, reason: ReasonCode, finding?: RuleFinding): RuleResult;
+/** A not-evaluated result (schema-invalid short-circuit or prereq-failed only). */
+export declare function notEvaluated(rule: RuleId, reason: 'not-evaluated.schema-invalid' | 'not-evaluated.prereq-failed'): RuleResult;

package/dist/rules/no-orphan-refs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @adrkit/evaluator — rule 4: no-orphan-refs (error).
+ *
+ * Local `supersedes` / `relatesTo` targets must resolve. A federated ref (`<log>:<id>`)
+ * resolves against a supplied federated-log snapshot; a federated ref whose log has NO
+ * snapshot is inert (`federated-log-absent`), never an orphan failure (C2). `supersededBy`
+ * is owned by supersession-consistent and is not re-reported here. Exactly one aggregate
+ * result (C11); status precedence keeps a dangling failure above a federated inert.
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateNoOrphanRefs(ctx: RuleContext): RuleResult;

package/dist/rules/schema-valid.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/evaluator — rule 1: schema-valid (error).
+ *
+ * Reads only the parse/contract findings on `proposalPath` (data-model §3). Any such
+ * finding => fail (error); the orchestrator then emits ten `not-evaluated` results
+ * (C11). Lower-level rule/path/id/field/pattern evidence is preserved in report-only
+ * `RuleFinding` fields; `RuleFinding.adr` stays strictly an AdrRef and never holds a
+ * filesystem path (T017).
+ */
+import type { ProposalResolution, RuleResult } from '../types.js';
+export declare function evaluateSchemaValid(resolution: ProposalResolution): RuleResult;

package/dist/rules/scope-hierarchy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @adrkit/evaluator — rule 7: scope-hierarchy (error).
+ *
+ * A `component` proposal that overlaps an APPLICABLE accepted `org` ADR whose assertion
+ * was GREEN on the supplied base input and FAILS on the supplied proposed input is an
+ * attributable contradiction ⇒ error (research §R5). Domain applicability is explicit:
+ * an org ADR with no domain is global; otherwise it applies only on exact domain
+ * equality. The evaluator itself compiles + evaluates the accepted assertion (it never
+ * accepts a precomputed verdict). Missing engine/source/base/proposed evidence is inert;
+ * a non-component proposal or one with no applicable org overlap passes.
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateScopeHierarchy(ctx: RuleContext): RuleResult;

package/dist/rules/supersession-consistent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @adrkit/evaluator — rule 3: supersession-consistent (error).
+ *
+ * New deterministic reciprocity + cycle checks over the corpus snapshot (research
+ * §R3), reusing `buildAdrGraph` for EDGES ONLY. Reciprocity: `A supersedes B` iff
+ * `B.supersededBy === A`. `dangling-supersededBy` is owned exclusively by this rule
+ * (C2) and suppresses the redundant non-reciprocal finding for the same ref. Cycles
+ * in the supersedes relation fail with `cycle`. Exactly one aggregate result (C11).
+ */
+import type { RuleContext } from './context.js';
+import type { RuleResult } from '../types.js';
+export declare function evaluateSupersessionConsistent(ctx: RuleContext): RuleResult;

package/dist/targets/canonical.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @adrkit/evaluator — canonical target normalization + record resolution (T035, R4/ADR-0009).
+ *
+ * Resolves a record's `affects` matchers to a finite canonical target-id set, honoring
+ * ADR-0009 semantics: union non-negated matches, subtract matching negations, require
+ * at least one positive matcher (negation-only ⇒ empty), and apply a `repo` qualifier
+ * only when it equals the caller-supplied current resolution `log` (a different-repo
+ * qualifier contributes no local match). The current log is passed explicitly to every
+ * resolver port; it is never inferred from a record's source `log`.
+ */
+import type { Adr, AffectsType } from '@adrkit/core';
+import type { CanonicalTargetId, CanonicalTargetKey, TargetInventorySnapshots, TargetResolutionRegistry } from '../types.js';
+/** Normalize a repo-relative path id to posix form (no leading `./`, no backslashes). */
+export declare function normalizePathId(path: string): string;
+export declare function makeTargetId(kind: AffectsType, id: string): CanonicalTargetId;
+/** The outcome of resolving a single applied `affects` matcher. */
+export interface MatcherResolution {
+    readonly type: AffectsType;
+    readonly pattern: string;
+    readonly negate: boolean;
+    /** `resolved` includes a different-repo matcher (deterministic empty locally). */
+    readonly status: 'resolved' | 'inert-backing' | 'inert-resolver';
+    readonly ids: readonly CanonicalTargetId[];
+}
+export interface RecordTargetResolution {
+    /** Final, unique, canonically-ordered target ids (positive − negated). */
+    readonly targets: readonly CanonicalTargetId[];
+    readonly targetKeys: ReadonlySet<CanonicalTargetKey>;
+    /** Per-applied-matcher outcomes, so each matcher can be validated independently (C3, finding #2). */
+    readonly matchers: readonly MatcherResolution[];
+    readonly hasMatchers: boolean;
+    readonly hasPositiveMatcher: boolean;
+}
+/** True if any matcher could not be resolved (missing inventory or resolver port). */
+export declare function anyMatcherInert(resolution: RecordTargetResolution): boolean;
+/** Resolve one record's affects matchers against the registry + inventory. */
+export declare function resolveRecordTargets(record: Adr, registry: TargetResolutionRegistry, inventory: TargetInventorySnapshots, resolutionLog: string | undefined): RecordTargetResolution;

package/dist/targets/package.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/evaluator — built-in `package` target resolver.
+ *
+ * Reuses core's neutral `matchPackagePattern` grammar (name + optional semver range)
+ * over a complete dependency inventory, per dependency — without copying the grammar
+ * or importing semver directly (that stays a core-internal concern). A missing
+ * `dependencies` inventory is inert (backing-absent); an unparseable pattern resolves
+ * to the empty set. Pure.
+ */
+import type { TargetResolverPort } from '../types.js';
+export declare function createPackageTargetResolver(): TargetResolverPort;

package/dist/targets/path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @adrkit/evaluator — built-in `path` target resolver.
+ *
+ * Reuses core's neutral repo-relative path-glob primitive (`matchPathPattern`) over a
+ * complete tracked-path inventory — it never copies the grammar. A missing
+ * `trackedPaths` inventory is inert (backing-absent); a bad/leading-slash pattern
+ * resolves to the empty set (⇒ affects-resolvable zero-targets, not a throw). Pure.
+ */
+import type { TargetResolverPort } from '../types.js';
+export declare function createPathTargetResolver(): TargetResolverPort;

package/dist/targets/registry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/evaluator — target resolver registry.
+ *
+ * A registry is a pure lookup from `AffectsType` to a deterministic resolver port.
+ * A lookup miss makes the corresponding matcher inert (`resolver-absent`), never a
+ * failure. Ports are built only by trusted composition code — never selected by JSON.
+ */
+import type { TargetResolutionRegistry, TargetResolverPort } from '../types.js';
+export declare function createTargetResolutionRegistry(ports: readonly TargetResolverPort[]): TargetResolutionRegistry;
+/** A registry with no resolvers — every target matcher is `resolver-absent` inert. */
+export declare const emptyTargetResolutionRegistry: TargetResolutionRegistry;