@nakafa/aksara-contracts 0.27.0

package/dist/preview/spec.js

@@ -0,0 +1,142 @@
+import { Schema } from "effect";
+import { GitCommitShaSchema, Sha256HashSchema } from "#contracts/ids";
+import { PreviewArtifactSchema } from "#contracts/preview/artifact";
+import { PreviewDocumentSchema, } from "#contracts/preview/document";
+import { PreviewRouteSchema } from "#contracts/preview/target";
+/** Stable protocol implemented by the loopback-only authoring provider. */
+export const LOCAL_PREVIEW_FORMAT = "aksara-local-preview";
+/** Exact Git evidence printed and served for one participating checkout. */
+export const PreviewRepositorySchema = Schema.Struct({
+    dirty: Schema.Boolean,
+    sha: GitCommitShaSchema,
+});
+const PreviewArtifactListSchema = Schema.NonEmptyArray(PreviewArtifactSchema).pipe(Schema.check(Schema.makeFilter((artifacts) => artifacts.length <= 2, {
+    message: "Expected at most two preview artifacts.",
+})));
+/** Checks one article projection against its selected registry route. */
+function matchesArticleDocument(document, projection) {
+    return (projection.kind === "article" &&
+        projection.articleSlug === document.route.articleSlug &&
+        projection.category === document.route.category &&
+        projection.contentKey === document.route.contentKey &&
+        projection.appLocale === document.route.appLocale &&
+        projection.artifactLocale === document.route.artifactLocale &&
+        projection.publicPath === document.route.publicPath);
+}
+/** Checks one material projection against its selected registry route. */
+function matchesMaterialDocument(document, projection) {
+    return (projection.kind === "subject-lesson" &&
+        projection.contentKey === document.route.contentKey &&
+        projection.appLocale === document.route.appLocale &&
+        projection.artifactLocale === document.route.artifactLocale &&
+        projection.materialKey === document.route.materialKey &&
+        projection.order === document.route.order &&
+        projection.publicPath === document.route.publicPath &&
+        projection.sectionKey === document.route.sectionKey &&
+        projection.topicTitle === document.route.topicTitle);
+}
+/** Checks one page projection against its selected registry route. */
+function matchesPageDocument(document, projection) {
+    return (projection.kind === "public-page" &&
+        projection.contentKey === document.route.contentKey &&
+        projection.appLocale === document.route.appLocale &&
+        projection.artifactLocale === document.route.artifactLocale &&
+        projection.pageKey === document.route.pageKey &&
+        projection.publicPath === document.route.publicPath &&
+        projection.sourcePath === document.sourcePath);
+}
+/** Checks one question projection against an exact prompt or answer identity. */
+function matchesQuestionIdentity(projection, identity) {
+    return (projection.kind === "question-body" &&
+        projection.bodyKind === identity.bodyKind &&
+        projection.contentKey === identity.contentKey &&
+        projection.artifactLocale === identity.artifactLocale &&
+        projection.peerContentKey === identity.peerContentKey &&
+        projection.questionKey === identity.questionKey &&
+        projection.questionNumber === identity.questionNumber &&
+        projection.setKey === identity.setKey);
+}
+/** Checks the ordered prompt required before one entitled answer artifact. */
+function matchesAnswerPrompt(projection, input) {
+    const { identity } = input;
+    return (projection.kind === "question-body" &&
+        projection.bodyKind === "question" &&
+        projection.contentKey === identity.peerContentKey &&
+        projection.artifactLocale === input.questionArtifactLocale &&
+        projection.peerContentKey === identity.contentKey &&
+        projection.questionKey === identity.questionKey &&
+        projection.questionNumber === identity.questionNumber &&
+        projection.setKey === identity.setKey);
+}
+/** Checks family-specific artifact count, order, identity, and projection kind. */
+function hasCoherentReadyArtifacts(input) {
+    const first = input.artifacts[0].projection;
+    if (input.document.family === "article") {
+        return (input.artifacts.length === 1 &&
+            matchesArticleDocument(input.document, first));
+    }
+    if (input.document.family === "material") {
+        return (input.artifacts.length === 1 &&
+            matchesMaterialDocument(input.document, first));
+    }
+    if (input.document.family === "page") {
+        return (input.artifacts.length === 1 && matchesPageDocument(input.document, first));
+    }
+    if (input.document.identity.bodyKind === "question") {
+        return (input.artifacts.length === 1 &&
+            matchesQuestionIdentity(first, input.document.identity));
+    }
+    const second = input.artifacts[1]?.projection;
+    return (input.artifacts.length === 2 &&
+        matchesAnswerPrompt(first, {
+            identity: input.document.identity,
+            questionArtifactLocale: input.document.target.placement.questionArtifactLocale,
+        }) &&
+        second !== undefined &&
+        matchesQuestionIdentity(second, input.document.identity));
+}
+const PreviewBaseSchema = Schema.Struct({
+    document: PreviewDocumentSchema,
+    format: Schema.Literal(LOCAL_PREVIEW_FORMAT),
+    repositories: Schema.Struct({
+        aksara: PreviewRepositorySchema,
+        nakafa: PreviewRepositorySchema,
+    }),
+    revision: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+});
+/** A changed route is intentionally unavailable while its source compiles. */
+export const PreviewPendingSchema = Schema.Struct({
+    ...PreviewBaseSchema.fields,
+    status: Schema.Literal("pending"),
+});
+/** Exact bounded artifacts available to the real loopback Nakafa app. */
+export const PreviewReadySchema = Schema.Struct({
+    ...PreviewBaseSchema.fields,
+    artifacts: PreviewArtifactListSchema,
+    rendererManifestHash: Sha256HashSchema,
+    status: Schema.Literal("ready"),
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentReadyArtifacts, {
+    message: "Expected preview artifacts to match the selected document exactly.",
+})));
+/** Sanitized compile failure that forbids fallback to an older route body. */
+export const PreviewFailedSchema = Schema.Struct({
+    ...PreviewBaseSchema.fields,
+    failure: Schema.Struct({
+        code: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(128))),
+        message: Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(512))),
+    }),
+    status: Schema.Literal("failed"),
+});
+/** Complete current local source state returned by the manifest endpoint. */
+export const LocalPreviewManifestSchema = Schema.Union([
+    PreviewPendingSchema,
+    PreviewReadySchema,
+    PreviewFailedSchema,
+]);
+/** Minimal SSE signal carrying only the derived route and manifest revision. */
+export const PreviewEventSchema = Schema.Struct({
+    format: Schema.Literal(LOCAL_PREVIEW_FORMAT),
+    revision: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThan(0))),
+    route: PreviewRouteSchema,
+    status: Schema.Literals(["pending", "ready", "failed"]),
+});

