@gentorial/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gentorial contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# `@gentorial/core`
+
+Gentorial 的框架无关协议层，包含课程定义、概念锚点、章节范围、学习者偏好、生成指令、受控课程块、诊断和插件接口。
+
+该包可同时在 Node.js 与浏览器中使用。它不会访问文件系统、发起网络请求，也不依赖 Vue、VitePress 或任何模型 SDK。
+
+```ts
+import { defineCourse } from '@gentorial/core'
+
+export default defineCourse({
+  schemaVersion: '1',
+  id: 'c-language',
+  title: 'C 语言教程',
+  lang: 'zh-CN',
+  contentDir: 'content',
+  generation: {
+    mode: 'hybrid',
+    defaultLocale: 'zh-CN'
+  },
+  accuracy: {
+    standards: ['ISO C17'],
+    policies: ['概念锚点的结论不可被反转']
+  }
+})
+```
+
+一次生成会分别记录作者限定的 `scope`、标题触发器、`after-source` 输出目标和学习者表达偏好。生成结果必须在 `grounding.sourceIds` 中声明对应章节来源；概念锚点仍通过 `grounding.conceptIds` 独立校验。
+
+`LessonConversationTurn` 用于记录结果上的深入问答。学习者消息是非空的 `content`，助手消息始终保存完整、可校验的 `GeneratedLesson`，因此后续回答与初始结果使用同一套安全输出协议。

package/dist/course.d.ts

@@ -0,0 +1,2 @@
+import type { CourseDefinition } from './types.js';
+export declare function defineCourse<const T extends CourseDefinition>(definition: T): T;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defineCourse } from './course.js';
+export type { GentorialPlugin, PromptExtensionContext, PromptFragment, TransformContext, ValidationContext } from './plugin.js';
+export { calloutBlockSchema, codeBlockSchema, comparisonBlockSchema, conceptSpecSchema, courseDefinitionSchema, courseManifestSchema, generatedLessonSchema, generateOutputSchema, generateSpecSchema, generateTriggerSchema, headingBlockSchema, learnerProfileSchema, lessonConversationTurnSchema, lessonBlockSchema, listBlockSchema, paragraphBlockSchema, sectionScopeSchema, sourceLocationSchema, validationDiagnosticSchema } from './schemas.js';
+export type { CalloutBlock, CodeBlock, ComparisonBlock, ConceptSpec, CourseDefinition, CourseManifest, GeneratedLesson, GenerateOutput, GenerateSpec, GenerateTrigger, HeadingBlock, LearnerProfile, LessonConversationTurn, LessonBlock, ListBlock, ParagraphBlock, SectionScope, SourceLocation, ValidationDiagnostic } from './types.js';

package/dist/index.js

