CompilerBase.ts

import { createHash } from 'crypto';

/**
 * Base Compiler Interface with Agent Identity Integration
 *
 * Provides common RBAC validation logic for all HoloScript compilers.
 * Supports dual-mode access control: legacy JWT RBAC tokens AND UCAN
 * capability tokens via the P3 Migration Bridge.
 *
 * All compilers MUST extend this base or implement ICompiler interface.
 *
 * @version 2.0.0
 */

import { getRBAC, ResourceType, type AccessDecision } from './identity/AgentRBAC';
import { WorkflowStep } from './identity/AgentIdentity';
import type { CulturalProfileMetadata } from './identity';
import type { CulturalCompatibilityResult } from './CulturalCompatibilityChecker';
import type {
  HoloComposition,
  HoloDomainBlock,
  HoloObjectDecl,
  HoloSpatialGroup,
} from '../parser/HoloCompositionTypes';
import type {
  GLTFExportResult,
  ARCompilationResult,
  AndroidXRCompileResult,
  VRRCompilationResult,
  IOSCompileResult,
} from './CompilerTypes';
import { CapabilityRBAC, getCapabilityRBAC } from './identity/CapabilityRBAC';
import type { CapabilityToken } from './identity/CapabilityToken';
import { type CompilerName, COMPILER_ANS_MAP, isValidCompilerName } from './identity/ANSNamespace';
import {
  type SpatialZoneEnforcer,
  type SpatialAccessDecision,
  SpatialPermission,
  getSpatialZoneEnforcer,
} from './identity/SpatialMemoryZones';
import {
  CompilerDocumentationGenerator,
  type TripleOutputResult,
  type DocumentationGeneratorOptions,
  type TripleOutputGenerationMeta,
} from './CompilerDocumentationGenerator';
import type { JsonLdSceneGraph } from './SemanticSceneGraph';

// ---------------------------------------------------------------------------
// Dual-mode token types (P3 Migration Bridge)
// ---------------------------------------------------------------------------

/**
 * Credential wrapper for UCAN capability tokens.
 *
 * Bundles the token with the issuer's Ed25519 public key, which is
 * required for signature verification.
 */
export interface CapabilityTokenCredential {
  /** UCAN capability token object */
  capabilityToken: CapabilityToken;

  /** Ed25519 public key of the token issuer (PEM-encoded) */
  issuerPublicKey: string;
}

/**
 * Union type for compiler access tokens.
 *
 * - `string`: Legacy JWT RBAC token (routed to AgentRBAC)
 * - `CapabilityTokenCredential`: UCAN capability token (routed to CapabilityRBAC)
 *
 * This enables the P3 Migration Bridge: callers can present either token type
 * and CompilerBase will route to the appropriate verification system.
 */
export type CompilerToken = string | CapabilityTokenCredential;

/**
 * Type guard to check if a token is a UCAN CapabilityTokenCredential.
 *
 * UCAN credential objects have `capabilityToken` and `issuerPublicKey` fields.
 * JWT tokens are plain strings.
 */
export function isCapabilityTokenCredential(
  token: CompilerToken | undefined | null
): token is CapabilityTokenCredential {
  if (!token || typeof token === 'string') return false;
  return (
    typeof token === 'object' &&
    'capabilityToken' in token &&
    'issuerPublicKey' in token &&
    token.capabilityToken != null &&
    typeof token.issuerPublicKey === 'string'
  );
}

// ---------------------------------------------------------------------------
// Compiler class name to ANS CompilerName mapping
// ---------------------------------------------------------------------------

/**
 * Maps compiler class names (e.g. 'UnityCompiler') to their ANS compiler
 * name (e.g. 'unity'). Used by the default `getRequiredCapability()` to
 * derive the ANS namespace from the class's `compilerName` property.
 */
const COMPILER_CLASS_TO_ANS_NAME: Readonly<Record<string, CompilerName>> = {
  UnityCompiler: 'unity',
  UnrealCompiler: 'unreal',
  GodotCompiler: 'godot',
  Canvas2DGameCompiler: 'canvas2d-game',
  VRChatCompiler: 'vrchat',
  OpenXRCompiler: 'openxr',
  OpenXRSpatialEntitiesCompiler: 'openxr-spatial-entities',
  VisionOSCompiler: 'visionos',
  AndroidXRCompiler: 'android-xr',
  QuestCompiler: 'quest',
  AIGlassesCompiler: 'ai-glasses',
  AndroidCompiler: 'android',
  IOSCompiler: 'ios',
  // ARCompiler, BabylonCompiler, PlayCanvasCompiler, ThreeJSCompiler, R3FCompiler — retired (apex-poison, 2026-06-17)
  WebGPUCompiler: 'webgpu',
  WASMCompiler: 'wasm',
  TSLCompiler: 'tsl',
  URDFCompiler: 'urdf',
  SDFCompiler: 'sdf',
  USDPhysicsCompiler: 'usd',
  GLTFPipeline: 'gltf',
  GaussianSplattingCompiler: '3dgs',
  DTDLCompiler: 'dtdl',
  NFTMarketplaceCompiler: 'nft-marketplace',
  SCMCompiler: 'scm',
  // VRRCompiler — retired (apex-poison, 2026-06-17)
  A2AAgentCardCompiler: 'a2a-agent-card',
  MultiLayerCompiler: 'multi-layer',
  IncrementalCompiler: 'incremental',
  StateCompiler: 'state',
  TraitCompositionCompiler: 'trait-composition',
  DomainBlockCompilerMixin: 'domain-block',
  NIRCompiler: 'nir',
  URDFToUSDZConverter: 'urdf',
  QuiltCompiler: 'quilt',
  MVHEVCCompiler: 'mv-hevc',
  NodeServiceCompiler: 'node-service',
  SDKCompiler: 'sdk',
  NextJSAPICompiler: 'nextjs-api',
  MCPConfigCompiler: 'mcp-config',
  HoloMCPCompiler: 'mcp-server',
  AgentInferenceCompiler: 'agent-inference',
  OmnigentAgentYamlCompiler: 'omnigent-agent-yaml',
  DaimonSeedCompiler: 'daimon-seed',
  HSIIRCompiler: 'hsi-ir',
  CodeEditorCompiler: 'code-editor',
  SVGCompiler: 'svg',
};

