zen/bindings/nodejs/index.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */

export type PolicyPropertyKind = 'input' | 'computed';
export type PolicyFieldKind = 'scalar' | 'enum' | 'relationship' | 'reference';
export type PolicySeverity = 'error' | 'warning' | 'hint';

/** Text range, `[start, end)` character offsets. */
export type PolicySpan = [number, number];

/** Rename target — a top-level entity, an entity field, a global property,
 *  or a property path within a graph document. */
export type PolicyRenameTarget =
  | { kind: 'entity'; name: string }
  | { kind: 'field'; entity: string; field: string }
  | { kind: 'global'; name: string }
  | { kind: 'graphProperty'; document: string; path: string }
  | { kind: 'graphNode'; document: string; nodeId: string };

/** What kind of span a cursor is sitting in, with any disambiguation. */
export type PolicyCursorTarget =
  | { kind: 'expression'; id: string }
  | { kind: 'assertionOutput' }
  | { kind: 'expressionKey' }
  | { kind: 'matchTarget' }
  | { kind: 'matchValue'; id: string }
  | { kind: 'decisionTableHead'; col: string }
  | { kind: 'decisionTableCell'; row: string; col: string }
  | { kind: 'dataModelName' }
  | { kind: 'dataModelProperty'; id: string }
  | { kind: 'transformInput' };

/**
 * How an entity field came into existence — declared by a DataModel
 * (`schema`) or produced by a rule block (`computed`). Computed fields
 * whose value provably consists of entity instances (identity preserved
 * through filter / index / slice) carry `instanceOf`.
 */
export type PolicyFieldOrigin =
  | { origin: 'schema'; source: string; fieldKind: PolicyFieldKindInfo }
  | { origin: 'computed'; writtenBy: PolicyPropertyWriter; instanceOf?: PolicyInstanceOf };
export type PolicyDiagnosticCode =
  | 'UNDEFINED_VARIABLE'
  | 'TYPE_MISMATCH'
  | 'INVALID_EXPRESSION'
  | 'PARSE_ERROR'
  | 'MISSING_DEFAULT_BRANCH'
  | 'EMPTY_BLOCK'
  | 'MIXED_SCOPE'
  | 'CYCLIC_DEPENDENCY'
  | 'DUPLICATE_WRITER'
  | 'INVALID_WRITE_PATH'
  | 'INPUT_OVERRIDE'
  | 'SELF_REFERENCING_WRITE'
  | 'UNREACHABLE_ENTITY_READ'
  | 'PARTIAL_OBJECT_WRITE'
  | 'DATA_MODEL_COLLISION'
  | 'UNKNOWN_DATA_MODEL_TARGET'
  | 'DUPLICATE_PROPERTY'
  | 'DUPLICATE_ENUM_VALUE'
  | 'INVALID_NAME'
  | 'MAX_DEPTH_EXCEEDED'
  | 'IMPORT_NOT_FOUND'
  | 'CIRCULAR_IMPORT'
  | 'UNSUPPORTED_NESTED_ITERATION'
  | 'INVALID_GRAPH_STRUCTURE'
  | 'UNREACHABLE_NODE'
  | 'MISSING_INPUT_SCHEMA'
  | 'UNRESOLVED_FUNCTION_TYPE'
  | 'IMPLICIT_ANY'
  | 'UNCHECKED_NODE'
  | 'REDUNDANT_NULLISH'
  | 'REPEATED_DERIVATION'
  | 'PREFER_MATCH'
  | 'PREFER_DICTIONARY'
  | 'REDUNDANT_TABLE_ROW'
  | 'NON_DISCRIMINATING_COLUMN'
  | 'REDUNDANT_PARENTHESES';

export type PolicyVariableType =
  | { type: 'any' }
  | { type: 'null' }
  | { type: 'bool' }
  | { type: 'string' }
  | { type: 'number' }
  | { type: 'date' }
  | { type: 'interval' }
  | { type: 'const'; value: string }
  | { type: 'enum'; name: string | null; values: string[] }
  | { type: 'array'; items: PolicyVariableType }
  | { type: 'object'; fields: Record<string, PolicyVariableType> }
  | { type: 'nullable'; inner: PolicyVariableType };

/**
 * Slot-aware autocomplete. `PolicyExpressionCursor.pos` passed to `slot()`, every `span` and
 * `replaceSpan` below are UTF-16 code units (JavaScript string offsets), not bytes.
 */
export type PolicySlotState =
  | 'start'
  | 'unaryStart'
  | 'value'
  | 'listElement'
  | 'range'
  | 'operator'
  | 'logical'
  | 'argument'
  | 'member'
  | 'closure'
  | 'inString'
  | 'path';
