@xemahq/kernel-contracts 0.2.3 → 0.3.0

package/dist/agent-workspace/awp-spec.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://xema.dev/schemas/awp-spec.v1.json",
-  "emittedAt": "2026-06-07T09:05:01.778Z",
+  "emittedAt": "2026-06-07T10:04:28.421Z",
   "spec": {
     "id": "awp/v1",
     "version": "1.2.0",

package/dist/widget/index.d.ts

@@ -0,0 +1,5 @@
+export * from './lib/chat-widget-kind';
+export * from './lib/chat-widget-payloads';
+export * from './lib/chat-widget-envelope';
+export * from './lib/widget-contribution';
+//# sourceMappingURL=index.d.ts.map

package/dist/widget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/widget/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC"}

package/dist/widget/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/chat-widget-kind"), exports);
+__exportStar(require("./lib/chat-widget-payloads"), exports);
+__exportStar(require("./lib/chat-widget-envelope"), exports);
+__exportStar(require("./lib/widget-contribution"), exports);
+//# sourceMappingURL=index.js.map

package/dist/widget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/widget/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,6DAA2C;AAC3C,6DAA2C;AAC3C,4DAA0C"}

package/dist/widget/lib/chat-widget-envelope.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export interface ChatWidgetEnvelope {
+    readonly kind: string;
+    readonly version: number;
+    readonly payload: unknown;
+}
+export declare const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope>;
+export declare enum ChatWidgetFallbackReason {
+    UnknownKind = "unknown-kind",
+    InvalidPayload = "invalid-payload",
+    UnsupportedVersion = "unsupported-version"
+}
+//# sourceMappingURL=chat-widget-envelope.d.ts.map

package/dist/widget/lib/chat-widget-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-envelope.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAGD,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAIjE,CAAC;AAOH,oBAAY,wBAAwB;IAClC,WAAW,iBAAiB;IAC5B,cAAc,oBAAoB;IAClC,kBAAkB,wBAAwB;CAC3C"}

package/dist/widget/lib/chat-widget-envelope.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatWidgetFallbackReason = exports.ChatWidgetEnvelopeSchema = void 0;
+const zod_1 = require("zod");
+exports.ChatWidgetEnvelopeSchema = zod_1.z.object({
+    kind: zod_1.z.string().min(1),
+    version: zod_1.z.number().int().positive(),
+    payload: zod_1.z.unknown(),
+});
+var ChatWidgetFallbackReason;
+(function (ChatWidgetFallbackReason) {
+    ChatWidgetFallbackReason["UnknownKind"] = "unknown-kind";
+    ChatWidgetFallbackReason["InvalidPayload"] = "invalid-payload";
+    ChatWidgetFallbackReason["UnsupportedVersion"] = "unsupported-version";
+})(ChatWidgetFallbackReason || (exports.ChatWidgetFallbackReason = ChatWidgetFallbackReason = {}));
+//# sourceMappingURL=chat-widget-envelope.js.map

package/dist/widget/lib/chat-widget-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-envelope.js","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-envelope.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAyBX,QAAA,wBAAwB,GAAkC,OAAC,CAAC,MAAM,CAAC;IAC9E,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC;AAOH,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAClC,wDAA4B,CAAA;IAC5B,8DAAkC,CAAA;IAClC,sEAA0C,CAAA;AAC5C,CAAC,EAJW,wBAAwB,wCAAxB,wBAAwB,QAInC"}

package/dist/widget/lib/chat-widget-kind.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare enum ChatWidgetKind {
+    Plan = "plan",
+    Diff = "diff",
+    Approval = "approval",
+    Table = "table",
+    Chart = "chart",
+    FileEdit = "file-edit"
+}
+export declare const ChatWidgetKindSchema: z.ZodEnum<typeof ChatWidgetKind>;
+export declare enum ChatChartKind {
+    Bar = "bar",
+    Line = "line"
+}
+export declare const ChatChartKindSchema: z.ZodEnum<typeof ChatChartKind>;
+//# sourceMappingURL=chat-widget-kind.d.ts.map

package/dist/widget/lib/chat-widget-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-kind.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-kind.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,oBAAY,cAAc;IAExB,IAAI,SAAS;IAEb,IAAI,SAAS;IAEb,QAAQ,aAAa;IAErB,KAAK,UAAU;IAEf,KAAK,UAAU;IAEf,QAAQ,cAAc;CACvB;AAGD,eAAO,MAAM,oBAAoB,kCAA+B,CAAC;AAMjE,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,mBAAmB,iCAA8B,CAAC"}

package/dist/widget/lib/chat-widget-kind.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatChartKindSchema = exports.ChatChartKind = exports.ChatWidgetKindSchema = exports.ChatWidgetKind = void 0;
+const zod_1 = require("zod");
+var ChatWidgetKind;
+(function (ChatWidgetKind) {
+    ChatWidgetKind["Plan"] = "plan";
+    ChatWidgetKind["Diff"] = "diff";
+    ChatWidgetKind["Approval"] = "approval";
+    ChatWidgetKind["Table"] = "table";
+    ChatWidgetKind["Chart"] = "chart";
+    ChatWidgetKind["FileEdit"] = "file-edit";
+})(ChatWidgetKind || (exports.ChatWidgetKind = ChatWidgetKind = {}));
+exports.ChatWidgetKindSchema = zod_1.z.nativeEnum(ChatWidgetKind);
+var ChatChartKind;
+(function (ChatChartKind) {
+    ChatChartKind["Bar"] = "bar";
+    ChatChartKind["Line"] = "line";
+})(ChatChartKind || (exports.ChatChartKind = ChatChartKind = {}));
+exports.ChatChartKindSchema = zod_1.z.nativeEnum(ChatChartKind);
+//# sourceMappingURL=chat-widget-kind.js.map

package/dist/widget/lib/chat-widget-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-kind.js","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-kind.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAuBxB,IAAY,cAaX;AAbD,WAAY,cAAc;IAExB,+BAAa,CAAA;IAEb,+BAAa,CAAA;IAEb,uCAAqB,CAAA;IAErB,iCAAe,CAAA;IAEf,iCAAe,CAAA;IAEf,wCAAsB,CAAA;AACxB,CAAC,EAbW,cAAc,8BAAd,cAAc,QAazB;AAGY,QAAA,oBAAoB,GAAG,OAAC,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AAMjE,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,4BAAW,CAAA;IACX,8BAAa,CAAA;AACf,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB;AAEY,QAAA,mBAAmB,GAAG,OAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC"}

package/dist/widget/lib/chat-widget-payloads.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { ChatWidgetKind } from './chat-widget-kind';
+export declare enum WidgetTodoState {
+    Todo = "todo",
+    Active = "active",
+    Done = "done"
+}
+export declare const WidgetTodoStateSchema: z.ZodEnum<typeof WidgetTodoState>;
+export declare const PlanWidgetItemSchema: z.ZodObject<{
+    label: z.ZodString;
+    state: z.ZodEnum<typeof WidgetTodoState>;
+}, z.core.$strip>;
+export declare const PlanWidgetPayloadSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        state: z.ZodEnum<typeof WidgetTodoState>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlanWidgetPayload = z.infer<typeof PlanWidgetPayloadSchema>;
+export declare const DiffWidgetPayloadSchema: z.ZodObject<{
+    path: z.ZodString;
+    add: z.ZodNumber;
+    del: z.ZodNumber;
+    hunks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DiffWidgetPayload = z.infer<typeof DiffWidgetPayloadSchema>;
+export declare const FileEditWidgetPayloadSchema: z.ZodObject<{
+    path: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    add: z.ZodNumber;
+    del: z.ZodNumber;
+}, z.core.$strip>;
+export type FileEditWidgetPayload = z.infer<typeof FileEditWidgetPayloadSchema>;
+export declare const ApprovalWidgetPayloadSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    accent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalWidgetPayload = z.infer<typeof ApprovalWidgetPayloadSchema>;
+export declare const TableWidgetColumnSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const TableWidgetPayloadSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>;
+export type TableWidgetPayload = z.infer<typeof TableWidgetPayloadSchema>;
+export declare const ChartWidgetSeriesSchema: z.ZodObject<{
+    label: z.ZodString;
+    points: z.ZodArray<z.ZodObject<{
+        x: z.ZodString;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ChartWidgetPayloadSchema: z.ZodObject<{
+    kind: z.ZodEnum<typeof import("./chat-widget-kind").ChatChartKind>;
+    series: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        points: z.ZodArray<z.ZodObject<{
+            x: z.ZodString;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChartWidgetPayload = z.infer<typeof ChartWidgetPayloadSchema>;
+export declare const FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS: Readonly<Record<ChatWidgetKind, z.ZodTypeAny>>;
+export declare const FIRST_PARTY_WIDGET_VERSIONS: Readonly<Record<ChatWidgetKind, number>>;
+//# sourceMappingURL=chat-widget-payloads.d.ts.map

package/dist/widget/lib/chat-widget-payloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-payloads.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-payloads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAkBzE,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AACD,eAAO,MAAM,qBAAqB,mCAAgC,CAAC;AAGnE,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAC;AAGH,eAAO,MAAM,uBAAuB;;;;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAGxE,eAAO,MAAM,2BAA2B;;;;;iBAKtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAOhF,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAGhF,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAG1E,eAAO,MAAM,uBAAuB;;;;;;iBAGlC,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAQ1E,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CACvD,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,UAAU,CAAC,CAQrC,CAAC;AAOF,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAChD,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAQ/B,CAAC"}

package/dist/widget/lib/chat-widget-payloads.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_PARTY_WIDGET_VERSIONS = exports.FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS = exports.ChartWidgetPayloadSchema = exports.ChartWidgetSeriesSchema = exports.TableWidgetPayloadSchema = exports.TableWidgetColumnSchema = exports.ApprovalWidgetPayloadSchema = exports.FileEditWidgetPayloadSchema = exports.DiffWidgetPayloadSchema = exports.PlanWidgetPayloadSchema = exports.PlanWidgetItemSchema = exports.WidgetTodoStateSchema = exports.WidgetTodoState = void 0;
+const zod_1 = require("zod");
+const chat_widget_kind_1 = require("./chat-widget-kind");
+var WidgetTodoState;
+(function (WidgetTodoState) {
+    WidgetTodoState["Todo"] = "todo";
+    WidgetTodoState["Active"] = "active";
+    WidgetTodoState["Done"] = "done";
+})(WidgetTodoState || (exports.WidgetTodoState = WidgetTodoState = {}));
+exports.WidgetTodoStateSchema = zod_1.z.nativeEnum(WidgetTodoState);
+exports.PlanWidgetItemSchema = zod_1.z.object({
+    label: zod_1.z.string().min(1),
+    state: exports.WidgetTodoStateSchema,
+});
+exports.PlanWidgetPayloadSchema = zod_1.z.object({
+    title: zod_1.z.string().optional(),
+    items: zod_1.z.array(exports.PlanWidgetItemSchema),
+});
+exports.DiffWidgetPayloadSchema = zod_1.z.object({
+    path: zod_1.z.string().min(1),
+    add: zod_1.z.number(),
+    del: zod_1.z.number(),
+    hunks: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.FileEditWidgetPayloadSchema = zod_1.z.object({
+    path: zod_1.z.string().min(1),
+    summary: zod_1.z.string().optional(),
+    add: zod_1.z.number(),
+    del: zod_1.z.number(),
+});
+exports.ApprovalWidgetPayloadSchema = zod_1.z.object({
+    sessionId: zod_1.z.string().min(1),
+    accent: zod_1.z.string().optional(),
+});
+exports.TableWidgetColumnSchema = zod_1.z.object({
+    key: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1),
+});
+exports.TableWidgetPayloadSchema = zod_1.z.object({
+    columns: zod_1.z.array(exports.TableWidgetColumnSchema),
+    rows: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number()]))),
+});
+exports.ChartWidgetSeriesSchema = zod_1.z.object({
+    label: zod_1.z.string().min(1),
+    points: zod_1.z.array(zod_1.z.object({ x: zod_1.z.string(), y: zod_1.z.number() })),
+});
+exports.ChartWidgetPayloadSchema = zod_1.z.object({
+    kind: chat_widget_kind_1.ChatChartKindSchema,
+    series: zod_1.z.array(exports.ChartWidgetSeriesSchema),
+});
+exports.FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS = {
+    [chat_widget_kind_1.ChatWidgetKind.Plan]: exports.PlanWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Diff]: exports.DiffWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Approval]: exports.ApprovalWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Table]: exports.TableWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Chart]: exports.ChartWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.FileEdit]: exports.FileEditWidgetPayloadSchema,
+};
+exports.FIRST_PARTY_WIDGET_VERSIONS = {
+    [chat_widget_kind_1.ChatWidgetKind.Plan]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Diff]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Approval]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Table]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Chart]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.FileEdit]: 1,
+};
+//# sourceMappingURL=chat-widget-payloads.js.map

