import { PathOp, PointerPath, PointerPathShapeError, STRICT_POINTER_POLICY, ShapePolicy, compilePointerPath, evaluatePointerPath, isTerminalFilterCompatiblePointerPath, pointerPathRoot, runPointerFilterTerminal, runPointerGet } from "./pointer-path.mjs";

//#region src/shared/schema.d.ts
type InputSource = 'literal' | 'file' | 'stdin' | 'env';
type PermissionEffect = 'allow' | 'deny' | 'approval';
/**
 * Resolve a raw effect string from config/YAML to its canonical PermissionEffect.
 * Unknown values are passed through as-is (TypeScript callers are already typed).
 */
declare function resolvePermissionEffect(raw: PermissionEffect | string): PermissionEffect;
type PermissionAction = 'read' | 'write' | 'invoke';
interface PermissionRule {
  endpoint?: string;
  tool?: string;
  action?: PermissionAction;
  notebook?: string;
  path?: string;
  root_id?: string;
  effect: PermissionEffect;
  note?: string;
}
interface PermissionConfig {
  default?: PermissionEffect;
  rules?: PermissionRule[];
}
interface PermissionRuleValidationError {
  message: string;
}
declare function validatePermissionRulesRaw(permission: unknown, scope: string): PermissionRuleValidationError[];
interface RawApiBehaviorConfig {
  enabled?: boolean;
  allow?: string[];
}
interface BehaviorConfig {
  allowYes?: boolean;
  approval?: {
    timeout?: number;
    autoOpen?: boolean;
    openDebounceMs?: number;
  };
  rawApi?: RawApiBehaviorConfig;
}
/** Fully resolved behavior with all fields populated. Used after merge. */
interface ResolvedRawApiBehaviorConfig {
  enabled: boolean;
  allow: string[];
}
interface ResolvedBehaviorConfig {
  allowYes: boolean;
  approval: {
    timeout: number;
    autoOpen: boolean;
    openDebounceMs: number;
  };
  rawApi: ResolvedRawApiBehaviorConfig;
}
interface BehaviorValidationError {
  kind: 'error';
  message: string;
}
interface BehaviorValidationWarning {
  kind: 'warning';
  key: string;
}
type BehaviorValidationResult = BehaviorValidationError | BehaviorValidationWarning;
/**
 * Validate a raw behavior value from parsed YAML.
 * Returns an array of errors and warnings. Errors are fatal; warnings are informational.
 */
