@contractspec/example.knowledge-canon 0.0.0-canary-20260113162409

package/dist/index.js

@@ -0,0 +1,8 @@
+import { answerWithKnowledge, selectKnowledgeBindings } from "./agent.js";
+import { artisanKnowledgeBlueprint } from "./blueprint.js";
+import example_default from "./example.js";
+import { artisanKnowledgeTenantConfig } from "./tenant.js";
+import { productCanonNotionSource } from "./source.sample.js";
+import "./docs/index.js";
+
+export { answerWithKnowledge, artisanKnowledgeBlueprint, artisanKnowledgeTenantConfig, example_default as example, productCanonNotionSource, selectKnowledgeBindings };

package/dist/source.sample.d.ts

@@ -0,0 +1,7 @@
+import { KnowledgeSourceConfig } from "@contractspec/lib.contracts/knowledge/source";
+
+//#region src/source.sample.d.ts
+declare const productCanonNotionSource: KnowledgeSourceConfig;
+//#endregion
+export { productCanonNotionSource };
+//# sourceMappingURL=source.sample.d.ts.map

package/dist/source.sample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.sample.d.ts","names":[],"sources":["../src/source.sample.ts"],"sourcesContent":[],"mappings":";;;cAEa,0BAA0B"}

package/dist/source.sample.js

@@ -0,0 +1,30 @@
+//#region src/source.sample.ts
+const productCanonNotionSource = {
+	meta: {
+		id: "source-canon-notion",
+		tenantId: "artisan-co",
+		spaceKey: "knowledge.product-canon",
+		spaceVersion: "1.0.0",
+		label: "Product Canon (Notion)",
+		sourceType: "notion",
+		createdAt: "2026-01-01T00:00:00.000Z",
+		updatedAt: "2026-01-01T00:00:00.000Z"
+	},
+	config: {
+		notionDatabaseId: "xxxxxxxxxxxxxxxx",
+		apiKey: "secret_notion_token"
+	},
+	syncSchedule: {
+		enabled: true,
+		cron: "0 * * * *"
+	},
+	lastSync: {
+		timestamp: /* @__PURE__ */ new Date("2026-01-01T00:00:00.000Z"),
+		success: true,
+		itemsProcessed: 128
+	}
+};
+
+//#endregion
+export { productCanonNotionSource };
+//# sourceMappingURL=source.sample.js.map

package/dist/source.sample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.sample.js","names":[],"sources":["../src/source.sample.ts"],"sourcesContent":["import type { KnowledgeSourceConfig } from '@contractspec/lib.contracts/knowledge/source';\n\nexport const productCanonNotionSource: KnowledgeSourceConfig = {\n  meta: {\n    id: 'source-canon-notion',\n    tenantId: 'artisan-co',\n    spaceKey: 'knowledge.product-canon',\n    spaceVersion: '1.0.0',\n    label: 'Product Canon (Notion)',\n    sourceType: 'notion',\n    createdAt: '2026-01-01T00:00:00.000Z',\n    updatedAt: '2026-01-01T00:00:00.000Z',\n  },\n  config: {\n    notionDatabaseId: 'xxxxxxxxxxxxxxxx',\n    apiKey: 'secret_notion_token',\n  },\n  syncSchedule: {\n    enabled: true,\n    cron: '0 * * * *',\n  },\n  lastSync: {\n    timestamp: new Date('2026-01-01T00:00:00.000Z'),\n    success: true,\n    itemsProcessed: 128,\n  },\n};\n"],"mappings":";AAEA,MAAa,2BAAkD;CAC7D,MAAM;EACJ,IAAI;EACJ,UAAU;EACV,UAAU;EACV,cAAc;EACd,OAAO;EACP,YAAY;EACZ,WAAW;EACX,WAAW;EACZ;CACD,QAAQ;EACN,kBAAkB;EAClB,QAAQ;EACT;CACD,cAAc;EACZ,SAAS;EACT,MAAM;EACP;CACD,UAAU;EACR,2BAAW,IAAI,KAAK,2BAA2B;EAC/C,SAAS;EACT,gBAAgB;EACjB;CACF"}