package/dist/preview/target.d.ts

@@ -0,0 +1,172 @@
+import { Schema } from "effect";
+/** Locale and existing public route refreshed by one preview update. */
+export declare const PreviewRouteSchema: Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+}>;
+/**
+ * Placement identity needed to select one preview body.
+ * Responses remain owned by the canonical question registry and projections.
+ */
+export declare const TryoutPreviewPlacementSchema: Schema.Struct<{
+    readonly answerArtifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+    readonly answerContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    readonly blueprint: Schema.optionalKey<Schema.Struct<{
+        readonly cognitiveLevel: Schema.String;
+        readonly contentDomain: Schema.String;
+        readonly topic: Schema.String;
+    }>>;
+    readonly countryKey: Schema.String;
+    readonly deliveryLanguage: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraDeliveryLanguage">;
+    readonly examKey: Schema.String;
+    readonly languagePolicy: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"app-locale">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"fixed">;
+        readonly language: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraDeliveryLanguage">;
+    }>]>;
+    readonly questionArtifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+    readonly questionContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+    readonly questionOrder: Schema.Finite;
+    readonly questionSourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+    readonly rendererDomain: Schema.Literals<readonly ["ai-ds", "biology", "chemistry", "mathematics", "physics", "politics", "site", "snbt-general", "snbt-math", "snbt-plain", "snbt-quant", "tka-math"]>;
+    readonly scope: Schema.Literal<"server">;
+    readonly sectionKey: Schema.String;
+    readonly setKey: Schema.String;
+    readonly sourceRevision: Schema.Trimmed;
+    readonly stimulusKey: Schema.optionalKey<Schema.String>;
+    readonly trackKey: Schema.String;
+}>;
+/** Exact current try-out rows needed to preview one authored question body. */
+export declare const TryoutPreviewTargetSchema: Schema.Struct<{
+    readonly exam: Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly description: Schema.optional<Schema.String>;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly sourceRevision: Schema.Trimmed;
+        readonly title: Schema.String;
+        readonly countryKey: Schema.String;
+        readonly examKey: Schema.String;
+        readonly kind: Schema.Literal<"exam">;
+        readonly order: Schema.Finite;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly scoringStrategy: Schema.Literals<readonly ["irt", "raw"]>;
+    }>;
+    readonly placement: Schema.Struct<{
+        readonly answerArtifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly answerContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly blueprint: Schema.optionalKey<Schema.Struct<{
+            readonly cognitiveLevel: Schema.String;
+            readonly contentDomain: Schema.String;
+            readonly topic: Schema.String;
+        }>>;
+        readonly countryKey: Schema.String;
+        readonly deliveryLanguage: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraDeliveryLanguage">;
+        readonly examKey: Schema.String;
+        readonly languagePolicy: Schema.Union<readonly [Schema.Struct<{
+            readonly kind: Schema.Literal<"app-locale">;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"fixed">;
+            readonly language: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraDeliveryLanguage">;
+        }>]>;
+        readonly questionArtifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+        readonly questionContentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+        readonly questionOrder: Schema.Finite;
+        readonly questionSourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+        readonly rendererDomain: Schema.Literals<readonly ["ai-ds", "biology", "chemistry", "mathematics", "physics", "politics", "site", "snbt-general", "snbt-math", "snbt-plain", "snbt-quant", "tka-math"]>;
+        readonly scope: Schema.Literal<"server">;
+        readonly sectionKey: Schema.String;
+        readonly setKey: Schema.String;
+        readonly sourceRevision: Schema.Trimmed;
+        readonly stimulusKey: Schema.optionalKey<Schema.String>;
+        readonly trackKey: Schema.String;
+    }>;
+    readonly section: Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly description: Schema.optional<Schema.String>;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly sourceRevision: Schema.Trimmed;
+        readonly title: Schema.String;
+        readonly countryKey: Schema.String;
+        readonly examKey: Schema.String;
+        readonly kind: Schema.Literal<"section">;
+        readonly order: Schema.Finite;
+        readonly publicPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+        readonly questionCount: Schema.Finite;
+        readonly questionSourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+        readonly sectionKey: Schema.String;
+        readonly setKey: Schema.String;
+        readonly timeLimitSeconds: Schema.Finite;
+        readonly trackKey: Schema.String;
+        readonly visibility: Schema.Literals<readonly ["internal-entry", "visible"]>;
+    }>;
+    readonly set: Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly description: Schema.optional<Schema.String>;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly sourceRevision: Schema.Trimmed;
+        readonly title: Schema.String;
+        readonly countryKey: Schema.String;
+        readonly examKey: Schema.String;
+        readonly internalEntrySectionKey: Schema.optional<Schema.String>;
+        readonly kind: Schema.Literal<"set">;
+        readonly order: Schema.Finite;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly questionCount: Schema.Finite;
+        readonly scoringStrategy: Schema.Literals<readonly ["irt", "raw"]>;
+        readonly sectionCount: Schema.Finite;
+        readonly setKey: Schema.String;
+        readonly trackKey: Schema.String;
+        readonly visibleSectionCount: Schema.Finite;
+    }>;
+    readonly track: Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly description: Schema.optional<Schema.String>;
+        readonly graph: Schema.Struct<{
+            readonly alignmentId: Schema.String;
+            readonly assetId: Schema.String;
+            readonly conceptId: Schema.String;
+            readonly learningObjectId: Schema.String;
+            readonly lensId: Schema.String;
+        }>;
+        readonly sourceRevision: Schema.Trimmed;
+        readonly title: Schema.String;
+        readonly countryKey: Schema.String;
+        readonly examKey: Schema.String;
+        readonly kind: Schema.Literal<"track">;
+        readonly order: Schema.Finite;
+        readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly questionCount: Schema.Finite;
+        readonly sectionCount: Schema.Finite;
+        readonly setCount: Schema.Finite;
+        readonly trackKey: Schema.String;
+        readonly trackKind: Schema.Literals<readonly ["subject", "year"]>;
+        readonly visibleSectionCount: Schema.Finite;
+    }>;
+}>;
+export type TryoutPreviewTarget = typeof TryoutPreviewTargetSchema.Type;
+/** Derives the existing try-out page used by the trusted authoring preview. */
+export declare function previewTryoutRoute(target: TryoutPreviewTarget): {
+    readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+    readonly publicPath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">;
+};