export type PolicySlotRole = 'unary' | 'condition' | 'value' | 'path';
/** One enum value: `label` for display, `source` the ready-to-splice ZEN literal (null when unquotable). */
export interface PolicyValueOption {
  value: string;
  label: string;
  source: string | null;
}
export interface PolicyEnumTable {
  name: string | null;
  options: PolicyValueOption[];
}
export interface PolicySlot {
  state: PolicySlotState;
  expected: PolicyVariableType | null;
  operand: PolicyVariableType | null;
  options: PolicyValueOption[];
  operators: string[];
  function: string | null;
  argument: number | null;
  /** `[start, end)` UTF-16 range the accepted suggestion replaces. */
  replaceSpan: PolicySpan;
  inString: string | null;
  listed: string[];
  autoOpen: boolean;
  /** Names bound by enclosing closures at the caret, innermost first (`x` for `as x`, `#` otherwise). */
  locals: Array<{ name: string; type: PolicyVariableType }>;
}
export type PolicyLiteralFact =
  | {
      kind: 'enum';
      span: PolicySpan;
      value: string;
      name: string | null;
      label: string;
      valid: boolean;
      enumIndex: number;
    }
  | {
      kind: 'date';
      span: PolicySpan;
      arg:
        | { kind: 'now' }
        | { kind: 'today' }
        | { kind: 'literal'; value: string; valid: boolean; tz?: string }
        | { kind: 'field'; path: string };
    }
  | { kind: 'bool'; span: PolicySpan; value: boolean };
/** Result of `slot(cursor, text)` and of each `slotBatch` request. */
export interface PolicySlotResponse {
  /** Whether the source is a complete, syntactically valid expression. */
  complete?: boolean;
  kind: 'standard' | 'unary';
  role: PolicySlotRole;
  /** `$` type for unary cells, otherwise the expected value type. */
  subjectType: PolicyVariableType | null;
  expectedType: PolicyVariableType | null;
  slot: PolicySlot;
  literals: PolicyLiteralFact[];
  enums: PolicyEnumTable[];
}
/**
 * One expression location of a policy or graph, returned by `facts(policyPath)`. `source` is the
 * stored text the facts were computed from; `subjectOptions` lists labeled enum values for an
 * empty unary or value cell.
 */
export interface PolicyExpressionFacts {
  complete?: boolean;
  blockId: string;
  target: PolicyCursorTarget;
  source: string;
  kind: 'standard' | 'unary';
  role: PolicySlotRole;
  subjectType: PolicyVariableType | null;
  expectedType: PolicyVariableType | null;
  literals: PolicyLiteralFact[];
  enums: PolicyEnumTable[];
  subjectOptions: PolicyValueOption[];
}

/**
 * Wire-format block — the same shape passed into `setPolicy` / `updateBlock`.
 * The engine emits these inside `replaceBlock` / `insertBlock` edits so a
 * host can swap them in by id without text-span surgery.
 */
export interface PolicyWireBlock {
  id: string;
  type: string;
  props: { dataJson?: string; schemaJson?: string };
}

/**
 * Block-level edit emitted by code-mod operations (rename today; cascade
 * delete / code-actions / extract-refactor planned). Hosts apply each by
 * id-keyed swap (same path as `updateBlock` / `removeBlock`).
 *
 * - `replaceBlock` — overwrite an existing block's wire content.
 * - `deleteBlock`  — remove a block by id.
 * - `insertBlock`  — append a new block (after `afterBlockId` if given).
 */
export type PolicyEngineEdit =
  | {
      kind: 'replaceBlock';
      policyPath: string;
      blockId: string;
      newBlock: PolicyWireBlock;
    }
  | { kind: 'deleteBlock'; policyPath: string; blockId: string }
  | {
      kind: 'insertBlock';
      policyPath: string;
      afterBlockId?: string;
      newBlock: PolicyWireBlock;
    }
  | {
      kind: 'replaceNode';
      document: string;
      nodeId: string;
      newNode: unknown;
    };

/**
 * What kind of usage site a `PolicyReferenceSite` represents.
 *
 * - `expressionRead` — a read in an expression body (assertion condition,
 *   decision-table cell, decision-tree statement value).
 * - `writeKey` — an `entity.field` write target (assertion output, DT
 *   column head, tree statement key).
 * - `dataModel` — a declaration site in a data-model block (entity name,
 *   property name, or relationship/reference target).
 */
export type PolicyReferenceKind = 'expressionRead' | 'writeKey' | 'dataModel';

