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'
  | '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 };

/** Language-agnostic symbol key for an infix operator. The client maps the key to a localized phrase. */
export type NlOpSym =
  | 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'ne' | 'in' | 'notIn'
  | 'contains' | 'notContains'
  | 'containsAny' | 'containsAll' | 'containsNone' | 'containsOnly'
  | 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'pow'
  | 'and' | 'or' | 'not' | 'coalesce';

/**
 * Structural separator word inside a multi-operand construct (conditional, closure, interval).
 * `has` replaces `where` when an alias-elided closure body leads with a member on the binding
 * ("any drivers has age less than 5"); clients should shorten the op label that follows it.
 */
export type NlWordSym = 'if' | 'then' | 'otherwise' | 'in' | 'where' | 'has' | 'rangeAnd';

/**
 * Resolved type of a value/field token. `enum` / `array<enum>` carry an `index`
 * into the per-result `enums` table; dedupe the domain once, reference by index.
 */
export type NlTypeTag =
  | { t: 'number' }
  | { t: 'string' }
  | { t: 'bool' }
  | { t: 'date' }
  | { t: 'interval' }
  | { t: 'object' }
  | { t: 'null' }
  | { t: 'unknown' }
  | { t: 'enum'; index: number }
  | { t: 'array'; items: NlTypeTag };

/** One operator the user may switch to: the symbol for labelling plus its ZEN source form for splicing. */
export interface NlOpChoice {
  sym: NlOpSym;
  source: string;
}

/**
 * One enum domain value: `label` for display, `source` as the ready-to-splice ZEN literal.
 * `source` is absent when the value contains both quote kinds and has no literal form.
 */
export interface NlEnumOption {
  label: string;
  source?: string;
}

/**
 * Widget hint present only when it adds information beyond the token's own type: enum domains
 * (`options` indexes the `enums` table), expected dates, or the operator choices valid for the
 * operand types — ordered comparisons only for number/date/unknown operands, eq/ne otherwise.
 */
/**
 * `quantSelect` marks a quantified-membership phrase (contains any/all/none/only). `subject` and
 * `list` are ready-to-splice ZEN source slices; the client rebuilds the whole spanned expression
 * from its canonical template for the picked symbol. `funcSelect` swaps a closure-function name
 * in place (all/some/none); the token span covers exactly the name.
 */
export type NlEditHint =
  | { kind: 'datePicker' }
  | { kind: 'select'; options: number }
  | { kind: 'multiSelect'; options: number }
  | { kind: 'opSelect'; options: NlOpChoice[] }
  | { kind: 'quantSelect'; options: NlOpSym[]; subject: string; list: string }
  | { kind: 'funcSelect'; options: string[] };

/**
 * One token in the symbolic NL stream. Structure is explicit via the
 * group/list/interval markers and the infix placement of `op` / `word` tokens.
 * `func.sym` / `method.sym` are stable camelCase keys (`'sum'`, `'format'`, `'d'`
 * for the date constructor); `closure: true` marks a closure call whose operands
 * follow as `element`, `word:'in'`, collection, `word:'where'`, body.
 */
export type NlTokenKind =
  | { t: 'groupOpen' }
  | { t: 'groupClose' }
  | { t: 'listOpen' }
  | { t: 'listClose' }
  | { t: 'comma' }
  | { t: 'enumList'; selected: string[] }
  | { t: 'context' }
  | { t: 'root' }
  | { t: 'null' }
  | { t: 'field'; path: string[]; ty: NlTypeTag }
  | { t: 'element'; alias?: string }
  | { t: 'number'; value: string }
  | { t: 'str'; value: string }
  | { t: 'bool'; value: boolean }
  | { t: 'op'; sym: NlOpSym; implied: boolean; between: boolean }
  | { t: 'word'; sym: NlWordSym }
  | { t: 'assign' }
  | { t: 'stmtEnd' }
  | { t: 'func'; sym: string; closure: boolean }
  | { t: 'method'; sym: string }
  | { t: 'templateOpen' }
  | { t: 'templateText'; value: string }
  | { t: 'templateClose' }
  | { t: 'intervalOpen'; inclusive: boolean }
  | { t: 'intervalClose'; inclusive: boolean }
  | { t: 'code'; source: string };

/** A projected token plus its source span (`[start, end)` bytes) and optional widget hint. */
export interface NlToken {
  token: NlTokenKind;
  span: PolicySpan;
  hint?: NlEditHint;
}

export type NlDiagnosticSource = 'lexer' | 'parser' | 'typeCheck' | 'compiler';

export interface NlDiagnostic {
  span: PolicySpan;
  message: string;
  severity: PolicySeverity;
  source: NlDiagnosticSource;
}

/** Result of projecting one expression; `enums` is the dedup table referenced by `NlTypeTag` / `NlEditHint` indices. */
export interface NlResult {
  id: string;
  tokens: NlToken[];
  enums: NlEnumOption[][];
  diagnostics: NlDiagnostic[];
  /** Resolved `$` type for unary requests (decision-table input cells); present even for empty text. */
  subjectType?: PolicyVariableType;
  /** Labeled options when the unary subject is an enum (dictionary labels applied); present even for empty text. */
  subjectOptions?: NlEnumOption[];
}

/**
 * One projected expression/cell of a policy, returned by `PolicyWorkspace.nl(policyPath)`.
 * The engine resolves scope + (for unary decision-table input cells) the subject type
 * internally, so no `rootType` is supplied. `target` routes the result to the editor it
 * came from (assertion condition, match arm, decision-table cell `{row, col}`, …).
 */
export interface PolicyNlExpression {
  blockId: string;
  target: PolicyCursorTarget;
  kind: 'standard' | 'unary';
  /** Expression text this projection was computed from — compare against the editor value to detect staleness. */
  source: string;
  tokens: NlToken[];
  enums: NlEnumOption[][];
  diagnostics: NlDiagnostic[];
  /** Resolved `$` type for unary cells. */
  subjectType?: PolicyVariableType;
  /** Labeled options when the unary subject is an enum (dictionary labels applied). */
  subjectOptions?: NlEnumOption[];
}

/**
 * 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;
}

/**
 * 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
  nl(policyPath: string): PolicyNlExpression[]
  nlTokenize(cursor: PolicyExpressionCursor, text: string): NlResult | null
  completions(cursor: PolicyExpressionCursor): Array<PolicyCompletion>
  prepareRename(cursor: PolicyExpressionCursor): PolicyPrepareRenameResult | null
  rename(req: PolicyRenameRequest): PolicyEngineEdit[]
  references(target: any): PolicyReferenceSite[]
  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>
}

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 nlEncodeString(value: string): string | null

export declare function nlTokenizeBatch(requests: NlTokenizeRequest[], rootType: PolicyVariableType, strict?: boolean): NlResult[]

export interface NlTokenizeRequest {
  id: string
  expression: string
  unary: boolean
  subjectType?: PolicyVariableType
}

export declare function overrideConfig(config: ZenConfig): void

export interface PolicyCompletion {
  label: string
  kind: string
  detail: string
  info: 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
}

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 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
}