@ruakit/schema 0.0.0-stage → 0.1.0-alpha.1

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}

package/dist/plan.js

@@ -0,0 +1,3 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+var b=Object.defineProperty;var a=(t,n)=>b(t,"name",{value:n,configurable:!0});import{z as e}from"zod";import{decisionRequestSchema as y,actionSchema as r}from"./decision.js";import{completionChecksSchema as x,controlLocatorSchema as O}from"./verification.js";const s=e.string().trim().min(1).max(200),i={id:s,message:e.string().trim().min(1).max(2e3),target:O},f=e.discriminatedUnion("type",[r.options[0].extend(i),r.options[1].extend(i),r.options[2].extend(i),r.options[3].extend(i),r.options[4].extend(i),r.options[5].extend(i),r.options[6].extend(i)]),h=e.strictObject({id:s,replacesPlanId:s.optional(),message:e.string().trim().min(1).max(2e3),steps:e.array(f).max(50).refine(t=>new Set(t.map(n=>n.id)).size===t.length,"Plan step IDs must be distinct."),checks:x}),j=e.strictObject({type:e.literal("approval"),message:e.string().trim().min(1).max(2e3),plan:h}),z=e.strictObject({planId:s,step:f}),I=e.strictObject({planId:s,completedSteps:e.array(z).max(200),failedStepId:s.nullable(),reason:e.enum(["target-unavailable","target-stale","outcome-mismatch"]),message:e.string().min(1).max(2e3)});function k(t){return t===null||typeof t=="boolean"?5:typeof t=="string"?t.length:typeof t=="number"&&Number.isFinite(t)?24:null}a(k,"primitiveSize");function N(t){if(Array.isArray(t))return!0;const n=Object.getPrototypeOf(t);return n===Object.prototype||n===null}a(N,"isJsonContainer");function P(t){const c=[{value:t,depth:0}],m=new Set;let p=0,d=0;for(;c.length>0;){const l=c.pop(),o=l.value;if(d+=1,d>2048||l.depth>8)return!1;const u=k(o);if(u!==null)p+=u;else if(typeof o=="object"&&o!==null){if(m.has(o)||(m.add(o),!N(o)))return!1;for(const[g,S]of Object.entries(o))p+=g.length+4,c.push({value:S,depth:l.depth+1})}else return!1;if(p>32768)return!1}return!0}a(P,"boundedJson");const w=e.custom(P,"Expected bounded JSON context."),E=y.omit({history:!0}).extend({protocol:e.literal("plan"),context:w.optional(),checks:x.nullable(),replan:I.nullable()}),F=e.union([h,j,e.strictObject({type:e.literal("clarify"),message:e.string().min(1).max(500)}),e.strictObject({type:e.literal("screenshot"),message:e.string().min(1).max(2e3)}),e.strictObject({type:e.literal("unsupported"),message:e.string().min(1).max(2e3)})]);export{z as completedPlanStepSchema,j as planApprovalSchema,w as planContextSchema,E as planRequestSchema,F as planResponseSchema,h as planSchema,f as plannedStepSchema,I as replanSchema};
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/plan.ts"],
+  "sourcesContent": ["// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT\nimport { z } from 'zod';\nimport { decisionRequestSchema, actionSchema } from './decision.js';\nimport {\n  completionChecksSchema,\n  controlLocatorSchema,\n} from './verification.js';\n\n/** Shared constraints for plan and step identifiers. */\nconst identifier = z.string().trim().min(1).max(200);\n\n/** Fields added to each action when it becomes a planned step. */\nconst metadata = {\n  id: identifier,\n  message: z.string().trim().min(1).max(2000),\n  target: controlLocatorSchema,\n};\n\n/** Resolve these locators against a fresh observation before executing each step. */\nexport const plannedStepSchema = z.discriminatedUnion('type', [\n  actionSchema.options[0].extend(metadata),\n  actionSchema.options[1].extend(metadata),\n  actionSchema.options[2].extend(metadata),\n  actionSchema.options[3].extend(metadata),\n  actionSchema.options[4].extend(metadata),\n  actionSchema.options[5].extend(metadata),\n  actionSchema.options[6].extend(metadata),\n]);\n\n/** An ordered plan and the checks used to assess its outcome. */\nexport const planSchema = z.strictObject({\n  id: identifier,\n  replacesPlanId: identifier.optional(),\n  message: z.string().trim().min(1).max(2000),\n  steps: z\n    .array(plannedStepSchema)\n    .max(50)\n    .refine(\n      (steps) => new Set(steps.map((step) => step.id)).size === steps.length,\n      'Plan step IDs must be distinct.',\n    ),\n  checks: completionChecksSchema,\n});\n\n/** Approval covers this concrete plan revision, including every action and argument. */\nexport const planApprovalSchema = z.strictObject({\n  type: z.literal('approval'),\n  message: z.string().trim().min(1).max(2000),\n  plan: planSchema,\n});\n\n/** A step that has already been executed as part of a plan. */\nexport const completedPlanStepSchema = z.strictObject({\n  planId: identifier,\n  step: plannedStepSchema,\n});\n\n/** Execution history and reason supplied when requesting a replacement plan. */\nexport const replanSchema = z.strictObject({\n  planId: identifier,\n  completedSteps: z.array(completedPlanStepSchema).max(200),\n  failedStepId: identifier.nullable(),\n  reason: z.enum(['target-unavailable', 'target-stale', 'outcome-mismatch']),\n  message: z.string().min(1).max(2000),\n});\n\n/** JSON-compatible context accepted by the planning protocol. */\nexport type JsonValue =\n  string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };\n\n/** Return the estimated size of a JSON primitive, or null for other values. */\nfunction primitiveSize(value: unknown): number | null {\n  if (value === null || typeof value === 'boolean') return 5;\n  if (typeof value === 'string') return value.length;\n  if (typeof value === 'number' && Number.isFinite(value)) return 24;\n  return null;\n}\n\n/** Accept arrays and plain objects, but not class instances or other objects. */\nfunction isJsonContainer(value: object): boolean {\n  if (Array.isArray(value)) return true;\n\n  const prototype = Object.getPrototypeOf(value);\n  return prototype === Object.prototype || prototype === null;\n}\n\n/** Check that context is plain JSON within the protocol's traversal and size limits. */\nfunction boundedJson(value: unknown): value is JsonValue {\n  const maxNodes = 2048;\n  const maxDepth = 8;\n  const maxSize = 32768;\n\n  // Track pending values, visited objects, and the estimated serialized size.\n  const pending = [{ value, depth: 0 }];\n  const seen = new Set<object>();\n  let size = 0;\n  let nodes = 0;\n\n  while (pending.length > 0) {\n    const item = pending.pop()!;\n    const current = item.value;\n\n    nodes += 1;\n    if (nodes > maxNodes || item.depth > maxDepth) return false;\n\n    const estimatedSize = primitiveSize(current);\n    if (estimatedSize !== null) {\n      size += estimatedSize;\n    } else if (typeof current === 'object' && current !== null) {\n      // Repeated references, cycles, and non-plain objects are not accepted.\n      if (seen.has(current)) return false;\n      seen.add(current);\n      if (!isJsonContainer(current)) return false;\n\n      // Account for property names and visit their values at the next depth.\n      for (const [key, child] of Object.entries(current)) {\n        size += key.length + 4;\n        pending.push({ value: child, depth: item.depth + 1 });\n      }\n    } else {\n      return false;\n    }\n\n    if (size > maxSize) return false;\n  }\n\n  return true;\n}\n\n/** Context is JSON data, bounded independently of page observations and images. */\nexport const planContextSchema = z.custom<JsonValue>(\n  boundedJson,\n  'Expected bounded JSON context.',\n);\n\n/** Request for a plan, optionally including application context and replan history. */\nexport const planRequestSchema = decisionRequestSchema\n  .omit({ history: true })\n  .extend({\n    protocol: z.literal('plan'),\n    context: planContextSchema.optional(),\n    checks: completionChecksSchema.nullable(),\n    replan: replanSchema.nullable(),\n  });\n\n/** A plan or a response explaining what the planner needs next. */\nexport const planResponseSchema = z.union([\n  planSchema,\n  planApprovalSchema,\n  z.strictObject({\n    type: z.literal('clarify'),\n    message: z.string().min(1).max(500),\n  }),\n  z.strictObject({\n    type: z.literal('screenshot'),\n    message: z.string().min(1).max(2000),\n  }),\n  z.strictObject({\n    type: z.literal('unsupported'),\n    message: z.string().min(1).max(2000),\n  }),\n]);\n\n/** A validated plan. */\nexport type Plan = z.infer<typeof planSchema>;\n/** One action in a plan. */\nexport type PlannedStep = z.infer<typeof plannedStepSchema>;\n/** A completed step and its originating plan. */\nexport type CompletedPlanStep = z.infer<typeof completedPlanStepSchema>;\n/** The context for replacing a plan. */\nexport type Replan = z.infer<typeof replanSchema>;\n/** A validated planning request. */\nexport type PlanRequest = z.infer<typeof planRequestSchema>;\n/** A validated planning response. */\nexport type PlanResponse = z.infer<typeof planResponseSchema>;\n/** A request to approve a concrete plan. */\nexport type PlanApproval = z.infer<typeof planApprovalSchema>;\n"],
+  "mappings": "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",
+  "names": ["z", "decisionRequestSchema", "actionSchema", "completionChecksSchema", "controlLocatorSchema", "identifier", "metadata", "plannedStepSchema", "planSchema", "steps", "step", "planApprovalSchema", "completedPlanStepSchema", "replanSchema", "primitiveSize", "value", "__name", "isJsonContainer", "prototype", "boundedJson", "pending", "seen", "size", "nodes", "item", "current", "estimatedSize", "key", "child", "planContextSchema", "planRequestSchema", "planResponseSchema"]
+}