declare function validateBehaviorRaw(behavior: unknown, scope: string): BehaviorValidationResult[];
/** Context assembled at evaluation time. All fields optional — unset = wildcard. */
interface PermissionContext {
  endpoint?: string;
  tool?: string;
  action?: PermissionAction;
  notebook?: string;
  path?: string;
}
type ToolTag = 'read' | 'write' | 'aggregate' | 'util';
type GuardFieldKind = 'id' | 'path' | 'notebook';
type FormatStrategy = 'direct' | 'records' | 'transaction' | 'object' | 'json';
type EndpointAction = PermissionAction;
type EndpointDomain = 'meta' | 'content' | 'config' | 'storage' | 'runtime' | 'network' | 'ui';
type EndpointConcern = 'notify' | 'process-exit' | 'high-load' | 'reindex' | 'id-regeneration' | 'filesystem' | 'network-request' | 'unbounded-read';
type EndpointCardinality = 'single' | 'batch' | 'global';
type SeverityLabel = 'low' | 'medium' | 'high';
/** @deprecated Use EndpointAction. */
type EndpointMode = EndpointAction;
/** @deprecated Use EndpointClassification['domain']. */
type EndpointSurface = 'meta' | 'content' | 'asset' | 'workspace' | 'runtime' | 'network';
/** @deprecated Use EndpointCardinality. */
type EndpointScope = EndpointCardinality;
/** @deprecated Removed in new classification model. */
type EndpointOperation = 'inspect' | 'search' | 'query' | 'create' | 'update' | 'delete' | 'move' | 'upload' | 'control';
/** @deprecated Use SeverityLabel. */
type RiskLabel = 'safe' | 'sensitive' | 'elevated' | 'destructive' | 'critical';
type ResourceKind = 'id' | 'notebook' | 'path' | 'workspace-path';
type JSONSchemaProperty = {
  type?: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object' | 'null';
  description?: string;
  enum?: readonly unknown[];
  default?: unknown;
  pattern?: string;
  items?: JSONSchemaProperty;
  properties?: Record<string, JSONSchemaProperty>;
  required?: readonly string[];
  additionalProperties?: boolean;
  format?: string;
};
type JSONSchema = JSONSchemaProperty & {
  type: 'object';
  properties: Record<string, JSONSchemaProperty>;
};
interface CliBehavior {
  /** If the payload has exactly one required string field, allow positional. */
  primary?: string;
  examples?: Array<{
    command: string;
    description?: string;
  }>;
  /** Short-flag aliases, e.g. { stmt: "s" }. */
  aliases?: Record<string, string>;
  /** Fields to exclude from individual CLI flags; pass them via --json instead. */
  skipFields?: string[];
  /** Allowed input sources per field. Missing entries default to ["literal"]. */
  allowSource?: Record<string, InputSource[]>;
}
interface PayloadTargetSpec {
  path: PointerPath;
  kind: ResourceKind;
  access: 'read' | 'write';
  /** Treat empty string as intentionally absent for optional kernel anchor fields. */
  skipEmpty?: boolean;
}
interface ResponseFilterContext {
  caller?: CallerContext;
  emitWarning?: (warning: Record<string, unknown>) => void;
}
interface FilterSpec {
  /** Payload resource filter contract. */
  payloadTargets?: PayloadTargetSpec[];
  /** @deprecated Legacy payload guard — no endpoint uses this; kept for type compat only. Will be removed. */
  payload?: Record<string, GuardFieldKind>;
  /**
   * Declarative response extractor.
   * `itemsAt` is evaluated against the unwrapped `data` value returned by SiyuanClient,
   * not the raw kernel envelope `{ code, msg, data }`.
   * Examples: `blocks[*]`, `notebooks[*]`, `[*]`.
   */
  response?: {
    /** Minimal pointer syntax: `blocks[*]`, `notebooks[*]`, `[*]`. */itemsAt: PointerPath; /** Which field within each item is the id / path / notebook. */
    fieldMap: Partial<Record<GuardFieldKind, string>>;
  };
  /** Imperative fallback — called if declarative response extractor can't express the logic. */
  filterResponse?: (response: unknown, engine: PermissionEngineLike, context?: ResponseFilterContext) => unknown | Promise<unknown>;
}
interface EndpointClassification {
  action: EndpointAction;
  domain: EndpointDomain;
  concerns?: EndpointConcern[];
  cardinality?: EndpointCardinality;
  severity?: SeverityLabel;
}
/** @deprecated Accepted at registry boundaries during migration. */
interface LegacyEndpointClassification {
  mode: EndpointMode;
  surface: EndpointSurface;
  scope: EndpointScope;
  operation?: EndpointOperation;
  riskOverride?: RiskLabel;
}
type AuthoredEndpointClassification = EndpointClassification | LegacyEndpointClassification;
interface DerivedMeta {
  classification: EndpointClassification;
  tags: string[];
  severity: SeverityLabel;
}
/**
 * Minimal shape of the permission engine that schema guards need.
 * The real engine (src/shared/permission.ts) implements this + more.
 */