export function getRegisteredCompilerANSName(compilerClassName: string): CompilerName | undefined {
  return COMPILER_CLASS_TO_ANS_NAME[compilerClassName];
}

/**
 * Base compiler options (extended by specific compilers)
 */
export interface BaseCompilerOptions {
  /**
   * Generate triple-output documentation (llms.txt, .well-known/mcp, markdown)
   * @default false
   */
  generateDocs?: boolean;

  /**
   * Documentation generator options (only used if generateDocs is true)
   */
  docsOptions?: DocumentationGeneratorOptions;

  /**
   * Attach a provenance hash to compilation output for audit-trail traceability.
   * When set, compilers SHOULD embed this value as a comment in their output.
   * Format: `// Provenance Hash: <hex>` (use `#` prefix for YAML/GDScript targets).
   */
  provenanceHash?: string;
}

/**
 * Compilation result with optional documentation outputs
 */
export interface CompilationResult {
  /** Primary compilation output (code, GLTF, etc.) */
  output:
    | string
    | Record<string, string>
    | GLTFExportResult
    | ARCompilationResult
    | VRRCompilationResult
    | AndroidXRCompileResult
    | IOSCompileResult
    /** Structured outputs (e.g. WASM bundle) when paired with triple-output docs */
    | Record<string, unknown>;

  /** Optional documentation bundle (if generateDocs enabled) */
  documentation?: TripleOutputResult;
}

/** What {@link flattenCompositionScenes} hands a compiler that builds one world. */
export interface FlattenedScenes {
  /** The composition to compile: the input itself when no scene adds anything. */
  composition: HoloComposition;
  /**
   * Scene environments that are not applied. `appliedFrom` names the scene whose
   * environment applies instead, or is `null` when the composition's own does.
   */
  unappliedEnvironments: Array<{ scene: string; appliedFrom: string | null }>;
  /**
   * Scene objects that are not built, because `takenName` (the object's own name,
   * the name of an object inside it, or an identifier building it would declare)
   * gives an identifier something already in the output declares. `takenBy` is
   * the compiler's plain words for that something ("a light", "the camera");
   * without it, it is another object. Only filled when the compiler passes
   * `identifierOf` or `declared`.
   */
  leftOutObjects: Array<{ scene: string; object: string; takenName: string; takenBy?: string }>;
}

/**
 * The identifiers a compiler declares in the one scope it builds objects in,
 * beyond the one each object's name gives. See {@link flattenCompositionScenes}.
 */
export interface DeclaredIdentifiers {
  /**
   * Every identifier the compiler declares in that scope when it compiles
   * `content`, each mapped to plain words for the part that declares it ("a
   * light", "the camera"). `content` is the composition as it will be compiled,
   * without the objects scenes add. Called at most once, and only when a scene
   * has objects to add.
   */
  reserved?(content: HoloComposition): ReadonlyMap<string, string>;
  /**
   * Every identifier building `obj` declares in that scope, with those of the
   * objects inside it: its name's own, and any the compiler derives from it.
   */
  of?(obj: HoloObjectDecl): string[];
}

/**
 * Compiler interface with agent identity enforcement
 */
export interface ICompiler {
  /**
   * Compile HoloComposition AST to target platform code
   *
   * @param composition - HoloScript AST
   * @param agentToken - JWT token proving agent identity
   * @param outputPath - Optional output file path for scope validation
   * @param sceneGraph - Optional pre-computed SSG for capability inference and optimization hints
   * @returns Compiled code (string or multi-file object)
   * @throws UnauthorizedCompilerAccessError if token invalid or lacks permissions
   */
  compile(
    composition: HoloComposition,
    agentToken: string,
    outputPath?: string,
    sceneGraph?: JsonLdSceneGraph
  ):
    | string
    | Record<string, string>
    | GLTFExportResult
    | ARCompilationResult
    | VRRCompilationResult
    | AndroidXRCompileResult
    | IOSCompileResult
    | any;
}

/**
 * Error thrown when agent lacks required permissions
 */
export class UnauthorizedCompilerAccessError extends Error {
  constructor(
    public readonly decision: AccessDecision,
    public readonly operation: string,
    public readonly compilerName: string
  ) {
    super(
      `[${compilerName}] Unauthorized ${operation}: ${decision.reason || 'Access denied'}\n` +
        `Required Permission: ${decision.requiredPermission || 'unknown'}`
    );
    this.name = 'UnauthorizedCompilerAccessError';
  }
}

/**
 * Base compiler class with RBAC enforcement
 *
 * All compilers SHOULD extend this class to inherit:
 * - AST access validation
 * - Code generation validation
 * - Output path scope validation
 * - Clear error messages
 *
 * Example:
 * ```typescript
 * export class UnityCompiler extends CompilerBase {
 *   compile(composition: HoloComposition, agentToken: string, outputPath?: string): string {
 *     // Validate AST access
 *     this.validateASTAccess(agentToken);
 *
 *     // Validate code generation permission
 *     this.validateCodeGeneration(agentToken);
 *
 *     // Validate output path (if provided)
 *     if (outputPath) {
 *       this.validateOutputPath(agentToken, outputPath);
 *     }
 *
 *     // Perform compilation...
 *     return csharpCode;
 *   }
 * }
 * ```
 */
