@supernovae-st/nika 0.120.2 → 0.120.3

package/dist/index.d.cts

@@ -540,7 +540,7 @@ interface NikaTraceVerifyOptions {
     signal?: AbortSignal;
 }
 /** The SDK operations whose engine refusal can be returned as a typed error. */
-type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'traceVerify' | 'schedule' | 'scheduleStatus';
+type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'traceVerify' | 'schedule' | 'scheduleStatus' | 'compile';
 /** One engine-owned schedule finding. The vocabulary remains additive. */
 interface NikaScheduleFinding {
     code: string;
@@ -698,6 +698,122 @@ interface NikaScheduleApplyResult {
     changed: boolean;
     status: NikaScheduleStatus;
 }
+/**
+ * One stateless authoring request. Exactly one shape:
+ *
+ * - CREATE: `{ intent }` (or the bare-string shorthand), optionally with
+ *   `answers` to the engine's stable question keys.
+ * - EDIT: `{ workflow, change }` — the accepted workflow's SOURCE plus the
+ *   change request — optionally with `answers`.
+ *
+ * The two shapes never mix, and there is no session: every call is a fresh
+ * request carrying everything the engine needs.
+ */
+type NikaCompileRequest = NikaCompileCreateRequest | NikaCompileEditRequest;
+interface NikaCompileCreateRequest {
+    /** Intent text, or an exact embedded skeleton name in this foundation. */
+    intent: string;
+    /**
+     * Answers to engine questions, by stable question key (`const.request`),
+     * as strict JSON values — never pre-serialized text. The SDK serializes
+     * each value exactly once onto the argv `KEY=JSON` channel; a value JSON
+     * cannot carry refuses with `NikaConfigurationError` before any spawn.
+     */
+    answers?: Record<string, unknown>;
+    workflow?: never;
+    change?: never;
+}
+interface NikaCompileEditRequest {
+    /** The accepted workflow's exact source bytes (as a string). */
+    workflow: string;
+    /**
+     * The requested change: free text in the engine's supported edit
+     * vocabulary, or one structured constant edit mirroring the engine's
+     * `set_constant` operation. The value is a strict JSON value, judged by
+     * the same law as `answers`.
+     */
+    change: string | NikaCompileSetConstant;
+    answers?: Record<string, unknown>;
+    intent?: never;
+}
+/** One structured constant edit, mirroring the engine's `set_constant`. */
+interface NikaCompileSetConstant {
+    set_constant: {
+        /** Bare constant name (no `const.` prefix, no path). */
+        name: string;
+        /** The new literal, as a strict JSON value. */
+        value: unknown;
+    };
+}
+interface NikaCompileOptions {
+    /**
+     * Aborts this authoring process only. Compile owns no Run: this never
+     * touches `run.cancel()` semantics (client#126), and no workflow effect
+     * exists to interrupt.
+     */
+    signal?: AbortSignal;
+    /** Positive integer milliseconds before the compile child or HTTP request is stopped. */
+    timeoutMs?: number;
+}
+/** The engine's own completeness words; `ready` is never derived from confidence. */
+type NikaCompileStatus = 'ready' | 'incomplete' | 'refused';
+/** One authoring question, exactly as the engine emitted it. */
+interface NikaCompileQuestion {
+    /** Stable semantic hole path (`const.request`), never a session id. */
+    key: string;
+    label: string;
+    type: 'text' | 'literal';
+    why: string;
+    mandatory: boolean;
+    [key: string]: unknown;
+}
+/** One structured authoring finding, exactly as the engine emitted it. */
+interface NikaCompileDiagnostic {
+    kind: 'applied' | 'missed' | 'unknown' | 'requiresHuman' | 'refused';
+    target: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** Authoring provenance — not program identity (#1664), not execution Proof. */
+interface NikaCompileProvenance {
+    compiler_version: string;
+    spec_pin: string;
+    skeleton: string | null;
+    cognition: 'deterministicOnly';
+    [key: string]: unknown;
+}
+/** The candidate's pure Check judgment, with its deliberately limited scope. */
+interface NikaCompilePreview {
+    /** `sourceOnly` in this foundation: no environment or admission claim. */
+    scope: 'sourceOnly';
+    report: NikaCheckResult;
+    [key: string]: unknown;
+}
+/**
+ * The reviewable authoring result. `candidate` is ordinary `.nika`
+ * SOURCE in memory — it is not a `Workflow` handle, and `run()` does not
+ * accept raw source: the caller materializes the candidate and `run(path)`
+ * re-admits it. The SDK never writes the candidate for you in this slice
+ * (no `dest`/`force`), and the engine never executes it.
+ *
+ * `incomplete` and `refused` are data, not exceptions: the SDK throws only
+ * on transport, protocol, compatibility and engine-stamped failures.
+ */
+interface NikaCompileOutcome {
+    /** The wire generation this payload was validated against. Always 1. */
+    compile_version: 1;
+    status: NikaCompileStatus;
+    /** Exactly `status === 'ready'` — the engine's word, not a client judgment. */
+    ready: boolean;
+    /** The candidate source; may still carry unfilled holes when not ready. */
+    candidate: string | null;
+    questions: NikaCompileQuestion[];
+    diagnostics: NikaCompileDiagnostic[];
+    /** The boundary the candidate requests (from its pure report); never a grant. */
+    requested_boundary: Record<string, unknown> | null;
+    check_preview: NikaCompilePreview | null;
+    provenance: NikaCompileProvenance;
+}
 
 declare class NikaError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -833,6 +949,21 @@ declare class Nika {
     private readonly eventBufferSize;
     constructor(config?: NikaConfig);
     check(workflow: string, options?: NikaCheckOptions): Promise<NikaCheckResult>;
+    /**
+     * Authoring (issue #128): describe work — or name an accepted workflow plus
+     * a change — and get the engine's checked candidate back, without running
+     * anything. `compile()` never means `run()`: the outcome is data (candidate
+     * source, questions, diagnostics, requested boundary, source-only Check
+     * preview, provenance), `incomplete`/`refused` resolve instead of throwing,
+     * and no workflow effect, approval or Proof exists.
+     *
+     * The candidate is ordinary `.nika` SOURCE. `run()` consumes a path,
+     * so the caller materializes the candidate and `run(path)` re-admits it —
+     * the compile preview is a review, never admission. Over `{ url }` this calls
+     * the authenticated Serve compile door, gated by its advertised capability;
+     * the SDK never compiles locally as a fallback.
+     */
+    compile(request: string | NikaCompileRequest, options?: NikaCompileOptions): Promise<NikaCompileOutcome>;
     /**
      * Resolves with the run's handle once the engine admitted it, and rejects
      * without one when the engine refused it. The handle owns the lifecycle:
@@ -886,4 +1017,4 @@ declare class Nika {
     private session;
 }
 
-export { Nika, type NikaAttachRunOptions, type NikaCancelResult, type NikaCheckFinding, type NikaCheckOptions, type NikaCheckResult, NikaCompatibilityError, type NikaConfig, NikaConfigurationError, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaJournalEvidence, type NikaLocalConfig, type NikaMachineError, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunEvent, type NikaRunEventKind, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSettlement, type NikaSpend, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaRunSucceeded, isNikaTerminalEvent };
+export { Nika, type NikaAttachRunOptions, type NikaCancelResult, type NikaCheckFinding, type NikaCheckOptions, type NikaCheckResult, NikaCompatibilityError, type NikaCompileDiagnostic, type NikaCompileOptions, type NikaCompileOutcome, type NikaCompilePreview, type NikaCompileProvenance, type NikaCompileQuestion, type NikaCompileRequest, type NikaCompileSetConstant, type NikaCompileStatus, type NikaConfig, NikaConfigurationError, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaJournalEvidence, type NikaLocalConfig, type NikaMachineError, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunEvent, type NikaRunEventKind, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSettlement, type NikaSpend, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaRunSucceeded, isNikaTerminalEvent };

package/dist/index.d.ts

@@ -540,7 +540,7 @@ interface NikaTraceVerifyOptions {
     signal?: AbortSignal;
 }
 /** The SDK operations whose engine refusal can be returned as a typed error. */
-type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'traceVerify' | 'schedule' | 'scheduleStatus';
+type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'traceVerify' | 'schedule' | 'scheduleStatus' | 'compile';
 /** One engine-owned schedule finding. The vocabulary remains additive. */
 interface NikaScheduleFinding {
     code: string;
@@ -698,6 +698,122 @@ interface NikaScheduleApplyResult {
     changed: boolean;
     status: NikaScheduleStatus;
 }
+/**
+ * One stateless authoring request. Exactly one shape:
+ *
+ * - CREATE: `{ intent }` (or the bare-string shorthand), optionally with
+ *   `answers` to the engine's stable question keys.
+ * - EDIT: `{ workflow, change }` — the accepted workflow's SOURCE plus the
+ *   change request — optionally with `answers`.
+ *
+ * The two shapes never mix, and there is no session: every call is a fresh
+ * request carrying everything the engine needs.
+ */
+type NikaCompileRequest = NikaCompileCreateRequest | NikaCompileEditRequest;
+interface NikaCompileCreateRequest {
+    /** Intent text, or an exact embedded skeleton name in this foundation. */
+    intent: string;
+    /**
+     * Answers to engine questions, by stable question key (`const.request`),
+     * as strict JSON values — never pre-serialized text. The SDK serializes
+     * each value exactly once onto the argv `KEY=JSON` channel; a value JSON
+     * cannot carry refuses with `NikaConfigurationError` before any spawn.
+     */
+    answers?: Record<string, unknown>;
+    workflow?: never;
+    change?: never;
+}
+interface NikaCompileEditRequest {
+    /** The accepted workflow's exact source bytes (as a string). */
+    workflow: string;
+    /**
+     * The requested change: free text in the engine's supported edit
+     * vocabulary, or one structured constant edit mirroring the engine's
+     * `set_constant` operation. The value is a strict JSON value, judged by
+     * the same law as `answers`.
+     */
+    change: string | NikaCompileSetConstant;
+    answers?: Record<string, unknown>;
+    intent?: never;
+}
+/** One structured constant edit, mirroring the engine's `set_constant`. */
+interface NikaCompileSetConstant {
+    set_constant: {
+        /** Bare constant name (no `const.` prefix, no path). */
+        name: string;
+        /** The new literal, as a strict JSON value. */
+        value: unknown;
+    };
+}
+interface NikaCompileOptions {
+    /**
+     * Aborts this authoring process only. Compile owns no Run: this never
+     * touches `run.cancel()` semantics (client#126), and no workflow effect
+     * exists to interrupt.
+     */
+    signal?: AbortSignal;
+    /** Positive integer milliseconds before the compile child or HTTP request is stopped. */
+    timeoutMs?: number;
+}
+/** The engine's own completeness words; `ready` is never derived from confidence. */
+type NikaCompileStatus = 'ready' | 'incomplete' | 'refused';
+/** One authoring question, exactly as the engine emitted it. */
+interface NikaCompileQuestion {
+    /** Stable semantic hole path (`const.request`), never a session id. */
+    key: string;
+    label: string;
+    type: 'text' | 'literal';
+    why: string;
+    mandatory: boolean;
+    [key: string]: unknown;
+}
+/** One structured authoring finding, exactly as the engine emitted it. */
+interface NikaCompileDiagnostic {
+    kind: 'applied' | 'missed' | 'unknown' | 'requiresHuman' | 'refused';
+    target: string;
+    message: string;
+    [key: string]: unknown;
+}
+/** Authoring provenance — not program identity (#1664), not execution Proof. */
+interface NikaCompileProvenance {
+    compiler_version: string;
+    spec_pin: string;
+    skeleton: string | null;
+    cognition: 'deterministicOnly';
+    [key: string]: unknown;
+}
+/** The candidate's pure Check judgment, with its deliberately limited scope. */
+interface NikaCompilePreview {
+    /** `sourceOnly` in this foundation: no environment or admission claim. */
+    scope: 'sourceOnly';
+    report: NikaCheckResult;
+    [key: string]: unknown;
+}
+/**
+ * The reviewable authoring result. `candidate` is ordinary `.nika`
+ * SOURCE in memory — it is not a `Workflow` handle, and `run()` does not
+ * accept raw source: the caller materializes the candidate and `run(path)`
+ * re-admits it. The SDK never writes the candidate for you in this slice
+ * (no `dest`/`force`), and the engine never executes it.
+ *
+ * `incomplete` and `refused` are data, not exceptions: the SDK throws only
+ * on transport, protocol, compatibility and engine-stamped failures.
+ */
+interface NikaCompileOutcome {
+    /** The wire generation this payload was validated against. Always 1. */
+    compile_version: 1;
+    status: NikaCompileStatus;
+    /** Exactly `status === 'ready'` — the engine's word, not a client judgment. */
+    ready: boolean;
+    /** The candidate source; may still carry unfilled holes when not ready. */
+    candidate: string | null;
+    questions: NikaCompileQuestion[];
+    diagnostics: NikaCompileDiagnostic[];
+    /** The boundary the candidate requests (from its pure report); never a grant. */
+    requested_boundary: Record<string, unknown> | null;
+    check_preview: NikaCompilePreview | null;
+    provenance: NikaCompileProvenance;
+}
 
 declare class NikaError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -833,6 +949,21 @@ declare class Nika {
     private readonly eventBufferSize;
     constructor(config?: NikaConfig);
     check(workflow: string, options?: NikaCheckOptions): Promise<NikaCheckResult>;
+    /**
+     * Authoring (issue #128): describe work — or name an accepted workflow plus
+     * a change — and get the engine's checked candidate back, without running
+     * anything. `compile()` never means `run()`: the outcome is data (candidate
+     * source, questions, diagnostics, requested boundary, source-only Check
+     * preview, provenance), `incomplete`/`refused` resolve instead of throwing,
+     * and no workflow effect, approval or Proof exists.
+     *
+     * The candidate is ordinary `.nika` SOURCE. `run()` consumes a path,
+     * so the caller materializes the candidate and `run(path)` re-admits it —
+     * the compile preview is a review, never admission. Over `{ url }` this calls
+     * the authenticated Serve compile door, gated by its advertised capability;
+     * the SDK never compiles locally as a fallback.
+     */
+    compile(request: string | NikaCompileRequest, options?: NikaCompileOptions): Promise<NikaCompileOutcome>;
     /**
      * Resolves with the run's handle once the engine admitted it, and rejects
      * without one when the engine refused it. The handle owns the lifecycle:
@@ -886,4 +1017,4 @@ declare class Nika {
     private session;
 }
 
-export { Nika, type NikaAttachRunOptions, type NikaCancelResult, type NikaCheckFinding, type NikaCheckOptions, type NikaCheckResult, NikaCompatibilityError, type NikaConfig, NikaConfigurationError, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaJournalEvidence, type NikaLocalConfig, type NikaMachineError, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunEvent, type NikaRunEventKind, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSettlement, type NikaSpend, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaRunSucceeded, isNikaTerminalEvent };
+export { Nika, type NikaAttachRunOptions, type NikaCancelResult, type NikaCheckFinding, type NikaCheckOptions, type NikaCheckResult, NikaCompatibilityError, type NikaCompileDiagnostic, type NikaCompileOptions, type NikaCompileOutcome, type NikaCompilePreview, type NikaCompileProvenance, type NikaCompileQuestion, type NikaCompileRequest, type NikaCompileSetConstant, type NikaCompileStatus, type NikaConfig, NikaConfigurationError, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaJournalEvidence, type NikaLocalConfig, type NikaMachineError, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunEvent, type NikaRunEventKind, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSettlement, type NikaSpend, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaRunSucceeded, isNikaTerminalEvent };