@dsh-enhanced/assistant-work-items 0.0.0-stage → 0.1.67

package/lib/admission.js

@@ -0,0 +1,642 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { byteLength, isActive, truncateUtf8 } from "./config.js";
+import { buildAuthorityBasis } from "./authority.js";
+import { resolveAcceptanceBinding } from "./acceptance-binding.js";
+import { buildMandateBasis, decisionRefusal, mandateDigest, normalizeExecuteDecision } from "./mandate.js";
+import { OPEN_STATES, WorkItemError } from "./types.js";
+import { continuationSourceKey } from './continuation-record.js';
+const KIND = /^[a-z][a-z0-9-]{0,63}$/;
+const EXTERNAL_ID = /^[\x20-\x7e]{1,256}$/;
+const BINDING_ID = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,255}$/;
+const SIGNAL_SOURCE = /^[a-z][a-z0-9-]{0,63}$/;
+const SIGNAL_REVISION = /^[\x20-\x7e]{1,128}$/;
+const EVIDENCE_KEY = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
+const THREAD_REF = /^[\x20-\x7e]{1,1024}$/;
+/** Hard cap on followed threads per item; keeps resolution bounded per sweep. */
+const MAX_FOLLOWS = 8;
+const HOUR_MS = 3_600_000;
+/** An item is settled when no further claim can move it without a new signal. */
+function isSettled(state) {
+    return !OPEN_STATES.includes(state);
+}
+function provenanceOf(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        fail('invalid-input', 'provenance must be an object');
+    }
+    const allowed = ['source', 'sourceVersion', 'signalDigest', 'observedAt', 'evidence'];
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            fail('invalid-input', `provenance contains unknown field ${key}`);
+    }
+    const source = text(value.source, 'provenance.source', 64);
+    if (!SIGNAL_SOURCE.test(source))
+        fail('invalid-input', 'provenance.source has an invalid shape');
+    const sourceVersion = text(value.sourceVersion, 'provenance.sourceVersion', 128);
+    if (!SIGNAL_REVISION.test(sourceVersion))
+        fail('invalid-input', 'provenance.sourceVersion has an invalid shape');
+    const signalDigest = text(value.signalDigest, 'provenance.signalDigest', 128);
+    if (!SIGNAL_REVISION.test(signalDigest))
+        fail('invalid-input', 'provenance.signalDigest has an invalid shape');
+    if (typeof value.observedAt !== 'number' || !Number.isSafeInteger(value.observedAt) || value.observedAt <= 0) {
+        fail('invalid-input', 'provenance.observedAt must be a positive integer timestamp');
+    }
+    let evidence;
+    if (value.evidence !== undefined) {
+        if (value.evidence === null || typeof value.evidence !== 'object' || Array.isArray(value.evidence)) {
+            fail('invalid-input', 'provenance.evidence must be an object');
+        }
+        const entries = Object.entries(value.evidence);
+        if (entries.length > 8)
+            fail('invalid-input', 'provenance.evidence accepts at most 8 entries');
+        evidence = {};
+        for (const [key, entry] of entries) {
+            if (!EVIDENCE_KEY.test(key))
+                fail('invalid-input', `provenance.evidence key ${key} has an invalid shape`);
+            if (typeof entry === 'string') {
+                if (byteLength(entry) > 256)
+                    fail('invalid-input', `provenance.evidence.${key} exceeds 256 bytes`);
+                evidence[key] = entry;
+            }
+            else if (typeof entry === 'boolean') {
+                evidence[key] = entry;
+            }
+            else if (typeof entry === 'number' && Number.isFinite(entry)) {
+                evidence[key] = entry;
+            }
+            else {
+                fail('invalid-input', `provenance.evidence.${key} must be a string, number or boolean`);
+            }
+        }
+    }
+    return Object.freeze({
+        source,
+        sourceVersion,
+        signalDigest,
+        observedAt: value.observedAt,
+        ...(evidence === undefined ? {} : { evidence: Object.freeze(evidence) }),
+    });
+}
+/** Validate and dedupe the followed-thread list of one admission input. */
+function threadRefsOf(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        fail('invalid-input', 'follows must be an array of thread references');
+    if (value.length > MAX_FOLLOWS)
+        fail('invalid-input', `follows accepts at most ${MAX_FOLLOWS} thread references`);
+    const seen = new Set();
+    const refs = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            fail('invalid-input', 'each follow must be a thread reference object');
+        }
+        const allowed = ['kind', 'ref'];
+        for (const key of Object.keys(entry)) {
+            const known = allowed.includes(key);
+            if (!known)
+                fail('invalid-input', `follow contains unknown field ${key}`);
+        }
+        const kind = text(entry.kind, 'follows.kind', 64);
+        if (!KIND.test(kind))
+            fail('invalid-input', 'follows.kind has an invalid shape');
+        const ref = text(entry.ref, 'follows.ref', 1024);
+        if (!THREAD_REF.test(ref))
+            fail('invalid-input', 'follows.ref has an invalid shape');
+        // Duplicate refs collapse: an item can follow the same thread only once, so
+        // a repeated ref must not consume another position or budget slot.
+        const key = `${kind}\u0000${ref}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push(Object.freeze({ kind, ref }));
+    }
+    return Object.freeze(refs);
+}
+function fail(code, message, detail) {
+    throw new WorkItemError(code, message, detail);
+}
+function text(value, field, maxBytes) {
+    if (typeof value !== 'string')
+        fail('invalid-input', `${field} must be a string`);
+    const normalized = value.normalize('NFC').trim();
+    if (normalized.length === 0)
+        fail('invalid-input', `${field} must not be empty`);
+    if (byteLength(normalized) > maxBytes)
+        fail('invalid-input', `${field} exceeds ${maxBytes} bytes`);
+    return normalized;
+}
+/** Stable per-source dedup identity for one external work signal. */
+export function dedupKeyFor(sourceId, kind, externalId) {
+    return createHash('sha256').update(`${sourceId}\u0000${kind}\u0000${externalId}`, 'utf8').digest('hex');
+}
+/** Dedup key of an execute decision: source and decision external id only, never the kind. */
+export function decisionDedupKeyFor(sourceId, externalId) {
+    // `execute-decision:v1` cannot be an ordinary kind (KIND forbids `:`), so the
+    // two key domains never collide.
+    return dedupKeyFor(sourceId, 'execute-decision:v1', externalId);
+}
+export function dedupBucketFor(createdAt, windowMs) {
+    return Math.floor(createdAt / windowMs);
+}
+/**
+ * The only write path for external work signals.
+ *
+ * Gate order is fixed and cheap-first, and every rejection happens before any
+ * durable write: an invalid owner route, a duplicate, an unlisted kind, a
+ * cooldown, the hourly rate or the open-item cap all leave the ledger
+ * untouched. In `observe` mode the same pipeline still records the item as
+ * `dropped`/`observe-only` with `observed = 1`, and never calls automations or
+ * delivery.
+ */
+export class WorkItemAdmission {
+    #deps;
+    #config;
+    #now;
+    #newId;
+    constructor(dependencies) {
+        this.#deps = dependencies;
+        this.#config = dependencies.config;
+        this.#now = dependencies.now ?? (() => Date.now());
+        this.#newId = dependencies.newId ?? (() => `wi-${Date.now().toString(36)}-${randomUUID().replace(/-/g, '').slice(0, 12)}`);
+    }
+    /**
+     * Validate and (maybe) admit one signal.
+     *
+     * Returns `created: false` with the existing item when the same signal was
+     * already admitted inside the dedup window.
+     */
+    admit(input) {
+        return this.#admit(input, undefined);
+    }
+    /**
+     * Admit one execute decision under a frozen mandate.
+     *
+     * Order: shape → active-only → owner route → decision replay (any state, any
+     * dedup window; a different mandate under the same id is `identity-mismatch`)
+     * → inferred gate (auto mode, named Policy rule, remaining budget ≥ 1) →
+     * ordinary kind/cooldown/rate/capacity gates → Policy `admit`, whose allowing
+     * rule must equal the named rule. A decision carrying an acceptance handle
+     * is also bound to the verifier's exact contract for this owner scope
+     * (after the inferred gate, before the ordinary gates). Every refusal
+     * happens before any durable write; the mandate is persisted inside the
+     * item's authority basis.
+     */
+    admitDecision(value) {
+        const config = this.#config;
+        if (!config.enabled)
+            fail('disabled', 'the work-item intake is disabled');
+        const decision = normalizeExecuteDecision(value);
+        if (!isActive(config))
+            fail('observe-mode', 'execute decisions are admitted only in active mode');
+        const result = this.#admit(decision.input, decision);
+        if (typeof result === 'string')
+            return Object.freeze({ outcome: 'refused', reasonCode: result });
+        const mandate = result.item.authority?.mandate;
+        if (mandate === undefined)
+            fail('storage', 'decision item is missing its frozen mandate');
+        return Object.freeze({
+            outcome: result.created ? 'admitted' : 'replayed',
+            item: result.item,
+            dispatch: result.dispatch,
+            mandate,
+        });
+    }
+    #admit(input, decision) {
+        const config = this.#config;
+        if (!config.enabled)
+            fail('disabled', 'the work-item intake is disabled');
+        const continuation = isActive(config) ? this.#deps.continuationFor?.(input) : undefined;
+        if (input.kind === 'owner-continuation' && !continuation)
+            fail('invalid-input', 'owner-continuation requires a private continuation mint');
+        const planBuilder = config.diagnosis && isActive(config) ? this.#deps.diagnosisPlanFor?.(input) : undefined;
+        if (continuation && planBuilder)
+            fail('invalid-input', 'continuation and diagnosis plans are exclusive');
+        if (config.diagnosis && isActive(config) && !planBuilder && !continuation)
+            fail('invalid-input', 'diagnosis worker admits only its private canonical source');
+        const now = this.#now();
+        const normalized = this.#normalize(input);
+        const follows = this.#followInputs(normalized.follows);
+        const receipt = this.#validateOwnerRoute(now);
+        const active = isActive(config);
+        if (continuation) {
+            if (continuation.sourceKey !== continuationSourceKey(continuation.parentItemId, continuation.sourceDigest))
+                fail('invalid-input', 'continuation source key differs');
+            const prior = this.#deps.store.findContinuationBySourceKey(continuation.sourceKey);
+            if (prior) {
+                const item = this.#deps.store.findItemById(prior.itemId), scope = config.scope;
+                if (!item || !scope || item.scope.principalId !== scope.principalId || item.scope.ownerRouteId !== scope.ownerRouteId
+                    || item.scope.workspace !== scope.workspace || item.scope.preset !== scope.preset || item.owner.principalRecordId !== receipt.principalRecordId
+                    || item.owner.principalVersion !== receipt.principalVersion || receipt.generation < item.owner.generation
+                    || receipt.generation === item.owner.generation && receipt.bindingVersion !== item.owner.bindingVersion)
+                    fail('identity-mismatch', 'continuation replay owner differs');
+                const dispatch = this.#deps.store.getDispatch(item.id);
+                if (!dispatch)
+                    fail('storage', 'continuation is missing its dispatch row');
+                return Object.freeze({ item, created: false, reason: 'duplicate', dispatch });
+            }
+        }
+        // Lazy recovery keeps the open-item count honest without a timer.
+        if (!config.diagnosis)
+            this.#deps.ledger.recover();
+        // A decision's identity is its id alone: the kind is part of the mandate
+        // (and its digest), not of the key, so the same id under another kind is an
+        // identity mismatch instead of a second item. The key domain is disjoint
+        // from ordinary signals, which cannot squat or withdraw a decision id.
+        const dedupKey = decision === undefined
+            ? dedupKeyFor(config.intakeSourceId, normalized.kind, normalized.externalId)
+            : decisionDedupKeyFor(config.intakeSourceId, normalized.externalId);
+        const dedupBucket = dedupBucketFor(now, config.admission.dedupWindowMs);
+        let mandate;
+        if (decision !== undefined) {
+            const digest = mandateDigest(decision, normalized);
+            // A decision id names exactly one item for its whole life: an open item
+            // in an older window or a settled one both answer the replay; neither
+            // the dedup window nor settlement may open a second item.
+            const prior = this.#deps.store.findLatestItemByDedupKey(dedupKey);
+            if (prior !== undefined) {
+                if (prior.authority?.mandate?.digest !== digest) {
+                    fail('identity-mismatch', 'decision id already admitted a different mandate');
+                }
+                const dispatch = this.#deps.store.getDispatch(prior.id);
+                if (dispatch === undefined)
+                    fail('storage', 'admitted item is missing its dispatch row');
+                return Object.freeze({ item: prior, created: false, reason: 'duplicate', dispatch });
+            }
+            const refusal = decisionRefusal(decision);
+            if (refusal !== undefined)
+                return refusal;
+            let acceptance;
+            if (decision.acceptance !== undefined) {
+                // One contract settles one item: another decision cannot reuse it.
+                // (This decision's own replay already returned above.)
+                if (this.#deps.store.findItemByAcceptanceContract(decision.acceptance.contractId) !== undefined)
+                    return 'acceptance-contract-bound';
+                const verifier = typeof this.#deps.verifier === 'function' ? this.#deps.verifier() : this.#deps.verifier;
+                const resolved = resolveAcceptanceBinding(verifier, decision.acceptance, receipt, now);
+                if (typeof resolved === 'string')
+                    return resolved;
+                acceptance = resolved;
+            }
+            mandate = buildMandateBasis(decision, digest, acceptance);
+        }
+        const existing = this.#deps.store.findItemByDedup(dedupKey, dedupBucket);
+        if (existing !== undefined) {
+            const dispatch = this.#deps.store.getDispatch(existing.id);
+            if (dispatch === undefined)
+                fail('storage', 'admitted item is missing its dispatch row');
+            return Object.freeze({ item: existing, created: false, reason: 'duplicate', dispatch });
+        }
+        // The window is a freshness bound, not a settlement bound: once the same
+        // canonical signal has been settled (completed, blocked, failed, dropped),
+        // a later corrected or withdrawn revision must not revive it as new work.
+        const settled = this.#deps.store.findLatestItemByDedupKey(dedupKey);
+        if (settled !== undefined && isSettled(settled.state)) {
+            const dispatch = this.#deps.store.getDispatch(settled.id);
+            if (dispatch === undefined)
+                fail('storage', 'admitted item is missing its dispatch row');
+            return Object.freeze({ item: settled, created: false, reason: 'fenced', dispatch });
+        }
+        // Canonical rows only: from here to `admitItem` there is no await, so a
+        // source alias (an event `@head`) is pinned in the same synchronous section
+        // that persists it.
+        const admittedFollows = this.#validateFollows(follows);
+        const wouldReject = this.#gateReasons(normalized.kind, now);
+        let authority = null;
+        if (active) {
+            const rejection = wouldReject[0];
+            if (rejection !== undefined)
+                fail(rejectionCode(rejection), rejectionMessage(rejection));
+            const authorized = this.#authorize(active, receipt, normalized.kind, dedupKey, dedupBucket, now, mandate);
+            if (authorized === 'policy-rule-mismatch')
+                return authorized;
+            authority = authorized;
+            if (mandate?.ruleId !== undefined && authority?.ruleId !== mandate.ruleId)
+                return 'policy-rule-mismatch';
+        }
+        const id = this.#newId();
+        const directory = this.#deps.workspace.directoryFor(id);
+        const truncatedBrief = byteLength(normalized.brief) > config.admission.maxBriefBytes;
+        const brief = truncatedBrief ? truncateUtf8(normalized.brief, config.admission.maxBriefBytes).value : normalized.brief;
+        const owner = Object.freeze({
+            principalRecordId: receipt.principalRecordId,
+            principalVersion: receipt.principalVersion,
+            workspace: receipt.workspace,
+            agentPreset: receipt.agentPreset,
+            bindingVersion: receipt.bindingVersion,
+            generation: receipt.generation,
+        });
+        const scope = config.scope;
+        if (scope === null)
+            fail('owner-route-unavailable', 'active admission requires a configured owner scope');
+        const item = Object.freeze({
+            id,
+            dedupKey,
+            dedupBucket,
+            sourceId: config.intakeSourceId,
+            kind: normalized.kind,
+            externalId: normalized.externalId,
+            title: normalized.title,
+            brief,
+            briefTruncated: truncatedBrief,
+            originBindingId: normalized.originBindingId,
+            acceptanceRef: normalized.acceptanceRef,
+            scope,
+            owner,
+            workerAutomationId: config.workerAutomationId ?? '',
+            authority,
+            state: active ? 'queued' : 'dropped',
+            stateReason: active ? null : 'observe-only',
+            attempt: 0,
+            maxAttempts: config.limits.maxAttempts,
+            leaseUntil: null,
+            leaseRunId: null,
+            occurrenceId: null,
+            workDir: directory,
+            lastReportStatus: null,
+            observed: !active,
+            createdAt: now,
+            updatedAt: now,
+        });
+        const dispatch = Object.freeze({
+            itemId: id,
+            automationId: config.workerAutomationId ?? '',
+            eventId: id,
+            occurredAt: now,
+            generation: 0,
+            wakeAttempts: 0,
+            state: active ? 'pending' : 'failed',
+            occurrenceId: null,
+            reason: active ? null : 'observe-only',
+            createdAt: now,
+            updatedAt: now,
+        });
+        const detail = { kind: normalized.kind, dedupBucket };
+        if (normalized.provenance !== null)
+            detail['provenance'] = normalized.provenance;
+        if (!active)
+            detail['wouldReject'] = wouldReject;
+        if (mandate !== undefined) {
+            detail['mandate'] = {
+                decisionId: mandate.decisionId, origin: mandate.origin, digest: mandate.digest,
+                ...(mandate.acceptance === undefined ? {} : {
+                    acceptance: { verifier: mandate.acceptance.verifier, author: mandate.acceptance.author, contractId: mandate.acceptance.contractId, contractDigest: mandate.acceptance.contractDigest },
+                }),
+            };
+        }
+        const continuationRecord = continuation?.create(item);
+        if (continuation && !continuationRecord)
+            fail('invalid-input', 'continuation builder did not freeze a record');
+        if (continuationRecord && (continuationRecord.sourceKey !== continuation.sourceKey || continuationRecord.sourceDigest !== continuation.sourceDigest || continuationRecord.parentItemId !== continuation.parentItemId))
+            fail('invalid-input', 'continuation builder changed its source identity');
+        const persisted = this.#deps.store.admitItem(item, {
+            kind: active ? 'admitted' : 'observed',
+            actor: 'admission',
+            detail,
+        }, dispatch, admittedFollows, planBuilder?.(item), continuationRecord);
+        if (persisted.id !== item.id) {
+            const existingDispatch = this.#deps.store.getDispatch(persisted.id);
+            if (!existingDispatch)
+                fail('storage', 'continuation is missing its dispatch row');
+            return Object.freeze({ item: persisted, created: false, reason: 'duplicate', dispatch: existingDispatch });
+        }
+        return Object.freeze({ item, created: true, dispatch });
+    }
+    /**
+     * Retire the open item a withdrawn signal already produced, if any.
+     *
+     * Withdrawal shares `admit()`'s normalization and dedup identity, so a
+     * `cancelled` revision of an execution resolves to the same item as its
+     * `failed` revision. Every open row of that key is retired, not just the
+     * newest: the dedup window may have rolled while an older item stayed open.
+     * It deliberately skips the owner-route re-anchor, Policy
+     * authorization, cooldown, kind/rate/capacity gates and ledger recovery:
+     * those bound *new* work, while withdrawal only reduces pending work. It
+     * cannot recall a report already handed to `assistant-delivery`; it retires
+     * open state and a still-pending wake-up, and the worker's next tool call
+     * observes the dropped item.
+     */
+    withdraw(input) {
+        const config = this.#config;
+        if (!config.enabled)
+            fail('disabled', 'the work-item intake is disabled');
+        // Normalization is shared with admission, so a malformed withdrawal —
+        // including a malformed provenance shape — is rejected rather than guessed.
+        const normalized = this.#normalize(input);
+        const dedupKey = dedupKeyFor(config.intakeSourceId, normalized.kind, normalized.externalId);
+        // The dedup window is a freshness bound, so settle the whole dedup key
+        // across windows: a withdrawal may arrive long after the failure it
+        // cancels, and an older still-open row must not survive it.
+        const withdrawn = this.#deps.store.withdrawByDedupKey(dedupKey, {
+            sourceId: normalized.provenance?.source ?? config.intakeSourceId,
+            externalId: normalized.externalId,
+            observedAt: normalized.provenance?.observedAt ?? this.#now(),
+        });
+        return Object.freeze({ outcome: withdrawn.outcome, items: withdrawn.items });
+    }
+    /** Gates that would reject this kind right now; empty when it may proceed. */
+    #gateReasons(kind, now) {
+        const config = this.#config;
+        const reasons = [];
+        if (!config.admission.allowedKinds.includes(kind))
+            reasons.push('kind-rejected');
+        const lastSameKind = this.#deps.store.lastAdmitAt(kind);
+        if (lastSameKind !== null && now - lastSameKind < config.admission.cooldownMs)
+            reasons.push('cooldown');
+        if (this.#deps.store.countItemsSince(now - HOUR_MS) >= config.admission.maxAdmitsPerHour)
+            reasons.push('rate-limited');
+        if (this.#deps.store.countOpenItems() >= config.admission.maxOpenItems)
+            reasons.push('capacity');
+        return Object.freeze(reasons);
+    }
+    #authorize(active, receipt, kind, dedupKey, dedupBucket, now, mandate) {
+        if (!active)
+            return null;
+        const policy = this.#deps.policy;
+        if (policy === undefined)
+            fail('missing-dependency', 'assistantPolicy is required for active admission');
+        const scope = this.#config.scope;
+        if (scope === null)
+            fail('owner-route-unavailable', 'active admission requires a configured owner scope');
+        const sourceId = this.#config.intakeSourceId;
+        const automationId = this.#config.workerAutomationId ?? '';
+        const request = {
+            subject: {
+                kind: 'background',
+                id: sourceId,
+                workspace: receipt.workspace,
+                principal: receipt.principalId,
+            },
+            action: 'admit',
+            resource: { kind: 'automation', id: automationId },
+            context: { initiator: 'background' },
+        };
+        const idempotencyKey = `work-item-admit:${dedupKey}:${String(dedupBucket)}`;
+        // A named rule is checked with the side-effect-free `evaluate` first, so a
+        // decision another rule would allow is refused without consuming the
+        // rule's authorization budget or writing an audit row. A deny falls
+        // through to `authorize`, which audits it as before. Older Policy peers
+        // without `evaluate` keep the post-authorize check below in `#admit`.
+        if (mandate?.ruleId !== undefined && typeof policy.evaluate === 'function') {
+            const preview = policy.evaluate(request);
+            if (preview.effect === 'allow' && preview.ruleId !== mandate.ruleId)
+                return 'policy-rule-mismatch';
+        }
+        const decision = policy.authorize(request, { idempotencyKey });
+        if (decision.effect !== 'allow') {
+            fail('source-rejected', `policy denied admission (${decision.reasonCode})`, kind);
+        }
+        return buildAuthorityBasis({ request, decision, sourceId, automationId, idempotencyKey, checkedAt: now, ...(mandate === undefined ? {} : { mandate }) });
+    }
+    /** Re-anchor the configured owner scope against the live delivery route. */
+    #validateOwnerRoute(now) {
+        const scope = this.#config.scope;
+        if (scope === null)
+            fail('owner-route-unavailable', 'no owner scope is configured');
+        if (scope.expiresAt <= now)
+            fail('owner-route-expired', 'the configured owner scope expired');
+        const delivery = typeof this.#deps.delivery === 'function' ? this.#deps.delivery() : this.#deps.delivery;
+        if (delivery === undefined)
+            fail('owner-route-unavailable', 'assistantDelivery is required to validate the owner route');
+        let receipt;
+        try {
+            receipt = delivery.validateOwnerRoute({
+                authorityId: scope.ownerRouteId,
+                principalId: scope.principalId,
+                workspace: scope.workspace,
+                agentPreset: scope.preset,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const code = error !== null && typeof error === 'object' && 'code' in error && error.code === 'missing-binding'
+                ? 'owner-route-invalid'
+                : 'owner-route-unavailable';
+            fail(code, 'owner route validation failed', detail);
+        }
+        if (receipt.receiptVersion !== 2)
+            fail('owner-route-invalid', 'owner route receipt has an unsupported version');
+        if (receipt.authorityId !== scope.ownerRouteId || receipt.workspace !== scope.workspace
+            || receipt.agentPreset !== scope.preset || receipt.principalId !== scope.principalId) {
+            fail('owner-route-invalid', 'owner route receipt does not match the configured scope');
+        }
+        if (receipt.principalRecordId === '' || !Number.isSafeInteger(receipt.principalVersion)) {
+            fail('owner-route-invalid', 'owner route receipt is missing its durable principal identity');
+        }
+        return receipt;
+    }
+    #normalize(input) {
+        if (input === null || typeof input !== 'object' || Array.isArray(input))
+            fail('invalid-input', 'admission input must be an object');
+        const allowed = ['kind', 'externalId', 'title', 'brief', 'originBindingId', 'acceptanceRef', 'provenance', 'follows'];
+        for (const key of Object.keys(input)) {
+            if (!allowed.includes(key))
+                fail('invalid-input', `admission input contains unknown field ${key}`);
+        }
+        const kind = text(input.kind, 'kind', 64);
+        if (!KIND.test(kind))
+            fail('kind-rejected', 'kind has an invalid shape');
+        const externalId = text(input.externalId, 'externalId', 256);
+        if (!EXTERNAL_ID.test(externalId) || externalId.includes('\u0000'))
+            fail('invalid-input', 'externalId has an invalid shape');
+        const title = text(input.title, 'title', 512);
+        const brief = text(input.brief, 'brief', Math.min(this.#config.admission.maxBriefBytes * 4, 262_144));
+        const originBindingId = text(input.originBindingId, 'originBindingId', 256);
+        if (!BINDING_ID.test(originBindingId))
+            fail('invalid-input', 'originBindingId has an invalid shape');
+        const acceptanceRef = input.acceptanceRef === undefined ? null : text(input.acceptanceRef, 'acceptanceRef', 1_024);
+        const provenance = input.provenance === undefined ? null : provenanceOf(input.provenance);
+        return { kind, externalId, title, brief, originBindingId, acceptanceRef, provenance, follows: threadRefsOf(input.follows) };
+    }
+    /**
+     * Resolve admitted follow refs to durable follow rows.
+     *
+     * The registration is read once at admission so the stored `source` and
+     * `source_generation` are immutable facts of that admission: a later change of
+     * the source's generation degrades the follow rather than rewriting it.
+     */
+    #followInputs(follows) {
+        if (follows.length === 0)
+            return Object.freeze([]);
+        const resolved = follows.map(ref => {
+            const registration = this.#deps.threadSource?.(ref.kind);
+            if (registration === undefined) {
+                fail('invalid-input', `followed thread kind ${ref.kind} has no registered source`);
+            }
+            return Object.freeze({
+                kind: ref.kind,
+                ref: ref.ref,
+                source: registration.source,
+                sourceGeneration: registration.generation,
+            });
+        });
+        return Object.freeze(resolved);
+    }
+    /**
+     * Run each source's optional admission `validate` for a new item. Called
+     * only after every replay/dedup/fence answer, so retrying an already admitted
+     * signal returns its duplicate even when the ref is no longer admissible
+     * (for example an event cursor that has since been passed).
+     *
+     * A source's optional `canonicalize` rewrites each ref first; `validate` and
+     * the stored row see only the canonical form, and refs that canonicalize to
+     * the same thread collapse like literal duplicates.
+     */
+    #validateFollows(follows) {
+        const seen = new Set();
+        const admitted = [];
+        for (const follow of follows) {
+            const registration = this.#deps.threadSource?.(follow.kind);
+            if (registration === undefined || registration.source !== follow.source || registration.generation !== follow.sourceGeneration) {
+                fail('invalid-input', `followed thread kind ${follow.kind} has no registered source`);
+            }
+            let ref = follow.ref;
+            if (registration.canonicalize !== undefined) {
+                try {
+                    ref = registration.canonicalize(follow.ref);
+                }
+                catch {
+                    ref = undefined;
+                }
+                if (typeof ref !== 'string' || !THREAD_REF.test(ref)) {
+                    fail('invalid-input', `followed thread ref is not admissible for source ${registration.source}`);
+                }
+            }
+            if (registration.validate !== undefined) {
+                let accepted = false;
+                try {
+                    accepted = registration.validate(ref) === true;
+                }
+                catch {
+                    accepted = false;
+                }
+                if (!accepted)
+                    fail('invalid-input', `followed thread ref is not admissible for source ${registration.source}`);
+            }
+            const key = `${follow.kind}\u0000${ref}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            admitted.push(ref === follow.ref ? follow : Object.freeze({ ...follow, ref }));
+        }
+        return Object.freeze(admitted);
+    }
+}
+function rejectionCode(reason) {
+    switch (reason) {
+        case 'kind-rejected': return 'kind-rejected';
+        case 'cooldown': return 'cooldown';
+        case 'rate-limited': return 'rate-limited';
+        case 'capacity': return 'capacity';
+        default: return 'invalid-input';
+    }
+}
+function rejectionMessage(reason) {
+    switch (reason) {
+        case 'kind-rejected': return 'this work-item kind is not admitted';
+        case 'cooldown': return 'this work-item kind is inside its admission cooldown';
+        case 'rate-limited': return 'the hourly admission rate is exhausted';
+        case 'capacity': return 'the open work-item cap is reached';
+        default: return 'admission rejected the signal';
+    }
+}
+//# sourceMappingURL=admission.js.map