package/dist/preview/target.js

@@ -0,0 +1,70 @@
+import { Schema, Struct } from "effect";
+import { PublicPathSchema } from "#contracts/ids";
+import { AppLocaleSchema } from "#contracts/locale";
+import { TryoutExamSchema, TryoutSectionSchema, TryoutSetSchema, TryoutTrackSchema, } from "#contracts/tryout/catalog";
+import { TryoutPlacementSourceSchema } from "#contracts/tryout/placement";
+/** Locale and existing public route refreshed by one preview update. */
+export const PreviewRouteSchema = Schema.Struct({
+    appLocale: AppLocaleSchema,
+    publicPath: PublicPathSchema,
+});
+/**
+ * Placement identity needed to select one preview body.
+ * Responses remain owned by the canonical question registry and projections.
+ */
+export const TryoutPreviewPlacementSchema = TryoutPlacementSourceSchema.pipe((schema) => schema.mapFields(Struct.omit(["response"])));
+/** Checks that every target row belongs to one locale-specific hierarchy. */
+function hasCoherentTryoutHierarchy(input) {
+    const rows = [input.track, input.set, input.section, input.placement];
+    return (rows.every(({ countryKey }) => countryKey === input.exam.countryKey) &&
+        rows.every(({ examKey }) => examKey === input.exam.examKey) &&
+        rows.every(({ appLocale }) => appLocale === input.exam.appLocale) &&
+        rows.every(({ sourceRevision }) => sourceRevision === input.exam.sourceRevision) &&
+        input.set.trackKey === input.track.trackKey &&
+        input.section.trackKey === input.track.trackKey &&
+        input.placement.trackKey === input.track.trackKey &&
+        input.section.setKey === input.set.setKey &&
+        input.placement.setKey === input.set.setKey &&
+        input.placement.sectionKey === input.section.sectionKey);
+}
+/** Checks nested routes and the internal-entry route fallback contract. */
+function hasCoherentTryoutRoutes(input) {
+    if (!input.track.publicPath.startsWith(`${input.exam.publicPath}/`)) {
+        return false;
+    }
+    if (!input.set.publicPath.startsWith(`${input.track.publicPath}/`)) {
+        return false;
+    }
+    if (input.section.visibility === "internal-entry") {
+        return input.set.internalEntrySectionKey === input.section.sectionKey;
+    }
+    return (input.set.internalEntrySectionKey === undefined &&
+        input.section.publicPath?.startsWith(`${input.set.publicPath}/`) === true);
+}
+/** Checks that the selected placement is owned by the target section source. */
+function hasCoherentTryoutPlacement(input) {
+    return (input.placement.questionOrder <= input.section.questionCount &&
+        input.placement.questionSourcePath ===
+            `${input.section.questionSourcePath}/question-${input.placement.questionOrder}`);
+}
+/** Exact current try-out rows needed to preview one authored question body. */
+export const TryoutPreviewTargetSchema = Schema.Struct({
+    exam: TryoutExamSchema,
+    placement: TryoutPreviewPlacementSchema,
+    section: TryoutSectionSchema,
+    set: TryoutSetSchema,
+    track: TryoutTrackSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentTryoutHierarchy, {
+    message: "Expected preview target hierarchy keys, locale, and revision to agree.",
+})), Schema.check(Schema.makeFilter(hasCoherentTryoutRoutes, {
+    message: "Expected preview target routes to form one reachable hierarchy.",
+})), Schema.check(Schema.makeFilter(hasCoherentTryoutPlacement, {
+    message: "Expected preview placement to belong to the selected section source.",
+})));
+/** Derives the existing try-out page used by the trusted authoring preview. */
+export function previewTryoutRoute(target) {
+    return PreviewRouteSchema.make({
+        appLocale: target.section.appLocale,
+        publicPath: target.section.publicPath ?? target.set.publicPath,
+    });
+}

