@nakafa/aksara-contracts 0.27.0

package/dist/program/snapshot/row.d.ts

@@ -0,0 +1,139 @@
+import { Schema } from "effect";
+/** Hashed current learning-program catalog record. */
+export declare const LearningProgramRecordSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"program">;
+    readonly row: Schema.Struct<{
+        readonly defaultCoverageStatus: Schema.Literals<readonly ["archived", "available", "hidden", "partial", "planned"]>;
+        readonly displayOrder: Schema.Int;
+        readonly 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"]>;
+        readonly key: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+        readonly kind: Schema.Literals<readonly ["admission-exam", "assessment", "custom-program", "institution-program", "school-curriculum"]>;
+        readonly navigation: Schema.Struct<{
+            readonly levels: Schema.NonEmptyArray<Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>>;
+            readonly model: Schema.Literals<readonly ["course-unit-lesson", "curriculum-tree", "exam-domain-set", "track-topic"]>;
+        }>;
+        readonly provider: Schema.Struct<{
+            readonly homeCountry: Schema.optional<Schema.String>;
+            readonly kind: Schema.Literals<readonly ["institution", "learner", "nakafa", "official"]>;
+            readonly name: Schema.Trimmed;
+        }>;
+        readonly recommendedCountry: Schema.optional<Schema.String>;
+        readonly sources: Schema.NonEmptyArray<Schema.Struct<{
+            readonly label: Schema.Trimmed;
+            readonly retrievedAt: Schema.String;
+            readonly reviewAfter: Schema.optional<Schema.String>;
+            readonly type: Schema.Literals<readonly ["institution-document", "nakafa-editorial", "official-blueprint", "official-policy", "official-portal"]>;
+            readonly url: Schema.String;
+        }>>;
+        readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly publicSlug: Schema.String;
+            readonly title: Schema.Trimmed;
+        }>>;
+        readonly version: Schema.Struct<{
+            readonly endsAt: Schema.optional<Schema.String>;
+            readonly label: Schema.Trimmed;
+            readonly startsAt: Schema.optional<Schema.String>;
+        }>;
+    }>;
+    readonly rowHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+/** Hashed current localized curriculum-route record. */
+export declare const CurriculumRouteRecordSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"curriculum">;
+    readonly row: 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;
+    }>;
+    readonly rowHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+/** Complete row vocabulary owned by the current program snapshot. */
+export declare const ProgramSnapshotRowSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"program">;
+    readonly row: Schema.Struct<{
+        readonly defaultCoverageStatus: Schema.Literals<readonly ["archived", "available", "hidden", "partial", "planned"]>;
+        readonly displayOrder: Schema.Int;
+        readonly 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"]>;
+        readonly key: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+        readonly kind: Schema.Literals<readonly ["admission-exam", "assessment", "custom-program", "institution-program", "school-curriculum"]>;
+        readonly navigation: Schema.Struct<{
+            readonly levels: Schema.NonEmptyArray<Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>>;
+            readonly model: Schema.Literals<readonly ["course-unit-lesson", "curriculum-tree", "exam-domain-set", "track-topic"]>;
+        }>;
+        readonly provider: Schema.Struct<{
+            readonly homeCountry: Schema.optional<Schema.String>;
+            readonly kind: Schema.Literals<readonly ["institution", "learner", "nakafa", "official"]>;
+            readonly name: Schema.Trimmed;
+        }>;
+        readonly recommendedCountry: Schema.optional<Schema.String>;
+        readonly sources: Schema.NonEmptyArray<Schema.Struct<{
+            readonly label: Schema.Trimmed;
+            readonly retrievedAt: Schema.String;
+            readonly reviewAfter: Schema.optional<Schema.String>;
+            readonly type: Schema.Literals<readonly ["institution-document", "nakafa-editorial", "official-blueprint", "official-policy", "official-portal"]>;
+            readonly url: Schema.String;
+        }>>;
+        readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly publicSlug: Schema.String;
+            readonly title: Schema.Trimmed;
+        }>>;
+        readonly version: Schema.Struct<{
+            readonly endsAt: Schema.optional<Schema.String>;
+            readonly label: Schema.Trimmed;
+            readonly startsAt: Schema.optional<Schema.String>;
+        }>;
+    }>;
+    readonly rowHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"curriculum">;
+    readonly row: 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;
+    }>;
+    readonly rowHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>]>;
+export type ProgramSnapshotRow = typeof ProgramSnapshotRowSchema.Type;
+export type ProgramSnapshotRowInput = Pick<typeof LearningProgramRecordSchema.Type, "kind" | "row"> | Pick<typeof CurriculumRouteRecordSchema.Type, "kind" | "row">;
+/** Serializes one current program snapshot row without its derived hash. */
+export declare function canonicalizeProgramSnapshotRow(record: ProgramSnapshotRowInput): string;

