@contractspec/example.locale-jurisdiction-gate 0.0.0-canary-20260113162409

package/dist/handlers/demo.handlers.d.ts

@@ -0,0 +1,59 @@
+//#region src/handlers/demo.handlers.d.ts
+type AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';
+interface AssistantAnswerIR {
+  locale: string;
+  jurisdiction: string;
+  allowedScope: AllowedScope;
+  sections: {
+    heading: string;
+    body: string;
+  }[];
+  citations: {
+    kbSnapshotId: string;
+    sourceType: string;
+    sourceId: string;
+    title?: string;
+    excerpt?: string;
+  }[];
+  disclaimers?: string[];
+  riskFlags?: string[];
+  refused?: boolean;
+  refusalReason?: string;
+}
+interface DemoAssistantHandlers {
+  answer(input: {
+    envelope: {
+      traceId: string;
+      locale: string;
+      kbSnapshotId: string;
+      allowedScope: AllowedScope;
+      regulatoryContext: {
+        jurisdiction: string;
+      };
+    };
+    question: string;
+  }): Promise<AssistantAnswerIR>;
+  explainConcept(input: {
+    envelope: {
+      traceId: string;
+      locale: string;
+      kbSnapshotId: string;
+      allowedScope: AllowedScope;
+      regulatoryContext: {
+        jurisdiction: string;
+      };
+    };
+    conceptKey: string;
+  }): Promise<AssistantAnswerIR>;
+}
+/**
+ * Deterministic demo assistant handlers (no LLM).
+ *
+ * - Validates envelope
+ * - Requires citations
+ * - Enforces allowedScope (education_only blocks actionable language)
+ */
+declare function createDemoAssistantHandlers(): DemoAssistantHandlers;
+//#endregion
+export { DemoAssistantHandlers, createDemoAssistantHandlers };
+//# sourceMappingURL=demo.handlers.d.ts.map

package/dist/handlers/demo.handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.handlers.d.ts","names":[],"sources":["../../src/handlers/demo.handlers.ts"],"sourcesContent":[],"mappings":";KAMK,YAAA;UAEK,iBAAA,CAFO;EAEP,MAAA,EAAA,MAAA;EAkBO,YAAA,EAAA,MAAA;EAMG,YAAA,EArBJ,YAqBI;EAIN,QAAA,EAAA;IAAR,OAAA,EAAA,MAAA;IAOc,IAAA,EAAA,MAAA;EAIN,CAAA,EAAA;EAAR,SAAA,EAAA;IAAO,YAAA,EAAA,MAAA;IAUG,UAAA,EAAA,MAAA;;;;;;;;;;UA/BC,qBAAA;;;;;;oBAMG;;;;;;MAId,QAAQ;;;;;;oBAOM;;;;;;MAId,QAAQ;;;;;;;;;iBAUE,2BAAA,CAAA,GAA+B"}

package/dist/handlers/demo.handlers.js

@@ -0,0 +1,86 @@
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from "../policy/guard.js";
+
+//#region src/handlers/demo.handlers.ts
+/**
+* Deterministic demo assistant handlers (no LLM).
+*
+* - Validates envelope
+* - Requires citations
+* - Enforces allowedScope (education_only blocks actionable language)
+*/
+function createDemoAssistantHandlers() {
+	async function answer(input) {
+		const env = validateEnvelope(input.envelope);
+		if (!env.ok) return {
+			locale: input.envelope.locale ?? "en-US",
+			jurisdiction: input.envelope.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+			allowedScope: input.envelope.allowedScope ?? "education_only",
+			sections: [{
+				heading: "Request blocked",
+				body: env.error.message
+			}],
+			citations: [],
+			disclaimers: ["This system refuses to answer without a valid envelope."],
+			riskFlags: [env.error.code],
+			refused: true,
+			refusalReason: env.error.code
+		};
+		const draft = {
+			locale: env.value.locale,
+			jurisdiction: env.value.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+			allowedScope: env.value.allowedScope ?? "education_only",
+			sections: [{
+				heading: "Answer (demo)",
+				body: `You asked: "${input.question}". This demo answer is derived from the KB snapshot only.`
+			}],
+			citations: [{
+				kbSnapshotId: env.value.kbSnapshotId ?? "unknown",
+				sourceType: "ruleVersion",
+				sourceId: "rv_demo",
+				title: "Demo rule version",
+				excerpt: "Demo excerpt"
+			}],
+			disclaimers: ["Educational demo only."],
+			riskFlags: []
+		};
+		const scope = enforceAllowedScope(env.value.allowedScope, draft);
+		if (!scope.ok) return {
+			...draft,
+			sections: [{
+				heading: "Escalation required",
+				body: scope.error.message
+			}],
+			citations: draft.citations,
+			refused: true,
+			refusalReason: scope.error.code,
+			riskFlags: [...draft.riskFlags ?? [], scope.error.code]
+		};
+		const cited = enforceCitations(draft);
+		if (!cited.ok) return {
+			...draft,
+			sections: [{
+				heading: "Request blocked",
+				body: cited.error.message
+			}],
+			citations: [],
+			refused: true,
+			refusalReason: cited.error.code,
+			riskFlags: [...draft.riskFlags ?? [], cited.error.code]
+		};
+		return draft;
+	}
+	async function explainConcept(input) {
+		return await answer({
+			envelope: input.envelope,
+			question: `Explain concept: ${input.conceptKey}`
+		});
+	}
+	return {
+		answer,
+		explainConcept
+	};
+}
+
+//#endregion
+export { createDemoAssistantHandlers };
+//# sourceMappingURL=demo.handlers.js.map