package/dist/program/curriculum.d.ts

@@ -0,0 +1,69 @@
+import { Schema } from "effect";
+import { type AppLocale } from "#contracts/locale";
+/** Localized public route namespaces shared by projection and verification. */
+export declare const CURRICULUM_NAMESPACES: {
+    readonly de: "lehrplaene";
+    readonly en: "curriculum";
+    readonly id: "kurikulum";
+};
+/** Resolves the route namespace owned by one application locale. */
+export declare function curriculumNamespace(appLocale: AppLocale): "curriculum" | "kurikulum" | "lehrplaene";
+/** Checks whether one curriculum level owns a learner-renderable route. */
+export declare const isRenderableCurriculumLevel: <I>(input: I) => input is I & ("class" | "course" | "stage" | "subject" | "track");
+/** Stable source-owned identity for one curriculum tree node. */
+export declare const CurriculumNodeKeySchema: Schema.brand<Schema.String, "@NakafaAI/AksaraCurriculumNodeKey">;
+export type CurriculumNodeKey = typeof CurriculumNodeKeySchema.Type;
+/** Localized curriculum route before material presentation context is added. */
+export declare const CurriculumRouteDraftSchema: Schema.Struct<{
+    appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    canonicalPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    displayGroupIconKey: Schema.optional<Schema.Literals<readonly ["advanced", "assessment", "certificate", "course", "diploma", "early-years", "global-education", "grade-1", "grade-10", "grade-11", "grade-12", "grade-2", "grade-3", "grade-4", "grade-5", "grade-6", "grade-7", "grade-8", "grade-9", "high-school", "mathematics", "middle-school", "primary-school", "science", "school", "standards", "state"]>>;
+    displayGroupTitle: Schema.optional<Schema.String>;
+    iconKey: Schema.Literals<readonly ["advanced", "assessment", "certificate", "course", "diploma", "early-years", "global-education", "grade-1", "grade-10", "grade-11", "grade-12", "grade-2", "grade-3", "grade-4", "grade-5", "grade-6", "grade-7", "grade-8", "grade-9", "high-school", "mathematics", "middle-school", "primary-school", "science", "school", "standards", "state"]>;
+    kind: Schema.Literal<"curriculum-context">;
+    level: Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>;
+    materialCardDescription: Schema.optional<Schema.String>;
+    materialCardTitle: Schema.optional<Schema.String>;
+    materialContextNodeKey: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraCurriculumNodeKey">>;
+    materialContextParentPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    materialContextPublicPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    materialDomain: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialDomain">>;
+    materialKey: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialKey">>;
+    nodeKey: Schema.String;
+    order: Schema.Int;
+    parentPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    programKey: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+    publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+    sitemap: Schema.Boolean;
+    sourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+    title: Schema.String;
+}>;
+export type CurriculumRouteDraft = typeof CurriculumRouteDraftSchema.Type;
+/** Exact localized curriculum route stored inside the program snapshot. */
+export declare const CurriculumRouteSchema: Schema.Struct<{
+    appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    canonicalPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    displayGroupIconKey: Schema.optional<Schema.Literals<readonly ["advanced", "assessment", "certificate", "course", "diploma", "early-years", "global-education", "grade-1", "grade-10", "grade-11", "grade-12", "grade-2", "grade-3", "grade-4", "grade-5", "grade-6", "grade-7", "grade-8", "grade-9", "high-school", "mathematics", "middle-school", "primary-school", "science", "school", "standards", "state"]>>;
+    displayGroupTitle: Schema.optional<Schema.String>;
+    iconKey: Schema.Literals<readonly ["advanced", "assessment", "certificate", "course", "diploma", "early-years", "global-education", "grade-1", "grade-10", "grade-11", "grade-12", "grade-2", "grade-3", "grade-4", "grade-5", "grade-6", "grade-7", "grade-8", "grade-9", "high-school", "mathematics", "middle-school", "primary-school", "science", "school", "standards", "state"]>;
+    kind: Schema.Literal<"curriculum-context">;
+    level: Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>;
+    materialCardDescription: Schema.optional<Schema.String>;
+    materialCardTitle: Schema.optional<Schema.String>;
+    materialContextNodeKey: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraCurriculumNodeKey">>;
+    materialContextParentPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    materialContextPublicPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    materialDomain: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialDomain">>;
+    materialKey: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraMaterialKey">>;
+    nodeKey: Schema.String;
+    order: Schema.Int;
+    parentPath: Schema.optional<Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">>;
+    programKey: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+    publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+    sitemap: Schema.Boolean;
+    sourcePath: Schema.brand<Schema.String, "@NakafaAI/AksaraCorpusSourcePath">;
+    title: Schema.String;
+}>;
+export type CurriculumRoute = typeof CurriculumRouteSchema.Type;
+/** Serializes one curriculum route in stable signed field order. */
+export declare function canonicalizeCurriculumRoute(route: CurriculumRoute): string;