package/dist/program/snapshot/row.js

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { CurriculumRouteSchema, canonicalizeCurriculumRoute, } from "#contracts/program/curriculum";
+import { canonicalizeLearningProgram, LearningProgramSchema, } from "#contracts/program/spec";
+/** Hashed current learning-program catalog record. */
+export const LearningProgramRecordSchema = Schema.Struct({
+    kind: Schema.Literal("program"),
+    row: LearningProgramSchema,
+    rowHash: Sha256HashSchema,
+});
+/** Hashed current localized curriculum-route record. */
+export const CurriculumRouteRecordSchema = Schema.Struct({
+    kind: Schema.Literal("curriculum"),
+    row: CurriculumRouteSchema,
+    rowHash: Sha256HashSchema,
+});
+/** Complete row vocabulary owned by the current program snapshot. */
+export const ProgramSnapshotRowSchema = Schema.Union([
+    LearningProgramRecordSchema,
+    CurriculumRouteRecordSchema,
+]);
+/** Serializes one current program snapshot row without its derived hash. */
+export function canonicalizeProgramSnapshotRow(record) {
+    if (record.kind === "program") {
+        return `{"kind":"program","row":${canonicalizeLearningProgram(record.row)}}`;
+    }
+    return `{"kind":"curriculum","row":${canonicalizeCurriculumRoute(record.row)}}`;
+}

package/dist/program/snapshot/spec.d.ts