package/dist/tenant.d.ts

@@ -0,0 +1,7 @@
+import { TenantAppConfig } from "@contractspec/lib.contracts/app-config/spec";
+
+//#region src/tenant.d.ts
+declare const artisanKnowledgeTenantConfig: TenantAppConfig;
+//#endregion
+export { artisanKnowledgeTenantConfig };
+//# sourceMappingURL=tenant.d.ts.map

package/dist/tenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.d.ts","names":[],"sources":["../src/tenant.ts"],"sourcesContent":[],"mappings":";;;cAEa,8BAA8B"}

package/dist/tenant.js

@@ -0,0 +1,33 @@
+//#region src/tenant.ts
+const artisanKnowledgeTenantConfig = {
+	meta: {
+		id: "tenant-config-artisan-knowledge",
+		tenantId: "artisan-co",
+		appId: "artisan",
+		blueprintName: "artisan.knowledge.product",
+		blueprintVersion: "1.0.0",
+		environment: "production",
+		version: "1.0.0",
+		status: "published",
+		createdAt: "2026-01-01T00:00:00.000Z",
+		updatedAt: "2026-01-01T00:00:00.000Z"
+	},
+	knowledge: [{
+		spaceKey: "knowledge.product-canon",
+		spaceVersion: "1.0.0",
+		scope: {
+			workflows: ["answerFaq"],
+			agents: ["productSupportAssistant"]
+		},
+		constraints: {
+			maxTokensPerQuery: 4096,
+			maxQueriesPerMinute: 30
+		}
+	}],
+	integrations: [],
+	notes: "Product Canon knowledge space bound for production assistants."
+};
+
+//#endregion
+export { artisanKnowledgeTenantConfig };
+//# sourceMappingURL=tenant.js.map

package/dist/tenant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.js","names":[],"sources":["../src/tenant.ts"],"sourcesContent":["import type { TenantAppConfig } from '@contractspec/lib.contracts/app-config/spec';\n\nexport const artisanKnowledgeTenantConfig: TenantAppConfig = {\n  meta: {\n    id: 'tenant-config-artisan-knowledge',\n    tenantId: 'artisan-co',\n    appId: 'artisan',\n    blueprintName: 'artisan.knowledge.product',\n    blueprintVersion: '1.0.0',\n    environment: 'production',\n    version: '1.0.0',\n    status: 'published',\n    createdAt: '2026-01-01T00:00:00.000Z',\n    updatedAt: '2026-01-01T00:00:00.000Z',\n  },\n  knowledge: [\n    {\n      spaceKey: 'knowledge.product-canon',\n      spaceVersion: '1.0.0',\n      scope: {\n        workflows: ['answerFaq'],\n        agents: ['productSupportAssistant'],\n      },\n      constraints: {\n        maxTokensPerQuery: 4096,\n        maxQueriesPerMinute: 30,\n      },\n    },\n  ],\n  integrations: [],\n  notes: 'Product Canon knowledge space bound for production assistants.',\n};\n"],"mappings":";AAEA,MAAa,+BAAgD;CAC3D,MAAM;EACJ,IAAI;EACJ,UAAU;EACV,OAAO;EACP,eAAe;EACf,kBAAkB;EAClB,aAAa;EACb,SAAS;EACT,QAAQ;EACR,WAAW;EACX,WAAW;EACZ;CACD,WAAW,CACT;EACE,UAAU;EACV,cAAc;EACd,OAAO;GACL,WAAW,CAAC,YAAY;GACxB,QAAQ,CAAC,0BAA0B;GACpC;EACD,aAAa;GACX,mBAAmB;GACnB,qBAAqB;GACtB;EACF,CACF;CACD,cAAc,EAAE;CAChB,OAAO;CACR"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@contractspec/example.knowledge-canon",
+  "version": "0.0.0-canary-20260113162409",
+  "description": "Knowledge example – Product Canon space (blueprint + tenant config + source sample + runtime helper).",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./agent": "./dist/agent.js",
+    "./blueprint": "./dist/blueprint.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/knowledge-canon.docblock": "./dist/docs/knowledge-canon.docblock.js",
+    "./example": "./dist/example.js",
+    "./source.sample": "./dist/source.sample.js",
+    "./tenant": "./dist/tenant.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/lib.contracts": "0.0.0-canary-20260113162409"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "0.0.0-canary-20260113162409",
+    "@contractspec/tool.typescript": "0.0.0-canary-20260113162409",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./agent": "./dist/agent.js",
+      "./blueprint": "./dist/blueprint.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/knowledge-canon.docblock": "./dist/docs/knowledge-canon.docblock.js",
+      "./example": "./dist/example.js",
+      "./source.sample": "./dist/source.sample.js",
+      "./tenant": "./dist/tenant.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/knowledge-canon"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/agent.ts