package/dist/protocol.d.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import type { DecisionRequest } from './decision.js';
+/** Name of the HTML metadata element used for runtime configuration. */
+export declare const RUNTIME_META_NAME = "ruakit-config";
+/** A conversational response contains no executable instructions. */
+export declare const clarificationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"clarification">;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** Result of an execution, including any observed verification evidence. */
+export declare const resultSchema: z.ZodObject<{
+    planId: z.ZodString;
+    status: z.ZodEnum<{
+        triggered: "triggered";
+        failed: "failed";
+    }>;
+    events: z.ZodArray<z.ZodString>;
+    goalCompleted: z.ZodOptional<z.ZodLiteral<true>>;
+    verification: z.ZodOptional<z.ZodObject<{
+        level: z.ZodEnum<{
+            observed: "observed";
+            confirmed: "confirmed";
+        }>;
+        checks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"value">;
+            description: z.ZodString;
+            control: z.ZodObject<{
+                id: z.ZodNullable<z.ZodString>;
+                role: z.ZodString;
+                label: z.ZodString;
+                context: z.ZodNullable<z.ZodString>;
+                group: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            equals: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"checked">;
+            description: z.ZodString;
+            control: z.ZodObject<{
+                id: z.ZodNullable<z.ZodString>;
+                role: z.ZodString;
+                label: z.ZodString;
+                context: z.ZodNullable<z.ZodString>;
+                group: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            equals: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"selected">;
+            description: z.ZodString;
+            control: z.ZodObject<{
+                id: z.ZodNullable<z.ZodString>;
+                role: z.ZodString;
+                label: z.ZodString;
+                context: z.ZodNullable<z.ZodString>;
+                group: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            equals: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            description: z.ZodString;
+            text: z.ZodString;
+            fresh: z.ZodBoolean;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"url">;
+            description: z.ZodString;
+            equals: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"absent">;
+            description: z.ZodString;
+            control: z.ZodObject<{
+                id: z.ZodNullable<z.ZodString>;
+                role: z.ZodString;
+                label: z.ZodString;
+                context: z.ZodNullable<z.ZodString>;
+                group: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+    }, z.core.$strict>>;
+    screenshot: z.ZodOptional<z.ZodObject<{
+        data: z.ZodString;
+        mimeType: z.ZodEnum<{
+            "image/png": "image/png";
+            "image/jpeg": "image/jpeg";
+            "image/webp": "image/webp";
+        }>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        capturedAt: z.ZodNumber;
+        url: z.ZodString;
+    }, z.core.$strict>>;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** A question and optional choices returned to the user. */
+export type Clarification = z.infer<typeof clarificationSchema>;
+/** One question and answer included in a decision request. */
+export type ClarificationTurn = DecisionRequest['clarifications'][number];
+/** A validated execution result. */
+export type ExecutionResult = z.infer<typeof resultSchema>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,qEAAqE;AACrE,eAAO,MAAM,mBAAmB;;;;kBAO9B,CAAC;AAEH,4EAA4E;AAC5E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUvB,CAAC;AAEH,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,3 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import{z as t}from"zod";import{completionChecksSchema as i,screenshotSchema as r}from"./verification.js";const a="ruakit-config",c=t.strictObject({type:t.literal("clarification"),question:t.string().trim().min(1).max(500),options:t.array(t.string().trim().min(1).max(400)).max(4).refine(e=>new Set(e).size===e.length,"Expected distinct options.")}),s=t.strictObject({planId:t.string().min(1).max(200),status:t.enum(["triggered","failed"]),events:t.array(t.string().max(500)).max(220),goalCompleted:t.literal(!0).optional(),verification:t.strictObject({level:t.enum(["observed","confirmed"]),checks:i}).optional(),screenshot:r.optional(),message:t.string().max(2e3).optional()});export{a as RUNTIME_META_NAME,c as clarificationSchema,s as resultSchema};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/protocol.ts"],
+  "sourcesContent": ["// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT\nimport { z } from 'zod';\nimport type { DecisionRequest } from './decision.js';\nimport { completionChecksSchema, screenshotSchema } from './verification.js';\n\n/** Name of the HTML metadata element used for runtime configuration. */\nexport const RUNTIME_META_NAME = 'ruakit-config';\n\n/** A conversational response contains no executable instructions. */\nexport const clarificationSchema = z.strictObject({\n  type: z.literal('clarification'),\n  question: z.string().trim().min(1).max(500),\n  options: z\n    .array(z.string().trim().min(1).max(400))\n    .max(4)\n    .refine((items) => new Set(items).size === items.length, 'Expected distinct options.'),\n});\n\n/** Result of an execution, including any observed verification evidence. */\nexport const resultSchema = z.strictObject({\n  planId: z.string().min(1).max(200),\n  status: z.enum(['triggered', 'failed']),\n  events: z.array(z.string().max(500)).max(220),\n  goalCompleted: z.literal(true).optional(),\n  verification: z\n    .strictObject({ level: z.enum(['observed', 'confirmed']), checks: completionChecksSchema })\n    .optional(),\n  screenshot: screenshotSchema.optional(),\n  message: z.string().max(2000).optional(),\n});\n\n/** A question and optional choices returned to the user. */\nexport type Clarification = z.infer<typeof clarificationSchema>;\n/** One question and answer included in a decision request. */\nexport type ClarificationTurn = DecisionRequest['clarifications'][number];\n/** A validated execution result. */\nexport type ExecutionResult = z.infer<typeof resultSchema>;\n"],
+  "mappings": ";AACA,OAAS,KAAAA,MAAS,MAElB,OAAS,0BAAAC,EAAwB,oBAAAC,MAAwB,oBAGlD,MAAMC,EAAoB,gBAGpBC,EAAsBJ,EAAE,aAAa,CAChD,KAAMA,EAAE,QAAQ,eAAe,EAC/B,SAAUA,EAAE,OAAM,EAAG,KAAI,EAAG,IAAI,CAAC,EAAE,IAAI,GAAG,EAC1C,QAASA,EACN,MAAMA,EAAE,OAAM,EAAG,KAAI,EAAG,IAAI,CAAC,EAAE,IAAI,GAAG,CAAC,EACvC,IAAI,CAAC,EACL,OAAQK,GAAU,IAAI,IAAIA,CAAK,EAAE,OAASA,EAAM,OAAQ,4BAA4B,EACxF,EAGYC,EAAeN,EAAE,aAAa,CACzC,OAAQA,EAAE,OAAM,EAAG,IAAI,CAAC,EAAE,IAAI,GAAG,EACjC,OAAQA,EAAE,KAAK,CAAC,YAAa,QAAQ,CAAC,EACtC,OAAQA,EAAE,MAAMA,EAAE,OAAM,EAAG,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,EAC5C,cAAeA,EAAE,QAAQ,EAAI,EAAE,SAAQ,EACvC,aAAcA,EACX,aAAa,CAAE,MAAOA,EAAE,KAAK,CAAC,WAAY,WAAW,CAAC,EAAG,OAAQC,CAAsB,CAAE,EACzF,SAAQ,EACX,WAAYC,EAAiB,SAAQ,EACrC,QAASF,EAAE,OAAM,EAAG,IAAI,GAAI,EAAE,SAAQ,EACvC",
+  "names": ["z", "completionChecksSchema", "screenshotSchema", "RUNTIME_META_NAME", "clarificationSchema", "items", "resultSchema"]
+}

package/dist/verification.d.ts

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+/** Identifies a control by its observed identity and accessible context. */
+export declare const controlLocatorSchema: z.ZodObject<{
+    id: z.ZodNullable<z.ZodString>;
+    role: z.ZodString;
+    label: z.ZodString;
+    context: z.ZodNullable<z.ZodString>;
+    group: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** A single observable condition that can establish progress toward a goal. */
+export declare const completionCheckSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"value">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"checked">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"selected">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    description: z.ZodString;
+    text: z.ZodString;
+    fresh: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"url">;
+    description: z.ZodString;
+    equals: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"absent">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+/** A nonempty, bounded collection of outcome checks. */
+export declare const completionChecksSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"value">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"checked">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"selected">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    equals: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    description: z.ZodString;
+    text: z.ZodString;
+    fresh: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"url">;
+    description: z.ZodString;
+    equals: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"absent">;
+    description: z.ZodString;
+    control: z.ZodObject<{
+        id: z.ZodNullable<z.ZodString>;
+        role: z.ZodString;
+        label: z.ZodString;
+        context: z.ZodNullable<z.ZodString>;
+        group: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">>;
+/** A validated observable outcome check. */
+export type CompletionCheck = z.infer<typeof completionCheckSchema>;
+/** The observed page information needed to evaluate outcome checks. */
+export interface VerificationState {
+    url: string;
+    text: string;
+    truncated: boolean;
+    controls: {
+        target: {
+            id: string;
+            version: number;
+        };
+        role: string;
+        label: string;
+        context: string;
+        groups?: {
+            name: string;
+        }[] | undefined;
+        value?: string | undefined;
+        checked?: boolean | undefined;
+        selectedValues?: string[] | undefined;
+    }[];
+}
+/** Deterministic checks of observable outcomes. This does not infer intent or prove backend persistence. */
+export declare function evaluateCompletionChecks(checks: readonly CompletionCheck[], state: VerificationState, baseline?: VerificationState): {
+    passed: boolean;
+    checks: {
+        description: string;
+        passed: boolean;
+    }[];
+};
+/** A bounded, encoded screenshot with its capture metadata. */
+export declare const screenshotSchema: z.ZodObject<{
+    data: z.ZodString;
+    mimeType: z.ZodEnum<{
+        "image/png": "image/png";
+        "image/jpeg": "image/jpeg";
+        "image/webp": "image/webp";
+    }>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    capturedAt: z.ZodNumber;
+    url: z.ZodString;
+}, z.core.$strict>;
+//# sourceMappingURL=verification.d.ts.map

package/dist/verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification.d.ts","sourceRoot":"","sources":["../src/verification.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB;;;;;;kBAM/B,CAAC;AAQH,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BA+BhC,CAAC;AAEH,wDAAwD;AACxD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAAgD,CAAC;AAEpF,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAGpE,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE;QACR,MAAM,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;QACxC,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,GAAG,SAAS,CAAC;QACxC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC3B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;KACvC,EAAE,CAAC;CACL;AAgED,4GAA4G;AAC5G,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,GAAE,iBAAyB,GAClC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CAAE,CAmBzE;AAED,+DAA+D;AAC/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;kBAsCzB,CAAC"}

package/dist/verification.js

@@ -0,0 +1,5 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+var c=Object.defineProperty;var l=(t,n)=>c(t,"name",{value:n,configurable:!0});import{z as e}from"zod";const p=e.strictObject({id:e.string().min(1).max(200).nullable(),role:e.string().max(100),label:e.string().max(1e3),context:e.string().max(1e3).nullable(),group:e.string().max(200).nullable()}),u=p,o=e.string().trim().min(1).max(500),g=e.discriminatedUnion("type",[e.strictObject({type:e.literal("value"),description:o,control:u,equals:e.string().max(2e4)}),e.strictObject({type:e.literal("checked"),description:o,control:u,equals:e.boolean()}),e.strictObject({type:e.literal("selected"),description:o,control:u,equals:e.array(e.string().max(4e3)).max(100)}),e.strictObject({type:e.literal("text"),description:o,text:e.string().trim().min(1).max(2e3),fresh:e.boolean()}),e.strictObject({type:e.literal("url"),description:o,equals:e.string().min(1).max(4e3)}),e.strictObject({type:e.literal("absent"),description:o,control:u})]),q=e.array(g).min(1).max(20);function d(t,n){return t.role===n.role&&t.label===n.label&&(n.context===null||t.context===n.context)&&(n.group===null||t.groups?.some(s=>s.name===n.group)===!0)}l(d,"matchesControl");function x(t,n,s){const r=n.text.includes(t.text),i=n.controls.some(m=>m.label.includes(t.text)),a=!t.fresh||!s.text.includes(t.text);return r&&!i&&a}l(x,"matchesText");function b(t,n){if(t.type==="value")return n.value===t.equals;if(t.type==="checked")return n.checked===t.equals;const s=n.selectedValues;return s===void 0?!1:s.length===t.equals.length&&new Set(t.equals).size===t.equals.length&&t.equals.every(r=>s.includes(r))}l(b,"matchesControlValue");function f(t,n){const s=n.controls.filter(i=>d(i,t.control));if(t.type==="absent")return!n.truncated&&s.length===0;const r=s.filter(i=>t.control.id===null||i.target.id===t.control.id);return r.length!==1?!1:b(t,r[0])}l(f,"matchesControlCheck");function j(t,n,s=n){const r=t.map(i=>{let a;return i.type==="text"?a=x(i,n,s):i.type==="url"?a=n.url===i.equals:a=f(i,n),{description:i.description,passed:a}});return{passed:r.length>0&&r.every(i=>i.passed),checks:r}}l(j,"evaluateCompletionChecks");const v=e.strictObject({data:e.string().min(1).max(7e6).regex(/^[A-Za-z0-9+/]+={0,2}$/).refine(t=>t.length%4===0),mimeType:e.enum(["image/png","image/jpeg","image/webp"]),width:e.number().int().positive().max(8192),height:e.number().int().positive().max(8192),capturedAt:e.number().int().nonnegative(),url:e.string().max(4e3)}).superRefine((t,n)=>{try{const s=globalThis.atob(t.data),r=t.mimeType==="image/png"?s.startsWith(`\x89PNG\r
+
+`):t.mimeType==="image/jpeg"?s.startsWith("\xFF\xD8\xFF"):s.startsWith("RIFF")&&s.slice(8,12)==="WEBP";(s.length>5*1024*1024||!r)&&n.addIssue({code:"custom",message:"Screenshot bytes must match the image type and fit within 5 MiB."})}catch{n.addIssue({code:"custom",message:"Screenshot data must contain valid base64 image bytes."})}});export{g as completionCheckSchema,q as completionChecksSchema,p as controlLocatorSchema,j as evaluateCompletionChecks,v as screenshotSchema};
+//# sourceMappingURL=verification.js.map

package/dist/verification.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/verification.ts"],
+  "sourcesContent": ["// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT\nimport { z } from 'zod';\n\n/** Identifies a control by its observed identity and accessible context. */\nexport const controlLocatorSchema = z.strictObject({\n  id: z.string().min(1).max(200).nullable(),\n  role: z.string().max(100),\n  label: z.string().max(1000),\n  context: z.string().max(1000).nullable(),\n  group: z.string().max(200).nullable(),\n});\n\n/** Reuse the same locator constraints for all control checks. */\nconst locator = controlLocatorSchema;\n\n/** Human-readable explanation of the outcome being checked. */\nconst description = z.string().trim().min(1).max(500);\n\n/** A single observable condition that can establish progress toward a goal. */\nexport const completionCheckSchema = z.discriminatedUnion('type', [\n  z.strictObject({\n    type: z.literal('value'),\n    description,\n    control: locator,\n    equals: z.string().max(20000),\n  }),\n  z.strictObject({\n    type: z.literal('checked'),\n    description,\n    control: locator,\n    equals: z.boolean(),\n  }),\n  z.strictObject({\n    type: z.literal('selected'),\n    description,\n    control: locator,\n    equals: z.array(z.string().max(4000)).max(100),\n  }),\n  z.strictObject({\n    type: z.literal('text'),\n    description,\n    text: z.string().trim().min(1).max(2000),\n    fresh: z.boolean(),\n  }),\n  z.strictObject({\n    type: z.literal('url'),\n    description,\n    equals: z.string().min(1).max(4000),\n  }),\n  z.strictObject({ type: z.literal('absent'), description, control: locator }),\n]);\n\n/** A nonempty, bounded collection of outcome checks. */\nexport const completionChecksSchema = z.array(completionCheckSchema).min(1).max(20);\n\n/** A validated observable outcome check. */\nexport type CompletionCheck = z.infer<typeof completionCheckSchema>;\n\n\n/** The observed page information needed to evaluate outcome checks. */\nexport interface VerificationState {\n  url: string;\n  text: string;\n  truncated: boolean;\n  controls: {\n    target: { id: string; version: number };\n    role: string;\n    label: string;\n    context: string;\n    groups?: { name: string }[] | undefined;\n    value?: string | undefined;\n    checked?: boolean | undefined;\n    selectedValues?: string[] | undefined;\n  }[];\n}\n\ntype ObservedControl = VerificationState['controls'][number];\ntype ControlLocator = z.infer<typeof controlLocatorSchema>;\ntype ControlCheck = Extract<CompletionCheck, { control: ControlLocator }>;\n\n/** Match accessible characteristics independently of the observation's target ID. */\nfunction matchesControl(control: ObservedControl, locator: ControlLocator): boolean {\n  return (\n    control.role === locator.role &&\n    control.label === locator.label &&\n    (locator.context === null || control.context === locator.context) &&\n    (locator.group === null ||\n      control.groups?.some((group) => group.name === locator.group) === true)\n  );\n}\n\n/** Check visible text without treating a control's caption as an acknowledgement. */\nfunction matchesText(\n  check: Extract<CompletionCheck, { type: 'text' }>,\n  state: VerificationState,\n  baseline: VerificationState,\n): boolean {\n  const isVisible = state.text.includes(check.text);\n  const isControlLabel = state.controls.some((control) => control.label.includes(check.text));\n  const isFresh = !check.fresh || !baseline.text.includes(check.text);\n\n  return isVisible && !isControlLabel && isFresh;\n}\n\n/** Compare the observed control's state with the expected value. */\nfunction matchesControlValue(\n  check: Exclude<ControlCheck, { type: 'absent' }>,\n  control: ObservedControl,\n): boolean {\n  if (check.type === 'value') return control.value === check.equals;\n  if (check.type === 'checked') return control.checked === check.equals;\n\n  const selectedValues = control.selectedValues;\n  if (selectedValues === undefined) return false;\n\n  return (\n    selectedValues.length === check.equals.length &&\n    new Set(check.equals).size === check.equals.length &&\n    check.equals.every((value) => selectedValues.includes(value))\n  );\n}\n\n/** Resolve a control check against the current observation. */\nfunction matchesControlCheck(check: ControlCheck, state: VerificationState): boolean {\n  const semanticMatches = state.controls.filter((control) => matchesControl(control, check.control));\n\n  // A recycled target ID must not hide a control when checking for absence.\n  if (check.type === 'absent') return !state.truncated && semanticMatches.length === 0;\n\n  const matches = semanticMatches.filter(\n    (control) => check.control.id === null || control.target.id === check.control.id,\n  );\n\n  // A value can only be verified when the locator identifies exactly one control.\n  if (matches.length !== 1) return false;\n  return matchesControlValue(check, matches[0]!);\n}\n\n/** Deterministic checks of observable outcomes. This does not infer intent or prove backend persistence. */\nexport function evaluateCompletionChecks(\n  checks: readonly CompletionCheck[],\n  state: VerificationState,\n  baseline: VerificationState = state,\n): { passed: boolean; checks: { description: string; passed: boolean }[] } {\n  const results = checks.map((check) => {\n    let passed: boolean;\n\n    if (check.type === 'text') {\n      passed = matchesText(check, state, baseline);\n    } else if (check.type === 'url') {\n      passed = state.url === check.equals;\n    } else {\n      passed = matchesControlCheck(check, state);\n    }\n\n    return { description: check.description, passed };\n  });\n\n  return {\n    passed: results.length > 0 && results.every((result) => result.passed),\n    checks: results,\n  };\n}\n\n/** A bounded, encoded screenshot with its capture metadata. */\nexport const screenshotSchema = z\n  .strictObject({\n    data: z\n      .string()\n      .min(1)\n      .max(7_000_000)\n      .regex(/^[A-Za-z0-9+/]+={0,2}$/)\n      .refine((data) => data.length % 4 === 0),\n    mimeType: z.enum(['image/png', 'image/jpeg', 'image/webp']),\n    width: z.number().int().positive().max(8192),\n    height: z.number().int().positive().max(8192),\n    capturedAt: z.number().int().nonnegative(),\n    url: z.string().max(4000),\n  })\n  .superRefine((image, context) => {\n    try {\n      // Decode the payload before checking its size and file signature.\n      const bytes = globalThis.atob(image.data);\n\n      const signatureMatches =\n        image.mimeType === 'image/png'\n          ? bytes.startsWith('\\x89PNG\\r\\n\\x1a\\n')\n          : image.mimeType === 'image/jpeg'\n            ? bytes.startsWith('\\xff\\xd8\\xff')\n            : bytes.startsWith('RIFF') && bytes.slice(8, 12) === 'WEBP';\n\n      if (bytes.length > 5 * 1024 * 1024 || !signatureMatches) {\n        context.addIssue({\n          code: 'custom',\n          message: 'Screenshot bytes must match the image type and fit within 5 MiB.',\n        });\n      }\n    } catch {\n      context.addIssue({\n        code: 'custom',\n        message: 'Screenshot data must contain valid base64 image bytes.',\n      });\n    }\n  });\n"],
+  "mappings": "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",
+  "names": ["z", "controlLocatorSchema", "locator", "description", "completionCheckSchema", "completionChecksSchema", "matchesControl", "control", "group", "__name", "matchesText", "check", "state", "baseline", "isVisible", "isControlLabel", "isFresh", "matchesControlValue", "selectedValues", "value", "matchesControlCheck", "semanticMatches", "matches", "evaluateCompletionChecks", "checks", "results", "passed", "result", "screenshotSchema", "data", "image", "context", "bytes", "signatureMatches"]
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@ruakit/schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "description": "Planning and execution protocols for RuaKit",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../shared/scripts/minify.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/src/decision.ts

@@ -0,0 +1,159 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { completionChecksSchema, screenshotSchema } from "./verification.js";
+
+/** Identifies a control in a particular observation. */
+const target = z.strictObject({
+  id: z.string().min(1).max(200),
+  version: z.number().int().positive(),
+});
+
+/** Describes an accessible group containing a control. */
+const controlGroup = z.strictObject({
+  role: z.enum([
+    "form",
+    "group",
+    "radiogroup",
+    "region",
+    "dialog",
+    "alertdialog",
+  ]),
+  name: z.string().min(1).max(200),
+});
+
+/** Describes an observed control and its current state. */
+const control = z.strictObject({
+  target,
+  tag: z.string().max(100),
+  type: z.string().max(100).optional(),
+  role: z.string().max(100),
+  label: z.string().max(1000),
+  description: z.string().max(1000).optional(),
+  placeholder: z.string().max(1000).optional(),
+  groups: z.array(controlGroup).min(1).max(4).optional(),
+  groupsTruncated: z.boolean().optional(),
+  context: z.string().max(1000),
+  enabled: z.boolean(),
+  readOnly: z.boolean(),
+  value: z.string().max(20000).optional(),
+  checked: z.boolean().optional(),
+  expanded: z.boolean().optional(),
+  selectedValues: z.array(z.string().max(4000)).max(100).optional(),
+  options: z
+    .array(
+      z.strictObject({
+        value: z.string().max(4000),
+        label: z.string().max(1000),
+        enabled: z.boolean(),
+      }),
+    )
+    .max(200)
+    .optional(),
+  valid: z.boolean().optional(),
+  contentEditable: z.boolean().optional(),
+});
+
+/** Actions the runtime can perform on an observed target. */
+export const actionSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("click"), target }),
+  z.strictObject({ type: z.literal("focus"), target }),
+  z.strictObject({
+    type: z.literal("insertText"),
+    target,
+    text: z.string().max(20000),
+  }),
+  z.strictObject({
+    type: z.literal("key"),
+    target,
+    key: z.string().min(1).max(100),
+    altKey: z.boolean(),
+    ctrlKey: z.boolean(),
+    metaKey: z.boolean(),
+    shiftKey: z.boolean(),
+  }),
+  z.strictObject({
+    type: z.literal("fill"),
+    target,
+    value: z.string().max(4000),
+  }),
+  z.strictObject({
+    type: z.literal("select"),
+    target,
+    values: z.array(z.string().max(4000)).min(1).max(100),
+  }),
+  z.strictObject({ type: z.literal("check"), target, checked: z.boolean() }),
+]);
+
+/** The model requests permission for this exact action. Only the host can approve it. */
+export const approvalDecisionSchema = z.strictObject({
+  type: z.literal("approval"),
+  message: z.string().trim().min(1).max(2000),
+  step: actionSchema,
+});
+
+/** Decisions a planner can return for the current observation. */
+export const decisionSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    type: z.literal("act"),
+    message: z.string().min(1).max(2000),
+    step: actionSchema,
+  }),
+  z.strictObject({
+    type: z.literal("complete"),
+    message: z.string().min(1).max(2000),
+    checks: completionChecksSchema,
+  }),
+  z.strictObject({
+    type: z.literal("prepare"),
+    message: z.string().min(1).max(2000),
+    checks: completionChecksSchema,
+  }),
+  z.strictObject({
+    type: z.literal("screenshot"),
+    message: z.string().min(1).max(2000),
+  }),
+  z.strictObject({
+    type: z.literal("clarify"),
+    message: z.string().min(1).max(500),
+  }),
+  z.strictObject({
+    type: z.literal("unsupported"),
+    message: z.string().min(1).max(2000),
+  }),
+  approvalDecisionSchema,
+]);
+
+/** A previous question and the user's answer. */
+const clarification = z.strictObject({
+  question: z.string().max(500),
+  answer: z.string().max(2000),
+});
+
+/** The page observation on which the planner should base its decision. */
+const snapshot = z.strictObject({
+  url: z.string().max(4000),
+  title: z.string().max(2000),
+  text: z.string().max(20000),
+  controls: z.array(control).max(200),
+  focused: target.nullable(),
+  truncated: z.boolean(),
+});
+
+/** Observation and conversation context sent to the planner. */
+export const decisionRequestSchema = z.strictObject({
+  platform: z.string().max(200).optional(),
+  prompt: z.string().trim().min(1).max(2000),
+  clarifications: z.array(clarification).max(3),
+  snapshot,
+  history: z.array(decisionSchema).max(20),
+  checks: completionChecksSchema.nullable().optional(),
+  canScreenshot: z.boolean().optional(),
+  screenshot: screenshotSchema.optional(),
+});
+
+/** A validated request for a planner decision. */
+export type DecisionRequest = z.infer<typeof decisionRequestSchema>;
+/** A validated planner decision. */
+export type Decision = z.infer<typeof decisionSchema>;
+/** A decision asking the host to approve one action. */
+export type ApprovalDecision = z.infer<typeof approvalDecisionSchema>;

package/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright 2026 RuaKit contributors. SPDX-License-Identifier: MIT
+export * from './protocol.js';
+export * from './decision.js';
+export * from './verification.js';
+export * from './plan.js';