/**
 * Supported compilation targets for string sanitization.
 *
 * SECURITY: Every target that generates code must have an entry here.
 * Using the wrong target (e.g. 'TypeScript' for Kotlin output) is a
 * Cross-Agent Compilation Injection vulnerability (CWE-94).
 */
export type EscapeTarget =
  | 'Solidity'
  | 'Swift'
  | 'Kotlin'
  | 'CSharp'
  | 'GDScript'
  | 'JSX'
  | 'TypeScript'
  | 'GLSL'
  | 'HLSL'
  | 'WGSL'
  | 'Python'
  | 'Lua'
  | 'USD'
  | 'XML'
  | 'JSON'
  | 'Rust';

function escapeCStyle(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/'/g, "\\'")
    .replace(/\n/g, '\\n')
    .replace(/\r/g, '\\r')
    .replace(/\t/g, '\\t')
    .replace(/\0/g, '\\0');
}

function escapeGDScript(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/'/g, "\\'")
    .replace(/\n/g, '\\n')
    .replace(/\t/g, '\\t')
    .replace(/\0/g, '');
}

function escapeJSX(value: string): string {
  return value
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
    .replace(/\{/g, '&#123;')
    .replace(/\}/g, '&#125;');
}

function escapeXML(value: string): string {
  return value
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&apos;');
}

