zen/bindings/nodejs/dts-header.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 }[];
    };