@astrale-os/sdk 0.5.0-beta.8 → 0.5.0-beta.80

package/dist/tooling/linter/catalog/compile.js

@@ -0,0 +1,110 @@
+import { LinterToolError } from '../diagnostics/index.js';
+const HEADER = ['id', 'scope', 'kind', 'severity', 'message', 'verification', 'example'];
+const RULE_KINDS = new Set([
+    'architecture',
+    'structure',
+    'dependency',
+    'declaration',
+    'dataflow',
+    'behavior',
+    'evidence',
+]);
+const RULE_SEVERITIES = new Set(['error', 'warning']);
+const ID = /^[A-Z]+(?:-[A-Z]+)+$/;
+const SCOPE = /^[a-z][a-z0-9.-]*$/;
+const EXAMPLE = /^[a-z][a-z0-9-]*[.]md$/;
+const MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+const MAX_RULES = 512;
+const MAX_CELL_BYTES = 16 * 1024;
+export function compileRuleCatalog(source) {
+    if (typeof source !== 'string')
+        invalid('Rule catalog must be a string.');
+    const bytes = Buffer.byteLength(source, 'utf8');
+    if (bytes > MAX_CATALOG_BYTES) {
+        invalid(`Rule catalog is ${bytes} bytes; maximum is ${MAX_CATALOG_BYTES}.`);
+    }
+    if (source.includes('\r'))
+        invalid('Rule catalog must use LF line endings.');
+    if (!source.endsWith('\n'))
+        invalid('Rule catalog must end with one newline.');
+    if (source.endsWith('\n\n'))
+        invalid('Rule catalog must not contain empty rows.');
+    const lines = source.slice(0, -1).split('\n');
+    const header = lines.shift()?.split('\t') ?? [];
+    if (!same(header, HEADER)) {
+        invalid(`Rule catalog header must be exactly: ${HEADER.join('\t')}`);
+    }
+    if (lines.length > MAX_RULES) {
+        invalid(`Rule catalog has ${lines.length} rows; maximum is ${MAX_RULES}.`);
+    }
+    const seen = new Set();
+    const rules = lines.map((line, index) => {
+        const number = index + 2;
+        if (!line)
+            invalid(`Rule catalog row ${number} is empty.`);
+        const cells = line.split('\t');
+        if (cells.length !== HEADER.length) {
+            invalid(`Rule catalog row ${number} has ${cells.length} cells; expected ${HEADER.length}.`);
+        }
+        for (let cell = 0; cell < cells.length; cell += 1) {
+            const value = cells[cell] ?? '';
+            if (!value)
+                invalid(`Rule catalog row ${number} has an empty ${HEADER[cell]} cell.`);
+            if (Buffer.byteLength(value, 'utf8') > MAX_CELL_BYTES) {
+                invalid(`Rule catalog row ${number} ${HEADER[cell]} exceeds ${MAX_CELL_BYTES} bytes.`);
+            }
+            if (hasControl(value)) {
+                invalid(`Rule catalog row ${number} has a control character in ${HEADER[cell]}.`);
+            }
+            if (value !== value.trim()) {
+                invalid(`Rule catalog row ${number} has surrounding whitespace in ${HEADER[cell]}.`);
+            }
+        }
+        const [id, scope, kind, severity, message, verification, example] = cells;
+        if (!ID.test(id) || id.length > 18)
+            invalid(`Rule catalog row ${number} has invalid ID ${id}.`);
+        if (seen.has(id))
+            invalid(`Rule catalog contains duplicate ID ${id}.`);
+        seen.add(id);
+        if (!SCOPE.test(scope))
+            invalid(`Rule ${id} has invalid scope ${scope}.`);
+        if (!RULE_KINDS.has(kind))
+            invalid(`Rule ${id} has invalid kind ${kind}.`);
+        if (!RULE_SEVERITIES.has(severity)) {
+            invalid(`Rule ${id} has invalid severity ${severity}.`);
+        }
+        if (!EXAMPLE.test(example))
+            invalid(`Rule ${id} has invalid example ${example}.`);
+        return Object.freeze({
+            id,
+            scope,
+            kind: kind,
+            severity: severity,
+            message,
+            verification,
+            example,
+        });
+    });
+    if (rules.length === 0)
+        invalid('Rule catalog must contain at least one rule.');
+    const byId = new Map(rules.map((rule) => [rule.id, rule]));
+    return Object.freeze({
+        size: rules.length,
+        rules: Object.freeze(rules),
+        get(id) {
+            return byId.get(id);
+        },
+    });
+}
+function hasControl(value) {
+    return Array.from(value).some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31) || code === 127;
+    });
+}
+function same(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function invalid(message) {
+    throw new LinterToolError(message, { code: 'LINTER_POLICY_INVALID' });
+}

package/dist/tooling/linter/catalog/index.d.ts

@@ -0,0 +1,18 @@
+export { compileRuleCatalog } from './compile.js';
+export { ruleRevision } from './revision.js';
+export type RuleKind = 'architecture' | 'structure' | 'dependency' | 'declaration' | 'dataflow' | 'behavior' | 'evidence';
+export type RuleSeverity = 'error' | 'warning';
+export interface RuleDefinition {
+    readonly id: string;
+    readonly scope: string;
+    readonly kind: RuleKind;
+    readonly severity: RuleSeverity;
+    readonly message: string;
+    readonly verification: string;
+    readonly example: string;
+}
+export interface RuleCatalog {
+    readonly size: number;
+    readonly rules: readonly RuleDefinition[];
+    get(id: string): RuleDefinition | undefined;
+}

package/dist/tooling/linter/catalog/index.js

@@ -0,0 +1,2 @@
+export { compileRuleCatalog } from './compile.js';
+export { ruleRevision } from './revision.js';

package/dist/tooling/linter/catalog/revision.d.ts

@@ -0,0 +1,6 @@
+import type { RuleDefinition } from './index.js';
+/**
+ * Revision the governed evaluation meaning. Presentation policy remains in the
+ * complete policy digest and does not unnecessarily stale a compatible verifier.
+ */
+export declare function ruleRevision(definition: RuleDefinition): string;

package/dist/tooling/linter/catalog/revision.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+const REVISION_DOMAIN = 'astrale-domain-rule-evaluation-revision:v1\n';
+/**
+ * Revision the governed evaluation meaning. Presentation policy remains in the
+ * complete policy digest and does not unnecessarily stale a compatible verifier.
+ */
+export function ruleRevision(definition) {
+    return createHash('sha256')
+        .update(REVISION_DOMAIN)
+        .update([definition.id, definition.scope, definition.kind, definition.verification].join('\0'), 'utf8')
+        .digest('hex');
+}

package/dist/tooling/linter/diagnostics/error.d.ts

@@ -0,0 +1,9 @@
+import type { LinterToolErrorCode } from './index.js';
+export declare class LinterToolError extends Error {
+    readonly exitCode: 2;
+    readonly code: LinterToolErrorCode;
+    constructor(message: string, options: {
+        readonly code: LinterToolErrorCode;
+        readonly cause?: unknown;
+    });
+}

package/dist/tooling/linter/diagnostics/error.js

@@ -0,0 +1,9 @@
+export class LinterToolError extends Error {
+    exitCode = 2;
+    code;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'LinterToolError';
+        this.code = options.code;
+    }
+}

