@lax-wp/editor 0.4.13 → 0.4.15-beta.0

package/dist/api/ruleAuthoring.d.ts

@@ -0,0 +1,305 @@
+/**
+ * ruleAuthoring.ts — the "say what you want in English, get a rule" half of
+ * the no-code rule builder (plan §P2).
+ *
+ *   POST /v1/rules/author/from-text        RULE_AUTHORING_ENABLED
+ *   POST /v1/rules/author/from-examples    RULE_AUTHORING_ENABLED
+ *   POST /v1/rules/{id}/author/revise      RULE_AUTHORING_ENABLED
+ *
+ * All three are DRAFT-FIRST (`internal/playbook-engine/api/rules_author.go`):
+ * they return a validated rule plus warnings and write NOTHING unless
+ * `commit: true`, which lands through the same single mutation path
+ * `POST /v1/rules` uses. The builder leans on that hard — a lawyer sees the
+ * drafted rule, revises it, and only then commits.
+ *
+ * Two response facts the UI depends on and that are easy to get wrong:
+ *   - `warnings` is always present (possibly empty) — field-catalog warnings,
+ *     never a rejection.
+ *   - `changes` is the revise endpoint's field-level diff and is `omitempty`:
+ *     an instruction the model decided changed nothing returns NO `changes`
+ *     key at all. "Absent" means "nothing changed", not "unknown", and the
+ *     revise UI says so rather than showing an empty diff as a failure.
+ *
+ * A 422 means the drafted rule failed validation even after the server's one
+ * repair round-trip — the fix is to the user's phrasing, so it gets its own
+ * error type and its own "rephrase and try again" affordance. A 503 is the
+ * LLM gateway, not the request, and gets a retry instead.
+ */
+import { z } from "zod";
+import { type CdtsScope } from "./playbook";
+import { type BuilderRule, type CapabilityStatus } from "./ruleBuilder";
+/** One entry of the revise diff. `before`/`after` are `any` server-side. */
+export declare const ruleFieldChangeSchema: z.ZodObject<{
+    field: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    field: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    field: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.ZodTypeAny, "passthrough">>;
+export type RuleFieldChange = z.infer<typeof ruleFieldChangeSchema>;
+/** The shared `authorRuleResponse` shape of all three endpoints. */
+export declare const authorRuleResponseSchema: z.ZodObject<{
+    rule: z.ZodObject<{
+        id: z.ZodString;
+        playbook_id: z.ZodString;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        predicate: z.ZodOptional<z.ZodType<import("./ruleBuilder").PredicateNode, z.ZodTypeDef, import("./ruleBuilder").PredicateNode>>;
+        action: z.ZodOptional<z.ZodString>;
+        default_severity: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        rationale: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        semantic_intent: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        read_only: z.ZodOptional<z.ZodBoolean>;
+        mandatory: z.ZodOptional<z.ZodBoolean>;
+        authority: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        standard_position: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        fallback_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        walkaway_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        playbook_id: z.ZodString;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        predicate: z.ZodOptional<z.ZodType<import("./ruleBuilder").PredicateNode, z.ZodTypeDef, import("./ruleBuilder").PredicateNode>>;
+        action: z.ZodOptional<z.ZodString>;
+        default_severity: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        rationale: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        semantic_intent: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        read_only: z.ZodOptional<z.ZodBoolean>;
+        mandatory: z.ZodOptional<z.ZodBoolean>;
+        authority: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        standard_position: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        fallback_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        walkaway_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        playbook_id: z.ZodString;
+        workspace_id: z.ZodOptional<z.ZodString>;
+        predicate: z.ZodOptional<z.ZodType<import("./ruleBuilder").PredicateNode, z.ZodTypeDef, import("./ruleBuilder").PredicateNode>>;
+        action: z.ZodOptional<z.ZodString>;
+        default_severity: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        rationale: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        semantic_intent: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        read_only: z.ZodOptional<z.ZodBoolean>;
+        mandatory: z.ZodOptional<z.ZodBoolean>;
+        authority: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+        standard_position: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        fallback_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+        walkaway_condition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough">>>>;
+    }, z.ZodTypeAny, "passthrough">>;
+    warnings: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>, string[], string[] | null | undefined>;
+    committed: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /** Absent on from-text / from-examples, and on a no-op revise. */
+    changes: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">>, "many">>>, z.objectOutputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">[], z.objectInputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">[] | null | undefined>;
+}, "strip", z.ZodTypeAny, {
+    changes: z.objectOutputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">[];
+    rule: {
+        id: string;
+        playbook_id: string;
+        rationale: string;
+        category?: string | undefined;
+        workspace_id?: string | undefined;
+        default_severity?: string | undefined;
+        standard_position?: z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+        authority?: string | undefined;
+        mandatory?: boolean | undefined;
+        read_only?: boolean | undefined;
+        source?: string | undefined;
+        action?: string | undefined;
+        semantic_intent?: string | undefined;
+        predicate?: import("./ruleBuilder").PredicateNode | undefined;
+        effort?: string | undefined;
+        fallback_condition?: z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+        walkaway_condition?: z.objectOutputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    warnings: string[];
+    committed: boolean;
+}, {
+    rule: {
+        id: string;
+        playbook_id: string;
+        category?: string | undefined;
+        workspace_id?: string | undefined;
+        default_severity?: string | undefined;
+        standard_position?: z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+        rationale?: string | undefined;
+        authority?: string | undefined;
+        mandatory?: boolean | undefined;
+        read_only?: boolean | undefined;
+        source?: string | undefined;
+        action?: string | undefined;
+        semantic_intent?: string | undefined;
+        predicate?: import("./ruleBuilder").PredicateNode | undefined;
+        effort?: string | undefined;
+        fallback_condition?: z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+        walkaway_condition?: z.objectInputType<{
+            text: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        }, z.ZodTypeAny, "passthrough"> | null | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+    changes?: z.objectInputType<{
+        field: z.ZodString;
+        before: z.ZodUnknown;
+        after: z.ZodUnknown;
+    }, z.ZodTypeAny, "passthrough">[] | null | undefined;
+    warnings?: string[] | null | undefined;
+    committed?: boolean | undefined;
+}>;
+export type AuthoredRuleDraft = z.infer<typeof authorRuleResponseSchema>;
+/**
+ * A 422 from an authoring route: the draft could not be validated even after
+ * the server's repair round. Distinct from a transport failure because the
+ * remedy is different — rephrase, do not retry.
+ */
+export declare class RuleAuthoringValidationError extends Error {
+    constructor(message: string);
+}
+export interface AuthorExample {
+    text: string;
+    label: "accept" | "reject";
+}
+/**
+ * Handler-side bounds (`validateExamples`), enforced locally too so the form
+ * can disable Draft with a reason instead of round-tripping a certain 400.
+ */
+export declare const EXAMPLE_BOUNDS: {
+    readonly min: 3;
+    readonly max: 10;
+    readonly maxTextBytes: 2048;
+};
+/** Returns the blocking reason for an example set, or "" when it is valid. */
+export declare const validateExamples: (examples: AuthorExample[]) => string;
+export interface AuthorFromTextInput {
+    playbookId: string;
+    text: string;
+    /** Steers the prompt only; a rule inherits its playbook's scope. */
+    scope?: CdtsScope;
+    commit?: boolean;
+}
+/** POST /v1/rules/author/from-text — one plain-English position → one rule. */
+export declare const authorRuleFromText: (input: AuthorFromTextInput) => Promise<AuthoredRuleDraft>;
+export interface AuthorFromExamplesInput {
+    playbookId: string;
+    examples: AuthorExample[];
+    guidance?: string;
+    commit?: boolean;
+}
+/** POST /v1/rules/author/from-examples — labelled clauses → one induced rule. */
+export declare const authorRuleFromExamples: (input: AuthorFromExamplesInput) => Promise<AuthoredRuleDraft>;
+export interface ReviseRuleInput {
+    instruction: string;
+    commit?: boolean;
+}
+/**
+ * POST /v1/rules/{id}/author/revise — an instruction against an EXISTING
+ * (stored) rule. The draft returned by from-text/from-examples has no stored
+ * identity until it is committed, so revise only applies to a saved rule; the
+ * builder gates the control on that rather than 404-ing the user.
+ */
+export declare const reviseRule: (ruleId: string, input: ReviseRuleInput) => Promise<AuthoredRuleDraft>;
+export declare const probeRuleAuthoring: () => Promise<CapabilityStatus>;
+export type { BuilderRule };