/**
 * One usage site of a `PolicyRenameTarget` in the workspace, returned by
 * `references()`. Carries enough context to navigate to the site or render
 * a "find references" panel.
 */
export interface PolicyReferenceSite {
  policyPath: string;
  blockId: string;
  expressionId?: string;
  /** The full original source string this site lives in. */
  source: string;
  /** Character offsets within `source` (LSP-style). */
  span: PolicySpan;
  kind: PolicyReferenceKind;
}

/** What kind of content a `PolicySearchHit` matched. */
export type PolicySearchHitKind =
  | 'document'
  | 'heading'
  | 'paragraph'
  | 'listItem'
  | 'codeBlock'
  | 'expression'
  | 'expressionKey'
  | 'tableColumn'
  | 'tableCell'
  | 'matchKey'
  | 'matchCondition'
  | 'matchValue'
  | 'assertionOutput'
  | 'assertionCondition'
  | 'dataModel'
  | 'dataModelProperty'
  | 'dictionary'
  | 'dictionaryEntry'
  | 'graphNode'
  | 'switchCondition'
  | 'function';

/**
 * One ranked fuzzy-search hit returned by `search()`. Location fields are
 * populated per kind: policy hits carry `blockId` (plus `expressionId`,
 * `row`/`column` for table cells), graph hits carry `nodeId`. `span` is a
 * character range within `text` (which may be a snippet of long sources).
 */
export interface PolicySearchHit {
  path: string;
  blockId?: string;
  nodeId?: string;
  expressionId?: string;
  row?: number;
  column?: string;
  kind: PolicySearchHitKind;
  text: string;
  /** Human context for the hit, e.g. column name, entity, or node name. */
  context?: string;
  span: PolicySpan;
  score: number;
}

/**
 * One node in the transitive dependency tree returned by `dependencies()`.
 * Each node names a property; `writtenBy` is the block that produces it
 * (absent for inputs — those are leaves). `deps` is the next layer of the
 * dependency tree, recursively. Cycles in the dep graph (cut by the
 * engine's self-edge skip) are protected here too — any revisited node has
 * empty `deps`.
 */
export interface PolicyDependencyNode {
  property: string;
  writtenBy?: PolicyPropertyWriter;
  unresolved?: boolean;
  resolvedType: PolicyVariableType;
  deps: PolicyDependencyNode[];
}

export interface PolicyEvaluationResult {
  output?: unknown;
  /** Evaluation duration in microseconds. */
  duration?: number;
  trace?: PolicyTrace;
  /** Present when a block failed mid-evaluation; `trace` then holds the partial trace up to the failure. */
  error?: PolicyEvaluationFailure;
}

export interface PolicyEvaluationFailure {
  policyPath: string;
  blockId: string;
  expression: string;
  message: string;
}

export interface PolicyTrace {
  engineVersion: string;
  properties: Record<string, unknown>;
  executions: PolicyBlockExecution[];
}

export interface PolicyBlockExecution {
  blockId: string;
  policyPath?: string;
  instancePath?: string;
  trace: PolicyBlockTrace;
  operandValues?: Record<string, unknown>;
  writes?: PolicyWriteTrace[];
  reads?: string[];
}

export interface PolicyWriteTrace {
  path: string;
  value: unknown;
}

export interface PolicyDecisionTableExtras {
  inputPass: string;
}

export type PolicyBlockTrace =
  | {
      kind: 'assertion';
      result: boolean;
      conditions: { id: string; result: boolean }[];
    }
  | {
      kind: 'decisionTable';
      matchedRows: number[];
      evaluations: Record<string, unknown>[];
      extras?: PolicyDecisionTableExtras;
    }
  | {
      kind: 'expression';
      property: string;
      value: unknown;
    }
  | {
      kind: 'match';
      matchedArm?: string;
      value: unknown;
      arms: { id: string; result: boolean }[];
    };

