@xnetjs/abuse 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @xnetjs/abuse
+
+Composable abuse, moderation, and reach policy decisions for xNet.
+
+This package is intentionally dependency-light so lower-level packages such as
+`@xnetjs/sync`, `@xnetjs/network`, and `@xnetjs/hub` can adopt the decision types
+without depending on `@xnetjs/data`.
+
+## Core Idea
+
+Adapters gather facts. Pure functions make decisions.
+
+```typescript
+import { decidePublicInteraction } from '@xnetjs/abuse'
+
+const decision = decidePublicInteraction({
+  actor: { firstContact: true },
+  labels: [{ value: 'spam', confidence: 0.6, sourceWeight: 1, sourceDID: 'did:key:z...' }],
+  quality: { slopScore: 0.4 }
+})
+
+console.log(decision.admission) // "quarantine"
+```
+
+## Current Scope
+
+- Shared decision/result types
+- Deterministic reason codes
+- Pure decision helpers for transport, remote mutation, public interaction, and reach
+- Adapter helpers under `@xnetjs/abuse/adapters`
+- Explanation helpers for UI/devtools/audit surfaces
+- Fixtures for tests and future package adapters
+
+## Adapter Entry Point
+
+Protocol packages should keep their local verification, rate-limit, and scoring code local,
+then adapt the result into shared abuse facts:
+
+```typescript
+import { createRemoteAdmissionPipeline } from '@xnetjs/abuse/adapters'
+
+const pipeline = createRemoteAdmissionPipeline({
+  adapt: (event: { signatureValid: boolean; overSizeLimit: boolean; peerScore: number }) => ({
+    surface: 'remoteMutation',
+    crypto: {
+      signatureValid: event.signatureValid
+    },
+    resource: {
+      overSizeLimit: event.overSizeLimit
+    },
+    actor: {
+      peerScore: event.peerScore
+    }
+  })
+})
+
+const result = pipeline.evaluate({
+  signatureValid: false,
+  overSizeLimit: false,
+  peerScore: 100
+})
+
+console.log(result.shouldMutate) // false
+```
+
+Signed moderation schemas live in future `@xnetjs/data` work so this package can stay
+safe for lower-level imports.

