/**
 * Attribution policy module.
 *
 * Central seam for gating durable writes based on the resolved
 * {@link AttributionTier} stamped onto the request. Call
 * {@link enforceAttributionPolicy} at the top of each write-path service
 * so all transports (HTTP, MCP stdio, MCP HTTP, CLI backup) honour the
 * same rules uniformly.
 *
 * Sources of configuration (resolved in priority order, most specific
 * wins):
 *   1. `NEOTOMA_ATTRIBUTION_POLICY=allow|warn|reject` environment variable.
 *   2. `NEOTOMA_MIN_ATTRIBUTION_TIER=hardware|software|unverified_client`.
 *   3. Per-write-path overrides supplied via
 *      `NEOTOMA_ATTRIBUTION_POLICY_JSON` (JSON object keyed by write path).
 *
 * Defaults preserve historical behaviour: everything is allowed, no
 * minimum tier.
 */
import type { AgentIdentity, AttributionTier } from "../crypto/agent_identity.js";
/**
 * Canonical write-path identifier. Used as the per-path override key and
 * mirrored in `enforceAttributionPolicy(writePath, …)` call sites.
 */
export type WritePath = "observations" | "relationships" | "sources" | "interpretations" | "timeline_events" | "corrections";
export type AnonymousWriteMode = "allow" | "warn" | "reject";
/** Shape surfaced on the `/session` response and on error envelopes. */
export interface AttributionPolicySnapshot {
    /** Global policy mode applied to writes with `tier === "anonymous"`. */
    anonymous_writes: AnonymousWriteMode;
    /** Optional floor tier; writes below this tier are rejected. */
    min_tier?: AttributionTier;
    /** Per-write-path overrides; present only when set. */
    per_path?: Partial<Record<WritePath, AnonymousWriteMode>>;
}
/**
 * Resolve the current policy snapshot from environment variables. Always
 * returns a fresh object; callers may surface this to clients without
 * worrying about mutation.
 */
export declare function getAttributionPolicySnapshot(): AttributionPolicySnapshot;
/**
 * Effective mode for a specific write path after applying per-path
 * overrides. Shared helper so {@link enforceAttributionPolicy} and the
 * `/session` eligibility flag agree on the resolved mode.
 */
export declare function effectiveAnonymousWriteMode(policy: AttributionPolicySnapshot, path: WritePath): AnonymousWriteMode;
/**
 * Structured error thrown by {@link enforceAttributionPolicy} when the
 * caller is below the required tier. HTTP handlers surface this as a 403
 * with `code: "ATTRIBUTION_REQUIRED"` (see `src/actions.ts`).
 */
export declare class AttributionPolicyError extends Error {
    readonly code: "ATTRIBUTION_REQUIRED";
    readonly statusCode = 403;
    readonly writePath: WritePath;
    readonly currentTier: AttributionTier;
    readonly minTier: AttributionTier;
    readonly hint: string;
    /** True for transient causes (e.g. AAuth JWKS outage); callers may retry. */
    readonly retryable: boolean;
    constructor(params: {
        writePath: WritePath;
        currentTier: AttributionTier;
        minTier: AttributionTier;
        hint: string;
        retryable?: boolean;
    });
    toErrorEnvelope(): {
        code: string;
        message: string;
        min_tier: AttributionTier;
        current_tier: AttributionTier;
        write_path: WritePath;
        hint: string;
        retryable: boolean;
    };
}
/**
 * Outcome returned by {@link enforceAttributionPolicy}. `action === "reject"`
 * is reported as a thrown error; callers only see `"allow"` or `"warn"`.
 * The `warn` outcome carries a message header so HTTP handlers can add
 * `X-Neotoma-Attribution-Warning`.
 */
export interface PolicyOutcome {
    action: "allow" | "warn";
    warningMessage?: string;
}
/**
 * Enforce the active policy for `writePath` against `identity`. Throws an
 * {@link AttributionPolicyError} on rejection; returns the outcome otherwise.
 * Callers MUST invoke this at the top of each public write method so
 * all transports (HTTP, MCP stdio, MCP HTTP, CLI backup) share one seam.
 *
 * This function is synchronous and cheap: it reads `process.env` once per
 * call. If a future profile caches snapshots, keep this signature stable
 * so call sites don't change.
 */
export declare function enforceAttributionPolicy(writePath: WritePath, identity: AgentIdentity | null): PolicyOutcome;
//# sourceMappingURL=attribution_policy.d.ts.map