package/dist/program/curriculum.js

@@ -0,0 +1,181 @@
+import { Schema } from "effect";
+import { CorpusSourcePathSchema, PublicPathSchema } from "#contracts/ids";
+import { AppLocaleSchema } from "#contracts/locale";
+import { MaterialDomainSchema } from "#contracts/material/domain";
+import { LearningProgramKeySchema, ProgramNavigationIconKeySchema, ProgramNavigationLevelSchema, } from "#contracts/program/spec";
+import { MaterialKeySchema } from "#contracts/projection/material";
+import { isLowerKebab } from "#contracts/text/syntax";
+const CurriculumNamespaceMapSchema = Schema.Struct({
+    de: Schema.Literal("lehrplaene"),
+    en: Schema.Literal("curriculum"),
+    id: Schema.Literal("kurikulum"),
+});
+const RenderableCurriculumLevelSchema = Schema.Literals([
+    "class",
+    "course",
+    "stage",
+    "subject",
+    "track",
+]);
+/** Checks one curriculum route key with its optional canonical root suffix. */
+function isCurriculumRouteNodeKey(value) {
+    const rootSuffix = ":root";
+    return isLowerKebab(value.endsWith(rootSuffix) ? value.slice(0, -rootSuffix.length) : value);
+}
+/** Localized public route namespaces shared by projection and verification. */
+export const CURRICULUM_NAMESPACES = CurriculumNamespaceMapSchema.make({
+    de: "lehrplaene",
+    en: "curriculum",
+    id: "kurikulum",
+});
+/** Resolves the route namespace owned by one application locale. */
+export function curriculumNamespace(appLocale) {
+    const localeCode = String(appLocale);
+    if (localeCode === "de") {
+        return CURRICULUM_NAMESPACES.de;
+    }
+    if (localeCode === "id") {
+        return CURRICULUM_NAMESPACES.id;
+    }
+    return CURRICULUM_NAMESPACES.en;
+}
+/** Checks whether one curriculum level owns a learner-renderable route. */
+export const isRenderableCurriculumLevel = Schema.is(RenderableCurriculumLevelSchema);
+/** Stable source-owned identity for one curriculum tree node. */
+export const CurriculumNodeKeySchema = Schema.String.pipe(Schema.check(Schema.makeFilter(isLowerKebab, {
+    description: "Lowercase kebab-case curriculum node key.",
+    identifier: "CurriculumNodeKey",
+    message: "Invalid curriculum node key.",
+})), Schema.brand("@NakafaAI/AksaraCurriculumNodeKey"));
+const CurriculumRouteNodeKeySchema = Schema.String.pipe(Schema.check(Schema.makeFilter(isCurriculumRouteNodeKey)));
+const CurriculumRouteFields = {
+    appLocale: AppLocaleSchema,
+    canonicalPath: Schema.optional(PublicPathSchema),
+    displayGroupIconKey: Schema.optional(ProgramNavigationIconKeySchema),
+    displayGroupTitle: Schema.optional(Schema.String),
+    iconKey: ProgramNavigationIconKeySchema,
+    kind: Schema.Literal("curriculum-context"),
+    level: ProgramNavigationLevelSchema,
+    materialCardDescription: Schema.optional(Schema.String),
+    materialCardTitle: Schema.optional(Schema.String),
+    materialContextNodeKey: Schema.optional(CurriculumNodeKeySchema),
+    materialContextParentPath: Schema.optional(PublicPathSchema),
+    materialContextPublicPath: Schema.optional(PublicPathSchema),
+    materialDomain: Schema.optional(MaterialDomainSchema),
+    materialKey: Schema.optional(MaterialKeySchema),
+    nodeKey: CurriculumRouteNodeKeySchema,
+    order: Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    parentPath: Schema.optional(PublicPathSchema),
+    programKey: LearningProgramKeySchema,
+    publicPath: PublicPathSchema,
+    sitemap: Schema.Boolean,
+    sourcePath: CorpusSourcePathSchema,
+    title: Schema.String,
+};
+/** Returns the direct parent of one canonical public path. */
+function parentPath(publicPath) {
+    return publicPath.slice(0, publicPath.lastIndexOf("/"));
+}
+/** Checks namespace, root, and direct-parent route ownership. */
+function hasCoherentRoute(input) {
+    const namespace = `${curriculumNamespace(input.appLocale)}/`;
+    if (!input.publicPath.startsWith(namespace)) {
+        return false;
+    }
+    if (input.sourcePath !== `packages/corpus/curriculum/${input.programKey}`) {
+        return false;
+    }
+    if (input.parentPath === undefined) {
+        return (input.level === "track" &&
+            input.nodeKey === `${input.programKey}:root` &&
+            input.publicPath.split("/").length === 2);
+    }
+    return (input.nodeKey !== `${input.programKey}:root` &&
+        input.parentPath === parentPath(input.publicPath));
+}
+/** Checks all-or-nothing material and context ownership fields. */
+function hasCoherentMaterialLink(input) {
+    const ownsMaterial = input.materialKey !== undefined;
+    const ownsCanonical = input.canonicalPath !== undefined;
+    const contextCount = [
+        input.materialContextNodeKey,
+        input.materialContextParentPath,
+        input.materialContextPublicPath,
+    ].filter((value) => value !== undefined).length;
+    if (!ownsMaterial) {
+        return !ownsCanonical && contextCount === 0;
+    }
+    return ownsCanonical && (contextCount === 0 || contextCount === 3);
+}
+/** Checks that every published material has its complete presentation context. */
+function hasCompleteMaterialContext(input) {
+    if (input.materialKey === undefined) {
+        return true;
+    }
+    return (input.materialContextNodeKey !== undefined &&
+        input.materialContextParentPath !== undefined &&
+        input.materialContextPublicPath !== undefined);
+}
+/** Checks that only learner-renderable levels enter the sitemap. */
+function hasCoherentSitemap(input) {
+    return !input.sitemap || isRenderableCurriculumLevel(input.level);
+}
+/** Localized curriculum route before material presentation context is added. */
+export const CurriculumRouteDraftSchema = Schema.Struct(CurriculumRouteFields).pipe(Schema.check(Schema.makeFilter(hasCoherentRoute, {
+    message: "Expected coherent localized curriculum route ownership.",
+})), Schema.check(Schema.makeFilter(hasCoherentMaterialLink, {
+    message: "Expected coherent curriculum material ownership.",
+})), Schema.check(Schema.makeFilter(hasCoherentSitemap, {
+    message: "Expected only renderable curriculum sitemap routes.",
+})));
+/** Exact localized curriculum route stored inside the program snapshot. */
+export const CurriculumRouteSchema = CurriculumRouteDraftSchema.pipe(Schema.check(Schema.makeFilter(hasCompleteMaterialContext, {
+    message: "Expected complete curriculum material context ownership.",
+})));
+/** Serializes one curriculum route in stable signed field order. */
+export function canonicalizeCurriculumRoute(route) {
+    return JSON.stringify({
+        appLocale: route.appLocale,
+        ...(route.canonicalPath === undefined
+            ? {}
+            : { canonicalPath: route.canonicalPath }),
+        ...(route.displayGroupIconKey === undefined
+            ? {}
+            : { displayGroupIconKey: route.displayGroupIconKey }),
+        ...(route.displayGroupTitle === undefined
+            ? {}
+            : { displayGroupTitle: route.displayGroupTitle }),
+        iconKey: route.iconKey,
+        kind: route.kind,
+        level: route.level,
+        ...(route.materialCardDescription === undefined
+            ? {}
+            : { materialCardDescription: route.materialCardDescription }),
+        ...(route.materialCardTitle === undefined
+            ? {}
+            : { materialCardTitle: route.materialCardTitle }),
+        ...(route.materialContextNodeKey === undefined
+            ? {}
+            : { materialContextNodeKey: route.materialContextNodeKey }),
+        ...(route.materialContextParentPath === undefined
+            ? {}
+            : { materialContextParentPath: route.materialContextParentPath }),
+        ...(route.materialContextPublicPath === undefined
+            ? {}
+            : { materialContextPublicPath: route.materialContextPublicPath }),
+        ...(route.materialDomain === undefined
+            ? {}
+            : { materialDomain: route.materialDomain }),
+        ...(route.materialKey === undefined
+            ? {}
+            : { materialKey: route.materialKey }),
+        nodeKey: route.nodeKey,
+        order: route.order,
+        ...(route.parentPath === undefined ? {} : { parentPath: route.parentPath }),
+        programKey: route.programKey,
+        publicPath: route.publicPath,
+        sitemap: route.sitemap,
+        sourcePath: route.sourcePath,
+        title: route.title,
+    });
+}