@contractspec/example.knowledge-canon 1.56.1 → 1.58.0

package/dist/index.js

@@ -1,8 +1,192 @@
-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 };
+// @bun
+// src/agent.ts
+function selectKnowledgeBindings(resolved, options) {
+  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;
+  });
+}
+async function answerWithKnowledge(resolved, question, { workflowId, agentId }) {
+  const bindings = selectKnowledgeBindings(resolved, { workflowId, agentId });
+  if (bindings.length === 0) {
+    return "No knowledge space available for this request.";
+  }
+  const summaries = bindings.map(({ space }) => `\u2022 ${space.meta.title || space.meta.description}`);
+  return [
+    `Q: ${question}`,
+    "Routed to knowledge spaces:",
+    ...summaries,
+    "",
+    "TODO: invoke knowledge search service and synthesize response."
+  ].join(`
+`);
+}
+
+// src/blueprint.ts
+import {
+  OwnersEnum,
+  StabilityEnum,
+  TagsEnum
+} from "@contractspec/lib.contracts/ownership";
+var artisanKnowledgeBlueprint = {
+  meta: {
+    key: "artisan.knowledge.product",
+    version: "1.0.0",
+    appId: "artisan",
+    title: "ArtisanOS Knowledge \u2013 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."
+};
+
+// src/docs/knowledge-canon.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    id: "docs.examples.knowledge-canon",
+    title: "Knowledge Example \u2014 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
+- Blueprint referencing a workflow depending on the Product Canon space.
+- Tenant app config binding the space to a workflow and agent scope.
+- Sample knowledge source configuration.
+- Helper to pick knowledge bindings from ResolvedAppConfig.
+
+## Guardrails
+- Keep sources scoped per tenant.
+- Keep secret fields out of config (use secret providers).
+- Enforce scope restrictions before answering.`
+  },
+  {
+    id: "docs.examples.knowledge-canon.usage",
+    title: "Knowledge Canon \u2014 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
+1) Register the knowledge space spec in your KnowledgeSpaceRegistry.
+2) Persist the source config through knowledge CRUD operations.
+3) Compose ResolvedAppConfig and pass it to your workflow/agent runtime.
+4) Use helpers like \`selectKnowledgeBindings\` before dispatching to search/embedding.
+
+## Notes
+- Avoid logging PII.
+- Keep search results auditable and cite sources.`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+
+// src/tenant.ts
+var 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."
+};
+
+// src/source.sample.ts
+var 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: new Date("2026-01-01T00:00:00.000Z"),
+    success: true,
+    itemsProcessed: 128
+  }
+};
+export {
+  selectKnowledgeBindings,
+  productCanonNotionSource,
+  example_default as example,
+  artisanKnowledgeTenantConfig,
+  artisanKnowledgeBlueprint,
+  answerWithKnowledge
+};

package/dist/node/agent.js

@@ -0,0 +1,31 @@
+// src/agent.ts
+function selectKnowledgeBindings(resolved, options) {
+  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;
+  });
+}
+async function answerWithKnowledge(resolved, question, { workflowId, agentId }) {
+  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(`
+`);
+}
+export {
+  selectKnowledgeBindings,
+  answerWithKnowledge
+};

package/dist/node/blueprint.js

@@ -0,0 +1,26 @@
+// src/blueprint.ts
+import {
+  OwnersEnum,
+  StabilityEnum,
+  TagsEnum
+} from "@contractspec/lib.contracts/ownership";
+var artisanKnowledgeBlueprint = {
+  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."
+};
+export {
+  artisanKnowledgeBlueprint
+};

package/dist/node/docs/index.js