package/dist/widget/lib/chat-widget-payloads.js.map

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

package/dist/widget/lib/widget-contribution.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export interface WidgetContributionManifest {
+    readonly kind: string;
+    readonly version: number;
+    readonly displayName: string;
+    readonly summary: string;
+    readonly payloadSchema: Record<string, unknown>;
+}
+export declare const WidgetContributionManifestSchema: z.ZodType<WidgetContributionManifest>;
+export interface WidgetKindCatalogueEntry {
+    readonly kind: string;
+    readonly version: number;
+    readonly displayName: string;
+    readonly summary: string;
+    readonly payloadSchema: Record<string, unknown>;
+    readonly source: WidgetKindSource;
+    readonly biomeId?: string;
+}
+export declare enum WidgetKindSource {
+    FirstParty = "first-party",
+    Biome = "biome"
+}
+export declare const WidgetKindSourceSchema: z.ZodEnum<typeof WidgetKindSource>;
+//# sourceMappingURL=widget-contribution.d.ts.map

package/dist/widget/lib/widget-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-contribution.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/widget-contribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,MAAM,WAAW,0BAA0B;IAMzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAUD,eAAO,MAAM,gCAAgC,EAAE,CAAC,CAAC,OAAO,CAAC,0BAA0B,CActC,CAAC;AAY9C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAGD,oBAAY,gBAAgB;IAC1B,UAAU,gBAAgB;IAC1B,KAAK,UAAU;CAChB;AAED,eAAO,MAAM,sBAAsB,oCAAiC,CAAC"}

