@contractspec/example.policy-safe-knowledge-assistant 1.57.0 → 1.58.0

package/.turbo/turbo-build.log

@@ -1,61 +1,59 @@
-$ bun build:types && bun build:bundle
-$ tsc --noEmit
-$ tsdown
-ℹ tsdown v0.20.3 powered by rolldown v1.0.0-rc.3
-ℹ config file: /home/runner/work/contractspec/contractspec/packages/examples/policy-safe-knowledge-assistant/tsdown.config.js 
-ℹ entry: src/example.ts, src/index.ts, src/policy-safe-knowledge-assistant.feature.ts, src/docs/index.ts, src/docs/policy-safe-knowledge-assistant.docblock.ts, src/handlers/index.ts, src/handlers/policy-safe-knowledge-assistant.handlers.ts, src/orchestrator/buildAnswer.ts, src/seed/fixtures.ts, src/seed/index.ts, src/seeders/index.ts, src/ui/PolicySafeKnowledgeAssistantDashboard.tsx, src/ui/index.ts, src/ui/hooks/usePolicySafeKnowledgeAssistant.ts
-ℹ target: esnext
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ dist/handlers/policy-safe-knowledge-assistant.handlers.js         9.46 kB │ gzip: 2.58 kB
-ℹ dist/ui/PolicySafeKnowledgeAssistantDashboard.js                  8.14 kB │ gzip: 2.11 kB
-ℹ dist/ui/hooks/usePolicySafeKnowledgeAssistant.js                  4.78 kB │ gzip: 1.47 kB
-ℹ dist/policy-safe-knowledge-assistant.feature.js                   2.55 kB │ gzip: 0.71 kB
-ℹ dist/orchestrator/buildAnswer.js                                  2.47 kB │ gzip: 0.93 kB
-ℹ dist/docs/policy-safe-knowledge-assistant.docblock.js             1.88 kB │ gzip: 0.90 kB
-ℹ dist/example.js                                                   1.20 kB │ gzip: 0.58 kB
-ℹ dist/seed/fixtures.js                                             0.80 kB │ gzip: 0.40 kB
-ℹ dist/index.js                                                     0.71 kB │ gzip: 0.25 kB
-ℹ dist/seeders/index.js                                             0.54 kB │ gzip: 0.38 kB
-ℹ dist/handlers/index.js                                            0.16 kB │ gzip: 0.11 kB
-ℹ dist/ui/index.js                                                  0.15 kB │ gzip: 0.09 kB
-ℹ dist/seed/index.js                                                0.07 kB │ gzip: 0.07 kB
-ℹ dist/docs/index.js                                                0.06 kB │ gzip: 0.08 kB
-ℹ dist/handlers/policy-safe-knowledge-assistant.handlers.js.map    20.30 kB │ gzip: 5.31 kB
-ℹ dist/ui/PolicySafeKnowledgeAssistantDashboard.js.map             10.46 kB │ gzip: 3.10 kB
-ℹ dist/ui/hooks/usePolicySafeKnowledgeAssistant.js.map              9.84 kB │ gzip: 2.85 kB
-ℹ dist/orchestrator/buildAnswer.js.map                              5.05 kB │ gzip: 1.68 kB
-ℹ dist/policy-safe-knowledge-assistant.feature.js.map               3.71 kB │ gzip: 1.05 kB
-ℹ dist/docs/policy-safe-knowledge-assistant.docblock.js.map         2.38 kB │ gzip: 1.08 kB
-ℹ dist/example.js.map                                               1.69 kB │ gzip: 0.80 kB
-ℹ dist/seed/fixtures.js.map                                         1.29 kB │ gzip: 0.55 kB
-ℹ dist/handlers/policy-safe-knowledge-assistant.handlers.d.ts.map   0.97 kB │ gzip: 0.39 kB
-ℹ dist/seeders/index.js.map                                         0.93 kB │ gzip: 0.61 kB
-ℹ dist/orchestrator/buildAnswer.d.ts.map                            0.62 kB │ gzip: 0.31 kB
-ℹ dist/ui/hooks/usePolicySafeKnowledgeAssistant.d.ts.map            0.61 kB │ gzip: 0.32 kB
-ℹ dist/ui/PolicySafeKnowledgeAssistantDashboard.d.ts.map            0.21 kB │ gzip: 0.16 kB
-ℹ dist/policy-safe-knowledge-assistant.feature.d.ts.map             0.19 kB │ gzip: 0.15 kB
-ℹ dist/seeders/index.d.ts.map                                       0.17 kB │ gzip: 0.15 kB
-ℹ dist/seed/fixtures.d.ts.map                                       0.16 kB │ gzip: 0.14 kB
-ℹ dist/example.d.ts.map                                             0.13 kB │ gzip: 0.13 kB
-ℹ dist/handlers/policy-safe-knowledge-assistant.handlers.d.ts       3.21 kB │ gzip: 0.85 kB
-ℹ dist/ui/hooks/usePolicySafeKnowledgeAssistant.d.ts                1.64 kB │ gzip: 0.58 kB
-ℹ dist/orchestrator/buildAnswer.d.ts                                1.31 kB │ gzip: 0.57 kB
-ℹ dist/seed/fixtures.d.ts                                           1.03 kB │ gzip: 0.37 kB
-ℹ dist/index.d.ts                                                   0.83 kB │ gzip: 0.27 kB
-ℹ dist/policy-safe-knowledge-assistant.feature.d.ts                 0.37 kB │ gzip: 0.20 kB
-ℹ dist/ui/PolicySafeKnowledgeAssistantDashboard.d.ts                0.34 kB │ gzip: 0.20 kB
-ℹ dist/seeders/index.d.ts                                           0.30 kB │ gzip: 0.23 kB
-ℹ dist/example.d.ts                                                 0.25 kB │ gzip: 0.17 kB
-ℹ dist/handlers/index.d.ts                                          0.24 kB │ gzip: 0.12 kB
-ℹ dist/ui/index.d.ts                                                0.15 kB │ gzip: 0.09 kB
-ℹ dist/seed/index.d.ts                                              0.07 kB │ gzip: 0.07 kB
-ℹ dist/docs/index.d.ts                                              0.01 kB │ gzip: 0.03 kB
-ℹ dist/docs/policy-safe-knowledge-assistant.docblock.d.ts           0.01 kB │ gzip: 0.03 kB
-ℹ 45 files, total: 101.44 kB
-[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
-  - tsdown:external (58%)
-  - rolldown-plugin-dts:generate (41%)
-See https://rolldown.rs/options/checks#plugintimings for more details.
+$ contractspec-bun-build prebuild
+$ bun run prebuild && bun run build:bundle && bun run build:types
+$ contractspec-bun-build prebuild
+$ contractspec-bun-build transpile
+[contractspec-bun-build] transpile target=bun root=src entries=14
+Bundled 14 modules in 20ms
 
-✔ Build complete in 31440ms
+  docs/index.js                                          1.86 KB   (entry point)
+  seeders/index.js                                       0.51 KB   (entry point)
+  handlers/index.js                                      12.77 KB  (entry point)
+  ./index.js                                             35.61 KB  (entry point)
+  seed/index.js                                          0.80 KB   (entry point)
+  seed/fixtures.js                                       0.80 KB   (entry point)
+  ui/index.js                                            16.74 KB  (entry point)
+  ui/PolicySafeKnowledgeAssistantDashboard.js            16.74 KB  (entry point)
+  ui/hooks/usePolicySafeKnowledgeAssistant.js            4.92 KB   (entry point)
+  docs/policy-safe-knowledge-assistant.docblock.js       1.86 KB   (entry point)
+  ./example.js                                           1.19 KB   (entry point)
+  handlers/policy-safe-knowledge-assistant.handlers.js   12.77 KB  (entry point)
+  orchestrator/buildAnswer.js                            2.43 KB   (entry point)
+  ./policy-safe-knowledge-assistant.feature.js           2.32 KB   (entry point)
+
+[contractspec-bun-build] transpile target=node root=src entries=14
+Bundled 14 modules in 13ms
+
+  docs/index.js                                          1.84 KB    (entry point)
+  seeders/index.js                                       506 bytes  (entry point)
+  handlers/index.js                                      12.76 KB   (entry point)
+  ./index.js                                             35.57 KB   (entry point)
+  seed/index.js                                          0.79 KB    (entry point)
+  seed/fixtures.js                                       0.79 KB    (entry point)
+  ui/index.js                                            16.71 KB   (entry point)
+  ui/PolicySafeKnowledgeAssistantDashboard.js            16.71 KB   (entry point)
+  ui/hooks/usePolicySafeKnowledgeAssistant.js            4.91 KB    (entry point)
+  docs/policy-safe-knowledge-assistant.docblock.js       1.84 KB    (entry point)
+  ./example.js                                           1.18 KB    (entry point)
+  handlers/policy-safe-knowledge-assistant.handlers.js   12.76 KB   (entry point)
+  orchestrator/buildAnswer.js                            2.43 KB    (entry point)
+  ./policy-safe-knowledge-assistant.feature.js           2.32 KB    (entry point)
+
+[contractspec-bun-build] transpile target=browser root=src entries=14
+Bundled 14 modules in 28ms
+
+  docs/index.js                                          1.84 KB    (entry point)
+  seeders/index.js                                       506 bytes  (entry point)
+  handlers/index.js                                      12.76 KB   (entry point)
+  ./index.js                                             35.57 KB   (entry point)
+  seed/index.js                                          0.79 KB    (entry point)
+  seed/fixtures.js                                       0.79 KB    (entry point)
+  ui/index.js                                            16.71 KB   (entry point)
+  ui/PolicySafeKnowledgeAssistantDashboard.js            16.71 KB   (entry point)
+  ui/hooks/usePolicySafeKnowledgeAssistant.js            4.91 KB    (entry point)
+  docs/policy-safe-knowledge-assistant.docblock.js       1.84 KB    (entry point)
+  ./example.js                                           1.18 KB    (entry point)
+  handlers/policy-safe-knowledge-assistant.handlers.js   12.76 KB   (entry point)
+  orchestrator/buildAnswer.js                            2.43 KB    (entry point)
+  ./policy-safe-knowledge-assistant.feature.js           2.32 KB    (entry point)
+
+$ contractspec-bun-build types

package/.turbo/turbo-prebuild.log

@@ -0,0 +1 @@
+$ contractspec-bun-build prebuild

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @contractspec/example.policy-safe-knowledge-assistant
 
+## 1.58.0
+
+### Minor Changes
+
+- d1f0fd0: chore: Migrate non-app package builds from tsdown to shared Bun tooling, add `@contractspec/tool.bun`, and standardize `prebuild`/`build`/`typecheck` with platform-aware exports and `tsc` declaration emission into `dist`.
+
+### Patch Changes
+
+- Updated dependencies [d1f0fd0]
+- Updated dependencies [4355a9e]
+  - @contractspec/example.locale-jurisdiction-gate@1.58.0
+  - @contractspec/example.versioned-knowledge-base@1.58.0
+  - @contractspec/example.kb-update-pipeline@1.58.0
+  - @contractspec/example.learning-patterns@1.58.0
+  - @contractspec/module.learning-journey@1.58.0
+  - @contractspec/lib.example-shared-ui@1.12.0
+  - @contractspec/lib.runtime-sandbox@0.13.0
+  - @contractspec/lib.design-system@1.58.0
+  - @contractspec/lib.ui-kit-web@1.58.0
+  - @contractspec/lib.contracts@1.58.0
+
 ## 1.57.0
 
 ### Minor Changes

package/dist/browser/docs/index.js

@@ -0,0 +1,38 @@
+// src/docs/policy-safe-knowledge-assistant.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var docBlocks = [
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.goal",
+    title: "Policy-safe Knowledge Assistant — Goal",
+    summary: "End-to-end example: versioned KB snapshots + locale/jurisdiction gating + HITL pipeline + learning hub.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/goal",
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"],
+    body: `## What this template proves
+- Assistant answers are structured and must cite a KB snapshot (or refuse).
+- Locale + jurisdiction are mandatory inputs for every assistant call.
+- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.
+- Learning hub demonstrates drills + coaching + quests without spam.
+
+## Offline-first
+- Seeded fixtures are deterministic and require no external services.
+- Optional non-authoritative fallback can be added behind a single feature flag (disabled by default).`
+  },
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.usage",
+    title: "Policy-safe Knowledge Assistant — Usage",
+    summary: "5–10 minute sandbox walkthrough for developers.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/usage",
+    tags: ["assistant", "knowledge", "usage"],
+    body: `## Demo walkthrough (high level)
+1) Onboard: set locale + jurisdiction.
+2) Publish snapshot: ingest source -> propose rule -> approve -> publish.
+3) Ask assistant: must pass gate and cite snapshot.
+4) Simulate change: watcher -> review -> publish new snapshot.
+5) Learning hub: drills session, ambient tip, quest start + step completion.`
+  }
+];
+registerDocBlocks(docBlocks);