@@ -0,0 +1,47 @@
+import type { ResolvedAppConfig } from '@contractspec/lib.contracts/app-config/runtime';
+
+/**
+ * Selects knowledge bindings that apply to a workflow or agent identifier.
+ */
+export function selectKnowledgeBindings(
+  resolved: ResolvedAppConfig,
+  options: { workflowId?: string; agentId?: string }
+) {
+  return resolved.knowledge.filter(({ binding }) => {
+    if (!binding.scope) return true;
+    if (
+      options.workflowId &&
+      binding.scope.workflows?.includes(options.workflowId)
+    )
+      return true;
+    if (options.agentId && binding.scope.agents?.includes(options.agentId))
+      return true;
+    return false;
+  });
+}
+
+/**
+ * Pseudo implementation of an assistant lookup that routes prompts to the appropriate
+ * knowledge sources. In a real system this would call the ingestion/search services.
+ */
+export async function answerWithKnowledge(
+  resolved: ResolvedAppConfig,
+  question: string,
+  { workflowId, agentId }: { workflowId?: string; agentId?: string }
+): Promise<string> {
+  const bindings = selectKnowledgeBindings(resolved, { workflowId, agentId });
+  if (bindings.length === 0) {
+    return 'No knowledge space available for this request.';
+  }
+
+  const summaries = bindings.map(
+    ({ space }) => `• ${space.meta.title || space.meta.description}`
+  );
+  return [
+    `Q: ${question}`,
+    'Routed to knowledge spaces:',
+    ...summaries,
+    '',
+    'TODO: invoke knowledge search service and synthesize response.',
+  ].join('\n');
+}

package/src/blueprint.ts

@@ -0,0 +1,26 @@
+import type { AppBlueprintSpec } from '@contractspec/lib.contracts/app-config/spec';
+import {
+  OwnersEnum,
+  StabilityEnum,
+  TagsEnum,
+} from '@contractspec/lib.contracts/ownership';
+
+export const artisanKnowledgeBlueprint: AppBlueprintSpec = {
+  meta: {
+    key: 'artisan.knowledge.product',
+    version: '1.0.0',
+    appId: 'artisan',
+    title: 'ArtisanOS Knowledge – Product Canon',
+    description:
+      'Blueprint that surfaces canonical product knowledge to agents and workflows.',
+    domain: 'knowledge',
+    owners: [OwnersEnum.PlatformContent],
+    tags: ['knowledge', 'product-canon', TagsEnum.Guide],
+    stability: StabilityEnum.Experimental,
+  },
+  workflows: {
+    answerFaq: { key: 'artisan.knowledge.answerFaq', version: '1.0.0' },
+  },
+  notes:
+    'Workflows and assistants running on this blueprint should bind the Product Canon knowledge space.',
+};

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './knowledge-canon.docblock';

package/src/docs/knowledge-canon.docblock.ts