package/dist/adapters-B-9W_mn3.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @xnetjs/abuse - Shared abuse decision types.
+ */
+type AbuseSurface = 'transport' | 'remoteMutation' | 'commentThread' | 'messageInbox' | 'searchIndex' | 'feed' | 'crawl' | 'localApi';
+type PolicyScope = 'user' | 'workspace' | 'community' | 'hub' | 'appView' | 'protocol';
+type AbuseAdmission = 'accept' | 'reject' | 'quarantine';
+type AbuseVisibility = 'show' | 'warn' | 'blur' | 'hide';
+type AbuseReach = 'normal' | 'demote' | 'exclude';
+type AbuseResource = 'normal' | 'throttle' | 'block-peer' | 'require-budget';
+type AbuseSeverity = 'low' | 'medium' | 'high' | 'critical';
+type AbuseReviewQueue = 'safety' | 'quality' | 'appeal' | 'operator';
+type AbuseReasonCode = 'accepted' | 'blocked-by-policy' | 'budget-required' | 'failed-admission' | 'first-contact' | 'invalid-doc-binding' | 'invalid-freshness' | 'invalid-hash' | 'invalid-signature' | 'low-confidence-quality-signal' | 'over-rate-limit' | 'over-size-limit' | 'peer-score-block' | 'peer-score-throttle' | 'quality-risk' | 'trusted-abuse-label' | 'trusted-warning-label' | 'unauthorized' | 'unsigned-update' | 'user-override';
+type AbuseLabel = {
+    value: string;
+    sourceDID?: string;
+    sourceWeight: number;
+    confidence: number;
+    expiresAt?: number;
+    evidenceRefs?: readonly string[];
+};
+type AbuseCryptoFacts = {
+    hashValid: boolean;
+    signatureValid: boolean;
+    authorized: boolean;
+    freshnessValid: boolean;
+    docBindingValid: boolean;
+};
+type AbuseResourceFacts = {
+    overSizeLimit: boolean;
+    overRateLimit: boolean;
+    estimatedCost: number;
+    budgetRemaining: number | null;
+};
+type AbuseActorFacts = {
+    did?: string;
+    peerId?: string;
+    firstContact: boolean;
+    peerScore: number;
+    localBlocked: boolean;
+    workspaceBlocked: boolean;
+    hubBlocked: boolean;
+};
+type AbuseQualitySignals = {
+    duplicateScore: number;
+    slopScore: number;
+    citationCoverage: number;
+    provenanceScore: number;
+};
+type AbusePolicyFacts = {
+    peerScoreBlockThreshold: number;
+    peerScoreThrottleThreshold: number;
+    abuseLabelHideThreshold: number;
+    abuseLabelWarnThreshold: number;
+    qualityReviewThreshold: number;
+    qualityWarnThreshold: number;
+    quarantineFirstContact: boolean;
+};
+type AbuseDecisionOverride = Partial<Pick<AbuseDecision, 'visibility' | 'reach' | 'notify' | 'includeInCounters' | 'includeInSearch'>> & {
+    reason?: string;
+};
+type AbuseFacts = {
+    surface: AbuseSurface;
+    crypto?: Partial<AbuseCryptoFacts>;
+    resource?: Partial<AbuseResourceFacts>;
+    actor?: Partial<AbuseActorFacts>;
+    labels?: readonly AbuseLabel[];
+    quality?: Partial<AbuseQualitySignals>;
+    policy?: Partial<AbusePolicyFacts>;
+    override?: AbuseDecisionOverride;
+    now?: number;
+};
+type NormalizedAbuseFacts = {
+    surface: AbuseSurface;
+    crypto: AbuseCryptoFacts;
+    resource: AbuseResourceFacts;
+    actor: AbuseActorFacts;
+    labels: readonly AbuseLabel[];
+    quality: AbuseQualitySignals;
+    policy: AbusePolicyFacts;
+    override?: AbuseDecisionOverride;
+    now: number;
+};
+type PendingLabel = {
+    value: string;
+    confidence: number;
+    reason: AbuseReasonCode;
+    evidenceRefs: readonly string[];
+};
+type PendingSecurityEvent = {
+    eventName: string;
+    severity: AbuseSeverity;
+    reason: AbuseReasonCode;
+};
+type AbuseReviewDecision = {
+    required: false;
+} | {
+    required: true;
+    queue: AbuseReviewQueue;
+    priority: number;
+};
+type AbuseDecision = {
+    admission: AbuseAdmission;
+    visibility: AbuseVisibility;
+    reach: AbuseReach;
+    resource: AbuseResource;
+    notify: boolean;
+    includeInCounters: boolean;
+    includeInSearch: boolean;
+    review: AbuseReviewDecision;
+    reasons: readonly AbuseReasonCode[];
+    evidenceRefs: readonly string[];
+    labelsToEmit: readonly PendingLabel[];
+    telemetry: readonly PendingSecurityEvent[];
+};
+type DecisionExplanationReason = {
+    code: AbuseReasonCode;
+    severity: AbuseSeverity;
+    message: string;
+};
+type DecisionExplanation = {
+    summary: string;
+    reasons: readonly DecisionExplanationReason[];
+};
+
+/**
+ * Privacy-preserving telemetry helpers for abuse decisions.
+ */
+
+type AbusePeerScoreBucket = 'unknown' | '<=10' | '11-30' | '31-50' | '51-80' | '81-100' | '>100';
+type AbuseTelemetryReporter = {
+    reportSecurityEvent(eventName: string, severity: AbuseSeverity, details?: Record<string, unknown>): unknown;
+    reportUsage?(metricName: string, value: number): unknown;
+};
+type RemoteMutationRejectionTelemetry = {
+    eventName: string;
+    severity: AbuseSeverity;
+    details: {
+        actionTaken: 'remote_mutation_rejected';
+        surface: AbuseSurface;
+        primaryReason: AbuseReasonCode;
+        reasons: readonly AbuseReasonCode[];
+        peerHash: string;
+        peerScoreBucket: AbusePeerScoreBucket;
+        resourceAction: AbuseDecision['resource'];
+        shouldThrottle: boolean;
+    };
+};
+type RemoteMutationRejectionTelemetryInput = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+    eventName?: string;
+    peerHashSalt?: string;
+};
+declare function bucketAbusePeerScore(score: number | null | undefined): AbusePeerScoreBucket;
+declare function hashAbusePeerIdentifier(peerId: string | null | undefined, salt?: string): string;
+declare function createRemoteMutationRejectionTelemetry(input: RemoteMutationRejectionTelemetryInput): RemoteMutationRejectionTelemetry | null;
+declare function reportRemoteMutationRejection(telemetry: AbuseTelemetryReporter | undefined, input: RemoteMutationRejectionTelemetryInput): boolean;
+
+/**
+ * Adapter helpers for wiring local package events into abuse decisions.
+ */
+
+type AbuseFactAdapter<TInput> = (input: TInput) => AbuseFacts;
+type AbuseDecisionFunction = (facts: AbuseFacts) => AbuseDecision;
+type AbuseAdapterResult = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+};
+declare function createAbuseFactAdapter<TInput>(adapter: AbuseFactAdapter<TInput>): AbuseFactAdapter<TInput>;
+declare function decideWithAdapter<TInput>(input: TInput, adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): AbuseAdapterResult;
+declare function createAbuseDecisionAdapter<TInput>(adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): (input: TInput) => AbuseAdapterResult;
+type RemoteAdmissionResult = AbuseAdapterResult & {
+    accepted: boolean;
+    shouldMutate: boolean;
+    shouldRelay: boolean;
+    shouldThrottle: boolean;
+};
+type RemoteAdmissionPipeline<TInput> = {
+    evaluate(input: TInput): RemoteAdmissionResult;
+};
+type RemoteAdmissionPipelineOptions<TInput> = {
+    adapt: AbuseFactAdapter<TInput>;
+    decide?: AbuseDecisionFunction;
+    telemetry?: AbuseTelemetryReporter;
+    telemetryEventName?: string;
+    telemetryPeerHashSalt?: string;
+};
+declare function createRemoteAdmissionPipeline<TInput>(options: RemoteAdmissionPipelineOptions<TInput>): RemoteAdmissionPipeline<TInput>;
+
+export { type AbuseLabel as A, type AbuseAdmission as B, type AbuseCryptoFacts as C, type DecisionExplanation as D, type AbuseDecisionOverride as E, type AbuseResourceFacts as F, type AbuseReviewDecision as G, type AbuseSeverity as H, type AbuseVisibility as I, type PendingLabel as J, type PendingSecurityEvent as K, type NormalizedAbuseFacts as N, type PolicyScope as P, type RemoteAdmissionPipeline as R, type AbuseFacts as a, type AbuseDecision as b, type AbuseReasonCode as c, type DecisionExplanationReason as d, type AbuseSurface as e, type AbuseQualitySignals as f, type AbuseReviewQueue as g, type AbuseResource as h, createAbuseDecisionAdapter as i, createAbuseFactAdapter as j, createRemoteAdmissionPipeline as k, decideWithAdapter as l, bucketAbusePeerScore as m, createRemoteMutationRejectionTelemetry as n, hashAbusePeerIdentifier as o, type AbuseAdapterResult as p, type AbuseDecisionFunction as q, reportRemoteMutationRejection as r, type AbuseFactAdapter as s, type RemoteAdmissionPipelineOptions as t, type RemoteAdmissionResult as u, type AbusePeerScoreBucket as v, type AbuseTelemetryReporter as w, type RemoteMutationRejectionTelemetry as x, type RemoteMutationRejectionTelemetryInput as y, type AbuseActorFacts as z };