package/dist/browser/docs/policy-safe-knowledge-assistant.docblock.js

@@ -0,0 +1,38 @@
+// src/docs/policy-safe-knowledge-assistant.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var docBlocks = [
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.goal",
+    title: "Policy-safe Knowledge Assistant — Goal",
+    summary: "End-to-end example: versioned KB snapshots + locale/jurisdiction gating + HITL pipeline + learning hub.",
+    kind: "goal",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/goal",
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"],
+    body: `## What this template proves
+- Assistant answers are structured and must cite a KB snapshot (or refuse).
+- Locale + jurisdiction are mandatory inputs for every assistant call.
+- Automation proposes KB patches; humans verify; publishing stays blocked until approvals.
+- Learning hub demonstrates drills + coaching + quests without spam.
+
+## Offline-first
+- Seeded fixtures are deterministic and require no external services.
+- Optional non-authoritative fallback can be added behind a single feature flag (disabled by default).`
+  },
+  {
+    id: "docs.examples.policy-safe-knowledge-assistant.usage",
+    title: "Policy-safe Knowledge Assistant — Usage",
+    summary: "5–10 minute sandbox walkthrough for developers.",
+    kind: "usage",
+    visibility: "public",
+    route: "/docs/examples/policy-safe-knowledge-assistant/usage",
+    tags: ["assistant", "knowledge", "usage"],
+    body: `## Demo walkthrough (high level)
+1) Onboard: set locale + jurisdiction.
+2) Publish snapshot: ingest source -> propose rule -> approve -> publish.
+3) Ask assistant: must pass gate and cite snapshot.
+4) Simulate change: watcher -> review -> publish new snapshot.
+5) Learning hub: drills session, ambient tip, quest start + step completion.`
+  }
+];
+registerDocBlocks(docBlocks);