export declare class Workspace {
  constructor(resolveFunctionType?: (source: string, inputType: PolicyVariableType) => string | null | undefined)
  functionResolutionRequests(): Array<PolicyFunctionResolutionRequest>
  setFunctionType(source: string, inputType: PolicyVariableType, tsType?: string | undefined | null): void
  setDocument(path: string, document: any): void
  setPolicy(path: string, document: any): void
  removePath(path: string): boolean
  isGraph(path: string): boolean
  uncheckedNodes(path: string): Array<string>
  paths(): Array<string>
  updateBlock(req: PolicyUpdateBlockRequest): void
  removeBlock(req: PolicyRemoveBlockRequest): boolean
  diagnostics(policyPath: string, maxDiagnostics?: number | undefined | null): Array<PolicyDiagnostic>
  allDiagnostics(maxDiagnostics?: number | undefined | null): Array<PolicyDiagnostic>
  entities(req: PolicyScopeRequest): Array<PolicyEntityInfo>
  globals(req: PolicyScopeRequest): Array<PolicyGlobalInfo>
  dictionaries(req: PolicyScopeRequest): Array<PolicyDictionaryInfo>
  inputs(req: PolicyScopeRequest): Array<PolicyInputProperty>
  outputs(req: PolicyScopeRequest): Array<PolicyOutputProperty>
  conditionalSchema(req: PolicyScopeRequest): PolicyConditionalSchema
  inspect(cursor: PolicyExpressionCursor): PolicyInspectResult | null
  completions(cursor: PolicyExpressionCursor): Array<PolicyCompletion>
  prepareRename(cursor: PolicyExpressionCursor): PolicyPrepareRenameResult | null
  rename(req: PolicyRenameRequest): PolicyEngineEdit[]
  references(target: any): PolicyReferenceSite[]
  search(query: string, limit?: number | undefined | null): PolicySearchHit[]
  inputSkeleton(req: PolicyScopeRequest): unknown
  dependencies(target: string, document?: string | undefined | null): PolicyDependencyNode
  evaluate(req: PolicyEvaluateRequest): PolicyEvaluationResult
  enhanceTrace(req: PolicyEvaluateRequest): PolicyEvaluationResult
  enhanceGraphTrace(path: string, trace: any): PolicyTrace
  componentMembers(policy: string): Array<string>
  crossComponentWriteConflicts(): Array<PolicyWriteConflict>
  slot(cursor: PolicyExpressionCursor, text: string): PolicySlotResponse | null
  facts(policyPath: string): PolicyExpressionFacts[]
}

export declare class ZenDecision {
  constructor()
  evaluate(context: any, opts?: ZenEvaluateOptions | undefined | null): Promise<ZenEngineResponse>
  safeEvaluate(context: any, opts?: ZenEvaluateOptions | undefined | null): Promise<{ success: true, data: ZenEngineResponse } | { success: false; error: any; }>
  validate(): void
}

export declare class ZenDecisionContent {
  constructor(content: Buffer | object)
  toBuffer(): Buffer
}

export declare class ZenEngine {
  constructor(options?: ZenEngineOptions | undefined | null)
  evaluate(key: string, context: any, opts?: ZenEvaluateOptions | undefined | null): Promise<ZenEngineResponse>
  createDecision(content: ZenDecisionContent | Buffer | object): ZenDecision
  getDecision(key: string): Promise<ZenDecision>
  safeEvaluate(key: string, context: any, opts?: ZenEvaluateOptions | undefined | null): Promise<{ success: true, data: ZenEngineResponse } | { success: false; error: any; }>
  safeGetDecision(key: string): Promise<{ success: true, data: ZenDecision } | { success: false; error: any; }>
  evaluateBatch(requests: Array<EvaluateBatchRequest>, opts?: ZenEvaluateOptions | undefined | null): Promise<Array<{ success: true; data: ZenEngineResponse } | { success: false; error: any }>>
  reload(): Promise<void>
  compileFailures(): Array<{ key: string; kind: string; diagnostics?: Array<{ code: string; message: string; severity: string }>; error?: string }>
  dispose(): void
}

export declare class ZenEngineHandlerRequest {
  constructor()
  get node(): DecisionNode
  get input(): any
  getField(path: string): unknown
  getFieldRaw(path: string): unknown
}

export interface DecisionNode {
  id: string
  name: string
  kind: string
  config: any
}

export interface EvaluateBatchRequest {
  key: string
  context: any
}

export declare function evaluateExpression(expression: string, context?: any | undefined | null): Promise<any>

export declare function evaluateExpressionSync(expression: string, context?: any | undefined | null): any

export declare function evaluateUnaryExpression(expression: string, context: any): Promise<boolean>

export declare function evaluateUnaryExpressionSync(expression: string, context: any): boolean

export declare function overrideConfig(config: ZenConfig): void

export interface PolicyCompletion {
  label: string
  kind: string
  detail: string
  info: string
  follow?: string
}

export interface PolicyConditionalSchema {
  kind: "union" | "flat"
  common: PolicySchemaGroup
  union?: PolicyDiscriminatedUnion
  conditional?: PolicySchemaGroup
}

export interface PolicyDiagnostic {
  code: PolicyDiagnosticCode
  message: string
  severity: PolicySeverity
  policyPath: string
  blockId?: string
  span?: PolicySpan
  expressionId?: string
  target?: PolicyCursorTarget
  exprCode?: string
  args?: Record<string, string>
}