@@ -0,0 +1,36 @@
+import { Schema } from "effect";
+/** Semantic wire identity of the current localized program snapshot. */
+export declare const PROGRAM_SNAPSHOT_FORMAT = "localized-program-snapshot";
+/** Source-derived row counts checked against each complete program replay. */
+export declare const ProgramCountsSchema: Schema.Struct<{
+    curriculumRowCount: Schema.Int;
+    programRowCount: Schema.Int;
+    rowCount: Schema.Int;
+    sitemapCount: Schema.Int;
+    slugCount: Schema.Int;
+}>;
+export type ProgramCounts = typeof ProgramCountsSchema.Type;
+/** Canonical current program facts before content-addressed identity. */
+export declare const ProgramSnapshotFactsSchema: Schema.Struct<{
+    curriculumRowCount: Schema.Int;
+    programRowCount: Schema.Int;
+    rowCount: Schema.Int;
+    sitemapCount: Schema.Int;
+    slugCount: Schema.Int;
+    activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+    rowDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+export type ProgramSnapshotFacts = typeof ProgramSnapshotFactsSchema.Type;
+/** Content-addressed current program snapshot selected by one release. */
+export declare const ProgramSnapshotSchema: Schema.Struct<{
+    readonly curriculumRowCount: Schema.Int;
+    readonly programRowCount: Schema.Int;
+    readonly rowCount: Schema.Int;
+    readonly sitemapCount: Schema.Int;
+    readonly slugCount: Schema.Int;
+    readonly activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+    readonly rowDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly format: Schema.Literal<"localized-program-snapshot">;
+    readonly snapshotId: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+export type ProgramSnapshot = typeof ProgramSnapshotSchema.Type;

package/dist/program/snapshot/spec.js

@@ -0,0 +1,39 @@
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { ActiveAppLocaleListSchema } from "#contracts/locale";
+/** Semantic wire identity of the current localized program snapshot. */
+export const PROGRAM_SNAPSHOT_FORMAT = "localized-program-snapshot";
+const CountSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+const ProgramCountFields = {
+    curriculumRowCount: CountSchema,
+    programRowCount: CountSchema,
+    rowCount: CountSchema,
+    sitemapCount: CountSchema,
+    slugCount: CountSchema,
+};
+/** Source-derived row counts checked against each complete program replay. */
+export const ProgramCountsSchema = Schema.Struct(ProgramCountFields);
+/** Checks aggregate arithmetic without coupling it to one corpus size. */
+function hasCompleteProgramSnapshot(input) {
+    return (input.programRowCount > 0 &&
+        input.slugCount === input.programRowCount * input.activeAppLocales.length &&
+        input.rowCount === input.programRowCount + input.curriculumRowCount &&
+        input.sitemapCount <= input.curriculumRowCount);
+}
+const ProgramSnapshotFactFields = {
+    activeAppLocales: ActiveAppLocaleListSchema,
+    ...ProgramCountFields,
+    rowDigest: Sha256HashSchema,
+};
+/** Canonical current program facts before content-addressed identity. */
+export const ProgramSnapshotFactsSchema = Schema.Struct(ProgramSnapshotFactFields).pipe(Schema.check(Schema.makeFilter(hasCompleteProgramSnapshot, {
+    message: "Expected self-consistent program and curriculum snapshot counts.",
+})));
+/** Content-addressed current program snapshot selected by one release. */
+export const ProgramSnapshotSchema = Schema.Struct({
+    ...ProgramSnapshotFactFields,
+    format: Schema.Literal(PROGRAM_SNAPSHOT_FORMAT),
+    snapshotId: Sha256HashSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCompleteProgramSnapshot, {
+    message: "Expected self-consistent program and curriculum snapshot counts.",
+})));

package/dist/program/spec.d.ts

@@ -0,0 +1,85 @@
+import { Schema } from "effect";
+/** Canonical language-neutral identity for one learning program. */
+export declare const LearningProgramKeySchema: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+export type LearningProgramKey = typeof LearningProgramKeySchema.Type;
+/** Product role of one reviewed learning program. */
+export declare const LearningProgramKindSchema: Schema.Literals<readonly ["admission-exam", "assessment", "custom-program", "institution-program", "school-curriculum"]>;
+/** Navigation model rendered by one learning program surface. */
+export declare const ProgramNavigationModelSchema: Schema.Literals<readonly ["course-unit-lesson", "curriculum-tree", "exam-domain-set", "track-topic"]>;
+/** Complete level vocabulary used by reviewed curriculum and exam sources. */
+export declare const ProgramNavigationLevelSchema: Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>;
+export type ProgramNavigationLevel = typeof ProgramNavigationLevelSchema.Type;
+/** Complete icon vocabulary referenced by learning program sources. */
+export declare const ProgramNavigationIconKeySchema: 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"]>;
+export type ProgramNavigationIconKey = typeof ProgramNavigationIconKeySchema.Type;
+/** Publication state derived from reviewed source coverage. */
+export declare const ProgramCoverageSchema: Schema.Literals<readonly ["archived", "available", "hidden", "partial", "planned"]>;
+/** Reviewed organization class behind one program. */
+export declare const ProgramProviderKindSchema: Schema.Literals<readonly ["institution", "learner", "nakafa", "official"]>;
+/** Provenance role of one cited program source. */
+export declare const ProgramSourceKindSchema: Schema.Literals<readonly ["institution-document", "nakafa-editorial", "official-blueprint", "official-policy", "official-portal"]>;
+/** One localized title and public slug owned by a learning program. */
+export declare const ProgramTranslationSchema: Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    readonly publicSlug: Schema.String;
+    readonly title: Schema.Trimmed;
+}>;
+export type ProgramTranslation = typeof ProgramTranslationSchema.Type;
+/** Reviewed provider identity attached to one learning program. */
+export declare const ProgramProviderSchema: Schema.Struct<{
+    readonly homeCountry: Schema.optional<Schema.String>;
+    readonly kind: Schema.Literals<readonly ["institution", "learner", "nakafa", "official"]>;
+    readonly name: Schema.Trimmed;
+}>;
+/** Exact official or editorial source used by one program registry row. */
+export declare const ProgramSourceSchema: Schema.Struct<{
+    readonly label: Schema.Trimmed;
+    readonly retrievedAt: Schema.String;
+    readonly reviewAfter: Schema.optional<Schema.String>;
+    readonly type: Schema.Literals<readonly ["institution-document", "nakafa-editorial", "official-blueprint", "official-policy", "official-portal"]>;
+    readonly url: Schema.String;
+}>;
+/** Version label and optional inclusive availability window. */
+export declare const ProgramVersionSchema: Schema.Struct<{
+    readonly endsAt: Schema.optional<Schema.String>;
+    readonly label: Schema.Trimmed;
+    readonly startsAt: Schema.optional<Schema.String>;
+}>;
+/** Complete source-controlled wire contract for one learning program. */
+export declare const LearningProgramSchema: Schema.Struct<{
+    readonly defaultCoverageStatus: Schema.Literals<readonly ["archived", "available", "hidden", "partial", "planned"]>;
+    readonly displayOrder: Schema.Int;
+    readonly 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"]>;
+    readonly key: Schema.brand<Schema.String, "@NakafaAI/AksaraLearningProgramKey">;
+    readonly kind: Schema.Literals<readonly ["admission-exam", "assessment", "custom-program", "institution-program", "school-curriculum"]>;
+    readonly navigation: Schema.Struct<{
+        readonly levels: Schema.NonEmptyArray<Schema.Literals<readonly ["class", "course", "domain", "lesson", "phase", "section", "set", "stage", "subject", "topic", "track", "unit"]>>;
+        readonly model: Schema.Literals<readonly ["course-unit-lesson", "curriculum-tree", "exam-domain-set", "track-topic"]>;
+    }>;
+    readonly provider: Schema.Struct<{
+        readonly homeCountry: Schema.optional<Schema.String>;
+        readonly kind: Schema.Literals<readonly ["institution", "learner", "nakafa", "official"]>;
+        readonly name: Schema.Trimmed;
+    }>;
+    readonly recommendedCountry: Schema.optional<Schema.String>;
+    readonly sources: Schema.NonEmptyArray<Schema.Struct<{
+        readonly label: Schema.Trimmed;
+        readonly retrievedAt: Schema.String;
+        readonly reviewAfter: Schema.optional<Schema.String>;
+        readonly type: Schema.Literals<readonly ["institution-document", "nakafa-editorial", "official-blueprint", "official-policy", "official-portal"]>;
+        readonly url: Schema.String;
+    }>>;
+    readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly publicSlug: Schema.String;
+        readonly title: Schema.Trimmed;
+    }>>;
+    readonly version: Schema.Struct<{
+        readonly endsAt: Schema.optional<Schema.String>;
+        readonly label: Schema.Trimmed;
+        readonly startsAt: Schema.optional<Schema.String>;
+    }>;
+}>;
+export type LearningProgram = typeof LearningProgramSchema.Type;
+/** Serializes one program in stable signed field order. */
+export declare function canonicalizeLearningProgram(program: LearningProgram): string;