package/dist/tooling/linter/diagnostics/index.d.ts

@@ -0,0 +1,28 @@
+import type { RuleKind } from '../catalog/index.js';
+export { LinterToolError } from './error.js';
+export { sortDiagnostics } from './sort.js';
+export type DiagnosticKind = 'violation' | 'ambiguity';
+export type DiagnosticSeverity = 'error' | 'warning' | 'notice';
+export type DiagnosticSource = 'domain-rule' | 'linter' | 'oxlint';
+export type DiagnosticAnalysisKind = RuleKind | 'generic';
+export type AmbiguityReason = 'analysis-limit' | 'dynamic-value' | 'external-evidence' | 'insufficient-evidence' | 'unresolved-import' | 'unresolved-symbol' | 'unsupported-syntax';
+export interface DiagnosticLocation {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly offset?: number;
+    readonly length?: number;
+}
+export interface LintDiagnostic {
+    readonly id: string;
+    readonly source: DiagnosticSource;
+    readonly scope: string;
+    readonly analysis: DiagnosticAnalysisKind;
+    readonly kind: DiagnosticKind;
+    readonly ambiguityReason?: AmbiguityReason;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly evidence?: string;
+    readonly location?: DiagnosticLocation;
+}
+export type LinterToolErrorCode = 'LINTER_CANCELLED' | 'LINTER_POLICY_INVALID' | 'LINTER_RULE_COVERAGE' | 'LINTER_RULE_FAILED' | 'LINTER_PROJECT_INVALID' | 'LINTER_PREFLIGHT_FAILED' | 'LINTER_SEMANTIC_FAILED' | 'OXLINT_CANCELLED' | 'OXLINT_FAILED' | 'OXLINT_INVALID_OUTPUT' | 'OXLINT_NOT_INSTALLED' | 'OXLINT_OUTPUT_LIMIT' | 'OXLINT_START_FAILED' | 'OXLINT_TIMEOUT';

