import { type AssetReference, type ResourceIntegrity } from "@skenora/contracts";
import type { ResolvedResource, ResourceAcquireOptions, ResourceDescriptor, ResourceLicenseMetadata, ResourceResolver, ResourceScopeOptions, ResourceTechnicalMetadata } from "./types.js";
export type LogicalAssetRef = string;
export interface ResourceBindingRequirement {
    readonly assetRef: LogicalAssetRef;
    readonly kind: AssetReference["kind"];
    readonly mediaType?: string;
    readonly integrity?: ResourceIntegrity;
}
/**
 * A host-created binding from a plan-level logical reference to an authorized
 * scene asset. The resources package does not perform authorization; callers
 * must only provide references that have already passed host policy.
 */
export interface ResourceBinding {
    readonly assetRef: LogicalAssetRef;
    readonly asset: Readonly<AssetReference>;
}
export type ResourceBindingIssueCode = "invalid-asset-ref" | "duplicate-asset-ref" | "duplicate-requirement" | "missing-binding" | "unexpected-binding" | "invalid-asset" | "missing-source" | "invalid-kind" | "invalid-media-type" | "kind-mismatch" | "media-type-mismatch" | "invalid-integrity" | "integrity-mismatch";
export interface ResourceBindingIssue {
    readonly code: ResourceBindingIssueCode;
    readonly path: readonly (string | number)[];
    readonly message: string;
    readonly assetRef?: LogicalAssetRef;
}
export interface ResourceBindingValidationResult {
    readonly valid: boolean;
    readonly issues: readonly ResourceBindingIssue[];
}
export interface ResourceBindingValidationOptions {
    /** Reject bindings not declared by the supplied requirements. */
    readonly allowAdditionalBindings?: boolean;
}
export interface ResourceBindingTable {
    readonly size: number;
    readonly bindings: readonly ResourceBinding[];
    get(assetRef: LogicalAssetRef): ResourceBinding | undefined;
    require(assetRef: LogicalAssetRef): ResourceBinding;
}
export declare class ResourceBindingValidationError extends Error {
    readonly issues: readonly ResourceBindingIssue[];
    constructor(issues: readonly ResourceBindingIssue[]);
}
/** Validates plan requirements without acquiring resources or performing I/O. */
export declare function validateResourceBindings(bindings: readonly Readonly<ResourceBinding>[], requirements?: readonly Readonly<ResourceBindingRequirement>[], options?: Readonly<ResourceBindingValidationOptions>): ResourceBindingValidationResult;
/**
 * Creates an immutable lookup table for a validated binding set. Asset values
 * are cloned and frozen so a plan execution cannot observe caller mutation.
 */
export declare function createResourceBindingTable(bindings: readonly Readonly<ResourceBinding>[], requirements?: readonly Readonly<ResourceBindingRequirement>[], options?: Readonly<ResourceBindingValidationOptions>): ResourceBindingTable;
export interface ModelVisibleResourceDescriptor {
    /** Opaque logical reference selected by the host, never a provider id. */
    readonly resourceRef: LogicalAssetRef;
    readonly label: string;
    readonly kind: AssetReference["kind"];
    readonly description?: string;
    readonly tags?: readonly string[];
    readonly mediaType?: string;
    readonly integrity?: ResourceIntegrity;
    readonly technical?: ResourceTechnicalMetadata;
    readonly license?: ResourceLicenseMetadata;
}
/**
 * Projects a provider descriptor into a model-visible DTO. Source, thumbnail,
 * provider id, and every locator-bearing field are intentionally omitted.
 */
export declare function toModelVisibleResourceDescriptor(descriptor: Readonly<ResourceDescriptor>, resourceRef: LogicalAssetRef): ModelVisibleResourceDescriptor;
export interface ResourceLease {
    readonly assetRef: LogicalAssetRef;
    /** Internal authorized reference; never pass this object to the model. */
    readonly asset: Readonly<AssetReference>;
    /** Resolves while the lease remains retained; release invalidates the URL. */
    readonly resource: Promise<ResolvedResource>;
    /** Idempotently releases this lease and its underlying ResourceScope. */
    release(): void;
}
export interface ResourceBindingScopeOptions extends ResourceScopeOptions {
    readonly requirements?: readonly Readonly<ResourceBindingRequirement>[];
    readonly validation?: Readonly<ResourceBindingValidationOptions>;
}
export interface ResourceBindingScope {
    readonly bindings: ResourceBindingTable;
    /** Starts acquisition and returns a release handle before provider resolve. */
    acquire(assetRef: LogicalAssetRef, options?: ResourceAcquireOptions): ResourceLease;
    acquireAll(assetRefs: readonly LogicalAssetRef[], options?: ResourceAcquireOptions): readonly ResourceLease[];
    dispose(): void;
}
/**
 * Coordinates one ResourceScope per logical lease. Releasing a lease or
 * disposing this scope delegates to the existing reference-counted cache and
 * Blob URL cleanup.
 */
export declare function createResourceBindingScope(resolver: ResourceResolver, bindings: ResourceBindingTable | readonly Readonly<ResourceBinding>[], options?: Readonly<ResourceBindingScopeOptions>): ResourceBindingScope;
//# sourceMappingURL=resource-bindings.d.ts.map