interface CallerContext {
  endpoint?: string;
  tool?: string;
}
interface PermissionEngineLike {
  checkEndpoint(id: string): void;
  checkTool(id: string): void;
  checkContentRef(ref: {
    kind: ResourceKind;
    value: string;
    access: 'read' | 'write';
  }, caller?: CallerContext, endpointAction?: PermissionAction): Promise<PermissionEffect>;
  resolveContentIds(ids: string[]): Promise<Map<string, {
    notebook: string;
    path: string;
  }>>;
  resolveContentId(id: string): Promise<{
    notebook: string;
    path: string;
  }>;
  filterItems<T>(items: T[], extract: (item: T) => {
    id?: string;
    path?: string;
    notebook?: string;
  }, caller?: CallerContext, access?: 'read' | 'write'): Promise<{
    kept: T[];
    removed: number;
    reasons: Record<string, number>;
  }>;
  evaluate(ctx: PermissionContext): PermissionEffect;
}
interface EndpointSchema<TResponseData = unknown> {
  /** The only authoritative identity — e.g. "/api/query/sql". */
  endpoint: string;
  summary: string;
  description?: string;
  payload: JSONSchema;
  /** Authored endpoint classification. */
  classification: AuthoredEndpointClassification;
  minKernelVersion?: string;
  deprecated?: {
    replacement?: string;
    removeAt?: string;
    reason?: string;
  };
  /** For endpoints that use multipart/form-data instead of JSON body. */
  multipart?: {
    fileFields: string[];
  };
  cli?: CliBehavior;
  guard?: FilterSpec;
  /** Pre-built compact format strategy. Ignored when `format` is present. */
  formatStrategy?: FormatStrategy;
  /** Optional compact renderer for `siyuan api <id> --print compact`. Takes precedence over formatStrategy. */
  format?: (ctx: EndpointFormatContext<TResponseData>) => string;
}
/** Derived, normalized view of EndpointSchema (produced by the registry). */
interface RegisteredEndpoint {
  schema: EndpointSchema;
  id: string;
  group: string;
  name: string;
  meta: DerivedMeta;
}
interface EndpointFormatContext<T = unknown> {
  endpoint: RegisteredEndpoint;
  payload: unknown;
  responseData: T;
  args: GlobalArgs;
}
interface ToolResult {
  content: string;
  details?: unknown;
  warnings?: string[];
  meta?: {
    elapsedMs?: number;
    filteredCount?: number;
    truncated?: boolean;
  };
}
interface CallEndpointOptions {
  /** Skip permission checks. Use only after tool-level permission check. */
  bypassPermission?: boolean;
}
interface ToolContext {
  client: unknown;
  registry: unknown;
  permission: PermissionEngineLike;
  callEndpoint: <T = unknown>(id: string, payload: unknown, opts?: CallEndpointOptions) => Promise<T>;
  callEndpointRaw: <T = unknown>(endpoint: string, payload: unknown) => Promise<T>;
  logger: unknown;
  args: GlobalArgs;
}
interface GlobalArgs {
  workspace?: string;
  baseUrl?: string;
  token?: string;
  format?: 'json' | 'pretty' | 'yaml';
  print?: 'compact' | 'json';
  debug?: boolean;
  dryRun?: boolean;
  config?: string;
  yes?: boolean;
}
interface ToolClassification {
  action: PermissionAction;
  domain: EndpointDomain;
  concerns?: EndpointConcern[];
  cardinality?: EndpointCardinality;
  severity?: SeverityLabel;
}
interface ToolSchema {
  id: string;
  summary: string;
  description?: string;
  tags?: ToolTag[];
  classification: ToolClassification;
  guard?: Pick<FilterSpec, 'payloadTargets'>;
  input: JSONSchema;
  output?: JSONSchemaProperty;
  cli?: CliBehavior;
  run: (ctx: ToolContext, input: unknown) => Promise<ToolResult>;
}
declare function deriveEndpointId(endpoint: string): {
  id: string;
  group: string;
  name: string;
};
//#endregion
export { AuthoredEndpointClassification, BehaviorConfig, BehaviorValidationError, BehaviorValidationWarning, CallEndpointOptions, CallerContext, CliBehavior, DerivedMeta, EndpointAction, EndpointCardinality, EndpointClassification, EndpointConcern, EndpointDomain, EndpointFormatContext, EndpointMode, EndpointOperation, EndpointSchema, EndpointScope, EndpointSurface, FilterSpec, FormatStrategy, GlobalArgs, GuardFieldKind, InputSource, JSONSchema, JSONSchemaProperty, LegacyEndpointClassification, type PathOp, PayloadTargetSpec, PermissionAction, PermissionConfig, PermissionContext, PermissionEffect, PermissionEngineLike, PermissionRule, PermissionRuleValidationError, type PointerPath, PointerPathShapeError, RawApiBehaviorConfig, RegisteredEndpoint, ResolvedBehaviorConfig, ResolvedRawApiBehaviorConfig, ResourceKind, ResponseFilterContext, RiskLabel, STRICT_POINTER_POLICY, SeverityLabel, type ShapePolicy, ToolClassification, ToolContext, ToolResult, ToolSchema, ToolTag, compilePointerPath, deriveEndpointId, evaluatePointerPath, isTerminalFilterCompatiblePointerPath, pointerPathRoot, resolvePermissionEffect, runPointerFilterTerminal, runPointerGet, validateBehaviorRaw, validatePermissionRulesRaw };