package/dist/tooling/linter/diagnostics/index.js

@@ -0,0 +1,2 @@
+export { LinterToolError } from './error.js';
+export { sortDiagnostics } from './sort.js';

package/dist/tooling/linter/diagnostics/sort.d.ts

@@ -0,0 +1,2 @@
+import type { LintDiagnostic } from './index.js';
+export declare function sortDiagnostics(input: readonly LintDiagnostic[]): LintDiagnostic[];

package/dist/tooling/linter/diagnostics/sort.js

@@ -0,0 +1,26 @@
+export function sortDiagnostics(input) {
+    const unique = new Map();
+    for (const diagnostic of input) {
+        const location = diagnostic.location;
+        const key = [
+            diagnostic.source,
+            diagnostic.id,
+            diagnostic.kind,
+            location?.path ?? '',
+            location?.line ?? 0,
+            location?.column ?? 0,
+            diagnostic.evidence ?? '',
+        ].join('\0');
+        unique.set(key, diagnostic);
+    }
+    return [...unique.values()].sort((left, right) => {
+        const leftLocation = left.location;
+        const rightLocation = right.location;
+        return ((leftLocation?.path ?? '').localeCompare(rightLocation?.path ?? '') ||
+            (leftLocation?.line ?? 0) - (rightLocation?.line ?? 0) ||
+            (leftLocation?.column ?? 0) - (rightLocation?.column ?? 0) ||
+            left.id.localeCompare(right.id) ||
+            left.kind.localeCompare(right.kind) ||
+            (left.evidence ?? '').localeCompare(right.evidence ?? ''));
+    });
+}

package/dist/tooling/linter/evaluation/binding/bind.d.ts

@@ -0,0 +1,4 @@
+import type { RuleCatalog } from '../../catalog/index.js';
+import type { DomainRulePack } from '../../packs/index.js';
+import type { EvaluationBinding, EvaluationBindingOptions, RuleImplementationPlan } from '../contract/index.js';
+export declare function bindEvaluation<TInput>(catalog: RuleCatalog, pack: DomainRulePack, plan: RuleImplementationPlan<TInput>, options?: EvaluationBindingOptions): EvaluationBinding<TInput>;

package/dist/tooling/linter/evaluation/binding/bind.js