package/dist/widget/lib/widget-contribution.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WidgetKindSourceSchema = exports.WidgetKindSource = exports.WidgetContributionManifestSchema = void 0;
+const zod_1 = require("zod");
+const WIDGET_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+exports.WidgetContributionManifestSchema = zod_1.z.object({
+    kind: zod_1.z
+        .string()
+        .min(1)
+        .max(100)
+        .regex(WIDGET_KIND_SLUG_REGEX, 'Widget kind slug must be lowercase letters, digits, and hyphens (start with a letter).'),
+    version: zod_1.z.number().int().positive(),
+    displayName: zod_1.z.string().min(1).max(200),
+    summary: zod_1.z.string().min(1).max(1000),
+    payloadSchema: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+var WidgetKindSource;
+(function (WidgetKindSource) {
+    WidgetKindSource["FirstParty"] = "first-party";
+    WidgetKindSource["Biome"] = "biome";
+})(WidgetKindSource || (exports.WidgetKindSource = WidgetKindSource = {}));
+exports.WidgetKindSourceSchema = zod_1.z.nativeEnum(WidgetKindSource);
+//# sourceMappingURL=widget-contribution.js.map

package/dist/widget/lib/widget-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-contribution.js","sourceRoot":"","sources":["../../../src/widget/lib/widget-contribution.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AA0CxB,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAQtC,QAAA,gCAAgC,GAC3C,OAAC,CAAC,MAAM,CAAC;IACP,IAAI,EAAE,OAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,KAAK,CACJ,sBAAsB,EACtB,wFAAwF,CACzF;IACH,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACpC,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC;CACjD,CAA0C,CAAC;AAwB9C,IAAY,gBAGX;AAHD,WAAY,gBAAgB;IAC1B,8CAA0B,CAAA;IAC1B,mCAAe,CAAA;AACjB,CAAC,EAHW,gBAAgB,gCAAhB,gBAAgB,QAG3B;AAEY,QAAA,sBAAsB,GAAG,OAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -10,18 +10,26 @@
     "dist",
     "src"
   ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "check:boundary": "node scripts/check-subpath-dag.mjs"
+  },
   "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@types/node": "25.2.3",
-    "eslint": "^9.39.4",
-    "eslint-config-prettier": "^10.1.8",
+    "@eslint/js": "catalog:",
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "eslint-config-prettier": "catalog:",
     "eslint-plugin-import": "^2.31.0",
-    "prettier": "3.6.2",
-    "typescript": "5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "prettier": "catalog:",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:"
   },
   "dependencies": {
-    "zod": "^4.3.6"
+    "zod": "catalog:"
   },
   "exports": {
     "./*": {
@@ -30,13 +38,5 @@
       "default": "./dist/*/index.js"
     },
     "./package.json": "./package.json"
-  },
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "tsc -p tsconfig.json && node scripts/emit-awp-spec.mjs",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint .",
-    "check:boundary": "node scripts/check-subpath-dag.mjs"
   }