@@ -0,0 +1,186 @@
+// src/schemas.ts
+import { z } from "zod";
+var nonBlankString = z.string().min(1).refine((value) => value.trim().length > 0, {
+  message: "Must not be blank"
+});
+var idSchema = z.string().min(1).regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i, "Invalid stable identifier");
+var sourceLocationSchema = z.object({
+  file: nonBlankString,
+  line: z.number().int().positive(),
+  column: z.number().int().positive().optional()
+}).strict();
+var validationDiagnosticSchema = z.object({
+  severity: z.enum(["error", "warning", "info"]),
+  code: nonBlankString,
+  message: nonBlankString,
+  source: sourceLocationSchema.optional(),
+  path: z.array(z.union([z.string(), z.number().int().nonnegative()])).optional()
+}).strict();
+var pluginSchema = z.custom(
+  (value) => typeof value === "object" && value !== null && typeof Reflect.get(value, "name") === "string" && typeof Reflect.get(value, "version") === "string",
+  "Invalid Gentorial plugin"
+);
+var courseDefinitionSchema = z.object({
+  schemaVersion: z.literal("1"),
+  id: idSchema,
+  title: nonBlankString,
+  description: nonBlankString.optional(),
+  lang: nonBlankString,
+  contentDir: nonBlankString,
+  generation: z.object({
+    mode: z.enum(["snapshot", "on-demand", "hybrid"]),
+    defaultLocale: nonBlankString
+  }).strict(),
+  accuracy: z.object({
+    policies: z.array(nonBlankString),
+    standards: z.array(nonBlankString).optional()
+  }).strict(),
+  plugins: z.array(pluginSchema).optional()
+}).strict();
+var conceptSpecSchema = z.object({
+  id: idSchema,
+  title: nonBlankString.optional(),
+  statement: nonBlankString,
+  source: sourceLocationSchema
+}).strict();
+var learnerProfileSchema = z.object({
+  locale: nonBlankString.optional(),
+  background: nonBlankString.optional(),
+  goal: nonBlankString.optional(),
+  detail: z.enum(["concise", "balanced", "deep"]).optional(),
+  tone: z.enum(["neutral", "conversational", "formal"]).optional(),
+  narrative: z.enum(["direct", "story", "timeline", "comparison"]).optional(),
+  examplePreferences: z.array(nonBlankString).min(1).optional()
+}).strict();
+var sectionScopeSchema = z.object({
+  type: z.literal("section"),
+  id: idSchema,
+  heading: nonBlankString,
+  level: z.number().int().min(1).max(6),
+  markdown: nonBlankString,
+  source: sourceLocationSchema
+}).strict();
+var generateTriggerSchema = z.object({
+  type: z.literal("heading"),
+  source: sourceLocationSchema
+}).strict();
+var generateOutputSchema = z.object({
+  placement: z.literal("after-source"),
+  mode: z.literal("replace")
+}).strict();
+var generateSpecSchema = z.object({
+  id: idSchema,
+  kind: z.enum(["explanation", "example", "comparison", "exercise", "feedback"]),
+  prompt: nonBlankString,
+  concepts: z.array(idSchema),
+  scope: sectionScopeSchema,
+  trigger: generateTriggerSchema,
+  output: generateOutputSchema,
+  source: sourceLocationSchema
+}).strict();
+var paragraphBlockSchema = z.object({
+  type: z.literal("paragraph"),
+  text: nonBlankString
+}).strict();
+var headingBlockSchema = z.object({
+  type: z.literal("heading"),
+  level: z.union([z.literal(2), z.literal(3), z.literal(4)]),
+  text: nonBlankString
+}).strict();
+var listBlockSchema = z.object({
+  type: z.literal("list"),
+  ordered: z.boolean(),
+  items: z.array(nonBlankString).min(1)
+}).strict();
+var codeBlockSchema = z.object({
+  type: z.literal("code"),
+  code: nonBlankString,
+  language: nonBlankString.optional(),
+  caption: nonBlankString.optional()
+}).strict();
+var calloutBlockSchema = z.object({
+  type: z.literal("callout"),
+  tone: z.enum(["info", "tip", "warning", "danger"]),
+  title: nonBlankString.optional(),
+  text: nonBlankString
+}).strict();
+var comparisonSideSchema = z.object({
+  title: nonBlankString,
+  items: z.array(nonBlankString).min(1)
+}).strict();
+var comparisonBlockSchema = z.object({
+  type: z.literal("comparison"),
+  left: comparisonSideSchema,
+  right: comparisonSideSchema
+}).strict();
+var lessonBlockSchema = z.discriminatedUnion("type", [
+  paragraphBlockSchema,
+  headingBlockSchema,
+  listBlockSchema,
+  codeBlockSchema,
+  calloutBlockSchema,
+  comparisonBlockSchema
+]);
+var generatedLessonSchema = z.object({
+  schemaVersion: z.literal("1"),
+  title: nonBlankString.optional(),
+  blocks: z.array(lessonBlockSchema).min(1),
+  grounding: z.object({
+    conceptIds: z.array(idSchema),
+    sourceIds: z.array(idSchema),
+    notes: z.array(nonBlankString).optional()
+  }).strict()
+}).strict();
+var lessonConversationTurnSchema = z.discriminatedUnion("role", [
+  z.object({
+    role: z.literal("user"),
+    content: nonBlankString
+  }).strict(),
+  z.object({
+    role: z.literal("assistant"),
+    lesson: generatedLessonSchema
+  }).strict()
+]);
+var manifestCourseSchema = courseDefinitionSchema.omit({ plugins: true }).extend({
+  plugins: z.array(
+    z.object({
+      name: nonBlankString,
+      version: nonBlankString
+    }).strict()
+  ).optional()
+}).strict();
+var courseManifestSchema = z.object({
+  schemaVersion: z.literal("1"),
+  course: manifestCourseSchema,
+  concepts: z.array(conceptSpecSchema),
+  generates: z.array(generateSpecSchema),
+  contentHash: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+
+// src/course.ts
+function defineCourse(definition) {
+  return courseDefinitionSchema.parse(definition);
+}
+export {
+  calloutBlockSchema,
+  codeBlockSchema,
+  comparisonBlockSchema,
+  conceptSpecSchema,
+  courseDefinitionSchema,
+  courseManifestSchema,
+  defineCourse,
+  generateOutputSchema,
+  generateSpecSchema,
+  generateTriggerSchema,
+  generatedLessonSchema,
+  headingBlockSchema,
+  learnerProfileSchema,
+  lessonBlockSchema,
+  lessonConversationTurnSchema,
+  listBlockSchema,
+  paragraphBlockSchema,
+  sectionScopeSchema,
+  sourceLocationSchema,
+  validationDiagnosticSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemas.ts","../src/course.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { GentorialPlugin } from './plugin.js'\n\nconst nonBlankString = z.string().min(1).refine((value) => value.trim().length > 0, {\n  message: 'Must not be blank'\n})\n\nconst idSchema = z\n  .string()\n  .min(1)\n  .regex(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/i, 'Invalid stable identifier')\n\nexport const sourceLocationSchema = z\n  .object({\n    file: nonBlankString,\n    line: z.number().int().positive(),\n    column: z.number().int().positive().optional()\n  })\n  .strict()\n\nexport const validationDiagnosticSchema = z\n  .object({\n    severity: z.enum(['error', 'warning', 'info']),\n    code: nonBlankString,\n    message: nonBlankString,\n    source: sourceLocationSchema.optional(),\n    path: z.array(z.union([z.string(), z.number().int().nonnegative()])).optional()\n  })\n  .strict()\n\nconst pluginSchema = z.custom<GentorialPlugin>(\n  (value) =>\n    typeof value === 'object' &&\n    value !== null &&\n    typeof Reflect.get(value, 'name') === 'string' &&\n    typeof Reflect.get(value, 'version') === 'string',\n  'Invalid Gentorial plugin'\n)\n\nexport const courseDefinitionSchema = z\n  .object({\n    schemaVersion: z.literal('1'),\n    id: idSchema,\n    title: nonBlankString,\n    description: nonBlankString.optional(),\n    lang: nonBlankString,\n    contentDir: nonBlankString,\n    generation: z\n      .object({\n        mode: z.enum(['snapshot', 'on-demand', 'hybrid']),\n        defaultLocale: nonBlankString\n      })\n      .strict(),\n    accuracy: z\n      .object({\n        policies: z.array(nonBlankString),\n        standards: z.array(nonBlankString).optional()\n      })\n      .strict(),\n    plugins: z.array(pluginSchema).optional()\n  })\n  .strict()\n\nexport const conceptSpecSchema = z\n  .object({\n    id: idSchema,\n    title: nonBlankString.optional(),\n    statement: nonBlankString,\n    source: sourceLocationSchema\n  })\n  .strict()\n\nexport const learnerProfileSchema = z\n  .object({\n    locale: nonBlankString.optional(),\n    background: nonBlankString.optional(),\n    goal: nonBlankString.optional(),\n    detail: z.enum(['concise', 'balanced', 'deep']).optional(),\n    tone: z.enum(['neutral', 'conversational', 'formal']).optional(),\n    narrative: z.enum(['direct', 'story', 'timeline', 'comparison']).optional(),\n    examplePreferences: z.array(nonBlankString).min(1).optional()\n  })\n  .strict()\n\nexport const sectionScopeSchema = z\n  .object({\n    type: z.literal('section'),\n    id: idSchema,\n    heading: nonBlankString,\n    level: z.number().int().min(1).max(6),\n    markdown: nonBlankString,\n    source: sourceLocationSchema\n  })\n  .strict()\n\nexport const generateTriggerSchema = z\n  .object({\n    type: z.literal('heading'),\n    source: sourceLocationSchema\n  })\n  .strict()\n\nexport const generateOutputSchema = z\n  .object({\n    placement: z.literal('after-source'),\n    mode: z.literal('replace')\n  })\n  .strict()\n\nexport const generateSpecSchema = z\n  .object({\n    id: idSchema,\n    kind: z.enum(['explanation', 'example', 'comparison', 'exercise', 'feedback']),\n    prompt: nonBlankString,\n    concepts: z.array(idSchema),\n    scope: sectionScopeSchema,\n    trigger: generateTriggerSchema,\n    output: generateOutputSchema,\n    source: sourceLocationSchema\n  })\n  .strict()\n\nexport const paragraphBlockSchema = z\n  .object({\n    type: z.literal('paragraph'),\n    text: nonBlankString\n  })\n  .strict()\n\nexport const headingBlockSchema = z\n  .object({\n    type: z.literal('heading'),\n    level: z.union([z.literal(2), z.literal(3), z.literal(4)]),\n    text: nonBlankString\n  })\n  .strict()\n\nexport const listBlockSchema = z\n  .object({\n    type: z.literal('list'),\n    ordered: z.boolean(),\n    items: z.array(nonBlankString).min(1)\n  })\n  .strict()\n\nexport const codeBlockSchema = z\n  .object({\n    type: z.literal('code'),\n    code: nonBlankString,\n    language: nonBlankString.optional(),\n    caption: nonBlankString.optional()\n  })\n  .strict()\n\nexport const calloutBlockSchema = z\n  .object({\n    type: z.literal('callout'),\n    tone: z.enum(['info', 'tip', 'warning', 'danger']),\n    title: nonBlankString.optional(),\n    text: nonBlankString\n  })\n  .strict()\n\nconst comparisonSideSchema = z\n  .object({\n    title: nonBlankString,\n    items: z.array(nonBlankString).min(1)\n  })\n  .strict()\n\nexport const comparisonBlockSchema = z\n  .object({\n    type: z.literal('comparison'),\n    left: comparisonSideSchema,\n    right: comparisonSideSchema\n  })\n  .strict()\n\nexport const lessonBlockSchema = z.discriminatedUnion('type', [\n  paragraphBlockSchema,\n  headingBlockSchema,\n  listBlockSchema,\n  codeBlockSchema,\n  calloutBlockSchema,\n  comparisonBlockSchema\n])\n\nexport const generatedLessonSchema = z\n  .object({\n    schemaVersion: z.literal('1'),\n    title: nonBlankString.optional(),\n    blocks: z.array(lessonBlockSchema).min(1),\n    grounding: z\n      .object({\n        conceptIds: z.array(idSchema),\n        sourceIds: z.array(idSchema),\n        notes: z.array(nonBlankString).optional()\n      })\n      .strict()\n  })\n  .strict()\n\nexport const lessonConversationTurnSchema = z.discriminatedUnion('role', [\n  z\n    .object({\n      role: z.literal('user'),\n      content: nonBlankString\n    })\n    .strict(),\n  z\n    .object({\n      role: z.literal('assistant'),\n      lesson: generatedLessonSchema\n    })\n    .strict()\n])\n\nconst manifestCourseSchema = courseDefinitionSchema\n  .omit({ plugins: true })\n  .extend({\n    plugins: z\n      .array(\n        z\n          .object({\n            name: nonBlankString,\n            version: nonBlankString\n          })\n          .strict()\n      )\n      .optional()\n  })\n  .strict()\n\nexport const courseManifestSchema = z\n  .object({\n    schemaVersion: z.literal('1'),\n    course: manifestCourseSchema,\n    concepts: z.array(conceptSpecSchema),\n    generates: z.array(generateSpecSchema),\n    contentHash: z.string().regex(/^[a-f0-9]{64}$/)\n  })\n  .strict()\n","import { courseDefinitionSchema } from './schemas.js'\nimport type { CourseDefinition } from './types.js'\n\nexport function defineCourse<const T extends CourseDefinition>(definition: T): T {\n  return courseDefinitionSchema.parse(definition) as T\n}\n"],"mappings":"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","names":[]}

package/dist/plugin.d.ts

@@ -0,0 +1,21 @@
+import type { ConceptSpec, CourseDefinition, GeneratedLesson, GenerateSpec, LessonBlock, ValidationDiagnostic } from './types.js';
+export type PromptFragment = {
+    role: 'system' | 'user';
+    text: string;
+};
+export type PromptExtensionContext = {
+    course: CourseDefinition;
+    generate: GenerateSpec;
+    concepts: ConceptSpec[];
+};
+export type ValidationContext = PromptExtensionContext & {
+    lesson: GeneratedLesson;
+};
+export type TransformContext = ValidationContext;
+export interface GentorialPlugin {
+    name: string;
+    version: string;
+    extendPrompt?(context: PromptExtensionContext): PromptFragment[] | Promise<PromptFragment[]>;
+    validate?(context: ValidationContext): ValidationDiagnostic[] | Promise<ValidationDiagnostic[]>;
+    transformBlocks?(context: TransformContext): LessonBlock[] | Promise<LessonBlock[]>;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,396 @@
+import { z } from 'zod';
+import type { GentorialPlugin } from './plugin.js';
+export declare const sourceLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const validationDiagnosticSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warning: "warning";
+    }>;
+    code: z.ZodString;
+    message: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    path: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strict>;
+export declare const courseDefinitionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    lang: z.ZodString;
+    contentDir: z.ZodString;
+    generation: z.ZodObject<{
+        mode: z.ZodEnum<{
+            hybrid: "hybrid";
+            "on-demand": "on-demand";
+            snapshot: "snapshot";
+        }>;
+        defaultLocale: z.ZodString;
+    }, z.core.$strict>;
+    accuracy: z.ZodObject<{
+        policies: z.ZodArray<z.ZodString>;
+        standards: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodCustom<GentorialPlugin, GentorialPlugin>>>;
+}, z.core.$strict>;
+export declare const conceptSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    statement: z.ZodString;
+    source: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const learnerProfileSchema: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodString>;
+    goal: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodEnum<{
+        balanced: "balanced";
+        concise: "concise";
+        deep: "deep";
+    }>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        conversational: "conversational";
+        formal: "formal";
+        neutral: "neutral";
+    }>>;
+    narrative: z.ZodOptional<z.ZodEnum<{
+        comparison: "comparison";
+        direct: "direct";
+        story: "story";
+        timeline: "timeline";
+    }>>;
+    examplePreferences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const sectionScopeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"section">;
+    id: z.ZodString;
+    heading: z.ZodString;
+    level: z.ZodNumber;
+    markdown: z.ZodString;
+    source: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const generateTriggerSchema: z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    source: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const generateOutputSchema: z.ZodObject<{
+    placement: z.ZodLiteral<"after-source">;
+    mode: z.ZodLiteral<"replace">;
+}, z.core.$strict>;
+export declare const generateSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        comparison: "comparison";
+        example: "example";
+        exercise: "exercise";
+        explanation: "explanation";
+        feedback: "feedback";
+    }>;
+    prompt: z.ZodString;
+    concepts: z.ZodArray<z.ZodString>;
+    scope: z.ZodObject<{
+        type: z.ZodLiteral<"section">;
+        id: z.ZodString;
+        heading: z.ZodString;
+        level: z.ZodNumber;
+        markdown: z.ZodString;
+        source: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    trigger: z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        source: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    output: z.ZodObject<{
+        placement: z.ZodLiteral<"after-source">;
+        mode: z.ZodLiteral<"replace">;
+    }, z.core.$strict>;
+    source: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const paragraphBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"paragraph">;
+    text: z.ZodString;
+}, z.core.$strict>;
+export declare const headingBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    level: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    text: z.ZodString;
+}, z.core.$strict>;
+export declare const listBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    ordered: z.ZodBoolean;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const codeBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const calloutBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"callout">;
+    tone: z.ZodEnum<{
+        danger: "danger";
+        info: "info";
+        tip: "tip";
+        warning: "warning";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+}, z.core.$strict>;
+export declare const comparisonBlockSchema: z.ZodObject<{
+    type: z.ZodLiteral<"comparison">;
+    left: z.ZodObject<{
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    right: z.ZodObject<{
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const lessonBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"paragraph">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"heading">;
+    level: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"list">;
+    ordered: z.ZodBoolean;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"code">;
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"callout">;
+    tone: z.ZodEnum<{
+        danger: "danger";
+        info: "info";
+        tip: "tip";
+        warning: "warning";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"comparison">;
+    left: z.ZodObject<{
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    right: z.ZodObject<{
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+export declare const generatedLessonSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    title: z.ZodOptional<z.ZodString>;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"paragraph">;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"heading">;
+        level: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"list">;
+        ordered: z.ZodBoolean;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"code">;
+        code: z.ZodString;
+        language: z.ZodOptional<z.ZodString>;
+        caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"callout">;
+        tone: z.ZodEnum<{
+            danger: "danger";
+            info: "info";
+            tip: "tip";
+            warning: "warning";
+        }>;
+        title: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"comparison">;
+        left: z.ZodObject<{
+            title: z.ZodString;
+            items: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+        right: z.ZodObject<{
+            title: z.ZodString;
+            items: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>], "type">>;
+    grounding: z.ZodObject<{
+        conceptIds: z.ZodArray<z.ZodString>;
+        sourceIds: z.ZodArray<z.ZodString>;
+        notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const lessonConversationTurnSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    role: z.ZodLiteral<"assistant">;
+    lesson: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"1">;
+        title: z.ZodOptional<z.ZodString>;
+        blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"paragraph">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"heading">;
+            level: z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"list">;
+            ordered: z.ZodBoolean;
+            items: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"code">;
+            code: z.ZodString;
+            language: z.ZodOptional<z.ZodString>;
+            caption: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"callout">;
+            tone: z.ZodEnum<{
+                danger: "danger";
+                info: "info";
+                tip: "tip";
+                warning: "warning";
+            }>;
+            title: z.ZodOptional<z.ZodString>;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"comparison">;
+            left: z.ZodObject<{
+                title: z.ZodString;
+                items: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+            right: z.ZodObject<{
+                title: z.ZodString;
+                items: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "type">>;
+        grounding: z.ZodObject<{
+            conceptIds: z.ZodArray<z.ZodString>;
+            sourceIds: z.ZodArray<z.ZodString>;
+            notes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "role">;
+export declare const courseManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1">;
+    course: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"1">;
+        id: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        lang: z.ZodString;
+        contentDir: z.ZodString;
+        generation: z.ZodObject<{
+            mode: z.ZodEnum<{
+                hybrid: "hybrid";
+                "on-demand": "on-demand";
+                snapshot: "snapshot";
+            }>;
+            defaultLocale: z.ZodString;
+        }, z.core.$strict>;
+        accuracy: z.ZodObject<{
+            policies: z.ZodArray<z.ZodString>;
+            standards: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        plugins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    concepts: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        statement: z.ZodString;
+        source: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    generates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            comparison: "comparison";
+            example: "example";
+            exercise: "exercise";
+            explanation: "explanation";
+            feedback: "feedback";
+        }>;
+        prompt: z.ZodString;
+        concepts: z.ZodArray<z.ZodString>;
+        scope: z.ZodObject<{
+            type: z.ZodLiteral<"section">;
+            id: z.ZodString;
+            heading: z.ZodString;
+            level: z.ZodNumber;
+            markdown: z.ZodString;
+            source: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                column: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        trigger: z.ZodObject<{
+            type: z.ZodLiteral<"heading">;
+            source: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                column: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        output: z.ZodObject<{
+            placement: z.ZodLiteral<"after-source">;
+            mode: z.ZodLiteral<"replace">;
+        }, z.core.$strict>;
+        source: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            column: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    contentHash: z.ZodString;
+}, z.core.$strict>;

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type { z } from 'zod';
+import type { calloutBlockSchema, codeBlockSchema, comparisonBlockSchema, conceptSpecSchema, courseDefinitionSchema, courseManifestSchema, generatedLessonSchema, generateOutputSchema, generateSpecSchema, generateTriggerSchema, headingBlockSchema, learnerProfileSchema, lessonConversationTurnSchema, lessonBlockSchema, listBlockSchema, paragraphBlockSchema, sectionScopeSchema, sourceLocationSchema, validationDiagnosticSchema } from './schemas.js';
+export type SourceLocation = z.infer<typeof sourceLocationSchema>;
+export type ValidationDiagnostic = z.infer<typeof validationDiagnosticSchema>;
+export type CourseDefinition = z.infer<typeof courseDefinitionSchema>;
+export type CourseManifest = z.infer<typeof courseManifestSchema>;
+export type ConceptSpec = z.infer<typeof conceptSpecSchema>;
+export type LearnerProfile = z.infer<typeof learnerProfileSchema>;
+export type SectionScope = z.infer<typeof sectionScopeSchema>;
+export type GenerateTrigger = z.infer<typeof generateTriggerSchema>;
+export type GenerateOutput = z.infer<typeof generateOutputSchema>;
+export type GenerateSpec = z.infer<typeof generateSpecSchema>;
+export type ParagraphBlock = z.infer<typeof paragraphBlockSchema>;
+export type HeadingBlock = z.infer<typeof headingBlockSchema>;
+export type ListBlock = z.infer<typeof listBlockSchema>;
+export type CodeBlock = z.infer<typeof codeBlockSchema>;
+export type CalloutBlock = z.infer<typeof calloutBlockSchema>;
+export type ComparisonBlock = z.infer<typeof comparisonBlockSchema>;
+export type LessonBlock = z.infer<typeof lessonBlockSchema>;
+export type GeneratedLesson = z.infer<typeof generatedLessonSchema>;
+export type LessonConversationTurn = z.infer<typeof lessonConversationTurnSchema>;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@gentorial/core",
+  "version": "0.1.0",
+  "description": "Framework-neutral course protocols and validation for Gentorial.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "gentorial",
+    "education",
+    "schema"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --clean && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../.. --config vitest.config.ts packages/core/src",
+    "pack:check": "pnpm pack --dry-run"
+  }
+}