function escapeShader(value: string): string {
  return value
    .replace(/\\/g, '')
    .replace(/\*/g, '')
    .replace(/\//g, '')
    .replace(/#/g, '')
    .replace(/\n/g, ' ')
    .replace(/\r/g, '');
}

function escapePython(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/'/g, "\\'")
    .replace(/\n/g, '\\n')
    .replace(/\r/g, '\\r')
    .replace(/\t/g, '\\t')
    .replace(/\0/g, '\\x00');
}

function escapeLua(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/'/g, "\\'")
    .replace(/\n/g, '\\n')
    .replace(/\r/g, '\\r')
    .replace(/\0/g, '\\0');
}

function escapeUSD(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/\n/g, '\\n')
    .replace(/\r/g, '\\r');
}

function escapeJSON(value: string): string {
  return value
    .replace(/\\/g, '\\\\')
    .replace(/"/g, '\\"')
    .replace(/\n/g, '\\n')
    .replace(/\r/g, '\\r')
    .replace(/\t/g, '\\t')
    .replace(/[\x00-\x1f]/g, (ch) => '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
}

export function escapeStringValue(value: string, target: EscapeTarget): string {
  if (!value) return value;
  switch (target) {
    case 'Solidity':
    case 'CSharp':
    case 'Swift':
    case 'Kotlin':
    case 'TypeScript':
    case 'Rust':
      return escapeCStyle(value);
    case 'GDScript':
      return escapeGDScript(value);
    case 'JSX':
      return escapeJSX(value);
    case 'XML':
      return escapeXML(value);
    case 'GLSL':
    case 'HLSL':
    case 'WGSL':
      return escapeShader(value);
    case 'Python':
      return escapePython(value);
    case 'Lua':
      return escapeLua(value);
    case 'USD':
      return escapeUSD(value);
    case 'JSON':
      return escapeJSON(value);
    default:
      return value;
  }
}

/**
 * Read `scene` blocks the way a compiler that builds ONE world reads the rest of
 * the composition.
 *
 * The parser keeps what a `scene "X" { ... }` block holds on `composition.scenes`,
 * not on `composition.objects`. A compiler that reads only `composition.objects`
 * therefore leaves every object written inside a scene out of its output, and
 * says nothing. Such a compiler calls this before it compiles and then compiles
 * the composition it returns: each scene's objects follow the top-level objects,
 * scene by scene, and go through the compiler's own object path. A scene has no
 * transform, so each object keeps its own position. Compilers that extend
 * {@link CompilerBase} call it through {@link CompilerBase.flattenScenes};
 * SceneIRCompiler and the Quest world emitter, which do not extend it, call it directly.
 *
 * Environment: the composition's own `environment` applies when it has one;
 * otherwise the first scene that declares one supplies it. One world has one
 * environment, so every other scene environment is listed in
 * `unappliedEnvironments`, with the one that applies instead.
 *
 * Names: scenes are separate in the source but become one world here. A compiler
 * that turns object names into identifiers passes `identifierOf`. A scene object
 * is then not built when it, or an object inside it, would get an identifier that
 * an object already in the output has (two scenes that each have a "Ground", or
 * a scene reusing a top-level name); it is listed in `leftOutObjects` instead of
 * producing output that cannot load. Objects are not the only things a compiler
 * names: one that also declares identifiers for other parts (lights, sounds, the
 * camera), or derives more than one from an object, passes `declared`, and a
 * scene object is then also left out when building it would declare one already
 * declared. Only the compiler knows what it names, so it says; this does not
 * guess. Clashes among the composition's own content are left alone, so its
 * output stays exactly as before.
 *
 * A compiler that has somewhere to report writes {@link CompilerBase.sceneWarnings}
 * (an emitter that is not a compiler class, {@link describeLeftOutScenes}) into its
 * output, so nothing is left out without being named. When no scene adds
 * anything, the input itself is returned, so a composition without scenes compiles
 * exactly as before. The input is never changed.
 */
export function flattenCompositionScenes(
  composition: HoloComposition,
  identifierOf?: (name: string) => string,
  declared?: DeclaredIdentifiers
): FlattenedScenes {
  const scenes = composition.scenes ?? [];
  const unappliedEnvironments: FlattenedScenes['unappliedEnvironments'] = [];
  const leftOutObjects: FlattenedScenes['leftOutObjects'] = [];

  let environment = composition.environment;
  let appliedFrom: string | null = null;
  for (const scene of scenes) {
    if (!scene.environment) continue;
    if (environment) {
      unappliedEnvironments.push({ scene: scene.name, appliedFrom });
    } else {
      environment = scene.environment;
      appliedFrom = scene.name;
    }
  }

  // Every name in these objects and in the objects inside them.
  const namesIn = (objects: HoloObjectDecl[] | undefined, into: string[]): string[] => {
    for (const obj of objects ?? []) {
      into.push(String(obj.name ?? ''));
      namesIn(obj.children, into);
    }
    return into;
  };
  const groupNames = (groups: HoloSpatialGroup[] | undefined, into: string[]): string[] => {
    for (const group of groups ?? []) {
      namesIn(group.objects, into);
      groupNames(group.groups, into);
    }
    return into;
  };
  // Each identifier already declared, with the compiler's words for what declares
  // it (undefined: another object). Filled only when a scene has objects to add.
  const taken = new Map<string, string | undefined>();
  const take = (identifier: string, by?: string) => {
    if (!taken.has(identifier)) taken.set(identifier, by);
  };
  const checked = identifierOf !== undefined || declared !== undefined;
  if (checked && scenes.some((scene) => (scene.objects ?? []).length > 0)) {
    if (identifierOf) {
      for (const name of namesIn(composition.objects, groupNames(composition.spatialGroups, []))) {
        take(identifierOf(name));
      }
    }
    const content =
      environment === composition.environment ? composition : { ...composition, environment };
    for (const [identifier, by] of declared?.reserved?.(content) ?? []) take(identifier, by);
  }

  const sceneObjects: HoloObjectDecl[] = [];
  for (const scene of scenes) {
    for (const obj of scene.objects ?? []) {
      if (checked) {
        // [the name a warning quotes, the identifier it gives]: each name as the
        // source spells it first, then what the compiler says building it declares.
        const claims: Array<[string, string]> = [
          ...(identifierOf
            ? namesIn([obj], []).map((name): [string, string] => [name, identifierOf(name)])
            : []),
          ...(declared?.of?.(obj) ?? []).map((id): [string, string] => [id, id]),
        ];
        const clash = claims.find(([, identifier]) => taken.has(identifier));
        if (clash) {
          const takenBy = taken.get(clash[1]);
          leftOutObjects.push({
            scene: scene.name,
            object: String(obj.name ?? ''),
            takenName: clash[0],
            ...(takenBy === undefined ? {} : { takenBy }),
          });
          continue;
        }
        for (const [, identifier] of claims) take(identifier);
      }
      sceneObjects.push(obj);
    }
  }

  if (sceneObjects.length === 0 && environment === composition.environment) {
    return { composition, unappliedEnvironments, leftOutObjects };
  }
  return {
    composition: {
      ...composition,
      objects: [...(composition.objects ?? []), ...sceneObjects],
      ...(environment ? { environment } : {}),
    },
    unappliedEnvironments,
    leftOutObjects,
  };
}

/**
 * One plain sentence for each piece of scene content {@link flattenCompositionScenes} left out,
 * with names escaped for `target` and kept on one line. A compiler that extends
 * {@link CompilerBase} gets these from {@link CompilerBase.sceneWarnings}; an emitter that is a
 * function of its own calls this, and writes each sentence into its output as a WARNING comment.
 */
export function describeLeftOutScenes(flattened: FlattenedScenes, target: EscapeTarget): string[] {
  const oneLine = (text: string) => text.replace(/[\r\n\u2028\u2029]+/g, ' ');
  const quote = (name: string) => `"${escapeStringValue(oneLine(name), target)}"`;
  return [
    ...flattened.unappliedEnvironments.map(({ scene, appliedFrom }) => {
      const applied =
        appliedFrom === null
          ? "the composition's own environment"
          : `the environment in scene ${quote(appliedFrom)}`;
      return `the environment in scene ${quote(scene)} is not applied: this output is one world with one environment, and ${applied} applies.`;
    }),
    ...flattened.leftOutObjects.map(
      ({ scene, object, takenName, takenBy = 'another object' }) =>
        `object ${quote(object)} in scene ${quote(scene)} is not built: this output is one world, and ${oneLine(takenBy)} in it already uses the name ${quote(takenName)}.`
    ),
  ];
}

/**
 * Read `group "X" { ... }` blocks as the spatial groups they describe.
 *
 * The `.holo` spelling of a group is `spatial_group`, and `group` is not a
 * keyword. The parser still accepts `group "X" { ... }`, the way it accepts any
 * block it does not know: it keeps it on `composition.domainBlocks` as a custom
 * domain block, with the objects written inside it on `children` and its other
 * lines (`position: [...]`, ...) on `properties`. A compiler that builds objects
 * from `composition.objects` and `composition.spatialGroups` therefore leaves
 * every object inside such a block out of its output, and says nothing, while
 * the `.hsplus` reading of the same text draws them inside their group.
 *
 * This returns a composition in which each such block is a spatial group
 * instead: the same name, its lines as the group's properties (so `position`,
 * `rotation` and `scale` move the group the way they move a `spatial_group`), and
 * its objects inside it, each keeping its own position relative to the group.
 * The groups follow the composition's own spatial groups, in source order, and
 * the blocks leave `domainBlocks`, so nothing reads them twice. A compiler calls
 * this before it compiles and then compiles the composition it returns. If it
 * also calls {@link flattenCompositionScenes}, it calls this first: flattening
 * then counts the objects inside these groups among the names already in use, so
 * with `identifierOf` a scene object that would clash with one of them is left
 * out and listed, rather than built twice under one identifier.
 *
 * Not carried over, because a spatial group has no place for them: the block's
 * `@trait` names (each trait's settings stay among the properties) and its
 * `on...` handlers. A `group` written inside a group block is read by the parser
 * as one of that block's properties, not as a block, so it is not read either.
 *
 * Without group blocks the input itself is returned, so such a composition
 * compiles exactly as before. The input is never changed.
 */
export function readGroupBlocksAsSpatialGroups(composition: HoloComposition): HoloComposition {
  const blocks = composition.domainBlocks ?? [];
  const isGroupBlock = (block: HoloDomainBlock) =>
    block.domain === 'custom' && String(block.keyword ?? '').toLowerCase() === 'group';
  if (!blocks.some(isGroupBlock)) return composition;

  const groups: HoloSpatialGroup[] = [];
  const otherBlocks: HoloDomainBlock[] = [];
  for (const block of blocks) {
    if (!isGroupBlock(block)) {
      otherBlocks.push(block);
      continue;
    }
    groups.push({
      type: 'SpatialGroup',
      name: block.name,
      properties: Object.entries(block.properties ?? {}).map(([key, value]) => ({
        type: 'GroupProperty' as const,
        key,
        value,
      })),
      objects: block.children ?? [],
      ...(block.loc ? { loc: block.loc } : {}),
    });
  }
  return {
    ...composition,
    domainBlocks: otherBlocks,
    spatialGroups: [...(composition.spatialGroups ?? []), ...groups],
  };
}

export abstract class CompilerBase implements ICompiler {
  protected rbac = getRBAC();

  /**
   * Sanitizes a string value for injection into a specific compiler target language.
   * Mitigates Cross-Agent Compilation Injection attacks (e.g. CWE-94).
   *
   * @param value The raw string value from the AST
   * @param target The compilation target language
   * @returns The escaped/sanitized string safe for interpolation
   */
  public escapeStringValue(value: string, target: EscapeTarget): string {
    return escapeStringValue(value, target);
  }

  /**
   * Lazy-initialized CapabilityRBAC adapter for UCAN token verification.
   * Only created when a UCAN capability token is first encountered.
   */
  private _capabilityRBAC: CapabilityRBAC | null = null;

  /**
   * Lazy-initialized SpatialZoneEnforcer for compile-time spatial zone checks.
   * Only created when spatial zone validation is first invoked.
   */
  private _spatialZoneEnforcer: SpatialZoneEnforcer | null = null;

  /**
   * Lazy-initialized documentation generator for triple-output compilation.
   * Only created when generateDocs option is enabled.
   */
  private _documentationGenerator: CompilerDocumentationGenerator | null = null;

  /**
   * Compiler name (for error messages)
   */
  protected abstract readonly compilerName: string;

  /**
   * Compile HoloComposition AST to target platform code
   * MUST be implemented by subclasses
   */
  abstract compile(
    composition: HoloComposition,
    agentToken: string,
    outputPath?: string,
    sceneGraph?: JsonLdSceneGraph
  ):
    | string
    | Record<string, string>
    | GLTFExportResult
    | ARCompilationResult
    | VRRCompilationResult
    | AndroidXRCompileResult
    | IOSCompileResult
    | any;

  /**
   * Compile to a path-keyed file map: relative output path → file contents.
   *
   * This is the standardized "emits buildable source" contract every target
   * shares — the byte-diff golden gates and the build-verify runner both consume
   * a `Record<string, string>`, so any target that implements this can be
   * gate-enforced and build-verified without bespoke per-target plumbing.
   *
   * The default handles two shapes: a single `string` (wrapped under
   * `defaultOutputFileName()`) and a string-valued object map (passed through).
   * A `compile()` result with no string output (binary/typed objects, e.g.
   * GLTFExportResult) THROWS rather than emit `"[object Object]"` garbage — those
   * targets must override. Multi-file targets (Android, AndroidXR) already override
   * to emit a full project layout. Auth is delegated to `compile()`, which each
   * subclass already gates; this method does not re-validate.
   *
   * @param composition - HoloScript AST
   * @param agentToken - JWT token proving agent identity (default '' bypasses RBAC)
   * @returns Map of relative output path → file contents
   */
  compileToFiles(composition: HoloComposition, agentToken = ''): Record<string, string> {
    const result = this.compile(composition, agentToken);
    if (typeof result === 'string') {
      return { [this.defaultOutputFileName()]: result };
    }
    if (result && typeof result === 'object') {
      // Already path-keyed (or close enough) — keep string entries as-is.
      const out: Record<string, string> = {};
      for (const [k, v] of Object.entries(result as Record<string, unknown>)) {
        if (typeof v === 'string') out[k] = v;
      }
      if (Object.keys(out).length > 0) return out;
    }
    // Fail loud: a compile() result with no string output (e.g. GLTFExportResult — binary/object
    // fields only) cannot be represented as a source-file map by the default. Emitting
    // String(result) would feed "[object Object]" to the byte-diff gate and build-verify runner —
    // silent garbage. Such targets MUST override compileToFiles().
    throw new Error(
      `${this.constructor.name}.compileToFiles(): compile() produced no string output ` +
        `(binary/object result); this target must override compileToFiles() to emit a path-keyed source map.`
    );
  }

  /**
   * Default single-file output name for the wrapping `compileToFiles()` default.
   * Override to name a single-file target's emit (e.g. `index.ts`, `Main.kt`).
   */
  protected defaultOutputFileName(): string {
    return 'output.txt';
  }

  /**
   * {@link flattenCompositionScenes}, for a compiler that extends this base. It
   * calls this at the start of `compile()`, compiles the composition it returns,
   * and writes {@link CompilerBase.sceneWarnings} into its output.
   */
  protected flattenScenes(
    composition: HoloComposition,
    identifierOf?: (name: string) => string,
    declared?: DeclaredIdentifiers
  ): FlattenedScenes {
    return flattenCompositionScenes(composition, identifierOf, declared);
  }

  /**
   * One plain sentence for each piece of scene content {@link CompilerBase.flattenScenes}
   * left out, with names escaped for `target` and kept on one line. The compiler
   * writes each sentence into its output as a WARNING comment.
   */
  protected sceneWarnings(flattened: FlattenedScenes, target: EscapeTarget): string[] {
    return describeLeftOutScenes(flattened, target);
  }

  // =========================================================================
  // P3 Migration Bridge: Dual-mode token support
  // =========================================================================

  /**
   * Get or create the CapabilityRBAC adapter instance.
   *
   * Lazily initialized to avoid overhead when only JWT tokens are used.
   */
  protected getCapabilityRBAC(): CapabilityRBAC {
    if (!this._capabilityRBAC) {
      this._capabilityRBAC = getCapabilityRBAC();
    }
    return this._capabilityRBAC;
  }

  /**
   * Get or create the SpatialZoneEnforcer instance.
   *
   * Lazily initialized to avoid overhead when spatial zones are not in use.
   */
  protected getSpatialZoneEnforcer(): SpatialZoneEnforcer {
    if (!this._spatialZoneEnforcer) {
      this._spatialZoneEnforcer = getSpatialZoneEnforcer();
    }
    return this._spatialZoneEnforcer;
  }

  /**
   * Get or create the CompilerDocumentationGenerator instance.
   *
   * Lazily initialized to avoid overhead when documentation generation is disabled.
   *
   * @param options - Documentation generator options
   */
  protected getDocumentationGenerator(
    options?: DocumentationGeneratorOptions
  ): CompilerDocumentationGenerator {
    if (!this._documentationGenerator) {
      this._documentationGenerator = new CompilerDocumentationGenerator(options);
    }
    return this._documentationGenerator;
  }

  /**
   * Generate triple-output documentation for a compilation result.
   *
   * This is a utility method that subclasses can call after successful compilation
   * to generate llms.txt, .well-known/mcp, and markdown documentation.
   *
   * @param composition - Parsed HoloScript composition AST
   * @param compiledCode - The compiled output code
   * @param options - Documentation generator options
   * @returns Triple-output documentation bundle
   *
   * @example
   * ```typescript
   * compile(composition: HoloComposition, agentToken: string, options?: MyCompilerOptions): CompilationResult {
   *   this.validateCompilerAccess(agentToken);
   *   const code = this.performCompilation(composition);
   *
   *   if (options?.generateDocs) {
   *     const docs = this.generateDocumentation(composition, code, options.docsOptions);
   *     return { output: code, documentation: docs };
   *   }
   *
   *   return { output: code };
   * }
   * ```
   */
  protected generateDocumentation(
    composition: HoloComposition,
    compiledCode: string | Record<string, string>,
    options?: DocumentationGeneratorOptions,
    generationMeta?: TripleOutputGenerationMeta
  ): TripleOutputResult {
    const generator = this.getDocumentationGenerator(options);
    return generator.generate(composition, this.compilerName, compiledCode, generationMeta);
  }

  /**
   * Normalize primary compiler output for llms.txt / markdown (avoid huge/binary payloads).
   */
  protected serializeOutputForDocumentation(
    output: CompilationResult['output']
  ): string | Record<string, string> {
    if (typeof output === 'string') {
      return output.length > 200_000 ? output.slice(0, 200_000) : output;
    }
    if (output && typeof output === 'object') {
      const rec = output as Record<string, unknown>;
      if ('gltf' in rec || 'buffers' in rec) {
        return {
          _kind: 'binary_or_gltf_bundle',
          keys: Object.keys(rec).join(','),
        };
      }
      const vals = Object.values(rec);
      if (vals.length > 0 && vals.every((v) => typeof v === 'string')) {
        return rec as Record<string, string>;
      }
      try {
        const json = JSON.stringify(output);
        return json.length > 200_000 ? json.slice(0, 200_000) : json;
      } catch {
        return { _kind: 'non_serializable', keys: Object.keys(rec).join(',') };
      }
    }
    return String(output);
  }

  /** Short digest for MCP card `_meta.holoscript.compilation_digest`. */
  protected digestForDocumentation(docPayload: string | Record<string, string>): string {
    const payload = typeof docPayload === 'string' ? docPayload : JSON.stringify(docPayload);
    return createHash('sha256').update(payload).digest('hex').slice(0, 16);
  }

  /**
   * When `generateDocs` is set on {@link BaseCompilerOptions}, returns a {@link CompilationResult}
   * with `documentation` (llms.txt, .well-known/mcp, markdown); otherwise returns `output` unchanged.
   */
  protected withTripleOutputIfRequested(
    composition: HoloComposition,
    output: unknown,
    opts?: BaseCompilerOptions
  ): unknown | CompilationResult {
    if (!opts?.generateDocs) {
      return output;
    }
    const docPayload = this.serializeOutputForDocumentation(output as CompilationResult['output']);
    const generationMeta: TripleOutputGenerationMeta = {
      compilationDigest: this.digestForDocumentation(docPayload),
    };
    const documentation = this.generateDocumentation(
      composition,
      docPayload,
      opts.docsOptions,
      generationMeta
    );
    return { output, documentation };
  }

  /**
   * Get the ANS capability namespace path for this compiler.
   *
   * Subclasses MAY override this to specify their exact ANS namespace.
   * The default implementation derives it from `compilerName` using the
   * `COMPILER_CLASS_TO_ANS_NAME` lookup table.
   *
   * @returns The ANS capability path (e.g., "/compile/web3d/r3f"), or
   *          `undefined` if the compiler has no registered ANS namespace.
   *
   * @example
   * ```typescript
   * // Default: derives from compilerName
   * class R3FCompiler extends CompilerBase {
   *   protected readonly compilerName = 'R3FCompiler';
   *   // getRequiredCapability() returns '/compile/web3d/r3f' automatically
   * }
   *
   * // Override: explicit namespace
   * class CustomCompiler extends CompilerBase {
   *   protected readonly compilerName = 'CustomCompiler';
   *   protected getRequiredCapability(): string | undefined {
   *     return '/compile/web3d/r3f';
   *   }
   * }
   * ```
   */
  protected getRequiredCapability(): string | undefined {
    const ansName = COMPILER_CLASS_TO_ANS_NAME[this.compilerName];
    if (ansName && isValidCompilerName(ansName)) {
      return COMPILER_ANS_MAP[ansName];
    }
    // Warn when a compiler subclass is missing from the ANS map — UCAN capability
    // checks will be skipped silently for this compiler until it is registered.
    if (process.env['NODE_ENV'] !== 'test') {
      console.warn(
        `[CompilerBase] Compiler '${this.compilerName}' has no ANS namespace entry. ` +
          `Add it to COMPILER_CLASS_TO_ANS_NAME to enable UCAN capability enforcement.`
      );
    }
    return undefined;
  }

  // =========================================================================
  // Legacy JWT RBAC validation (unchanged from v1.0.0)
  // =========================================================================

  /**
   * Validate agent can read AST
   * Skips validation when no token is provided.
   * In production (`NODE_ENV=production`) a warning is emitted when no token is
   * supplied — callers should always authenticate compiler access in production.
   *
   * @param agentToken - Agent JWT token (optional)
   * @throws UnauthorizedCompilerAccessError if token is provided but invalid
   */
  protected validateASTAccess(agentToken?: string): void {
    if (!agentToken) {
      if (process.env['NODE_ENV'] === 'production') {
        console.warn(
          `[${this.compilerName}] validateASTAccess called without a token in production. ` +
            'All compiler calls should be authenticated. Pass an agent token to enforce RBAC.'
        );
      }
      return;
    }

    const decision = this.rbac.checkAccess({
      token: agentToken,
      resourceType: ResourceType.AST,
      operation: 'read',
      expectedWorkflowStep: WorkflowStep.GENERATE_ASSEMBLY,
    });

    if (!decision.allowed) {
      throw new UnauthorizedCompilerAccessError(decision, 'AST access', this.compilerName);
    }
  }

  /**
   * Validate agent can generate code
   * Skips validation when no token is provided.
   * In production (`NODE_ENV=production`) a warning is emitted when no token is
   * supplied — callers should always authenticate compiler access in production.
   *
   * @param agentToken - Agent JWT token (optional)
   * @throws UnauthorizedCompilerAccessError if token is provided but invalid
   */
  protected validateCodeGeneration(agentToken?: string): void {
    if (!agentToken) {
      if (process.env['NODE_ENV'] === 'production') {
        console.warn(
          `[${this.compilerName}] validateCodeGeneration called without a token in production. ` +
            'All compiler calls should be authenticated. Pass an agent token to enforce RBAC.'
        );
      }
      return;
    }

    const decision = this.rbac.checkAccess({
      token: agentToken,
      resourceType: ResourceType.CODE,
      operation: 'write',
      expectedWorkflowStep: WorkflowStep.GENERATE_ASSEMBLY,
    });

    if (!decision.allowed) {
      throw new UnauthorizedCompilerAccessError(decision, 'code generation', this.compilerName);
    }
  }

  /**
   * Validate agent can write to output path
   * Skips validation when no token is provided.
   * In production (`NODE_ENV=production`) a warning is emitted when no token is
   * supplied — callers should always authenticate compiler access in production.
   *
   * @param agentToken - Agent JWT token (optional)
   * @param outputPath - Target output file path
   * @throws UnauthorizedCompilerAccessError if token is provided but invalid
   */
  protected validateOutputPath(agentToken?: string, outputPath?: string): void {
    if (!agentToken) {
      if (process.env['NODE_ENV'] === 'production') {
        console.warn(
          `[${this.compilerName}] validateOutputPath called without a token in production. ` +
            'All compiler calls should be authenticated. Pass an agent token to enforce RBAC.'
        );
      }
      return;
    }

    const decision = this.rbac.checkAccess({
      token: agentToken,
      resourceType: ResourceType.OUTPUT,
      operation: 'write',
      resourcePath: outputPath,
      expectedWorkflowStep: WorkflowStep.SERIALIZE,
    });

    if (!decision.allowed) {
      throw new UnauthorizedCompilerAccessError(
        decision,
        `output write to '${outputPath}'`,
        this.compilerName
      );
    }
  }

  // =========================================================================
  // UCAN Capability Token validation (P3 Migration Bridge)
  // =========================================================================

  /**
   * Validate compiler access using a UCAN capability token.
   *
   * Checks that the capability token grants access to the required resources
   * (AST read, CODE write, and optionally OUTPUT write) using the
   * CapabilityRBAC adapter.
   *
   * @param credential - UCAN capability token credential
   * @param outputPath - Optional output path for scope validation
   * @throws UnauthorizedCompilerAccessError if any capability check fails
   */
  protected validateCapabilityAccess(
    credential: CapabilityTokenCredential,
    outputPath?: string
  ): void {
    const capRBAC = this.getCapabilityRBAC();

    // Check AST read access
    const astDecision = capRBAC.checkAccess({
      token: '',
      capabilityToken: credential.capabilityToken,
      issuerPublicKey: credential.issuerPublicKey,
      resourceType: ResourceType.AST,
      operation: 'read',
    });

    if (!astDecision.allowed) {
      throw new UnauthorizedCompilerAccessError(astDecision, 'AST access', this.compilerName);
    }

    // Check CODE write access
    const codeDecision = capRBAC.checkAccess({
      token: '',
      capabilityToken: credential.capabilityToken,
      issuerPublicKey: credential.issuerPublicKey,
      resourceType: ResourceType.CODE,
      operation: 'write',
    });

    if (!codeDecision.allowed) {
      throw new UnauthorizedCompilerAccessError(codeDecision, 'code generation', this.compilerName);
    }

    // Check OUTPUT write access (if outputPath provided)
    if (outputPath) {
      const outputDecision = capRBAC.checkAccess({
        token: '',
        capabilityToken: credential.capabilityToken,
        issuerPublicKey: credential.issuerPublicKey,
        resourceType: ResourceType.OUTPUT,
        operation: 'write',
        resourcePath: outputPath,
      });

      if (!outputDecision.allowed) {
        throw new UnauthorizedCompilerAccessError(
          outputDecision,
          `output write to '${outputPath}'`,
          this.compilerName
        );
      }
    }
  }

  // =========================================================================
  // Spatial Memory Zone validation
  // =========================================================================

  /**
   * Validate spatial zone access for the current compilation.
   *
   * This step runs **after** RBAC/UCAN token verification and enforces
   * compile-time spatial zone permissions when zones are registered.
   *
   * **Backward compatible**: When no zones are registered in the global
   * SpatialZoneEnforcer, this method is a no-op.
   *
   * **Non-blocking**: Zone enforcement failures are logged as warnings
   * but do NOT throw or block compilation. This allows gradual rollout
   * of spatial zone policies without breaking existing pipelines.
   *
   * @param agentToken - JWT token string (spatial zones use JWT verification)
   */
  protected validateSpatialZoneAccess(agentToken?: string): void {
    // Skip when no token provided (same pattern as other validators)
    if (!agentToken) return;

    const enforcer = this.getSpatialZoneEnforcer();
    const zoneIds = enforcer.getRegisteredZoneIds();

    // No zones registered: skip silently (backward compatible)
    if (zoneIds.length === 0) return;

    // Check SPATIAL_READ access in each registered zone.
    // This verifies the agent has at minimum read-level spatial access
    // during compilation. Specific operations (write, delete, admin)
    // are enforced by the runtime layer or by subclass overrides.
    for (const zoneId of zoneIds) {
      const decision: SpatialAccessDecision = enforcer.checkZoneAccess(
        agentToken,
        zoneId,
        SpatialPermission.SPATIAL_READ
      );

      if (!decision.allowed) {
        // Log warning but do NOT block compilation.
        // Zone enforcement is advisory during the rollout phase.
        console.warn(
          `[${this.compilerName}] Spatial zone access warning: ` +
            `agent ${decision.agentId ?? 'unknown'} denied SPATIAL_READ ` +
            `in zone "${zoneId}": ${decision.reason}`
        );
      }
    }
  }

  // =========================================================================
  // Dual-mode access validation (P3 Migration Bridge)
  // =========================================================================

  /**
   * Validate all compiler permissions in single call (dual-mode).
   *
   * **P3 Migration Bridge**: This method now accepts both JWT RBAC tokens
   * (string) and UCAN capability tokens (CapabilityTokenCredential).
   *
   * Token routing:
   * - `undefined` / `null` / empty string: Skip all validation (backwards compatibility)
   * - `string` (non-empty): Route to legacy JWT RBAC via AgentRBAC.checkAccess()
   * - `CapabilityTokenCredential`: Route to UCAN via CapabilityRBAC.checkAccess()
   *
   * Convenience method combining AST access + code generation + optional output validation.
   * Skips ALL validation when no token is provided (backwards compatibility / testing).
   *
   * @param agentToken - JWT token string OR UCAN CapabilityTokenCredential (optional)
   * @param outputPath - Optional output path
   * @throws UnauthorizedCompilerAccessError if any validation fails
   */
  protected validateCompilerAccess(agentToken?: CompilerToken, outputPath?: string): void {
    // Skip validation when no token provided (backwards compatibility)
    if (!agentToken) return;

    // P3 Migration Bridge: Route to UCAN capability verification
    if (isCapabilityTokenCredential(agentToken)) {
      this.validateCapabilityAccess(agentToken, outputPath);
      // Note: Spatial zone validation requires a JWT string token.
      // UCAN tokens do not carry the sub/agent_role claims that
      // SpatialZoneEnforcer needs, so spatial checks are skipped
      // for UCAN credentials.
      return;
    }

    // Legacy JWT RBAC path (unchanged behavior)
    this.validateASTAccess(agentToken);
    this.validateCodeGeneration(agentToken);
    if (outputPath) {
      this.validateOutputPath(agentToken, outputPath);
    }

    // Spatial zone enforcement (runs after RBAC token verification).
    // Non-blocking: logs warnings but does not throw.
    this.validateSpatialZoneAccess(agentToken);
  }

  // =========================================================================
  // Cultural compatibility validation
  // =========================================================================

  /**
   * Extract cultural profile from an agent token.
   *
   * @param agentToken - JWT token string (capability tokens do not carry cultural profiles)
   * @returns The cultural profile if present, or null
   */
  protected extractCulturalProfile(agentToken?: string): CulturalProfileMetadata | null {
    if (!agentToken) return null;
    return this.rbac.extractCulturalProfile(agentToken);
  }

  /**
   * Validate cultural compatibility across multiple agent tokens.
   *
   * Subclasses can call this during multi-agent compilation to ensure
   * all participating agents have compatible cultural profiles before
   * proceeding with code generation.
   *
   * @param agentTokens - Map of agent name to JWT token
   * @param normSets    - Optional map of agent name to norm_set arrays
   * @returns Cultural compatibility result, or null if fewer than 2 agents
   *          have cultural profiles
   */
  protected validateCulturalCompatibility(
    agentTokens: Map<string, string>,
    normSets?: Map<string, string[]>
  ): CulturalCompatibilityResult | null {
    return this.rbac.validateCulturalCompatibility(agentTokens, normSets);
  }
}

/**
 * Utility: Create a test token for development/testing
 *
 * WARNING: Only use in non-production environments!
 *
 * @returns Valid code generator token for testing
 */
export function createTestCompilerToken(): string {
  // Return empty string to bypass RBAC validation in tests
  // The validateCompilerAccess methods skip when agentToken is falsy
  return '';
}