-}
+}

package/src/widget/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/chat-widget-kind';
+export * from './lib/chat-widget-payloads';
+export * from './lib/chat-widget-envelope';
+export * from './lib/widget-contribution';

package/src/widget/lib/chat-widget-envelope.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetEnvelope` — a single widget instance recorded on an assistant
+ * message's `metadata.widgets[]` and rendered by the host-web ChatWidget
+ * registry (HANDOFF §3.2).
+ *
+ * `kind` is a first-party {@link ChatWidgetKind} value OR a namespaced biome
+ * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for
+ * THIS kind — the FE renders the registered renderer when `version <=
+ * supportedVersion`, else a safe fallback card. `payload` is the kind-specific
+ * payload (validated by the producer against the kind's schema; the FE
+ * re-validates before render so a malformed payload renders the fallback rather
+ * than being dropped).
+ *
+ * This is the kernel-canonical mirror of the FE `ChatWidgetEnvelope` interface
+ * — keep the shapes value-identical.
+ */
+export interface ChatWidgetEnvelope {
+  readonly kind: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+/** Zod validator for {@link ChatWidgetEnvelope}. */
+export const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope> = z.object({
+  kind: z.string().min(1),
+  version: z.number().int().positive(),
+  payload: z.unknown(),
+});
+
+/**
+ * Why a widget fell back to the safe card — populated on the FE resolved
+ * decision so the Studio debugger can see WHY. Mirror of the FE
+ * `ChatWidgetFallbackReason`. Closed set.
+ */
+export enum ChatWidgetFallbackReason {
+  UnknownKind = 'unknown-kind',
+  InvalidPayload = 'invalid-payload',
+  UnsupportedVersion = 'unsupported-version',
+}

package/src/widget/lib/chat-widget-kind.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetKind` — the closed first-party set of rich in-chat widget kinds an
+ * agent may render through the generic `render_widget` tool (see the Xema OS
+ * ChatWidget feature). Each kind is a GENERIC, domain-agnostic presentation
+ * primitive — chosen to cover the broadest possible range of "structured thing
+ * the agent wants to show the user" without baking in any vertical semantics.
+ *
+ * ── Value-identity invariant ────────────────────────────────────────────────
+ * This enum is the kernel-canonical mirror of the host-web FE model
+ * (`submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-model.ts`,
+ * `ChatWidgetKind`). The two MUST stay value-identical: the FE consumes this
+ * contract via the frontend-bridge sync, and the registry resolves a payload to
+ * a renderer by matching `kind`. Adding a generic kind = add the enum member in
+ * BOTH places (the "2-file rule") plus a payload schema below.
+ *
+ * ── Closed first-party set vs. open biome set ───────────────────────────────
+ * A biome contributes its OWN widget kind as a namespaced string
+ * (`<biomeId>:<kind>`) through a `widget-kind` contribution — it never extends
+ * this enum. This mirrors the closed-enum + open-namespaced-string pattern used
+ * by the FE registry's `registerChatWidget`.
+ */
+export enum ChatWidgetKind {
+  /** A checklist / plan (todo items with status). The agent's "here's the plan". */
+  Plan = 'plan',
+  /** A single-file unified diff (path + hunks). "Here's the change I propose." */
+  Diff = 'diff',
+  /** A suspended capability call awaiting human approval, keyed by approval id. */
+  Approval = 'approval',
+  /** A generic columns + rows table. The universal "show me structured records". */
+  Table = 'table',
+  /** A compact bar/line chart over labelled series. "Visualise these numbers." */
+  Chart = 'chart',
+  /** A header-only file-change summary (path + add/del counts), no hunks. */
+  FileEdit = 'file-edit',
+}
+
+/** Zod mirror of {@link ChatWidgetKind} for wire-boundary validation. */
+export const ChatWidgetKindSchema = z.nativeEnum(ChatWidgetKind);
+
+/**
+ * The chart shapes the first-party `chart` widget can draw. Closed set — kept
+ * value-identical with the FE's `ChatChartKind`.
+ */
+export enum ChatChartKind {
+  Bar = 'bar',
+  Line = 'line',
+}
+
+export const ChatChartKindSchema = z.nativeEnum(ChatChartKind);

