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'; id?: string }
  | { 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 }[];
    };