package/dist/adapters-B63EWOI3.d.ts

@@ -0,0 +1,196 @@
+/**
+ * @xnetjs/abuse - Shared abuse decision types.
+ */
+type AbuseSurface = 'transport' | 'remoteMutation' | 'commentThread' | 'messageInbox' | 'searchIndex' | 'feed' | 'crawl' | 'localApi';
+type PolicyScope = 'user' | 'workspace' | 'community' | 'hub' | 'appView' | 'protocol';
+type AbuseAdmission = 'accept' | 'reject' | 'quarantine';
+type AbuseVisibility = 'show' | 'warn' | 'blur' | 'hide';
+type AbuseReach = 'normal' | 'demote' | 'exclude';
+type AbuseResource = 'normal' | 'throttle' | 'block-peer' | 'require-budget';
+type AbuseSeverity = 'low' | 'medium' | 'high' | 'critical';
+type AbuseReviewQueue = 'safety' | 'quality' | 'appeal' | 'operator';
+type AbuseReasonCode = 'accepted' | 'blocked-by-policy' | 'budget-required' | 'failed-admission' | 'first-contact' | 'invalid-doc-binding' | 'invalid-freshness' | 'invalid-hash' | 'invalid-signature' | 'low-confidence-quality-signal' | 'over-rate-limit' | 'over-size-limit' | 'peer-score-block' | 'peer-score-throttle' | 'quality-risk' | 'trusted-abuse-label' | 'trusted-warning-label' | 'unauthorized' | 'unsigned-update' | 'policy-override' | 'user-override';
+type AbuseLabel = {
+    id?: string;
+    value: string;
+    sourceDID?: string;
+    sourceWeight: number;
+    confidence: number;
+    expiresAt?: number;
+    evidenceRefs?: readonly string[];
+    negates?: string;
+};
+type AbuseCryptoFacts = {
+    hashValid: boolean;
+    signatureValid: boolean;
+    authorized: boolean;
+    freshnessValid: boolean;
+    docBindingValid: boolean;
+};
+type AbuseResourceFacts = {
+    overSizeLimit: boolean;
+    overRateLimit: boolean;
+    estimatedCost: number;
+    budgetRemaining: number | null;
+};
+type AbuseActorFacts = {
+    did?: string;
+    peerId?: string;
+    firstContact: boolean;
+    peerScore: number;
+    localBlocked: boolean;
+    workspaceBlocked: boolean;
+    hubBlocked: boolean;
+    appViewBlocked: boolean;
+};
+type AbuseQualitySignals = {
+    duplicateScore: number;
+    slopScore: number;
+    citationCoverage: number;
+    provenanceScore: number;
+};
+type AbusePolicyFacts = {
+    peerScoreBlockThreshold: number;
+    peerScoreThrottleThreshold: number;
+    abuseLabelHideThreshold: number;
+    abuseLabelWarnThreshold: number;
+    qualityReviewThreshold: number;
+    qualityWarnThreshold: number;
+    quarantineFirstContact: boolean;
+};
+type AbuseDecisionOverrideScope = 'user' | 'workspace' | 'reviewer';
+type AbuseDecisionOverride = Partial<Pick<AbuseDecision, 'visibility' | 'reach' | 'notify' | 'includeInCounters' | 'includeInSearch'>> & {
+    scope?: AbuseDecisionOverrideScope;
+    sourceDID?: string;
+    reason?: string;
+};
+type AbuseFacts = {
+    surface: AbuseSurface;
+    crypto?: Partial<AbuseCryptoFacts>;
+    resource?: Partial<AbuseResourceFacts>;
+    actor?: Partial<AbuseActorFacts>;
+    labels?: readonly AbuseLabel[];
+    quality?: Partial<AbuseQualitySignals>;
+    policy?: Partial<AbusePolicyFacts>;
+    override?: AbuseDecisionOverride;
+    now?: number;
+};
+type NormalizedAbuseFacts = {
+    surface: AbuseSurface;
+    crypto: AbuseCryptoFacts;
+    resource: AbuseResourceFacts;
+    actor: AbuseActorFacts;
+    labels: readonly AbuseLabel[];
+    quality: AbuseQualitySignals;
+    policy: AbusePolicyFacts;
+    override?: AbuseDecisionOverride;
+    now: number;
+};
+type PendingLabel = {
+    value: string;
+    confidence: number;
+    reason: AbuseReasonCode;
+    evidenceRefs: readonly string[];
+};
+type PendingSecurityEvent = {
+    eventName: string;
+    severity: AbuseSeverity;
+    reason: AbuseReasonCode;
+};
+type AbuseReviewDecision = {
+    required: false;
+} | {
+    required: true;
+    queue: AbuseReviewQueue;
+    priority: number;
+};
+type AbuseDecision = {
+    admission: AbuseAdmission;
+    visibility: AbuseVisibility;
+    reach: AbuseReach;
+    resource: AbuseResource;
+    notify: boolean;
+    includeInCounters: boolean;
+    includeInSearch: boolean;
+    review: AbuseReviewDecision;
+    reasons: readonly AbuseReasonCode[];
+    evidenceRefs: readonly string[];
+    labelsToEmit: readonly PendingLabel[];
+    telemetry: readonly PendingSecurityEvent[];
+};
+type DecisionExplanationReason = {
+    code: AbuseReasonCode;
+    severity: AbuseSeverity;
+    message: string;
+};
+type DecisionExplanation = {
+    summary: string;
+    reasons: readonly DecisionExplanationReason[];
+};
+
+/**
+ * Privacy-preserving telemetry helpers for abuse decisions.
+ */
+
+type AbusePeerScoreBucket = 'unknown' | '<=10' | '11-30' | '31-50' | '51-80' | '81-100' | '>100';
+type AbuseTelemetryReporter = {
+    reportSecurityEvent(eventName: string, severity: AbuseSeverity, details?: Record<string, unknown>): unknown;
+    reportUsage?(metricName: string, value: number): unknown;
+};
+type RemoteMutationRejectionTelemetry = {
+    eventName: string;
+    severity: AbuseSeverity;
+    details: {
+        actionTaken: 'remote_mutation_rejected';
+        surface: AbuseSurface;
+        primaryReason: AbuseReasonCode;
+        reasons: readonly AbuseReasonCode[];
+        peerHash: string;
+        peerScoreBucket: AbusePeerScoreBucket;
+        resourceAction: AbuseDecision['resource'];
+        shouldThrottle: boolean;
+    };
+};
+type RemoteMutationRejectionTelemetryInput = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+    eventName?: string;
+    peerHashSalt?: string;
+};
+declare function bucketAbusePeerScore(score: number | null | undefined): AbusePeerScoreBucket;
+declare function hashAbusePeerIdentifier(peerId: string | null | undefined, salt?: string): string;
+declare function createRemoteMutationRejectionTelemetry(input: RemoteMutationRejectionTelemetryInput): RemoteMutationRejectionTelemetry | null;
+declare function reportRemoteMutationRejection(telemetry: AbuseTelemetryReporter | undefined, input: RemoteMutationRejectionTelemetryInput): boolean;
+
+/**
+ * Adapter helpers for wiring local package events into abuse decisions.
+ */
+
+type AbuseFactAdapter<TInput> = (input: TInput) => AbuseFacts;
+type AbuseDecisionFunction = (facts: AbuseFacts) => AbuseDecision;
+type AbuseAdapterResult = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+};
+declare function createAbuseFactAdapter<TInput>(adapter: AbuseFactAdapter<TInput>): AbuseFactAdapter<TInput>;
+declare function decideWithAdapter<TInput>(input: TInput, adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): AbuseAdapterResult;
+declare function createAbuseDecisionAdapter<TInput>(adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): (input: TInput) => AbuseAdapterResult;
+type RemoteAdmissionResult = AbuseAdapterResult & {
+    accepted: boolean;
+    shouldMutate: boolean;
+    shouldRelay: boolean;
+    shouldThrottle: boolean;
+};
+type RemoteAdmissionPipeline<TInput> = {
+    evaluate(input: TInput): RemoteAdmissionResult;
+};
+type RemoteAdmissionPipelineOptions<TInput> = {
+    adapt: AbuseFactAdapter<TInput>;
+    decide?: AbuseDecisionFunction;
+    telemetry?: AbuseTelemetryReporter;
+    telemetryEventName?: string;
+    telemetryPeerHashSalt?: string;
+};
+declare function createRemoteAdmissionPipeline<TInput>(options: RemoteAdmissionPipelineOptions<TInput>): RemoteAdmissionPipeline<TInput>;
+
+export { type AbuseLabel as A, type RemoteMutationRejectionTelemetry as B, type RemoteMutationRejectionTelemetryInput as C, type DecisionExplanation as D, type AbuseActorFacts as E, type AbuseAdmission as F, type AbuseCryptoFacts as G, type AbuseDecisionOverrideScope as H, type AbuseResourceFacts as I, type AbuseReviewDecision as J, type AbuseSeverity as K, type PendingLabel as L, type PendingSecurityEvent as M, type NormalizedAbuseFacts as N, type PolicyScope as P, type RemoteAdmissionPipeline as R, type AbuseFacts as a, type AbuseDecision as b, type AbuseReasonCode as c, type DecisionExplanationReason as d, type AbuseSurface as e, type AbuseQualitySignals as f, type AbuseVisibility as g, type AbuseReach as h, type AbuseReviewQueue as i, type AbuseResource as j, type AbuseDecisionOverride as k, createAbuseDecisionAdapter as l, createAbuseFactAdapter as m, createRemoteAdmissionPipeline as n, decideWithAdapter as o, bucketAbusePeerScore as p, createRemoteMutationRejectionTelemetry as q, hashAbusePeerIdentifier as r, reportRemoteMutationRejection as s, type AbuseAdapterResult as t, type AbuseDecisionFunction as u, type AbuseFactAdapter as v, type RemoteAdmissionPipelineOptions as w, type RemoteAdmissionResult as x, type AbusePeerScoreBucket as y, type AbuseTelemetryReporter as z };