package/src/widget/lib/chat-widget-payloads.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+import { ChatChartKindSchema, ChatWidgetKind } from './chat-widget-kind';
+
+/**
+ * Per-kind payload contracts for the first-party {@link ChatWidgetKind} set.
+ *
+ * These schemas are the WIRE contract the `render_widget` tool validates against
+ * before a widget envelope is recorded onto an assistant message's
+ * `metadata.widgets[]`. They are kept STRUCTURALLY value-identical with the FE
+ * narrowing validators in
+ * `submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-builtins.tsx`
+ * — the FE re-validates client-side (so a future/unknown payload still routes to
+ * the safe fallback card), but the runtime fails fast on a bad payload so a
+ * malformed widget never reaches the transcript.
+ *
+ * Zero runtime deps beyond zod (kernel-leaf invariant).
+ */
+
+/** Mirror of the FE `TodoState` (session-kit). Closed set. */
+export enum WidgetTodoState {
+  Todo = 'todo',
+  Active = 'active',
+  Done = 'done',
+}
+export const WidgetTodoStateSchema = z.nativeEnum(WidgetTodoState);
+
+/** A single plan/checklist item. Mirrors session-kit `TodoItem`. */
+export const PlanWidgetItemSchema = z.object({
+  label: z.string().min(1),
+  state: WidgetTodoStateSchema,
+});
+
+/** `plan` payload — a titled checklist of todo items. */
+export const PlanWidgetPayloadSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(PlanWidgetItemSchema),
+});
+export type PlanWidgetPayload = z.infer<typeof PlanWidgetPayloadSchema>;
+
+/**
+ * `diff` payload — a single-file unified diff. `hunks` are raw diff lines whose
+ * first character is the marker (`+`/`-`/space). Mirrors session-kit `DiffFile`.
+ */
+export const DiffWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  add: z.number(),
+  del: z.number(),
+  hunks: z.array(z.string()).optional(),
+});
+export type DiffWidgetPayload = z.infer<typeof DiffWidgetPayloadSchema>;
+
+/** `file-edit` payload — a header-only file change summary (no hunks). */
+export const FileEditWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  summary: z.string().optional(),
+  add: z.number(),
+  del: z.number(),
+});
+export type FileEditWidgetPayload = z.infer<typeof FileEditWidgetPayloadSchema>;
+
+/**
+ * `approval` payload — the suspended capability call awaiting approval, keyed by
+ * the session it belongs to. The FE mounts the same Pillar-3 inline approval
+ * card from this id.
+ */
+export const ApprovalWidgetPayloadSchema = z.object({
+  sessionId: z.string().min(1),
+  accent: z.string().optional(),
+});
+export type ApprovalWidgetPayload = z.infer<typeof ApprovalWidgetPayloadSchema>;
+
+/** A `table` column descriptor. */
+export const TableWidgetColumnSchema = z.object({
+  key: z.string().min(1),
+  label: z.string().min(1),
+});
+
+/** `table` payload — generic columns + rows. Cells are strings or numbers. */
+export const TableWidgetPayloadSchema = z.object({
+  columns: z.array(TableWidgetColumnSchema),
+  rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))),
+});
+export type TableWidgetPayload = z.infer<typeof TableWidgetPayloadSchema>;
+
+/** A single chart series (one bar/line group). */
+export const ChartWidgetSeriesSchema = z.object({
+  label: z.string().min(1),
+  points: z.array(z.object({ x: z.string(), y: z.number() })),
+});
+
+/** `chart` payload — a compact bar/line chart over labelled series. */
+export const ChartWidgetPayloadSchema = z.object({
+  kind: ChatChartKindSchema,
+  series: z.array(ChartWidgetSeriesSchema),
+});
+export type ChartWidgetPayload = z.infer<typeof ChartWidgetPayloadSchema>;
+
+/**
+ * The closed registry of first-party kind → payload schema. The single source
+ * of truth the `render_widget` tool & runtime use to validate a first-party
+ * widget payload by `kind`. Adding a generic kind = one enum member + one schema
+ * here + the FE mirror (the "2-file rule").
+ */
+export const FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS: Readonly<
+  Record<ChatWidgetKind, z.ZodTypeAny>
+> = {
+  [ChatWidgetKind.Plan]: PlanWidgetPayloadSchema,
+  [ChatWidgetKind.Diff]: DiffWidgetPayloadSchema,
+  [ChatWidgetKind.Approval]: ApprovalWidgetPayloadSchema,
+  [ChatWidgetKind.Table]: TableWidgetPayloadSchema,
+  [ChatWidgetKind.Chart]: ChartWidgetPayloadSchema,
+  [ChatWidgetKind.FileEdit]: FileEditWidgetPayloadSchema,
+};
+
+/**
+ * The current schema version for each first-party kind. Bumped when a kind's
+ * payload schema changes shape; the FE renders the registered renderer only
+ * when `envelope.version <= supportedVersion`, else the safe fallback.
+ */
+export const FIRST_PARTY_WIDGET_VERSIONS: Readonly<
+  Record<ChatWidgetKind, number>
+> = {
+  [ChatWidgetKind.Plan]: 1,
+  [ChatWidgetKind.Diff]: 1,
+  [ChatWidgetKind.Approval]: 1,
+  [ChatWidgetKind.Table]: 1,
+  [ChatWidgetKind.Chart]: 1,
+  [ChatWidgetKind.FileEdit]: 1,
+};