@@ -0,0 +1,29 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.knowledge-canon',
+    title: 'Knowledge Example — Product Canon Space',
+    summary:
+      'Bind the Product Canon KnowledgeSpaceSpec to a tenant and expose it to agents/workflows via ResolvedAppConfig.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/knowledge-canon',
+    tags: ['knowledge', 'canon', 'example'],
+    body: `## Included assets\n- Blueprint referencing a workflow depending on the Product Canon space.\n- Tenant app config binding the space to a workflow and agent scope.\n- Sample knowledge source configuration.\n- Helper to pick knowledge bindings from ResolvedAppConfig.\n\n## Guardrails\n- Keep sources scoped per tenant.\n- Keep secret fields out of config (use secret providers).\n- Enforce scope restrictions before answering.`,
+  },
+  {
+    id: 'docs.examples.knowledge-canon.usage',
+    title: 'Knowledge Canon — Usage',
+    summary:
+      'How to register the space, configure sources, and route requests.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/knowledge-canon/usage',
+    tags: ['knowledge', 'usage'],
+    body: `## Usage\n1) Register the knowledge space spec in your KnowledgeSpaceRegistry.\n2) Persist the source config through knowledge CRUD operations.\n3) Compose ResolvedAppConfig and pass it to your workflow/agent runtime.\n4) Use helpers like \`selectKnowledgeBindings\` before dispatching to search/embedding.\n\n## Notes\n- Avoid logging PII.\n- Keep search results auditable and cite sources.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'knowledge-canon',
+    version: '1.0.0',
+    title: 'Knowledge Canon (Product Canon space)',
+    description:
+      'Bind a canonical knowledge space to a tenant and route assistant/workflow requests to the right sources (blueprint + app config pattern).',
+    kind: 'knowledge',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['knowledge', 'canon', 'app-config', 'agents', 'workflows'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.knowledge-canon',
+    usageDocId: 'docs.examples.knowledge-canon.usage',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.knowledge-canon',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './agent';
+export * from './blueprint';
+export * from './tenant';
+export * from './source.sample';
+export { default as example } from './example';
+import './docs';

package/src/source.sample.ts

@@ -0,0 +1,27 @@
+import type { KnowledgeSourceConfig } from '@contractspec/lib.contracts/knowledge/source';
+
+export const productCanonNotionSource: KnowledgeSourceConfig = {
+  meta: {
+    id: 'source-canon-notion',
+    tenantId: 'artisan-co',
+    spaceKey: 'knowledge.product-canon',
+    spaceVersion: '1.0.0',
+    label: 'Product Canon (Notion)',
+    sourceType: 'notion',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+  config: {
+    notionDatabaseId: 'xxxxxxxxxxxxxxxx',
+    apiKey: 'secret_notion_token',
+  },
+  syncSchedule: {
+    enabled: true,
+    cron: '0 * * * *',
+  },
+  lastSync: {
+    timestamp: new Date('2026-01-01T00:00:00.000Z'),
+    success: true,
+    itemsProcessed: 128,
+  },
+};

package/src/tenant.ts

@@ -0,0 +1,32 @@
+import type { TenantAppConfig } from '@contractspec/lib.contracts/app-config/spec';
+
+export const artisanKnowledgeTenantConfig: TenantAppConfig = {
+  meta: {
+    id: 'tenant-config-artisan-knowledge',
+    tenantId: 'artisan-co',
+    appId: 'artisan',
+    blueprintName: 'artisan.knowledge.product',
+    blueprintVersion: '1.0.0',
+    environment: 'production',
+    version: '1.0.0',
+    status: 'published',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+  },
+  knowledge: [
+    {
+      spaceKey: 'knowledge.product-canon',
+      spaceVersion: '1.0.0',
+      scope: {
+        workflows: ['answerFaq'],
+        agents: ['productSupportAssistant'],
+      },
+      constraints: {
+        maxTokensPerQuery: 4096,
+        maxQueriesPerMinute: 30,
+      },
+    },
+  ],
+  integrations: [],
+  notes: 'Product Canon knowledge space bound for production assistants.',
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}
+
+