@openfairygui/backend 0.2.0-alpha.8 → 0.2.0

package/dist/node.d.cts

@@ -1,8 +1,513 @@
-import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-Jec6FcF5.cjs";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
+import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
 
+//#region src/path-policy.d.ts
+interface PathPolicyViolationError {
+  code: 'path_policy_violation';
+  message: string;
+  policy: 'save_target';
+  attemptedPath: string;
+  allowedPath: string;
+}
+//#endregion
+//#region src/contracts.d.ts
+declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
+declare const BACKEND_CAPABILITY_SCHEMA_VERSION: 2;
+declare const BACKEND_COMPATIBILITY_POLICY: {
+  readonly incompatibleChange: "requires contractVersion bump";
+  readonly capabilitySchemaChange: "requires capabilitySchemaVersion bump";
+  readonly additiveChange: "allowed without breaking existing consumers";
+};
+type BackendStage = 'read' | 'authoring' | 'runtime';
+interface BackendMessage {
+  code: string;
+  message: string;
+}
+interface BackendDiagnostic {
+  code: string;
+  message: string;
+  severity: 'info' | 'warning' | 'error';
+  path?: string;
+  nodeKind?: string;
+  resourceKind?: string;
+  gearKind?: string;
+  field?: string;
+  operationKind?: string;
+  opIndex?: number;
+  opId?: string;
+}
+interface BackendResponseMeta {
+  requestId: string;
+  sessionId?: string;
+  revision?: number;
+  durationMs: number;
+  warnings: BackendMessage[];
+  diagnostics: BackendDiagnostic[];
+  stage: BackendStage;
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+}
+//#endregion
+//#region src/runtime/contracts.d.ts
+/** An exclusive lock owned for the lifetime of one backend session. */
+interface BackendSessionLock {
+  /** Persist optional host metadata without changing lock ownership. */
+  writeMetadata(content: string): Promise<void>;
+  /** Release ownership. Browser implementations must also release when their document terminates. */
+  release(): Promise<void>;
+}
+interface BackendFileStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+}
+interface BackendFileSystem {
+  stat(filePath: string): Promise<BackendFileStat>;
+  readdir(dirPath: string): Promise<string[]>;
+  readFile(filePath: string): Promise<string>;
+  readFileRaw(filePath: string): Promise<Uint8Array>;
+  writeFile(filePath: string, content: string): Promise<void>;
+  writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+  mkdir(dirPath: string, options?: {
+    recursive?: boolean;
+  }): Promise<void>;
+  resolvePath(filePath: string): Promise<string>;
+  acquireSessionLock(lockPath: string): Promise<BackendSessionLock>;
+  unlink(filePath: string): Promise<void>;
+  rmdir(dirPath: string): Promise<void>;
+  join(...paths: string[]): string;
+  dirname(filePath: string): string;
+  resolve(...paths: string[]): string;
+}
+interface BackendHostAdapter {
+  lockMetadata?(input: {
+    canonicalPathKey: string;
+    canonicalProjectPath: string;
+    lockFilePath: string;
+  }): unknown;
+}
+interface BackendArtifactBridgeCapability {
+  available: false;
+  requiredHost: 'node';
+  executionBoundary: 'external-bridge';
+  bridgeEntrypoint: '@openfairygui/backend/node';
+  reason: string;
+}
+interface BackendCapabilityManifest {
+  browserSafe: true;
+  rootEntrypoint: '@openfairygui/backend';
+  nodeEntrypoint: '@openfairygui/backend/node';
+  adapters: {
+    fileSystem: {
+      injected: true;
+      requiredFor: readonly ['openSession', 'saveSession', 'materializeSession'];
+    };
+    projectStorage: {
+      injected: true;
+      browserSafe: true;
+      requiredFor: readonly ['openProjectSession.writeback', 'saveSession', 'materializeSession'];
+      adapterFactory: 'createBackendStorageFileSystem';
+    };
+    host: {
+      injected: true;
+      requiredFor: readonly ['advisoryLockMetadata'];
+    };
+  };
+  executionBoundaries: {
+    projectSession: 'in-process-browser-safe';
+    fileBackedSession: 'adapter-backed';
+    artifactPublish: BackendArtifactBridgeCapability;
+    artifactRestore: BackendArtifactBridgeCapability;
+  };
+  diagnostics: {
+    stableCodes: true;
+    errorDiagnosticMirror: true;
+  };
+}
+interface BackendCapabilities {
+  contractVersion: typeof BACKEND_CONTRACT_VERSION;
+  capabilitySchemaVersion: typeof BACKEND_CAPABILITY_SCHEMA_VERSION;
+  transactionKernelOwner: '@openfairygui/core';
+  appSeamOwner: '@openfairygui/functions';
+  runtimeOwner: '@openfairygui/backend';
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  read: {
+    capabilitySnapshot: true;
+    sessionSnapshot: true;
+  };
+  authoring: {
+    applyTransaction: true;
+    saveSession: true;
+    resourceKinds: readonly string[];
+    nodeKinds: readonly string[];
+    gearKinds: readonly string[];
+    transactionScope: {
+      resourceKinds: readonly string[];
+      nodeKinds: readonly string[];
+      gearKinds: readonly string[];
+    };
+    unsupported: readonly ['artifact.publish', 'artifact.restore'];
+  };
+  artifact: {
+    publish: false;
+    restore: false;
+    status: 'bridge-required';
+    publishBridge: BackendArtifactBridgeCapability;
+    restoreBridge: BackendArtifactBridgeCapability;
+  };
+  manifest: BackendCapabilityManifest;
+  compatibilityPolicy: typeof BACKEND_COMPATIBILITY_POLICY;
+  runtime: {
+    sessionRuntime: true;
+    advisoryLocking: true;
+    coordinatedSave: true;
+    atomicSave: false;
+    staleRevisionProtection: true;
+    pathPolicy: {
+      canonicalization: 'realpath+normalized-casefold';
+      sessionIdentity: 'project-root';
+      saveTarget: 'opened-project-only';
+      outputTargets: 'deferred';
+      workspaceBoundary: 'project-root-only';
+    };
+    events: {
+      polling: true;
+      subscriptions: false;
+      retentionLimit: 1000;
+      sequenceScope: 'runtime';
+    };
+    jobs: {
+      inMemory: true;
+      cooperativeCancel: true;
+      persistent: false;
+      supportedKinds: readonly ['cache.refresh'];
+      artifactJobs: false;
+      completedRetentionLimit: 100;
+    };
+    cache: {
+      derivedReadOnly: true;
+      keyedBy: 'canonicalPathKey';
+      sourceOfTruth: false;
+      refreshMethod: 'refreshCache';
+    };
+  };
+}
+interface BackendSessionSnapshot {
+  sessionId: string;
+  canonicalProjectPath: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  uamFidelity: 'full' | 'unsupported';
+  lockHeld: boolean;
+  capabilities: BackendCapabilities;
+}
+interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
+  mode: 'fullProject';
+  reason?: string;
+  materializeRevision: number;
+  saveRevision: number;
+  writtenPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+}
+interface BackendSuccess<T> {
+  ok: true;
+  meta: BackendResponseMeta;
+  data: T;
+}
+interface BackendFailure<E extends BackendError = BackendError> {
+  ok: false;
+  meta: BackendResponseMeta;
+  error: E;
+  session?: BackendSessionSnapshot;
+}
+type BackendResult<T, E extends BackendError = BackendError> = BackendSuccess<T> | BackendFailure<E>;
+interface SessionNotFoundError {
+  code: 'session_not_found';
+  message: string;
+  sessionId: string;
+}
+interface SessionStaleWriteError {
+  code: 'stale_write';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  expectedRevision: number;
+  actualRevision: number;
+}
+interface InProcessLockConflictError {
+  code: 'lock_conflict';
+  kind: 'in_process_session_exists';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId: string;
+  lockFilePath?: string;
+}
+interface AdvisoryLockConflictError {
+  code: 'lock_conflict';
+  kind: 'advisory_lock_conflict';
+  message: string;
+  canonicalPathKey: string;
+  holderSessionId?: string;
+  lockFilePath: string;
+}
+interface SavePartialFailureError {
+  code: 'save_partial_failure';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  committedPaths: string[];
+  failedPaths: string[];
+  diskMayBePartiallyUpdated: true;
+}
+interface UamFidelityUnsupportedError {
+  code: 'uam_fidelity_unsupported';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+}
+interface MaterializeValidationFailedError {
+  code: 'materialize_validation_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  issueCount: number;
+  diagnostics: BackendDiagnostic[];
+}
+interface MaterializeWriteFailedError {
+  code: 'write_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  writtenPaths: string[];
+  failedPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+  diskMayBePartiallyUpdated: true;
+}
+type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
+interface BackendEvent {
+  sequence: number;
+  kind: BackendEventKind;
+  timestamp: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  jobId?: string;
+  diagnostics: BackendDiagnostic[];
+  payload?: unknown;
+}
+interface GetEventsInput {
+  sessionId: string;
+  after?: string;
+  limit?: number;
+}
+interface GetEventsSnapshot {
+  events: BackendEvent[];
+  oldestSequence: number;
+  currentSequence: number;
+  cursorExpired: boolean;
+}
+interface EventCursorInvalidError {
+  code: 'event_cursor_invalid';
+  message: string;
+  sessionId: string;
+  after: string;
+}
+type BackendJobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+type BackendJobKind = 'cache.refresh';
+type BackendJobListStatusFilter = BackendJobStatus | 'active' | 'terminal';
+interface BackendJobProgress {
+  completed: number;
+  total?: number;
+  message?: string;
+}
+interface BackendJobSnapshot {
+  jobId: string;
+  kind: BackendJobKind;
+  status: BackendJobStatus;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  sessionId?: string;
+  canonicalPathKey?: string;
+  revision?: number;
+  cacheRevision?: number;
+  diagnostics: BackendDiagnostic[];
+  progress?: BackendJobProgress;
+  result?: unknown;
+  error?: BackendError;
+}
+interface BackendJobListSnapshot {
+  jobs: BackendJobSnapshot[];
+}
+interface GetJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface ListJobsInput {
+  sessionId: string;
+  status?: BackendJobListStatusFilter;
+  kind?: BackendJobKind;
+  limit?: number;
+}
+interface CancelJobInput {
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotFoundError {
+  code: 'job_not_found';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface BackendJobNotCancellableError {
+  code: 'job_not_cancellable';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  status: 'completed' | 'failed' | 'cancelled';
+}
+interface BackendJobCancelledError {
+  code: 'job_cancelled';
+  message: string;
+  sessionId: string;
+  jobId: string;
+}
+interface CacheRefreshFailedError {
+  code: 'cache_refresh_failed';
+  message: string;
+  sessionId: string;
+  jobId: string;
+  causeCode?: string;
+}
+interface BackendCapabilityUnavailableError {
+  code: 'capability_unavailable';
+  message: string;
+  capability: 'fileSystem' | 'artifact.publish' | 'artifact.restore';
+  requiredAdapter?: 'BackendFileSystem';
+  requiredHost?: 'node';
+  bridgeBoundary?: 'external-bridge';
+}
+interface BackendCacheSnapshot {
+  cacheRevision: number;
+  entries: BackendCacheEntry[];
+}
+interface BackendCacheEntry {
+  canonicalPathKey: string;
+  sessionId?: string;
+  revision: number;
+  lastSavedRevision: number;
+  dirty: boolean;
+  valid: boolean;
+  indexedAt: string;
+  summary: {
+    resourceCount: number;
+    packageCount?: number;
+    diagnostics: BackendDiagnostic[];
+  };
+}
+interface GetCacheSnapshotInput {
+  sessionId: string;
+}
+interface RefreshCacheInput {
+  sessionId: string;
+  reason?: 'manual' | 'session_open' | 'after_save';
+}
+type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+interface ApplySessionTransactionInput {
+  sessionId: string;
+  expectedRevision: number;
+  operations: UamTransactionOperation[];
+}
+interface OpenProjectSessionInput {
+  /** Authoritative UAM project. Use BackendRuntime.openSession() when importing an existing project from storage. */
+  project: UamProject;
+  sessionId?: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+  /** Optional writeback target for the authoritative UAM project; this is not an import source. */
+  storage?: BackendProjectSessionStorage;
+}
+interface BackendProjectSessionStorage {
+  fileSystem: BackendFileSystem;
+  fairyPath: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface SaveSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  force?: boolean;
+  mode?: 'materializeCleanSession';
+}
+interface MaterializeSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  storage?: BackendProjectSessionStorage;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  mode?: 'fullProject';
+  reason?: string;
+}
+interface BackendRuntimeOptions {
+  fileSystem?: BackendFileSystem;
+  host?: BackendHostAdapter;
+}
+//#endregion
+//#region src/runtime.d.ts
+declare class BackendRuntime {
+  private readonly fileSystem?;
+  private readonly capabilities;
+  private readonly sessions;
+  private readonly sessionsByPath;
+  private readonly eventsBySession;
+  private readonly jobsBySession;
+  private readonly cacheBySession;
+  private eventSequence;
+  private readonly context;
+  private readonly readService;
+  private readonly runtimeService;
+  private readonly authoringService;
+  private readonly cacheService;
+  private readonly eventService;
+  private readonly jobService;
+  constructor(options?: BackendRuntimeOptions);
+  getCapabilities(): BackendSuccess<BackendCapabilities>;
+  openSession(input: {
+    projectPath: string;
+  }): Promise<BackendResult<BackendSessionSnapshot, InProcessLockConflictError | AdvisoryLockConflictError | BackendCapabilityUnavailableError>>;
+  openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot>;
+  getSession(input: {
+    sessionId: string;
+  }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
+  applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
+  saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
+  materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | UamFidelityUnsupportedError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
+  closeSession(input: {
+    sessionId: string;
+  }): Promise<BackendResult<{
+    sessionId: string;
+    closed: true;
+  }, SessionNotFoundError>>;
+  getEvents(input: GetEventsInput): BackendResult<GetEventsSnapshot, SessionNotFoundError | EventCursorInvalidError>;
+  getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError>;
+  listJobs(input: ListJobsInput): BackendResult<BackendJobListSnapshot, SessionNotFoundError>;
+  cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError>;
+  getCacheSnapshot(input: GetCacheSnapshotInput): BackendResult<BackendCacheSnapshot, SessionNotFoundError>;
+  refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
+}
+//#endregion
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;
 declare function createNodeBackendHostAdapter(): BackendHostAdapter;
 declare function createNodeBackendRuntime(options?: BackendRuntimeOptions): BackendRuntime;
 //#endregion
-export { type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };
+export { type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, BackendRuntime, type BackendRuntimeOptions, type BackendSessionLock, createNodeBackendFileSystem, createNodeBackendHostAdapter, createNodeBackendRuntime };