package/src/widget/lib/widget-contribution.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+
+/**
+ * Manifest shape carried by every `ContributionKind.WidgetKind` envelope.
+ *
+ * One contribution = one widget kind. The shape mirrors
+ * `CapabilityContributionManifest` (see `../capability/lib/capability-contribution.ts`)
+ * so the generic `BootstrapContributionsService<TKind, TManifest>` template and
+ * the codemod can ingest it the same way every other contribution kind is
+ * ingested. Provenance (`biomeId`, `biomeVersion`) is stamped by the bootstrap
+ * pipeline from the discovering biome's manifest — authors do NOT declare it
+ * inline.
+ *
+ * A biome contributes a widget kind so its frontend biome can register a
+ * renderer for it via `registerChatWidget('<biomeId>:<kind>', …)`. The
+ * `kind` here is the BARE, biome-local kind slug; the catalogue namespaces it
+ * to `<biomeId>:<kind>` at ingest so it can never shadow a first-party kind.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. `payloadSchema` is an opaque JSON Schema passed through
+ * verbatim (the catalogue surfaces it to the FE and to authoring tools; it is
+ * NOT a kernel-validated shape — validating it as JSON Schema here would be
+ * either partial or pull in a JSON-Schema validator, violating the kernel-leaf
+ * invariant).
+ */
+export interface WidgetContributionManifest {
+  /**
+   * Biome-local kind slug (lowercase, hyphenated). Namespaced to
+   * `<biomeId>:<kind>` by the catalogue — a biome can never claim a bare
+   * first-party kind.
+   */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Human-readable display name surfaced in the catalogue (≤ 200 chars). */
+  readonly displayName: string;
+  /** One-line summary of WHAT the widget shows + WHEN to use it (≤ 1000 chars). */
+  readonly summary: string;
+  /** JSON Schema for the widget payload — passed through verbatim. */
+  readonly payloadSchema: Record<string, unknown>;
+}
+
+const WIDGET_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Zod validator for {@link WidgetContributionManifest}. The bootstrap template
+ * and the catalogue's `POST /widget-kinds/register` route BOTH route every
+ * candidate manifest through this before persisting, so a malformed
+ * contribution fails at the boundary instead of at render time.
+ */
+export const WidgetContributionManifestSchema: z.ZodType<WidgetContributionManifest> =
+  z.object({
+    kind: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        WIDGET_KIND_SLUG_REGEX,
+        'Widget kind slug must be lowercase letters, digits, and hyphens (start with a letter).',
+      ),
+    version: z.number().int().positive(),
+    displayName: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    payloadSchema: z.record(z.string(), z.unknown()),
+  }) as z.ZodType<WidgetContributionManifest>;
+
+/**
+ * A resolved widget-kind catalogue entry — what `GET /widget-kinds` returns. It
+ * unifies the closed first-party set and the open biome-contributed set behind
+ * ONE shape the FE consumes to know which kinds exist (and to register
+ * biome-contributed kinds into the open FE registry).
+ *
+ * `source` discriminates provenance; `kind` is the FULLY-NAMESPACED slug the FE
+ * registry keys by (a first-party kind is its bare enum value; a biome kind is
+ * `<biomeId>:<kind>`).
+ */
+export interface WidgetKindCatalogueEntry {
+  readonly kind: string;
+  readonly version: number;
+  readonly displayName: string;
+  readonly summary: string;
+  readonly payloadSchema: Record<string, unknown>;
+  readonly source: WidgetKindSource;
+  /** Present only for biome-contributed kinds. */
+  readonly biomeId?: string;
+}
+
+/** Provenance of a catalogue entry. Closed set. */
+export enum WidgetKindSource {
+  FirstParty = 'first-party',
+  Biome = 'biome',
+}
+
+export const WidgetKindSourceSchema = z.nativeEnum(WidgetKindSource);

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Support. While redistributing the Work or
-      Derivative Works thereof, You may choose to offer, and charge a
-      fee for, acceptance of support, warranty, indemnity, or other
-      liability obligations and/or rights consistent with this License.
-      However, in accepting such obligations, You may act only on Your
-      own behalf and on Your sole responsibility, not on behalf of any
-      other Contributor, and only if You agree to indemnify, defend, and
-      hold each Contributor harmless for any liability incurred by, or
-      claims asserted against, such Contributor by reason of your
-      accepting any such warranty or support.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 Xema
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.