@@ -0,0 +1,384 @@
+import { ruleRevision } from '../../catalog/index.js';
+import { LinterToolError, } from '../../diagnostics/index.js';
+import { diagnostic } from './diagnostic.js';
+const TOKEN = /^[a-z][a-z0-9.-]{0,63}$/;
+const REVISION = /^[a-f0-9]{64}$/;
+const RULE_ID = /^[A-Z]+(?:-[A-Z]+)+$/;
+const MAX_VERSION_BYTES = 128;
+const MAX_EVIDENCE_BYTES = 8 * 1024;
+const MAX_FINDINGS_PER_RULE = 128;
+const AMBIGUITY_REASONS = new Set([
+    'analysis-limit',
+    'dynamic-value',
+    'external-evidence',
+    'insufficient-evidence',
+    'unresolved-import',
+    'unresolved-symbol',
+    'unsupported-syntax',
+]);
+export function bindEvaluation(catalog, pack, plan, options = {}) {
+    if (!plan || typeof plan !== 'object')
+        coverageFailure('Rule implementation plan is malformed.');
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        coverageFailure('Rule evaluation binding options are malformed.');
+    }
+    if (!plan.evidenceAdmission ||
+        typeof plan.evidenceAdmission !== 'object' ||
+        typeof plan.evidenceAdmission.assertLocation !== 'function') {
+        coverageFailure('Rule implementation plan has no evidence admission.');
+    }
+    const evidenceAdmission = Object.freeze({
+        assertLocation: plan.evidenceAdmission.assertLocation,
+    });
+    const definitions = admitPack(catalog, pack);
+    const registry = admitImplementations(catalog, pack, definitions, plan.available);
+    const unavailable = admitUnavailable(definitions, registry, plan.unavailable);
+    const disabled = admitDisabled(definitions, options.disabledRuleIds ?? []);
+    const coverage = coverageFor(definitions, registry, unavailable, disabled);
+    return Object.freeze({
+        coverage,
+        assertAvailable(requiredRuleIds) {
+            if (!Array.isArray(requiredRuleIds))
+                coverageFailure('Required rule IDs must be an array.');
+            const seen = new Set();
+            const unavailable = [];
+            for (const id of requiredRuleIds) {
+                if (typeof id !== 'string' || !RULE_ID.test(id)) {
+                    coverageFailure('Required rule IDs must contain valid rule identifiers.');
+                }
+                if (seen.has(id))
+                    coverageFailure(`Required rule ID ${id} is repeated.`);
+                seen.add(id);
+                if (!definitions.some((definition) => definition.id === id)) {
+                    coverageFailure(`Required rule ${id} is absent from pack ${pack.id}.`);
+                }
+                if (!registry.has(id) || disabled.has(id))
+                    unavailable.push(id);
+            }
+            if (unavailable.length > 0) {
+                coverageFailure(`Required rules are unavailable: ${unavailable.join(', ')}.`);
+            }
+        },
+        async evaluate(input, signal) {
+            ensureActive(signal);
+            const diagnostics = [];
+            const outcomes = [];
+            for (const definition of definitions) {
+                if (disabled.has(definition.id))
+                    continue;
+                const implementation = registry.get(definition.id);
+                if (!implementation)
+                    continue;
+                ensureActive(signal);
+                let value;
+                try {
+                    value = await implementation.evaluate(input);
+                }
+                catch (cause) {
+                    if (signal?.aborted)
+                        cancelled(signal.reason ?? cause);
+                    throw new LinterToolError(`Rule implementation failed for ${definition.id}.`, {
+                        code: 'LINTER_RULE_FAILED',
+                        cause,
+                    });
+                }
+                const decision = admitDecision(definition.id, value, input, evidenceAdmission);
+                if (decision.status === 'fail' || decision.status === 'indeterminate') {
+                    diagnostics.push(...decision.findings.map((finding) => diagnostic(definition, finding)));
+                }
+                outcomes.push(Object.freeze({
+                    id: definition.id,
+                    status: decision.status,
+                    ...(decision.evidence ? { evidence: decision.evidence } : {}),
+                    implementation: implementation.implementation,
+                }));
+            }
+            return Object.freeze({
+                diagnostics: Object.freeze(diagnostics),
+                outcomes: Object.freeze(outcomes),
+            });
+        },
+    });
+}
+function admitDisabled(definitions, input) {
+    if (!Array.isArray(input))
+        coverageFailure('Disabled rule IDs must be an array.');
+    const inPack = new Set(definitions.map(({ id }) => id));
+    const disabled = new Set();
+    for (const id of input) {
+        if (typeof id !== 'string' || !RULE_ID.test(id) || !inPack.has(id)) {
+            coverageFailure('Disabled rule IDs must name known pack rules.');
+        }
+        if (disabled.has(id))
+            coverageFailure(`Disabled rule ID ${id} is repeated.`);
+        disabled.add(id);
+    }
+    return disabled;
+}
+function admitUnavailable(definitions, registry, input) {
+    if (!Array.isArray(input))
+        coverageFailure('Rule unavailability declarations must be an array.');
+    const inPack = new Set(definitions.map(({ id }) => id));
+    const unavailable = new Map();
+    for (const entry of input) {
+        if (!entry || typeof entry !== 'object' || !inPack.has(entry.ruleId)) {
+            coverageFailure('Rule unavailability declaration names an unknown pack rule.');
+        }
+        if (entry.reason !== 'no-compatible-implementation' &&
+            entry.reason !== 'required-facts-unavailable' &&
+            entry.reason !== 'implementation-disabled') {
+            coverageFailure(`Rule ${entry.ruleId} has an invalid unavailability reason.`);
+        }
+        if (registry.has(entry.ruleId)) {
+            coverageFailure(`Rule ${entry.ruleId} is both available and unavailable.`);
+        }
+        if (unavailable.has(entry.ruleId)) {
+            coverageFailure(`Rule ${entry.ruleId} has several unavailability declarations.`);
+        }
+        unavailable.set(entry.ruleId, entry.reason);
+    }
+    return unavailable;
+}
+function admitPack(catalog, pack) {
+    if (pack.id !== 'astrale.domain')
+        coverageFailure('Domain rule pack has an invalid ID.');
+    admitIdentity({ id: pack.id, version: pack.version }, 'Rule pack');
+    if (!Array.isArray(pack.ruleIds) || !Array.isArray(pack.requirements)) {
+        coverageFailure('Domain rule pack is malformed.');
+    }
+    const seen = new Set();
+    for (const id of pack.ruleIds) {
+        if (seen.has(id))
+            coverageFailure(`Rule pack repeats ${id}.`);
+        seen.add(id);
+        if (!catalog.get(id))
+            coverageFailure(`Rule pack names unknown catalog rule ${id}.`);
+    }
+    const missing = catalog.rules.filter(({ id }) => !seen.has(id));
+    if (missing.length > 0) {
+        coverageFailure(`Rule pack omits catalog rules: ${missing.map(({ id }) => id).join(', ')}.`);
+    }
+    if (pack.requirements.length !== pack.ruleIds.length) {
+        coverageFailure('Rule pack requirement coverage is incomplete.');
+    }
+    for (let index = 0; index < pack.requirements.length; index += 1) {
+        if (pack.requirements[index]?.ruleId !== pack.ruleIds[index]) {
+            coverageFailure('Rule pack requirements and rule IDs are not aligned.');
+        }
+    }
+    return Object.freeze(pack.ruleIds.map((id) => catalog.get(id)));
+}
+function admitImplementations(catalog, pack, definitions, implementations) {
+    if (!Array.isArray(implementations))
+        coverageFailure('Rule implementations must be an array.');
+    const inPack = new Set(definitions.map(({ id }) => id));
+    const registry = new Map();
+    for (const implementation of implementations) {
+        if (!implementation || typeof implementation !== 'object') {
+            coverageFailure('Rule implementation is malformed.');
+        }
+        if (registry.has(implementation.ruleId)) {
+            coverageFailure(`Rule ${implementation.ruleId} has several implementations.`);
+        }
+        const definition = catalog.get(implementation.ruleId);
+        if (!definition || !inPack.has(implementation.ruleId)) {
+            coverageFailure(`Implementation names unknown pack rule ${implementation.ruleId}.`);
+        }
+        admitIdentity(implementation.implementation, `Implementation ${implementation.ruleId}`);
+        if (!REVISION.test(implementation.ruleRevision)) {
+            coverageFailure(`Implementation ${implementation.ruleId} has an invalid rule revision.`);
+        }
+        const expected = ruleRevision(definition);
+        if (implementation.ruleRevision !== expected) {
+            coverageFailure(`Implementation ${implementation.ruleId} implements revision ${implementation.ruleRevision}; catalog requires ${expected}.`);
+        }
+        const requiredFacts = pack.requirements.find(({ ruleId }) => ruleId === implementation.ruleId).facts;
+        if (!Array.isArray(implementation.requiredFacts) ||
+            implementation.requiredFacts.length !== requiredFacts.length ||
+            implementation.requiredFacts.some((fact, index) => fact !== requiredFacts[index])) {
+            coverageFailure(`Implementation ${implementation.ruleId} has drifted fact requirements.`);
+        }
+        if (typeof implementation.evaluate !== 'function') {
+            coverageFailure(`Implementation ${implementation.ruleId} has no evaluator.`);
+        }
+        registry.set(implementation.ruleId, Object.freeze({
+            ruleId: implementation.ruleId,
+            ruleRevision: implementation.ruleRevision,
+            requiredFacts: Object.freeze([...implementation.requiredFacts]),
+            implementation: Object.freeze({
+                id: implementation.implementation.id,
+                version: implementation.implementation.version,
+            }),
+            evaluate: implementation.evaluate,
+        }));
+    }
+    return registry;
+}
+function admitIdentity(identity, owner) {
+    if (!identity || typeof identity !== 'object' || !TOKEN.test(identity.id)) {
+        coverageFailure(`${owner} has an invalid ID.`);
+    }
+    if (typeof identity.version !== 'string' ||
+        !identity.version.trim() ||
+        Buffer.byteLength(identity.version, 'utf8') > MAX_VERSION_BYTES) {
+        coverageFailure(`${owner} has an invalid version.`);
+    }
+}
+function coverageFor(definitions, registry, unavailable, disabled) {
+    const rules = definitions.map((definition) => {
+        if (disabled.has(definition.id)) {
+            return Object.freeze({
+                id: definition.id,
+                state: 'unavailable',
+                reason: 'implementation-disabled',
+            });
+        }
+        const implementation = registry.get(definition.id);
+        return implementation
+            ? Object.freeze({
+                id: definition.id,
+                state: 'available',
+                implementation: implementation.implementation,
+            })
+            : Object.freeze({
+                id: definition.id,
+                state: 'unavailable',
+                reason: unavailable.get(definition.id) ?? 'no-compatible-implementation',
+            });
+    });
+    const available = rules.filter(({ state }) => state === 'available').length;
+    return Object.freeze({
+        total: definitions.length,
+        available,
+        unavailable: definitions.length - available,
+        rules: Object.freeze(rules),
+    });
+}
+function admitDecision(id, value, input, evidenceAdmission) {
+    if (!record(value))
+        ruleFailure(`Implementation ${id} returned a malformed decision.`);
+    if (value.status !== 'pass' &&
+        value.status !== 'not-applicable' &&
+        value.status !== 'fail' &&
+        value.status !== 'indeterminate' &&
+        value.status !== 'error') {
+        ruleFailure(`Implementation ${id} returned an invalid status.`);
+    }
+    const evidence = value.evidence === undefined ? undefined : boundedText(value.evidence, id);
+    if (value.status === 'error') {
+        if (!evidence)
+            ruleFailure(`Implementation ${id} error has no evidence.`);
+        if (value.findings !== undefined)
+            ruleFailure(`Implementation ${id} error contains findings.`);
+        return Object.freeze({ status: 'error', evidence });
+    }
+    if (value.status === 'pass' || value.status === 'not-applicable') {
+        if (value.findings !== undefined) {
+            ruleFailure(`Implementation ${id} ${value.status} result contains findings.`);
+        }
+        return Object.freeze({ status: value.status, ...(evidence ? { evidence } : {}) });
+    }
+    if (!Array.isArray(value.findings) || value.findings.length === 0) {
+        ruleFailure(`Implementation ${id} ${value.status} result has no findings.`);
+    }
+    if (value.findings.length > MAX_FINDINGS_PER_RULE) {
+        ruleFailure(`Implementation ${id} returned too many findings.`);
+    }
+    const findings = value.findings.map((finding) => admitFinding(id, finding, input, evidenceAdmission));
+    const derived = findings.some(({ kind }) => kind === 'fail') ? 'fail' : 'indeterminate';
+    if (value.status !== derived) {
+        ruleFailure(`Implementation ${id} status does not match its findings.`);
+    }
+    return Object.freeze({
+        status: derived,
+        findings: Object.freeze(findings),
+        ...(evidence ? { evidence } : {}),
+    });
+}
+function admitFinding(id, value, input, evidenceAdmission) {
+    if (!record(value) || (value.kind !== 'fail' && value.kind !== 'indeterminate')) {
+        ruleFailure(`Implementation ${id} returned a malformed finding.`);
+    }
+    const evidence = boundedText(value.evidence, id);
+    let ambiguityReason;
+    if (value.kind === 'fail') {
+        if (value.ambiguityReason !== undefined) {
+            ruleFailure(`Fail finding ${id} has an ambiguity reason.`);
+        }
+    }
+    else if (value.ambiguityReason === undefined) {
+        ambiguityReason = 'insufficient-evidence';
+    }
+    else if (typeof value.ambiguityReason !== 'string' ||
+        !AMBIGUITY_REASONS.has(value.ambiguityReason)) {
+        ruleFailure(`Indeterminate finding ${id} has an invalid reason.`);
+    }
+    else
+        ambiguityReason = value.ambiguityReason;
+    const location = value.location === undefined
+        ? undefined
+        : admitLocation(id, value.location, input, evidenceAdmission);
+    return Object.freeze({
+        kind: value.kind,
+        evidence,
+        ...(ambiguityReason ? { ambiguityReason } : {}),
+        ...(location ? { location } : {}),
+    });
+}
+function admitLocation(id, value, input, evidenceAdmission) {
+    if (!record(value) ||
+        typeof value.path !== 'string' ||
+        !positive(value.line) ||
+        !positive(value.column)) {
+        ruleFailure(`Implementation ${id} returned an invalid location.`);
+    }
+    const hasOffset = value.offset !== undefined;
+    const hasLength = value.length !== undefined;
+    if (hasOffset !== hasLength)
+        ruleFailure(`Implementation ${id} location has an incomplete span.`);
+    if (hasOffset) {
+        if (!nonnegative(value.offset) || !positive(value.length)) {
+            ruleFailure(`Implementation ${id} returned an invalid span.`);
+        }
+    }
+    const location = Object.freeze({
+        path: value.path,
+        line: value.line,
+        column: value.column,
+        ...(hasOffset ? { offset: value.offset, length: value.length } : {}),
+    });
+    evidenceAdmission.assertLocation(id, location, input);
+    return location;
+}
+function boundedText(value, id) {
+    if (typeof value !== 'string' || !value.trim()) {
+        ruleFailure(`Implementation ${id} returned empty evidence.`);
+    }
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > MAX_EVIDENCE_BYTES) {
+        ruleFailure(`Implementation ${id} evidence is ${bytes} bytes; maximum is ${MAX_EVIDENCE_BYTES}.`);
+    }
+    return value;
+}
+function ensureActive(signal) {
+    if (signal?.aborted)
+        cancelled(signal.reason);
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function positive(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+function nonnegative(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function coverageFailure(message) {
+    throw new LinterToolError(message, { code: 'LINTER_RULE_COVERAGE' });
+}
+function ruleFailure(message) {
+    throw new LinterToolError(message, { code: 'LINTER_RULE_FAILED' });
+}
+function cancelled(cause) {
+    throw new LinterToolError('Domain lint was cancelled.', { code: 'LINTER_CANCELLED', cause });
+}

package/dist/tooling/linter/evaluation/binding/diagnostic.d.ts

@@ -0,0 +1,4 @@
+import type { RuleDefinition } from '../../catalog/index.js';
+import type { LintDiagnostic } from '../../diagnostics/index.js';
+import type { RuleEvidence } from '../contract/index.js';
+export declare function diagnostic(definition: RuleDefinition, finding: RuleEvidence): LintDiagnostic;

package/dist/tooling/linter/evaluation/binding/diagnostic.js

@@ -0,0 +1,16 @@
+export function diagnostic(definition, finding) {
+    return Object.freeze({
+        id: definition.id,
+        source: 'domain-rule',
+        scope: definition.scope,
+        analysis: definition.kind,
+        kind: finding.kind === 'fail' ? 'violation' : 'ambiguity',
+        ...(finding.kind === 'indeterminate'
+            ? { ambiguityReason: finding.ambiguityReason ?? 'insufficient-evidence' }
+            : {}),
+        severity: finding.kind === 'indeterminate' ? 'notice' : definition.severity,
+        message: definition.message,
+        evidence: finding.evidence,
+        ...(finding.location ? { location: finding.location } : {}),
+    });
+}

package/dist/tooling/linter/evaluation/binding/index.d.ts

@@ -0,0 +1 @@
+export { bindEvaluation } from './bind.js';

package/dist/tooling/linter/evaluation/binding/index.js

@@ -0,0 +1 @@
+export { bindEvaluation } from './bind.js';