package/dist/adapters-B92QvJK9.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @xnetjs/abuse - Shared abuse decision types.
+ */
+type AbuseSurface = 'transport' | 'remoteMutation' | 'commentThread' | 'messageInbox' | 'searchIndex' | 'feed' | 'crawl' | 'localApi';
+type PolicyScope = 'user' | 'workspace' | 'community' | 'hub' | 'appView' | 'protocol';
+type AbuseAdmission = 'accept' | 'reject' | 'quarantine';
+type AbuseVisibility = 'show' | 'warn' | 'blur' | 'hide';
+type AbuseReach = 'normal' | 'demote' | 'exclude';
+type AbuseResource = 'normal' | 'throttle' | 'block-peer' | 'require-budget';
+type AbuseSeverity = 'low' | 'medium' | 'high' | 'critical';
+type AbuseReviewQueue = 'safety' | 'quality' | 'appeal' | 'operator';
+type AbuseReasonCode = 'accepted' | 'blocked-by-policy' | 'budget-required' | 'failed-admission' | 'first-contact' | 'invalid-doc-binding' | 'invalid-freshness' | 'invalid-hash' | 'invalid-signature' | 'low-confidence-quality-signal' | 'over-rate-limit' | 'over-size-limit' | 'peer-score-block' | 'peer-score-throttle' | 'quality-risk' | 'trusted-abuse-label' | 'trusted-warning-label' | 'unauthorized' | 'unsigned-update' | 'user-override';
+type AbuseLabel = {
+    value: string;
+    sourceDID?: string;
+    sourceWeight: number;
+    confidence: number;
+    expiresAt?: number;
+    evidenceRefs?: readonly string[];
+};
+type AbuseCryptoFacts = {
+    hashValid: boolean;
+    signatureValid: boolean;
+    authorized: boolean;
+    freshnessValid: boolean;
+    docBindingValid: boolean;
+};
+type AbuseResourceFacts = {
+    overSizeLimit: boolean;
+    overRateLimit: boolean;
+    estimatedCost: number;
+    budgetRemaining: number | null;
+};
+type AbuseActorFacts = {
+    did?: string;
+    peerId?: string;
+    firstContact: boolean;
+    peerScore: number;
+    localBlocked: boolean;
+    workspaceBlocked: boolean;
+    hubBlocked: boolean;
+};
+type AbuseQualitySignals = {
+    duplicateScore: number;
+    slopScore: number;
+    citationCoverage: number;
+    provenanceScore: number;
+};
+type AbusePolicyFacts = {
+    peerScoreBlockThreshold: number;
+    peerScoreThrottleThreshold: number;
+    abuseLabelHideThreshold: number;
+    abuseLabelWarnThreshold: number;
+    qualityReviewThreshold: number;
+    qualityWarnThreshold: number;
+    quarantineFirstContact: boolean;
+};
+type AbuseDecisionOverride = Partial<Pick<AbuseDecision, 'visibility' | 'reach' | 'notify' | 'includeInCounters' | 'includeInSearch'>> & {
+    reason?: string;
+};
+type AbuseFacts = {
+    surface: AbuseSurface;
+    crypto?: Partial<AbuseCryptoFacts>;
+    resource?: Partial<AbuseResourceFacts>;
+    actor?: Partial<AbuseActorFacts>;
+    labels?: readonly AbuseLabel[];
+    quality?: Partial<AbuseQualitySignals>;
+    policy?: Partial<AbusePolicyFacts>;
+    override?: AbuseDecisionOverride;
+    now?: number;
+};
+type NormalizedAbuseFacts = {
+    surface: AbuseSurface;
+    crypto: AbuseCryptoFacts;
+    resource: AbuseResourceFacts;
+    actor: AbuseActorFacts;
+    labels: readonly AbuseLabel[];
+    quality: AbuseQualitySignals;
+    policy: AbusePolicyFacts;
+    override?: AbuseDecisionOverride;
+    now: number;
+};
+type PendingLabel = {
+    value: string;
+    confidence: number;
+    reason: AbuseReasonCode;
+    evidenceRefs: readonly string[];
+};
+type PendingSecurityEvent = {
+    eventName: string;
+    severity: AbuseSeverity;
+    reason: AbuseReasonCode;
+};
+type AbuseReviewDecision = {
+    required: false;
+} | {
+    required: true;
+    queue: AbuseReviewQueue;
+    priority: number;
+};
+type AbuseDecision = {
+    admission: AbuseAdmission;
+    visibility: AbuseVisibility;
+    reach: AbuseReach;
+    resource: AbuseResource;
+    notify: boolean;
+    includeInCounters: boolean;
+    includeInSearch: boolean;
+    review: AbuseReviewDecision;
+    reasons: readonly AbuseReasonCode[];
+    evidenceRefs: readonly string[];
+    labelsToEmit: readonly PendingLabel[];
+    telemetry: readonly PendingSecurityEvent[];
+};
+type DecisionExplanationReason = {
+    code: AbuseReasonCode;
+    severity: AbuseSeverity;
+    message: string;
+};
+type DecisionExplanation = {
+    summary: string;
+    reasons: readonly DecisionExplanationReason[];
+};
+
+/**
+ * Privacy-preserving telemetry helpers for abuse decisions.
+ */
+
+type AbusePeerScoreBucket = 'unknown' | '<=10' | '11-30' | '31-50' | '51-80' | '81-100' | '>100';
+type AbuseTelemetryReporter = {
+    reportSecurityEvent(eventName: string, severity: AbuseSeverity, details?: Record<string, unknown>): unknown;
+    reportUsage?(metricName: string, value: number): unknown;
+};
+type RemoteMutationRejectionTelemetry = {
+    eventName: string;
+    severity: AbuseSeverity;
+    details: {
+        actionTaken: 'remote_mutation_rejected';
+        surface: AbuseSurface;
+        primaryReason: AbuseReasonCode;
+        reasons: readonly AbuseReasonCode[];
+        peerHash: string;
+        peerScoreBucket: AbusePeerScoreBucket;
+        resourceAction: AbuseDecision['resource'];
+        shouldThrottle: boolean;
+    };
+};
+type RemoteMutationRejectionTelemetryInput = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+    eventName?: string;
+    peerHashSalt?: string;
+};
+declare function bucketAbusePeerScore(score: number | null | undefined): AbusePeerScoreBucket;
+declare function hashAbusePeerIdentifier(peerId: string | null | undefined, salt?: string): string;
+declare function createRemoteMutationRejectionTelemetry(input: RemoteMutationRejectionTelemetryInput): RemoteMutationRejectionTelemetry | null;
+declare function reportRemoteMutationRejection(telemetry: AbuseTelemetryReporter | undefined, input: RemoteMutationRejectionTelemetryInput): boolean;
+
+/**
+ * Adapter helpers for wiring local package events into abuse decisions.
+ */
+
+type AbuseFactAdapter<TInput> = (input: TInput) => AbuseFacts;
+type AbuseDecisionFunction = (facts: AbuseFacts) => AbuseDecision;
+type AbuseAdapterResult = {
+    facts: AbuseFacts;
+    decision: AbuseDecision;
+};
+declare function createAbuseFactAdapter<TInput>(adapter: AbuseFactAdapter<TInput>): AbuseFactAdapter<TInput>;
+declare function decideWithAdapter<TInput>(input: TInput, adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): AbuseAdapterResult;
+declare function createAbuseDecisionAdapter<TInput>(adapter: AbuseFactAdapter<TInput>, decide?: AbuseDecisionFunction): (input: TInput) => AbuseAdapterResult;
+type RemoteAdmissionResult = AbuseAdapterResult & {
+    accepted: boolean;
+    shouldMutate: boolean;
+    shouldRelay: boolean;
+    shouldThrottle: boolean;
+};
+type RemoteAdmissionPipeline<TInput> = {
+    evaluate(input: TInput): RemoteAdmissionResult;
+};
+type RemoteAdmissionPipelineOptions<TInput> = {
+    adapt: AbuseFactAdapter<TInput>;
+    decide?: AbuseDecisionFunction;
+    telemetry?: AbuseTelemetryReporter;
+    telemetryEventName?: string;
+    telemetryPeerHashSalt?: string;
+};
+declare function createRemoteAdmissionPipeline<TInput>(options: RemoteAdmissionPipelineOptions<TInput>): RemoteAdmissionPipeline<TInput>;
+
+export { type AbuseLabel as A, type AbuseCryptoFacts as B, type AbuseDecisionOverride as C, type DecisionExplanation as D, type AbuseResource as E, type AbuseResourceFacts as F, type AbuseReviewDecision as G, type AbuseSeverity as H, type AbuseVisibility as I, type PendingLabel as J, type PendingSecurityEvent as K, type NormalizedAbuseFacts as N, type PolicyScope as P, type RemoteAdmissionPipeline as R, type AbuseFacts as a, type AbuseDecision as b, type AbuseReasonCode as c, type DecisionExplanationReason as d, type AbuseSurface as e, type AbuseQualitySignals as f, type AbuseReviewQueue as g, createAbuseDecisionAdapter as h, createAbuseFactAdapter as i, createRemoteAdmissionPipeline as j, decideWithAdapter as k, bucketAbusePeerScore as l, createRemoteMutationRejectionTelemetry as m, hashAbusePeerIdentifier as n, type AbuseAdapterResult as o, type AbuseDecisionFunction as p, type AbuseFactAdapter as q, reportRemoteMutationRejection as r, type RemoteAdmissionPipelineOptions as s, type RemoteAdmissionResult as t, type AbusePeerScoreBucket as u, type AbuseTelemetryReporter as v, type RemoteMutationRejectionTelemetry as w, type RemoteMutationRejectionTelemetryInput as x, type AbuseActorFacts as y, type AbuseAdmission as z };