@@ -0,0 +1,42 @@
+// src/docs/knowledge-canon.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- Blueprint referencing a workflow depending on the Product Canon space.
+- Tenant app config binding the space to a workflow and agent scope.
+- Sample knowledge source configuration.
+- Helper to pick knowledge bindings from ResolvedAppConfig.
+
+## Guardrails
+- Keep sources scoped per tenant.
+- Keep secret fields out of config (use secret providers).
+- 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
+1) Register the knowledge space spec in your KnowledgeSpaceRegistry.
+2) Persist the source config through knowledge CRUD operations.
+3) Compose ResolvedAppConfig and pass it to your workflow/agent runtime.
+4) Use helpers like \`selectKnowledgeBindings\` before dispatching to search/embedding.
+
+## Notes
+- Avoid logging PII.
+- Keep search results auditable and cite sources.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/docs/knowledge-canon.docblock.js

@@ -0,0 +1,42 @@
+// src/docs/knowledge-canon.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- Blueprint referencing a workflow depending on the Product Canon space.
+- Tenant app config binding the space to a workflow and agent scope.
+- Sample knowledge source configuration.
+- Helper to pick knowledge bindings from ResolvedAppConfig.
+
+## Guardrails
+- Keep sources scoped per tenant.
+- Keep secret fields out of config (use secret providers).
+- 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
+1) Register the knowledge space spec in your KnowledgeSpaceRegistry.
+2) Persist the source config through knowledge CRUD operations.
+3) Compose ResolvedAppConfig and pass it to your workflow/agent runtime.
+4) Use helpers like \`selectKnowledgeBindings\` before dispatching to search/embedding.
+
+## Notes
+- Avoid logging PII.
+- Keep search results auditable and cite sources.`
+  }
+];
+registerDocBlocks(blocks);

package/dist/node/example.js

@@ -0,0 +1,33 @@
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+export {
+  example_default as default
+};

package/dist/node/index.js

@@ -0,0 +1,191 @@
+// src/agent.ts
+function selectKnowledgeBindings(resolved, options) {
+  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;
+  });
+}
+async function answerWithKnowledge(resolved, question, { workflowId, agentId }) {
+  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(`
+`);
+}
+
+// src/blueprint.ts
+import {
+  OwnersEnum,
+  StabilityEnum,
+  TagsEnum
+} from "@contractspec/lib.contracts/ownership";
+var artisanKnowledgeBlueprint = {
+  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."
+};
+
+// src/docs/knowledge-canon.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts/docs";
+var blocks = [
+  {
+    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
+- Blueprint referencing a workflow depending on the Product Canon space.
+- Tenant app config binding the space to a workflow and agent scope.
+- Sample knowledge source configuration.
+- Helper to pick knowledge bindings from ResolvedAppConfig.
+
+## Guardrails
+- Keep sources scoped per tenant.
+- Keep secret fields out of config (use secret providers).
+- 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
+1) Register the knowledge space spec in your KnowledgeSpaceRegistry.
+2) Persist the source config through knowledge CRUD operations.
+3) Compose ResolvedAppConfig and pass it to your workflow/agent runtime.
+4) Use helpers like \`selectKnowledgeBindings\` before dispatching to search/embedding.
+
+## Notes
+- Avoid logging PII.
+- Keep search results auditable and cite sources.`
+  }
+];
+registerDocBlocks(blocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var 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 }
+  }
+});
+var example_default = example;
+
+// src/tenant.ts
+var 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."
+};
+
+// src/source.sample.ts
+var 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: new Date("2026-01-01T00:00:00.000Z"),
+    success: true,
+    itemsProcessed: 128
+  }
+};
+export {
+  selectKnowledgeBindings,
+  productCanonNotionSource,
+  example_default as example,
+  artisanKnowledgeTenantConfig,
+  artisanKnowledgeBlueprint,
+  answerWithKnowledge
+};

package/dist/node/source.sample.js

@@ -0,0 +1,29 @@
+// src/source.sample.ts
+var 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: new Date("2026-01-01T00:00:00.000Z"),
+    success: true,
+    itemsProcessed: 128
+  }
+};
+export {
+  productCanonNotionSource
+};

package/dist/node/tenant.js

@@ -0,0 +1,34 @@
+// src/tenant.ts
+var 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."
+};
+export {
+  artisanKnowledgeTenantConfig
+};

package/dist/source.sample.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"source.sample.d.ts","names":[],"sources":["../src/source.sample.ts"],"sourcesContent":[],"mappings":";;;cAEa,0BAA0B"}
+{"version":3,"file":"source.sample.d.ts","sourceRoot":"","sources":["../src/source.sample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AAE1F,eAAO,MAAM,wBAAwB,EAAE,qBAwBtC,CAAC"}