package/dist/browser/example.js

@@ -0,0 +1,37 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "policy-safe-knowledge-assistant",
+    version: "1.0.0",
+    title: "Policy-safe Knowledge Assistant",
+    description: "All-in-one template: locale/jurisdiction gating + versioned KB snapshots + HITL update pipeline + learning hub.",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["assistant", "knowledge", "policy", "hitl", "learning"]
+  },
+  docs: {
+    goalDocId: "docs.examples.policy-safe-knowledge-assistant.goal",
+    usageDocId: "docs.examples.policy-safe-knowledge-assistant.usage"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.policy-safe-knowledge-assistant",
+    feature: "./policy-safe-knowledge-assistant.feature",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: {
+      enabled: true,
+      modes: ["playground", "specs", "builder", "markdown", "evolution"]
+    },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/browser/handlers/index.js

@@ -0,0 +1,334 @@
+// src/orchestrator/buildAnswer.ts
+import {
+  enforceAllowedScope,
+  enforceCitations,
+  validateEnvelope
+} from "@contractspec/example.locale-jurisdiction-gate/policy/guard";
+async function buildPolicySafeAnswer(input) {
+  const env = validateEnvelope(input.envelope);
+  if (!env.ok) {
+    return {
+      locale: input.envelope.locale ?? "en-GB",
+      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 results = await input.kbSearch({
+    snapshotId: env.value.kbSnapshotId,
+    jurisdiction: env.value.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+    query: input.question
+  });
+  const citations = results.items.map((item) => ({
+    kbSnapshotId: env.value.kbSnapshotId,
+    sourceType: "ruleVersion",
+    sourceId: item.ruleVersionId,
+    title: "Curated rule version",
+    excerpt: item.excerpt
+  }));
+  const draft = {
+    locale: env.value.locale,
+    jurisdiction: env.value.regulatoryContext?.jurisdiction ?? "UNKNOWN",
+    allowedScope: env.value.allowedScope,
+    sections: [
+      {
+        heading: "Answer (KB-derived)",
+        body: results.items.length > 0 ? `This answer is derived from ${results.items.length} curated rule version(s) in the referenced snapshot.` : "No curated knowledge found in the referenced snapshot."
+      }
+    ],
+    citations,
+    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 }],
+      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;
+}
+
+// src/handlers/policy-safe-knowledge-assistant.handlers.ts
+import { web } from "@contractspec/lib.runtime-sandbox";
+var { generateId } = web;
+function parseJsonArray(value) {
+  if (!value)
+    return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((v) => typeof v === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function nowIso() {
+  return new Date().toISOString();
+}
+function createPolicySafeKnowledgeAssistantHandlers(db) {
+  async function getUserContext(input) {
+    const result = await db.query(`SELECT * FROM psa_user_context WHERE "projectId" = $1 LIMIT 1`, [input.projectId]);
+    const row = result.rows[0];
+    if (!row) {
+      return {
+        projectId: input.projectId,
+        locale: "en-GB",
+        jurisdiction: "EU",
+        allowedScope: "education_only",
+        kbSnapshotId: null
+      };
+    }
+    return {
+      projectId: row.projectId,
+      locale: row.locale,
+      jurisdiction: row.jurisdiction,
+      allowedScope: row.allowedScope,
+      kbSnapshotId: row.kbSnapshotId
+    };
+  }
+  async function setUserContext(input) {
+    const existing = await db.query(`SELECT "projectId" FROM psa_user_context WHERE "projectId" = $1 LIMIT 1`, [input.projectId]);
+    if (existing.rows.length) {
+      await db.execute(`UPDATE psa_user_context SET locale = $1, jurisdiction = $2, "allowedScope" = $3 WHERE "projectId" = $4`, [input.locale, input.jurisdiction, input.allowedScope, input.projectId]);
+    } else {
+      await db.execute(`INSERT INTO psa_user_context ("projectId", locale, jurisdiction, "allowedScope", "kbSnapshotId") VALUES ($1, $2, $3, $4, $5)`, [
+        input.projectId,
+        input.locale,
+        input.jurisdiction,
+        input.allowedScope,
+        null
+      ]);
+    }
+    return await getUserContext({ projectId: input.projectId });
+  }
+  async function createRule(input) {
+    const id = generateId("psa_rule");
+    await db.execute(`INSERT INTO psa_rule (id, "projectId", jurisdiction, "topicKey") VALUES ($1, $2, $3, $4)`, [id, input.projectId, input.jurisdiction, input.topicKey]);
+    return { id, ...input };
+  }
+  async function upsertRuleVersion(input) {
+    if (!input.sourceRefs.length)
+      throw new Error("SOURCE_REFS_REQUIRED");
+    const rulesResult = await db.query(`SELECT * FROM psa_rule WHERE id = $1 LIMIT 1`, [input.ruleId]);
+    const rule = rulesResult.rows[0];
+    if (!rule)
+      throw new Error("RULE_NOT_FOUND");
+    const maxResult = await db.query(`SELECT MAX(version) as maxVersion FROM psa_rule_version WHERE "ruleId" = $1`, [input.ruleId]);
+    const maxVersion = Number(maxResult.rows[0]?.maxVersion ?? 0);
+    const version = maxVersion + 1;
+    const id = generateId("psa_rv");
+    const createdAt = nowIso();
+    await db.execute(`INSERT INTO psa_rule_version (id, "ruleId", jurisdiction, "topicKey", version, content, status, "sourceRefsJson", "approvedBy", "approvedAt", "createdAt")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`, [
+      id,
+      input.ruleId,
+      rule.jurisdiction,
+      rule.topicKey,
+      version,
+      input.content,
+      "draft",
+      JSON.stringify(input.sourceRefs),
+      null,
+      null,
+      createdAt
+    ]);
+    return {
+      id,
+      ruleId: input.ruleId,
+      jurisdiction: rule.jurisdiction,
+      topicKey: rule.topicKey,
+      version,
+      content: input.content,
+      status: "draft",
+      sourceRefs: input.sourceRefs,
+      createdAt: new Date(createdAt)
+    };
+  }
+  async function approveRuleVersion(input) {
+    const approvedAt = nowIso();
+    await db.execute(`UPDATE psa_rule_version SET status = $1, "approvedBy" = $2, "approvedAt" = $3 WHERE id = $4`, ["approved", input.approver, approvedAt, input.ruleVersionId]);
+    return { ruleVersionId: input.ruleVersionId, status: "approved" };
+  }
+  async function publishSnapshot(input) {
+    const approvedResult = await db.query(`SELECT id FROM psa_rule_version WHERE jurisdiction = $1 AND status = 'approved' ORDER BY id ASC`, [input.jurisdiction]);
+    const includedIds = approvedResult.rows.map((r) => r.id).filter(Boolean);
+    if (!includedIds.length)
+      throw new Error("NO_APPROVED_RULES");
+    const id = generateId("psa_snap");
+    const publishedAt = nowIso();
+    await db.execute(`INSERT INTO psa_snapshot (id, jurisdiction, "asOfDate", "includedRuleVersionIdsJson", "publishedAt")
+       VALUES ($1, $2, $3, $4, $5)`, [
+      id,
+      input.jurisdiction,
+      input.asOfDate.toISOString(),
+      JSON.stringify(includedIds),
+      publishedAt
+    ]);
+    await db.execute(`UPDATE psa_user_context SET "kbSnapshotId" = $1 WHERE "projectId" = $2`, [id, input.projectId]);
+    return {
+      id,
+      jurisdiction: input.jurisdiction,
+      includedRuleVersionIds: includedIds
+    };
+  }
+  async function searchKb(input) {
+    const snapResult = await db.query(`SELECT * FROM psa_snapshot WHERE id = $1 LIMIT 1`, [input.snapshotId]);
+    const snap = snapResult.rows[0];
+    if (!snap)
+      throw new Error("SNAPSHOT_NOT_FOUND");
+    if (snap.jurisdiction !== input.jurisdiction)
+      throw new Error("JURISDICTION_MISMATCH");
+    const includedIds = parseJsonArray(snap.includedRuleVersionIdsJson);
+    const tokens = input.query.toLowerCase().split(/\s+/).map((t) => t.trim()).filter(Boolean);
+    const items = [];
+    for (const id of includedIds) {
+      const rvResult = await db.query(`SELECT * FROM psa_rule_version WHERE id = $1 LIMIT 1`, [id]);
+      const rv = rvResult.rows[0];
+      if (!rv)
+        continue;
+      const hay = rv.content.toLowerCase();
+      const match = tokens.length ? tokens.every((t) => hay.includes(t)) : true;
+      if (!match)
+        continue;
+      items.push({ ruleVersionId: rv.id, excerpt: rv.content.slice(0, 140) });
+    }
+    return { items };
+  }
+  async function answer(input) {
+    const ctx = await getUserContext({ projectId: input.projectId });
+    if (!ctx.kbSnapshotId) {
+      const refused = await buildPolicySafeAnswer({
+        envelope: {
+          traceId: generateId("trace"),
+          locale: ctx.locale,
+          kbSnapshotId: "",
+          allowedScope: ctx.allowedScope,
+          regulatoryContext: { jurisdiction: ctx.jurisdiction }
+        },
+        question: input.question,
+        kbSearch: async () => ({ items: [] })
+      });
+      return refused;
+    }
+    return await buildPolicySafeAnswer({
+      envelope: {
+        traceId: generateId("trace"),
+        locale: ctx.locale,
+        kbSnapshotId: ctx.kbSnapshotId,
+        allowedScope: ctx.allowedScope,
+        regulatoryContext: { jurisdiction: ctx.jurisdiction }
+      },
+      question: input.question,
+      kbSearch: async (q) => await searchKb(q)
+    });
+  }
+  async function createChangeCandidate(input) {
+    const id = generateId("psa_change");
+    await db.execute(`INSERT INTO psa_change_candidate (id, "projectId", jurisdiction, "detectedAt", "diffSummary", "riskLevel", "proposedRuleVersionIdsJson")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`, [
+      id,
+      input.projectId,
+      input.jurisdiction,
+      nowIso(),
+      input.diffSummary,
+      input.riskLevel,
+      JSON.stringify(input.proposedRuleVersionIds)
+    ]);
+    return { id };
+  }
+  async function createReviewTask(input) {
+    const candResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [input.changeCandidateId]);
+    const candidate = candResult.rows[0];
+    if (!candidate)
+      throw new Error("CHANGE_CANDIDATE_NOT_FOUND");
+    const assignedRole = candidate.riskLevel === "high" ? "expert" : "curator";
+    const id = generateId("psa_review");
+    await db.execute(`INSERT INTO psa_review_task (id, "changeCandidateId", status, "assignedRole", decision, "decidedAt", "decidedBy")
+       VALUES ($1, $2, $3, $4, $5, $6, $7)`, [id, input.changeCandidateId, "open", assignedRole, null, null, null]);
+    return { id, assignedRole };
+  }
+  async function submitDecision(input) {
+    const reviewResult = await db.query(`SELECT * FROM psa_review_task WHERE id = $1 LIMIT 1`, [input.reviewTaskId]);
+    const task = reviewResult.rows[0];
+    if (!task)
+      throw new Error("REVIEW_TASK_NOT_FOUND");
+    const candidateResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [task.changeCandidateId]);
+    const candidate = candidateResult.rows[0];
+    if (!candidate)
+      throw new Error("CHANGE_CANDIDATE_NOT_FOUND");
+    if (candidate.riskLevel === "high" && input.decision === "approve" && input.decidedByRole !== "expert") {
+      throw new Error("FORBIDDEN_ROLE");
+    }
+    const decidedAt = nowIso();
+    await db.execute(`UPDATE psa_review_task SET status = $1, decision = $2, "decidedAt" = $3, "decidedBy" = $4 WHERE id = $5`, [
+      "decided",
+      input.decision,
+      decidedAt,
+      input.decidedBy,
+      input.reviewTaskId
+    ]);
+    return { id: input.reviewTaskId, status: "decided" };
+  }
+  async function publishIfReady(input) {
+    const openResult = await db.query(`SELECT COUNT(*) as count FROM psa_review_task WHERE status != 'decided'`, []);
+    const openCount = Number(openResult.rows[0]?.count ?? 0);
+    if (openCount > 0)
+      throw new Error("NOT_READY");
+    const decidedResult = await db.query(`SELECT * FROM psa_review_task`, []);
+    for (const row of decidedResult.rows) {
+      if (row.decision !== "approve")
+        continue;
+      const candQueryResult = await db.query(`SELECT * FROM psa_change_candidate WHERE id = $1 LIMIT 1`, [row.changeCandidateId]);
+      const cand = candQueryResult.rows[0];
+      if (!cand)
+        continue;
+      if (cand.jurisdiction !== input.jurisdiction)
+        continue;
+      const proposedIds = parseJsonArray(cand.proposedRuleVersionIdsJson);
+      for (const rvId of proposedIds) {
+        const rvQueryResult = await db.query(`SELECT status FROM psa_rule_version WHERE id = $1 LIMIT 1`, [rvId]);
+        const status = String(rvQueryResult.rows[0]?.status ?? "");
+        if (status !== "approved")
+          throw new Error("NOT_READY");
+      }
+    }
+    return { published: true };
+  }
+  return {
+    getUserContext,
+    setUserContext,
+    createRule,
+    upsertRuleVersion,
+    approveRuleVersion,
+    publishSnapshot,
+    searchKb,
+    answer,
+    createChangeCandidate,
+    createReviewTask,
+    submitDecision,
+    publishIfReady
+  };
+}
+export {
+  createPolicySafeKnowledgeAssistantHandlers
+};