export interface PolicyDictionaryEntryInfo {
  value: string
  label: string
}

export interface PolicyDictionaryInfo {
  name: string
  source: string
  entries: Array<PolicyDictionaryEntryInfo>
}

export interface PolicyDiscriminantVariant {
  value?: string
  arm: string
  group: PolicySchemaGroup
}

export interface PolicyDiscriminatedUnion {
  property: string
  resolvedType: PolicyVariableType
  variants: Array<PolicyDiscriminantVariant>
}

export interface PolicyEntityFieldInfo {
  name: string
  resolvedType: PolicyVariableType
  origin: PolicyFieldOrigin
}

export interface PolicyEntityInfo {
  name: string
  fields: Array<PolicyEntityFieldInfo>
}

export interface PolicyEvaluateRequest {
  policyPath: string
  input: unknown
  goals?: Array<string>
  trace?: boolean
}

export interface PolicyExpressionCursor {
  policyPath: string
  blockId: string
  pos: number
  target: PolicyCursorTarget
}

export interface PolicyFieldKindInfo {
  kind: PolicyFieldKind
  target?: string
  array?: boolean
}

export interface PolicyFunctionResolutionRequest {
  source: string
  inputType: PolicyVariableType
}

export interface PolicyGlobalInfo {
  name: string
  resolvedType: PolicyVariableType
  origin: PolicyFieldOrigin
}

export interface PolicyGuardedProperty {
  path: string
  resolvedType: PolicyVariableType
  requiredWhen?: string
}

export interface PolicyInputProperty {
  path: string
  resolvedType: PolicyVariableType
}

export interface PolicyInspectResult {
  span: PolicySpan
  kind: PolicyVariableType
  label: string
}

export interface PolicyInstanceOf {
  target: string
  array: boolean
}

export interface PolicyOutputProperty {
  path: string
  resolvedType: PolicyVariableType
  kind: PolicyPropertyKind
  writtenBy?: PolicyPropertyWriter
  instanceOf?: PolicyInstanceOf
}

export interface PolicyPrepareRenameResult {
  target: PolicyRenameTarget
  span: PolicySpan
}

export interface PolicyPropertyWriter {
  policyPath: string
  blockId: string
}

export interface PolicyRemoveBlockRequest {
  policyPath: string
  blockId: string
}

export interface PolicyRenameRequest {
  target: PolicyRenameTarget
  newName: string
}

export interface PolicySchemaGroup {
  inputs: Array<PolicyGuardedProperty>
  outputs: Array<PolicyGuardedProperty>
}

export interface PolicyScopeRequest {
  policyPath: string
  goals?: Array<string>
}

export interface PolicyUpdateBlockRequest {
  policyPath: string
  block: unknown
}

export interface PolicyWriteConflict {
  path: string
  policies: Array<string>
}

export declare function renderTemplate(template: string, context: any): Promise<any>

export declare function renderTemplateSync(template: string, context: any): any

export declare function slotBatch(requests: Array<SlotRequest>, strict?: boolean | undefined | null): Array<{ id: string; result: PolicySlotResponse }>

export interface SlotRequest {
  id: string
  text: string
  pos: number
  unary: boolean
  role: PolicySlotRole
  scope: PolicyVariableType
  expected?: PolicyVariableType | null
  labels?: Record<string, Record<string, string>> | null
}

export interface ZenConfig {
  nodesInContext?: boolean
  functionTimeoutMillis?: number
  httpAuth?: boolean
}

export interface ZenEngineHandlerResponse {
  output: any
  traceData?: any
}

export interface ZenEngineOptions {
loader?: ((key: string) => Promise<Buffer | ZenDecisionContent>) | { type: 'static'; content: Record<string, object> } | { type: 'fs'; path: string } | { type: 'zip'; bytes: Buffer }
customHandler?: (request: ZenEngineHandlerRequest) => Promise<ZenEngineHandlerResponse>
httpHandler?: (request: ZenHttpHandlerRequest) => Promise<ZenHttpHandlerResponse>
}

export interface ZenEngineResponse {
  performance: string
  result: any
  trace?: Record<string, ZenEngineTrace>
}

export interface ZenEngineTrace {
  id: string
  name: string
  input: any
  output: any
  performance?: string
  traceData?: any
  order: number
}

export interface ZenEvaluateOptions {
  maxDepth?: number
  trace?: boolean | 'string' | 'reference' | 'referenceString'
}

export interface ZenHttpHandlerRequest {
  method: string
  url: string
  body?: any
  headers: Record<string, string>
  params: Record<string, string>
}

export interface ZenHttpHandlerResponse {
  status: number
  headers: any
  data: any
}