package/dist/program/spec.js

@@ -0,0 +1,197 @@
+import { Schema } from "effect";
+import { CountryCodeSchema } from "#contracts/country";
+import { DateOnlySchema } from "#contracts/date";
+import { APP_LOCALE_CODES, AppLocaleSchema } from "#contracts/locale";
+import { isHttpsUrl, isLowerKebab } from "#contracts/text/syntax";
+/** Canonical language-neutral identity for one learning program. */
+export const LearningProgramKeySchema = Schema.String.pipe(Schema.check(Schema.makeFilter(isLowerKebab, {
+    description: "Lowercase kebab-case canonical learning program key.",
+    identifier: "LearningProgramKey",
+    message: "Invalid learning program key. Expected lowercase kebab-case.",
+})), Schema.brand("@NakafaAI/AksaraLearningProgramKey"));
+/** Product role of one reviewed learning program. */
+export const LearningProgramKindSchema = Schema.Literals([
+    "admission-exam",
+    "assessment",
+    "custom-program",
+    "institution-program",
+    "school-curriculum",
+]);
+/** Navigation model rendered by one learning program surface. */
+export const ProgramNavigationModelSchema = Schema.Literals([
+    "course-unit-lesson",
+    "curriculum-tree",
+    "exam-domain-set",
+    "track-topic",
+]);
+/** Complete level vocabulary used by reviewed curriculum and exam sources. */
+export const ProgramNavigationLevelSchema = Schema.Literals([
+    "class",
+    "course",
+    "domain",
+    "lesson",
+    "phase",
+    "section",
+    "set",
+    "stage",
+    "subject",
+    "topic",
+    "track",
+    "unit",
+]);
+/** Complete icon vocabulary referenced by learning program sources. */
+export const ProgramNavigationIconKeySchema = Schema.Literals([
+    "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",
+]);
+/** Publication state derived from reviewed source coverage. */
+export const ProgramCoverageSchema = Schema.Literals([
+    "archived",
+    "available",
+    "hidden",
+    "partial",
+    "planned",
+]);
+/** Reviewed organization class behind one program. */
+export const ProgramProviderKindSchema = Schema.Literals([
+    "institution",
+    "learner",
+    "nakafa",
+    "official",
+]);
+/** Provenance role of one cited program source. */
+export const ProgramSourceKindSchema = Schema.Literals([
+    "institution-document",
+    "nakafa-editorial",
+    "official-blueprint",
+    "official-policy",
+    "official-portal",
+]);
+const ProgramSlugSchema = Schema.String.pipe(Schema.check(Schema.makeFilter(isLowerKebab)));
+/** One localized title and public slug owned by a learning program. */
+export const ProgramTranslationSchema = Schema.Struct({
+    appLocale: AppLocaleSchema,
+    publicSlug: ProgramSlugSchema,
+    title: Schema.Trimmed.check(Schema.isNonEmpty()),
+});
+/** Checks translations for unique canonical application-locale order. */
+function hasCanonicalTranslations(translations) {
+    return translations.every((translation, index) => {
+        const previous = translations[index - 1];
+        return (previous === undefined ||
+            APP_LOCALE_CODES.indexOf(previous.appLocale) <
+                APP_LOCALE_CODES.indexOf(translation.appLocale));
+    });
+}
+const ProgramTranslationListSchema = Schema.NonEmptyArray(ProgramTranslationSchema).pipe(Schema.check(Schema.makeFilter(hasCanonicalTranslations, {
+    message: "Program translations must use unique canonical app-locale order.",
+})));
+/** Reviewed provider identity attached to one learning program. */
+export const ProgramProviderSchema = Schema.Struct({
+    homeCountry: Schema.optional(CountryCodeSchema),
+    kind: ProgramProviderKindSchema,
+    name: Schema.Trimmed.check(Schema.isNonEmpty()),
+});
+/** Exact official or editorial source used by one program registry row. */
+export const ProgramSourceSchema = Schema.Struct({
+    label: Schema.Trimmed.check(Schema.isNonEmpty()),
+    retrievedAt: DateOnlySchema,
+    reviewAfter: Schema.optional(DateOnlySchema),
+    type: ProgramSourceKindSchema,
+    url: Schema.String.pipe(Schema.check(Schema.makeFilter(isHttpsUrl))),
+});
+/** Version label and optional inclusive availability window. */
+export const ProgramVersionSchema = Schema.Struct({
+    endsAt: Schema.optional(DateOnlySchema),
+    label: Schema.Trimmed.check(Schema.isNonEmpty()),
+    startsAt: Schema.optional(DateOnlySchema),
+}).pipe(Schema.check(Schema.makeFilter(({ endsAt, startsAt }) => endsAt === undefined || startsAt === undefined || startsAt <= endsAt, { message: "Expected a coherent learning program date window." })));
+/** Complete source-controlled wire contract for one learning program. */
+export const LearningProgramSchema = Schema.Struct({
+    defaultCoverageStatus: ProgramCoverageSchema,
+    displayOrder: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    iconKey: ProgramNavigationIconKeySchema,
+    key: LearningProgramKeySchema,
+    kind: LearningProgramKindSchema,
+    navigation: Schema.Struct({
+        levels: Schema.NonEmptyArray(ProgramNavigationLevelSchema),
+        model: ProgramNavigationModelSchema,
+    }),
+    provider: ProgramProviderSchema,
+    recommendedCountry: Schema.optional(CountryCodeSchema),
+    sources: Schema.NonEmptyArray(ProgramSourceSchema),
+    translations: ProgramTranslationListSchema,
+    version: ProgramVersionSchema,
+});
+/** Serializes one program in stable signed field order. */
+export function canonicalizeLearningProgram(program) {
+    return JSON.stringify({
+        defaultCoverageStatus: program.defaultCoverageStatus,
+        displayOrder: program.displayOrder,
+        iconKey: program.iconKey,
+        key: program.key,
+        kind: program.kind,
+        navigation: {
+            levels: program.navigation.levels,
+            model: program.navigation.model,
+        },
+        provider: {
+            ...(program.provider.homeCountry === undefined
+                ? {}
+                : { homeCountry: program.provider.homeCountry }),
+            kind: program.provider.kind,
+            name: program.provider.name,
+        },
+        ...(program.recommendedCountry === undefined
+            ? {}
+            : { recommendedCountry: program.recommendedCountry }),
+        sources: program.sources.map((source) => ({
+            label: source.label,
+            retrievedAt: source.retrievedAt,
+            ...(source.reviewAfter === undefined
+                ? {}
+                : { reviewAfter: source.reviewAfter }),
+            type: source.type,
+            url: source.url,
+        })),
+        translations: program.translations.map((translation) => ({
+            appLocale: translation.appLocale,
+            publicSlug: translation.publicSlug,
+            title: translation.title,
+        })),
+        version: {
+            ...(program.version.endsAt === undefined
+                ? {}
+                : { endsAt: program.version.endsAt }),
+            label: program.version.label,
+            ...(program.version.startsAt === undefined
+                ? {}
+                : { startsAt: program.version.startsAt }),
+        },
+    });
+}