package/dist/handlers/demo.handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.handlers.js","names":[],"sources":["../../src/handlers/demo.handlers.ts"],"sourcesContent":["import {\n  enforceAllowedScope,\n  enforceCitations,\n  validateEnvelope,\n} from '../policy/guard';\n\ntype AllowedScope = 'education_only' | 'generic_info' | 'escalation_required';\n\ninterface AssistantAnswerIR {\n  locale: string;\n  jurisdiction: string;\n  allowedScope: AllowedScope;\n  sections: { heading: string; body: string }[];\n  citations: {\n    kbSnapshotId: string;\n    sourceType: string;\n    sourceId: string;\n    title?: string;\n    excerpt?: string;\n  }[];\n  disclaimers?: string[];\n  riskFlags?: string[];\n  refused?: boolean;\n  refusalReason?: string;\n}\n\nexport interface DemoAssistantHandlers {\n  answer(input: {\n    envelope: {\n      traceId: string;\n      locale: string;\n      kbSnapshotId: string;\n      allowedScope: AllowedScope;\n      regulatoryContext: { jurisdiction: string };\n    };\n    question: string;\n  }): Promise<AssistantAnswerIR>;\n\n  explainConcept(input: {\n    envelope: {\n      traceId: string;\n      locale: string;\n      kbSnapshotId: string;\n      allowedScope: AllowedScope;\n      regulatoryContext: { jurisdiction: string };\n    };\n    conceptKey: string;\n  }): Promise<AssistantAnswerIR>;\n}\n\n/**\n * Deterministic demo assistant handlers (no LLM).\n *\n * - Validates envelope\n * - Requires citations\n * - Enforces allowedScope (education_only blocks actionable language)\n */\nexport function createDemoAssistantHandlers(): DemoAssistantHandlers {\n  async function answer(input: {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    envelope: DemoAssistantHandlers['answer'] extends (a: infer A) => any\n      ? A extends { envelope: infer E }\n        ? E\n        : never\n      : never;\n    question: string;\n  }): Promise<AssistantAnswerIR> {\n    const env = validateEnvelope(input.envelope);\n    if (!env.ok) {\n      return {\n        locale: input.envelope.locale ?? 'en-US',\n        jurisdiction:\n          input.envelope.regulatoryContext?.jurisdiction ?? 'UNKNOWN',\n        allowedScope: input.envelope.allowedScope ?? 'education_only',\n        sections: [\n          {\n            heading: 'Request blocked',\n            body: env.error.message,\n          },\n        ],\n        citations: [],\n        disclaimers: [\n          'This system refuses to answer without a valid envelope.',\n        ],\n        riskFlags: [env.error.code],\n        refused: true,\n        refusalReason: env.error.code,\n      };\n    }\n\n    const draft: AssistantAnswerIR = {\n      locale: env.value.locale,\n      jurisdiction: env.value.regulatoryContext?.jurisdiction ?? 'UNKNOWN',\n      allowedScope: env.value.allowedScope ?? 'education_only',\n      sections: [\n        {\n          heading: 'Answer (demo)',\n          body: `You asked: \"${input.question}\". This demo answer is derived from the KB snapshot only.`,\n        },\n      ],\n      citations: [\n        {\n          kbSnapshotId: env.value.kbSnapshotId ?? 'unknown',\n          sourceType: 'ruleVersion',\n          sourceId: 'rv_demo',\n          title: 'Demo rule version',\n          excerpt: 'Demo excerpt',\n        },\n      ],\n      disclaimers: ['Educational demo only.'],\n      riskFlags: [],\n    };\n\n    const scope = enforceAllowedScope(env.value.allowedScope, draft);\n    if (!scope.ok) {\n      return {\n        ...draft,\n        sections: [\n          { heading: 'Escalation required', body: scope.error.message },\n        ],\n        citations: draft.citations,\n        refused: true,\n        refusalReason: scope.error.code,\n        riskFlags: [...(draft.riskFlags ?? []), scope.error.code],\n      };\n    }\n\n    const cited = enforceCitations(draft);\n    if (!cited.ok) {\n      return {\n        ...draft,\n        sections: [{ heading: 'Request blocked', body: cited.error.message }],\n        citations: [],\n        refused: true,\n        refusalReason: cited.error.code,\n        riskFlags: [...(draft.riskFlags ?? []), cited.error.code],\n      };\n    }\n\n    return draft;\n  }\n\n  async function explainConcept(input: {\n    envelope: DemoAssistantHandlers['explainConcept'] extends (\n      a: infer A\n    ) => any // eslint-disable-line @typescript-eslint/no-explicit-any\n      ? A extends { envelope: infer E }\n        ? E\n        : never\n      : never;\n    conceptKey: string;\n  }): Promise<AssistantAnswerIR> {\n    return await answer({\n      envelope: input.envelope,\n      question: `Explain concept: ${input.conceptKey}`,\n    });\n  }\n\n  return { answer, explainConcept };\n}\n"],"mappings":";;;;;;;;;;AAyDA,SAAgB,8BAAqD;CACnE,eAAe,OAAO,OAQS;EAC7B,MAAM,MAAM,iBAAiB,MAAM,SAAS;AAC5C,MAAI,CAAC,IAAI,GACP,QAAO;GACL,QAAQ,MAAM,SAAS,UAAU;GACjC,cACE,MAAM,SAAS,mBAAmB,gBAAgB;GACpD,cAAc,MAAM,SAAS,gBAAgB;GAC7C,UAAU,CACR;IACE,SAAS;IACT,MAAM,IAAI,MAAM;IACjB,CACF;GACD,WAAW,EAAE;GACb,aAAa,CACX,0DACD;GACD,WAAW,CAAC,IAAI,MAAM,KAAK;GAC3B,SAAS;GACT,eAAe,IAAI,MAAM;GAC1B;EAGH,MAAM,QAA2B;GAC/B,QAAQ,IAAI,MAAM;GAClB,cAAc,IAAI,MAAM,mBAAmB,gBAAgB;GAC3D,cAAc,IAAI,MAAM,gBAAgB;GACxC,UAAU,CACR;IACE,SAAS;IACT,MAAM,eAAe,MAAM,SAAS;IACrC,CACF;GACD,WAAW,CACT;IACE,cAAc,IAAI,MAAM,gBAAgB;IACxC,YAAY;IACZ,UAAU;IACV,OAAO;IACP,SAAS;IACV,CACF;GACD,aAAa,CAAC,yBAAyB;GACvC,WAAW,EAAE;GACd;EAED,MAAM,QAAQ,oBAAoB,IAAI,MAAM,cAAc,MAAM;AAChE,MAAI,CAAC,MAAM,GACT,QAAO;GACL,GAAG;GACH,UAAU,CACR;IAAE,SAAS;IAAuB,MAAM,MAAM,MAAM;IAAS,CAC9D;GACD,WAAW,MAAM;GACjB,SAAS;GACT,eAAe,MAAM,MAAM;GAC3B,WAAW,CAAC,GAAI,MAAM,aAAa,EAAE,EAAG,MAAM,MAAM,KAAK;GAC1D;EAGH,MAAM,QAAQ,iBAAiB,MAAM;AACrC,MAAI,CAAC,MAAM,GACT,QAAO;GACL,GAAG;GACH,UAAU,CAAC;IAAE,SAAS;IAAmB,MAAM,MAAM,MAAM;IAAS,CAAC;GACrE,WAAW,EAAE;GACb,SAAS;GACT,eAAe,MAAM,MAAM;GAC3B,WAAW,CAAC,GAAI,MAAM,aAAa,EAAE,EAAG,MAAM,MAAM,KAAK;GAC1D;AAGH,SAAO;;CAGT,eAAe,eAAe,OASC;AAC7B,SAAO,MAAM,OAAO;GAClB,UAAU,MAAM;GAChB,UAAU,oBAAoB,MAAM;GACrC,CAAC;;AAGJ,QAAO;EAAE;EAAQ;EAAgB"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,2 @@
+import { DemoAssistantHandlers, createDemoAssistantHandlers } from "./demo.handlers.js";
+export { DemoAssistantHandlers, createDemoAssistantHandlers };

package/dist/handlers/index.js

@@ -0,0 +1,3 @@
+import { createDemoAssistantHandlers } from "./demo.handlers.js";
+
+export { createDemoAssistantHandlers };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { AllowedScopeEnum, AssistantAnswerIRModel, AssistantAnswerSectionModel, AssistantCitationModel, LLMCallEnvelopeModel, RegulatoryContextModel, UserProfileModel } from "./entities/models.js";
+import "./entities/index.js";
+import { AssistantAnswerBlockedEvent, AssistantAnswerDeliveredEvent, AssistantAnswerRequestedEvent } from "./events.js";
+import example from "./example.js";
+import { DemoAssistantHandlers, createDemoAssistantHandlers } from "./handlers/demo.handlers.js";
+import { AssistantAnswerContract, AssistantExplainConceptContract } from "./operations/assistant.js";
+import "./operations/index.js";
+import { AllowedScope, GateError, GateResult } from "./policy/types.js";
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from "./policy/guard.js";
+import { LocaleJurisdictionGateFeature } from "./locale-jurisdiction-gate.feature.js";
+export { AllowedScope, AllowedScopeEnum, AssistantAnswerBlockedEvent, AssistantAnswerContract, AssistantAnswerDeliveredEvent, AssistantAnswerIRModel, AssistantAnswerRequestedEvent, AssistantAnswerSectionModel, AssistantCitationModel, AssistantExplainConceptContract, DemoAssistantHandlers, GateError, GateResult, LLMCallEnvelopeModel, LocaleJurisdictionGateFeature, RegulatoryContextModel, UserProfileModel, createDemoAssistantHandlers, enforceAllowedScope, enforceCitations, example, validateEnvelope };

package/dist/index.js

@@ -0,0 +1,12 @@
+import { AssistantAnswerBlockedEvent, AssistantAnswerDeliveredEvent, AssistantAnswerRequestedEvent } from "./events.js";
+import example_default from "./example.js";
+import { AllowedScopeEnum, AssistantAnswerIRModel, AssistantAnswerSectionModel, AssistantCitationModel, LLMCallEnvelopeModel, RegulatoryContextModel, UserProfileModel } from "./entities/models.js";
+import "./entities/index.js";
+import { AssistantAnswerContract, AssistantExplainConceptContract } from "./operations/assistant.js";
+import "./operations/index.js";
+import { enforceAllowedScope, enforceCitations, validateEnvelope } from "./policy/guard.js";
+import { createDemoAssistantHandlers } from "./handlers/demo.handlers.js";
+import { LocaleJurisdictionGateFeature } from "./locale-jurisdiction-gate.feature.js";
+import "./docs/index.js";
+
+export { AllowedScopeEnum, AssistantAnswerBlockedEvent, AssistantAnswerContract, AssistantAnswerDeliveredEvent, AssistantAnswerIRModel, AssistantAnswerRequestedEvent, AssistantAnswerSectionModel, AssistantCitationModel, AssistantExplainConceptContract, LLMCallEnvelopeModel, LocaleJurisdictionGateFeature, RegulatoryContextModel, UserProfileModel, createDemoAssistantHandlers, enforceAllowedScope, enforceCitations, example_default as example, validateEnvelope };

package/dist/locale-jurisdiction-gate.feature.d.ts

@@ -0,0 +1,7 @@
+import * as _contractspec_lib_contracts3 from "@contractspec/lib.contracts";
+
+//#region src/locale-jurisdiction-gate.feature.d.ts
+declare const LocaleJurisdictionGateFeature: _contractspec_lib_contracts3.FeatureModuleSpec;
+//#endregion
+export { LocaleJurisdictionGateFeature };
+//# sourceMappingURL=locale-jurisdiction-gate.feature.d.ts.map

package/dist/locale-jurisdiction-gate.feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-jurisdiction-gate.feature.d.ts","names":[],"sources":["../src/locale-jurisdiction-gate.feature.ts"],"sourcesContent":[],"mappings":";;;cAEa,+BA2BX,4BAAA,CA3BwC"}

package/dist/locale-jurisdiction-gate.feature.js

@@ -0,0 +1,53 @@
+import { defineFeature } from "@contractspec/lib.contracts";
+
+//#region src/locale-jurisdiction-gate.feature.ts
+const LocaleJurisdictionGateFeature = defineFeature({
+	meta: {
+		key: "locale-jurisdiction-gate",
+		version: "1.0.0",
+		title: "Locale + Jurisdiction Gate",
+		description: "Fail-closed gating for assistant calls requiring locale/jurisdiction/snapshot/scope and citations.",
+		domain: "knowledge",
+		owners: ["@examples"],
+		tags: [
+			"assistant",
+			"policy",
+			"locale",
+			"jurisdiction",
+			"knowledge"
+		],
+		stability: "experimental"
+	},
+	operations: [{
+		key: "assistant.answer",
+		version: "1.0.0"
+	}, {
+		key: "assistant.explainConcept",
+		version: "1.0.0"
+	}],
+	events: [
+		{
+			key: "assistant.answer.requested",
+			version: "1.0.0"
+		},
+		{
+			key: "assistant.answer.blocked",
+			version: "1.0.0"
+		},
+		{
+			key: "assistant.answer.delivered",
+			version: "1.0.0"
+		}
+	],
+	presentations: [],
+	opToPresentation: [],
+	presentationsTargets: [],
+	capabilities: { requires: [{
+		key: "knowledge",
+		version: "1.0.0"
+	}] }
+});
+
+//#endregion
+export { LocaleJurisdictionGateFeature };
+//# sourceMappingURL=locale-jurisdiction-gate.feature.js.map

package/dist/locale-jurisdiction-gate.feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-jurisdiction-gate.feature.js","names":[],"sources":["../src/locale-jurisdiction-gate.feature.ts"],"sourcesContent":["import { defineFeature } from '@contractspec/lib.contracts';\n\nexport const LocaleJurisdictionGateFeature = defineFeature({\n  meta: {\n    key: 'locale-jurisdiction-gate',\n    version: '1.0.0',\n    title: 'Locale + Jurisdiction Gate',\n    description:\n      'Fail-closed gating for assistant calls requiring locale/jurisdiction/snapshot/scope and citations.',\n    domain: 'knowledge',\n    owners: ['@examples'],\n    tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],\n    stability: 'experimental',\n  },\n  operations: [\n    { key: 'assistant.answer', version: '1.0.0' },\n    { key: 'assistant.explainConcept', version: '1.0.0' },\n  ],\n  events: [\n    { key: 'assistant.answer.requested', version: '1.0.0' },\n    { key: 'assistant.answer.blocked', version: '1.0.0' },\n    { key: 'assistant.answer.delivered', version: '1.0.0' },\n  ],\n  presentations: [],\n  opToPresentation: [],\n  presentationsTargets: [],\n  capabilities: {\n    requires: [{ key: 'knowledge', version: '1.0.0' }],\n  },\n});\n"],"mappings":";;;AAEA,MAAa,gCAAgC,cAAc;CACzD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,OAAO;EACP,aACE;EACF,QAAQ;EACR,QAAQ,CAAC,YAAY;EACrB,MAAM;GAAC;GAAa;GAAU;GAAU;GAAgB;GAAY;EACpE,WAAW;EACZ;CACD,YAAY,CACV;EAAE,KAAK;EAAoB,SAAS;EAAS,EAC7C;EAAE,KAAK;EAA4B,SAAS;EAAS,CACtD;CACD,QAAQ;EACN;GAAE,KAAK;GAA8B,SAAS;GAAS;EACvD;GAAE,KAAK;GAA4B,SAAS;GAAS;EACrD;GAAE,KAAK;GAA8B,SAAS;GAAS;EACxD;CACD,eAAe,EAAE;CACjB,kBAAkB,EAAE;CACpB,sBAAsB,EAAE;CACxB,cAAc,EACZ,UAAU,CAAC;EAAE,KAAK;EAAa,SAAS;EAAS,CAAC,EACnD;CACF,CAAC"}

package/dist/operations/assistant.d.ts

@@ -0,0 +1,245 @@
+import * as _contractspec_lib_contracts4 from "@contractspec/lib.contracts";
+import * as _contractspec_lib_schema63 from "@contractspec/lib.schema";
+
+//#region src/operations/assistant.d.ts
+declare const AssistantAnswerContract: _contractspec_lib_contracts4.OperationSpec<_contractspec_lib_schema63.SchemaModel<{
+  envelope: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      traceId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      locale: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      regulatoryContext: {
+        type: _contractspec_lib_schema63.SchemaModel<{
+          jurisdiction: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: false;
+          };
+          region: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: true;
+          };
+          clientType: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: true;
+          };
+          allowedScope: {
+            type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+            isOptional: false;
+          };
+        }>;
+        isOptional: false;
+      };
+      kbSnapshotId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      allowedScope: {
+        type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+        isOptional: false;
+      };
+    }>;
+    isOptional: false;
+  };
+  question: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+}>, _contractspec_lib_schema63.SchemaModel<{
+  locale: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+  jurisdiction: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+  allowedScope: {
+    type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+    isOptional: false;
+  };
+  sections: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      heading: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      body: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  citations: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      kbSnapshotId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      sourceType: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      sourceId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: true;
+      };
+      excerpt: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  disclaimers: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isArray: true;
+    isOptional: true;
+  };
+  riskFlags: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isArray: true;
+    isOptional: true;
+  };
+  refused: {
+    type: _contractspec_lib_schema63.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  refusalReason: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, undefined>;
+declare const AssistantExplainConceptContract: _contractspec_lib_contracts4.OperationSpec<_contractspec_lib_schema63.SchemaModel<{
+  envelope: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      traceId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      locale: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      regulatoryContext: {
+        type: _contractspec_lib_schema63.SchemaModel<{
+          jurisdiction: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: false;
+          };
+          region: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: true;
+          };
+          clientType: {
+            type: _contractspec_lib_schema63.FieldType<string, string>;
+            isOptional: true;
+          };
+          allowedScope: {
+            type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+            isOptional: false;
+          };
+        }>;
+        isOptional: false;
+      };
+      kbSnapshotId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      allowedScope: {
+        type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+        isOptional: false;
+      };
+    }>;
+    isOptional: false;
+  };
+  conceptKey: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+}>, _contractspec_lib_schema63.SchemaModel<{
+  locale: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+  jurisdiction: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: false;
+  };
+  allowedScope: {
+    type: _contractspec_lib_schema63.EnumType<[string, string, string]>;
+    isOptional: false;
+  };
+  sections: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      heading: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      body: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  citations: {
+    type: _contractspec_lib_schema63.SchemaModel<{
+      kbSnapshotId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      sourceType: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      sourceId: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: false;
+      };
+      title: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: true;
+      };
+      excerpt: {
+        type: _contractspec_lib_schema63.FieldType<string, string>;
+        isOptional: true;
+      };
+    }>;
+    isArray: true;
+    isOptional: false;
+  };
+  disclaimers: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isArray: true;
+    isOptional: true;
+  };
+  riskFlags: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isArray: true;
+    isOptional: true;
+  };
+  refused: {
+    type: _contractspec_lib_schema63.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  refusalReason: {
+    type: _contractspec_lib_schema63.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, undefined>;
+//#endregion
+export { AssistantAnswerContract, AssistantExplainConceptContract };
+//# sourceMappingURL=assistant.d.ts.map

package/dist/operations/assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.d.ts","names":[],"sources":["../../src/operations/assistant.ts"],"sourcesContent":[],"mappings":";;;;cA0Ba,sDAAuB,yCAAA;;;;QAAvB,IAAA,EAmDX,0BAAA,CAAA,SAAA,CAAA,MAAA,EAAA,MAAA,CAAA;QAAA,UAAA,EAAA,KAAA;;;;;;;;;;;;UAnDkC,MAAA,EAAA;;;;;;;;;;;;;;;;;yBAAA;MAAA,CAAA;MAqDvB,YAAA,EAAA;QAkBX,IAAA,qCAAA,CAAA,CAAA,MAAA,EAAA,MAAA,EAAA,MAAA,CAAA,CAAA;;;;;;;;;;;;IAlB0C,IAAA,EArDR,0BAAA,CAAA,SAqDQ,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;;;;;;;;;;;;;QAAA,IAAA,sCAAA,CAAA,MAAA,EAAA,MAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAA/B,8DAA+B,yCAAA;;;;cAkB1C,0BAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAlB0C,0BAAA,CAAA"}

package/dist/operations/assistant.js

@@ -0,0 +1,115 @@
+import { AssistantAnswerIRModel, LLMCallEnvelopeModel } from "../entities/models.js";
+import { defineCommand } from "@contractspec/lib.contracts";
+import { ScalarTypeEnum, defineSchemaModel as defineSchemaModel$1 } from "@contractspec/lib.schema";
+
+//#region src/operations/assistant.ts
+const AssistantQuestionInput = defineSchemaModel$1({
+	name: "AssistantQuestionInput",
+	description: "Input for assistant calls with mandatory envelope.",
+	fields: {
+		envelope: {
+			type: LLMCallEnvelopeModel,
+			isOptional: false
+		},
+		question: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const AssistantConceptInput = defineSchemaModel$1({
+	name: "AssistantConceptInput",
+	description: "Input for explaining a concept with mandatory envelope.",
+	fields: {
+		envelope: {
+			type: LLMCallEnvelopeModel,
+			isOptional: false
+		},
+		conceptKey: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		}
+	}
+});
+const AssistantAnswerContract = defineCommand({
+	meta: {
+		key: "assistant.answer",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@examples"],
+		tags: [
+			"assistant",
+			"policy",
+			"locale",
+			"jurisdiction",
+			"knowledge"
+		],
+		description: "Answer a user question using a KB snapshot with strict locale/jurisdiction gating.",
+		goal: "Provide policy-safe answers that cite a KB snapshot or refuse.",
+		context: "Called by UI or workflows; must fail-closed if envelope is invalid or citations are missing."
+	},
+	io: {
+		input: AssistantQuestionInput,
+		output: AssistantAnswerIRModel,
+		errors: {
+			LOCALE_REQUIRED: {
+				description: "Locale is required and must be supported",
+				http: 400,
+				gqlCode: "LOCALE_REQUIRED",
+				when: "locale is missing or unsupported"
+			},
+			JURISDICTION_REQUIRED: {
+				description: "Jurisdiction is required",
+				http: 400,
+				gqlCode: "JURISDICTION_REQUIRED",
+				when: "jurisdiction is missing"
+			},
+			KB_SNAPSHOT_REQUIRED: {
+				description: "KB snapshot id is required",
+				http: 400,
+				gqlCode: "KB_SNAPSHOT_REQUIRED",
+				when: "kbSnapshotId is missing"
+			},
+			CITATIONS_REQUIRED: {
+				description: "Answers must include citations to a KB snapshot",
+				http: 422,
+				gqlCode: "CITATIONS_REQUIRED",
+				when: "answer has no citations"
+			},
+			SCOPE_VIOLATION: {
+				description: "Answer violates allowed scope and must be refused/escalated",
+				http: 403,
+				gqlCode: "SCOPE_VIOLATION",
+				when: "output includes forbidden content under the given allowedScope"
+			}
+		}
+	},
+	policy: { auth: "user" }
+});
+const AssistantExplainConceptContract = defineCommand({
+	meta: {
+		key: "assistant.explainConcept",
+		version: "1.0.0",
+		stability: "experimental",
+		owners: ["@examples"],
+		tags: [
+			"assistant",
+			"policy",
+			"knowledge",
+			"concepts"
+		],
+		description: "Explain a concept using a KB snapshot with strict locale/jurisdiction gating.",
+		goal: "Explain concepts with citations or refuse.",
+		context: "Same constraints as assistant.answer."
+	},
+	io: {
+		input: AssistantConceptInput,
+		output: AssistantAnswerIRModel,
+		errors: AssistantAnswerContract.io.errors
+	},
+	policy: { auth: "user" }
+});
+
+//#endregion
+export { AssistantAnswerContract, AssistantExplainConceptContract };
+//# sourceMappingURL=assistant.js.map

package/dist/operations/assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.js","names":["defineSchemaModel"],"sources":["../../src/operations/assistant.ts"],"sourcesContent":["import { defineCommand } from '@contractspec/lib.contracts';\nimport { ScalarTypeEnum, defineSchemaModel } from '@contractspec/lib.schema';\n\nimport {\n  AssistantAnswerIRModel,\n  LLMCallEnvelopeModel,\n} from '../entities/models';\n\nconst AssistantQuestionInput = defineSchemaModel({\n  name: 'AssistantQuestionInput',\n  description: 'Input for assistant calls with mandatory envelope.',\n  fields: {\n    envelope: { type: LLMCallEnvelopeModel, isOptional: false },\n    question: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },\n  },\n});\n\nconst AssistantConceptInput = defineSchemaModel({\n  name: 'AssistantConceptInput',\n  description: 'Input for explaining a concept with mandatory envelope.',\n  fields: {\n    envelope: { type: LLMCallEnvelopeModel, isOptional: false },\n    conceptKey: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },\n  },\n});\n\nexport const AssistantAnswerContract = defineCommand({\n  meta: {\n    key: 'assistant.answer',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@examples'],\n    tags: ['assistant', 'policy', 'locale', 'jurisdiction', 'knowledge'],\n    description:\n      'Answer a user question using a KB snapshot with strict locale/jurisdiction gating.',\n    goal: 'Provide policy-safe answers that cite a KB snapshot or refuse.',\n    context:\n      'Called by UI or workflows; must fail-closed if envelope is invalid or citations are missing.',\n  },\n  io: {\n    input: AssistantQuestionInput,\n    output: AssistantAnswerIRModel,\n    errors: {\n      LOCALE_REQUIRED: {\n        description: 'Locale is required and must be supported',\n        http: 400,\n        gqlCode: 'LOCALE_REQUIRED',\n        when: 'locale is missing or unsupported',\n      },\n      JURISDICTION_REQUIRED: {\n        description: 'Jurisdiction is required',\n        http: 400,\n        gqlCode: 'JURISDICTION_REQUIRED',\n        when: 'jurisdiction is missing',\n      },\n      KB_SNAPSHOT_REQUIRED: {\n        description: 'KB snapshot id is required',\n        http: 400,\n        gqlCode: 'KB_SNAPSHOT_REQUIRED',\n        when: 'kbSnapshotId is missing',\n      },\n      CITATIONS_REQUIRED: {\n        description: 'Answers must include citations to a KB snapshot',\n        http: 422,\n        gqlCode: 'CITATIONS_REQUIRED',\n        when: 'answer has no citations',\n      },\n      SCOPE_VIOLATION: {\n        description:\n          'Answer violates allowed scope and must be refused/escalated',\n        http: 403,\n        gqlCode: 'SCOPE_VIOLATION',\n        when: 'output includes forbidden content under the given allowedScope',\n      },\n    },\n  },\n  policy: { auth: 'user' },\n});\n\nexport const AssistantExplainConceptContract = defineCommand({\n  meta: {\n    key: 'assistant.explainConcept',\n    version: '1.0.0',\n    stability: 'experimental',\n    owners: ['@examples'],\n    tags: ['assistant', 'policy', 'knowledge', 'concepts'],\n    description:\n      'Explain a concept using a KB snapshot with strict locale/jurisdiction gating.',\n    goal: 'Explain concepts with citations or refuse.',\n    context: 'Same constraints as assistant.answer.',\n  },\n  io: {\n    input: AssistantConceptInput,\n    output: AssistantAnswerIRModel,\n    errors: AssistantAnswerContract.io.errors,\n  },\n  policy: { auth: 'user' },\n});\n"],"mappings":";;;;;AAQA,MAAM,yBAAyBA,oBAAkB;CAC/C,MAAM;CACN,aAAa;CACb,QAAQ;EACN,UAAU;GAAE,MAAM;GAAsB,YAAY;GAAO;EAC3D,UAAU;GAAE,MAAM,eAAe,iBAAiB;GAAE,YAAY;GAAO;EACxE;CACF,CAAC;AAEF,MAAM,wBAAwBA,oBAAkB;CAC9C,MAAM;CACN,aAAa;CACb,QAAQ;EACN,UAAU;GAAE,MAAM;GAAsB,YAAY;GAAO;EAC3D,YAAY;GAAE,MAAM,eAAe,iBAAiB;GAAE,YAAY;GAAO;EAC1E;CACF,CAAC;AAEF,MAAa,0BAA0B,cAAc;CACnD,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,YAAY;EACrB,MAAM;GAAC;GAAa;GAAU;GAAU;GAAgB;GAAY;EACpE,aACE;EACF,MAAM;EACN,SACE;EACH;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACR,QAAQ;GACN,iBAAiB;IACf,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,uBAAuB;IACrB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,sBAAsB;IACpB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,oBAAoB;IAClB,aAAa;IACb,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACD,iBAAiB;IACf,aACE;IACF,MAAM;IACN,SAAS;IACT,MAAM;IACP;GACF;EACF;CACD,QAAQ,EAAE,MAAM,QAAQ;CACzB,CAAC;AAEF,MAAa,kCAAkC,cAAc;CAC3D,MAAM;EACJ,KAAK;EACL,SAAS;EACT,WAAW;EACX,QAAQ,CAAC,YAAY;EACrB,MAAM;GAAC;GAAa;GAAU;GAAa;GAAW;EACtD,aACE;EACF,MAAM;EACN,SAAS;EACV;CACD,IAAI;EACF,OAAO;EACP,QAAQ;EACR,QAAQ,wBAAwB,GAAG;EACpC;CACD,QAAQ,EAAE,MAAM,QAAQ;CACzB,CAAC"}

package/dist/operations/index.d.ts

@@ -0,0 +1,2 @@
+import { AssistantAnswerContract, AssistantExplainConceptContract } from "./assistant.js";
+export { AssistantAnswerContract, AssistantExplainConceptContract };

package/dist/operations/index.js

@@ -0,0 +1,3 @@
+import { AssistantAnswerContract, AssistantExplainConceptContract } from "./assistant.js";
+
+export { AssistantAnswerContract, AssistantExplainConceptContract };