@nakafa/aksara-contracts 0.27.0

package/dist/quran/snapshot/row/hash.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { canonicalizeLearningGraphIdentity } from "#contracts/graph/spec";
+import { Sha256HashSchema } from "#contracts/ids";
+import { canonicalizeQuranAttribution } from "#contracts/quran/attribution";
+import { QuranSnapshotRowSchema, } from "#contracts/quran/snapshot/row";
+const ROW_DOMAIN = "nakafa.aksara.quran-row";
+/** Node could not compute a deterministic Quran row identity. */
+export class QuranRowHashError extends Schema.TaggedError()("QuranRowHashError", { scope: Schema.Literals(["digest", "row"]) }) {
+}
+/** Serializes one published translation list in signed field order. */
+function canonicalizeTranslations(translations) {
+    return translations.map((translation) => ({
+        appLocale: translation.appLocale,
+        value: {
+            footnotes: translation.value.footnotes,
+            text: translation.value.text,
+        },
+    }));
+}
+/** Serializes signed Tafsir access without trusting object insertion order. */
+function canonicalizeTafsirAccess(access) {
+    return {
+        appLocale: access.appLocale,
+        kind: access.kind,
+        notice: access.notice,
+        sourceId: access.sourceId,
+    };
+}
+/** Serializes one current runtime verse without insertion-order trust. */
+function canonicalizeVerse(verse) {
+    return {
+        meta: {
+            hizbQuarter: verse.meta.hizbQuarter,
+            juz: verse.meta.juz,
+            manzil: verse.meta.manzil,
+            page: verse.meta.page,
+            ruku: verse.meta.ruku,
+            sajda: verse.meta.sajda,
+        },
+        number: {
+            inQuran: verse.number.inQuran,
+            inSurah: verse.number.inSurah,
+        },
+        tafsir: verse.tafsir.map((entry) => ({
+            appLocale: entry.appLocale,
+            footnotes: entry.footnotes,
+            text: entry.text,
+        })),
+        text: { arabic: verse.text.arabic },
+        translations: canonicalizeTranslations(verse.translations),
+    };
+}
+/** Produces stable JSON for one exhaustive current Quran payload. */
+export function canonicalizeQuranRow(payload) {
+    if (payload.kind === "quran-attribution") {
+        return JSON.stringify({
+            activeAppLocales: payload.activeAppLocales,
+            kind: payload.kind,
+            sources: payload.sources.map(canonicalizeQuranAttribution),
+            tafsirAccess: payload.tafsirAccess.map(canonicalizeTafsirAccess),
+        });
+    }
+    if (payload.kind === "quran-surah") {
+        return JSON.stringify({
+            kind: payload.kind,
+            name: {
+                arabic: payload.name.arabic,
+                meaning: {
+                    de: payload.name.meaning.de,
+                    en: payload.name.meaning.en,
+                    id: payload.name.meaning.id,
+                },
+                transliteration: payload.name.transliteration,
+            },
+            number: payload.number,
+            numberOfVerses: payload.numberOfVerses,
+            revelation: {
+                order: payload.revelation.order,
+                place: payload.revelation.place,
+            },
+        });
+    }
+    if (payload.kind === "quran-chunk") {
+        return JSON.stringify({
+            firstQuranNumber: payload.firstQuranNumber,
+            firstVerse: payload.firstVerse,
+            kind: payload.kind,
+            lastVerse: payload.lastVerse,
+            surahNumber: payload.surahNumber,
+            verses: payload.verses.map(canonicalizeVerse),
+        });
+    }
+    return JSON.stringify({
+        appLocale: payload.appLocale,
+        graph: canonicalizeLearningGraphIdentity(payload.graph),
+        kind: payload.kind,
+        route: payload.route,
+        surahNumber: payload.surahNumber,
+        text: payload.text,
+        title: payload.title,
+    });
+}
+/** Computes one current row's domain-separated identity. */
+export const hashQuranRow = Effect.fn("AksaraContracts.hashQuranRow")((payload) => Effect.try({
+    catch: () => new QuranRowHashError({ scope: "row" }),
+    try: () => Sha256HashSchema.make(`sha256:${createHash("sha256")
+        .update(`${ROW_DOMAIN}\n${canonicalizeQuranRow(payload)}`)
+        .digest("hex")}`),
+}));
+/** Creates one snapshot-bound current row. */
+export const bindQuranRow = Effect.fn("AksaraContracts.bindQuranRow")(function* (snapshotId, payload) {
+    const rowHash = yield* hashQuranRow(payload);
+    return QuranSnapshotRowSchema.make({ payload, rowHash, snapshotId });
+});

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

@@ -0,0 +1,354 @@
+import { Schema } from "effect";
+/** One locale-indexed QuranEnc translation. */
+export declare const QuranLocalizedTranslationSchema: Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    readonly value: Schema.Struct<{
+        readonly footnotes: Schema.String;
+        readonly text: Schema.String;
+    }>;
+}>;
+export type QuranLocalizedTranslation = typeof QuranLocalizedTranslationSchema.Type;
+/** One exact verse with explicit translation locale entries. */
+export declare const QuranRuntimeVerseSchema: Schema.Struct<{
+    readonly meta: Schema.Struct<{
+        readonly hizbQuarter: Schema.Int;
+        readonly juz: Schema.Int;
+        readonly manzil: Schema.Int;
+        readonly page: Schema.Int;
+        readonly ruku: Schema.Int;
+        readonly sajda: Schema.NullOr<Schema.Literals<readonly ["obligatory", "recommended"]>>;
+    }>;
+    readonly number: Schema.Struct<{
+        readonly inQuran: Schema.Int;
+        readonly inSurah: Schema.Int;
+    }>;
+    readonly tafsir: Schema.$Array<Schema.Struct<{
+        readonly appLocale: Schema.Literal<"id">;
+        readonly footnotes: Schema.NullOr<Schema.String>;
+        readonly text: Schema.String;
+    }>>;
+    readonly text: Schema.Struct<{
+        readonly arabic: Schema.String;
+    }>;
+    readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        readonly value: Schema.Struct<{
+            readonly footnotes: Schema.String;
+            readonly text: Schema.String;
+        }>;
+    }>>;
+}>;
+export type QuranRuntimeVerse = typeof QuranRuntimeVerseSchema.Type;
+/** Immutable bounded runtime row containing ordered verses. */
+export declare const QuranChunkRowSchema: Schema.Struct<{
+    readonly firstQuranNumber: Schema.Int;
+    readonly firstVerse: Schema.Int;
+    readonly kind: Schema.Literal<"quran-chunk">;
+    readonly lastVerse: Schema.Int;
+    readonly surahNumber: Schema.Int;
+    readonly verses: Schema.NonEmptyArray<Schema.Struct<{
+        readonly meta: Schema.Struct<{
+            readonly hizbQuarter: Schema.Int;
+            readonly juz: Schema.Int;
+            readonly manzil: Schema.Int;
+            readonly page: Schema.Int;
+            readonly ruku: Schema.Int;
+            readonly sajda: Schema.NullOr<Schema.Literals<readonly ["obligatory", "recommended"]>>;
+        }>;
+        readonly number: Schema.Struct<{
+            readonly inQuran: Schema.Int;
+            readonly inSurah: Schema.Int;
+        }>;
+        readonly tafsir: Schema.$Array<Schema.Struct<{
+            readonly appLocale: Schema.Literal<"id">;
+            readonly footnotes: Schema.NullOr<Schema.String>;
+            readonly text: Schema.String;
+        }>>;
+        readonly text: Schema.Struct<{
+            readonly arabic: Schema.String;
+        }>;
+        readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly value: Schema.Struct<{
+                readonly footnotes: Schema.String;
+                readonly text: Schema.String;
+            }>;
+        }>>;
+    }>>;
+}>;
+/** One locale-specific Quran route and full-text search document. */
+export declare const QuranSearchRowSchema: Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    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 kind: Schema.Literal<"quran-search">;
+    readonly route: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+    readonly surahNumber: Schema.Int;
+    readonly text: Schema.String;
+    readonly title: Schema.String;
+}>;
+/** Complete structured Quran row vocabulary. */
+export declare const QuranRowPayloadSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+    readonly kind: Schema.Literal<"quran-attribution">;
+    readonly sources: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+        readonly copy: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly notice: Schema.Trimmed;
+            readonly title: Schema.Trimmed;
+        }>>;
+        readonly publisher: Schema.Trimmed;
+        readonly retrievedAt: Schema.String;
+        readonly sourceUrl: Schema.String;
+        readonly updateUrl: Schema.String;
+        readonly version: Schema.Trimmed;
+        readonly artifact: Schema.Struct<{
+            readonly byteCount: Schema.Int;
+            readonly digest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+            readonly fileCount: Schema.Int;
+        }>;
+        readonly id: Schema.Literals<readonly ["tanzil-text", "tanzil-metadata", "kemenag-names", "bubenheim-names", "quranenc-english", "quranenc-indonesian", "quranenc-german", "quranenc-tafsir"]>;
+        readonly kind: Schema.Literal<"embedded">;
+        readonly terms: Schema.Struct<{
+            readonly artifact: Schema.Struct<{
+                readonly byteCount: Schema.Int;
+                readonly digest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+                readonly fileCount: Schema.Int;
+            }>;
+            readonly url: Schema.String;
+        }>;
+    }>, Schema.Struct<{
+        readonly copy: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly notice: Schema.Trimmed;
+            readonly title: Schema.Trimmed;
+        }>>;
+        readonly publisher: Schema.Trimmed;
+        readonly retrievedAt: Schema.String;
+        readonly sourceUrl: Schema.String;
+        readonly updateUrl: Schema.String;
+        readonly version: Schema.Trimmed;
+        readonly id: Schema.Literals<readonly ["mokhtasar-english", "mokhtasar-german"]>;
+        readonly kind: Schema.Literal<"external">;
+        readonly terms: Schema.Struct<{
+            readonly access: Schema.Literal<"link-only">;
+            readonly url: Schema.String;
+        }>;
+    }>]>>;
+    readonly tafsirAccess: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literal<"en">, "@NakafaAI/AksaraAppLocale">;
+        readonly kind: Schema.Literal<"external">;
+        readonly notice: Schema.Trimmed;
+        readonly sourceId: Schema.Literal<"mokhtasar-english">;
+    }>, Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literal<"id">, "@NakafaAI/AksaraAppLocale">;
+        readonly kind: Schema.Literal<"embedded">;
+        readonly notice: Schema.Trimmed;
+        readonly sourceId: Schema.Literal<"quranenc-tafsir">;
+    }>, Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literal<"de">, "@NakafaAI/AksaraAppLocale">;
+        readonly kind: Schema.Literal<"external">;
+        readonly notice: Schema.Trimmed;
+        readonly sourceId: Schema.Literal<"mokhtasar-german">;
+    }>]>>;
+}>, Schema.Struct<{
+    readonly name: Schema.Struct<{
+        readonly arabic: Schema.String;
+        readonly meaning: Schema.$Record<Schema.Literals<readonly ["en", "id", "de"]>, Schema.String>;
+        readonly transliteration: Schema.String;
+    }>;
+    readonly number: Schema.Int;
+    readonly numberOfVerses: Schema.Int;
+    readonly revelation: Schema.Struct<{
+        readonly order: Schema.Int;
+        readonly place: Schema.Literals<readonly ["Meccan", "Medinan"]>;
+    }>;
+    readonly kind: Schema.Literal<"quran-surah">;
+}>, Schema.Struct<{
+    readonly firstQuranNumber: Schema.Int;
+    readonly firstVerse: Schema.Int;
+    readonly kind: Schema.Literal<"quran-chunk">;
+    readonly lastVerse: Schema.Int;
+    readonly surahNumber: Schema.Int;
+    readonly verses: Schema.NonEmptyArray<Schema.Struct<{
+        readonly meta: Schema.Struct<{
+            readonly hizbQuarter: Schema.Int;
+            readonly juz: Schema.Int;
+            readonly manzil: Schema.Int;
+            readonly page: Schema.Int;
+            readonly ruku: Schema.Int;
+            readonly sajda: Schema.NullOr<Schema.Literals<readonly ["obligatory", "recommended"]>>;
+        }>;
+        readonly number: Schema.Struct<{
+            readonly inQuran: Schema.Int;
+            readonly inSurah: Schema.Int;
+        }>;
+        readonly tafsir: Schema.$Array<Schema.Struct<{
+            readonly appLocale: Schema.Literal<"id">;
+            readonly footnotes: Schema.NullOr<Schema.String>;
+            readonly text: Schema.String;
+        }>>;
+        readonly text: Schema.Struct<{
+            readonly arabic: Schema.String;
+        }>;
+        readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+            readonly value: Schema.Struct<{
+                readonly footnotes: Schema.String;
+                readonly text: Schema.String;
+            }>;
+        }>>;
+    }>>;
+}>, Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    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 kind: Schema.Literal<"quran-search">;
+    readonly route: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+    readonly surahNumber: Schema.Int;
+    readonly text: Schema.String;
+    readonly title: Schema.String;
+}>]>;
+export type QuranRowPayload = typeof QuranRowPayloadSchema.Type;
+/** One content-addressed row bound to an immutable Quran snapshot. */
+export declare const QuranSnapshotRowSchema: Schema.Struct<{
+    readonly payload: Schema.Union<readonly [Schema.Struct<{
+        readonly activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+        readonly kind: Schema.Literal<"quran-attribution">;
+        readonly sources: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly copy: Schema.NonEmptyArray<Schema.Struct<{
+                readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+                readonly notice: Schema.Trimmed;
+                readonly title: Schema.Trimmed;
+            }>>;
+            readonly publisher: Schema.Trimmed;
+            readonly retrievedAt: Schema.String;
+            readonly sourceUrl: Schema.String;
+            readonly updateUrl: Schema.String;
+            readonly version: Schema.Trimmed;
+            readonly artifact: Schema.Struct<{
+                readonly byteCount: Schema.Int;
+                readonly digest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+                readonly fileCount: Schema.Int;
+            }>;
+            readonly id: Schema.Literals<readonly ["tanzil-text", "tanzil-metadata", "kemenag-names", "bubenheim-names", "quranenc-english", "quranenc-indonesian", "quranenc-german", "quranenc-tafsir"]>;
+            readonly kind: Schema.Literal<"embedded">;
+            readonly terms: Schema.Struct<{
+                readonly artifact: Schema.Struct<{
+                    readonly byteCount: Schema.Int;
+                    readonly digest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+                    readonly fileCount: Schema.Int;
+                }>;
+                readonly url: Schema.String;
+            }>;
+        }>, Schema.Struct<{
+            readonly copy: Schema.NonEmptyArray<Schema.Struct<{
+                readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+                readonly notice: Schema.Trimmed;
+                readonly title: Schema.Trimmed;
+            }>>;
+            readonly publisher: Schema.Trimmed;
+            readonly retrievedAt: Schema.String;
+            readonly sourceUrl: Schema.String;
+            readonly updateUrl: Schema.String;
+            readonly version: Schema.Trimmed;
+            readonly id: Schema.Literals<readonly ["mokhtasar-english", "mokhtasar-german"]>;
+            readonly kind: Schema.Literal<"external">;
+            readonly terms: Schema.Struct<{
+                readonly access: Schema.Literal<"link-only">;
+                readonly url: Schema.String;
+            }>;
+        }>]>>;
+        readonly tafsirAccess: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literal<"en">, "@NakafaAI/AksaraAppLocale">;
+            readonly kind: Schema.Literal<"external">;
+            readonly notice: Schema.Trimmed;
+            readonly sourceId: Schema.Literal<"mokhtasar-english">;
+        }>, Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literal<"id">, "@NakafaAI/AksaraAppLocale">;
+            readonly kind: Schema.Literal<"embedded">;
+            readonly notice: Schema.Trimmed;
+            readonly sourceId: Schema.Literal<"quranenc-tafsir">;
+        }>, Schema.Struct<{
+            readonly appLocale: Schema.brand<Schema.Literal<"de">, "@NakafaAI/AksaraAppLocale">;
+            readonly kind: Schema.Literal<"external">;
+            readonly notice: Schema.Trimmed;
+            readonly sourceId: Schema.Literal<"mokhtasar-german">;
+        }>]>>;
+    }>, Schema.Struct<{
+        readonly name: Schema.Struct<{
+            readonly arabic: Schema.String;
+            readonly meaning: Schema.$Record<Schema.Literals<readonly ["en", "id", "de"]>, Schema.String>;
+            readonly transliteration: Schema.String;
+        }>;
+        readonly number: Schema.Int;
+        readonly numberOfVerses: Schema.Int;
+        readonly revelation: Schema.Struct<{
+            readonly order: Schema.Int;
+            readonly place: Schema.Literals<readonly ["Meccan", "Medinan"]>;
+        }>;
+        readonly kind: Schema.Literal<"quran-surah">;
+    }>, Schema.Struct<{
+        readonly firstQuranNumber: Schema.Int;
+        readonly firstVerse: Schema.Int;
+        readonly kind: Schema.Literal<"quran-chunk">;
+        readonly lastVerse: Schema.Int;
+        readonly surahNumber: Schema.Int;
+        readonly verses: Schema.NonEmptyArray<Schema.Struct<{
+            readonly meta: Schema.Struct<{
+                readonly hizbQuarter: Schema.Int;
+                readonly juz: Schema.Int;
+                readonly manzil: Schema.Int;
+                readonly page: Schema.Int;
+                readonly ruku: Schema.Int;
+                readonly sajda: Schema.NullOr<Schema.Literals<readonly ["obligatory", "recommended"]>>;
+            }>;
+            readonly number: Schema.Struct<{
+                readonly inQuran: Schema.Int;
+                readonly inSurah: Schema.Int;
+            }>;
+            readonly tafsir: Schema.$Array<Schema.Struct<{
+                readonly appLocale: Schema.Literal<"id">;
+                readonly footnotes: Schema.NullOr<Schema.String>;
+                readonly text: Schema.String;
+            }>>;
+            readonly text: Schema.Struct<{
+                readonly arabic: Schema.String;
+            }>;
+            readonly translations: Schema.NonEmptyArray<Schema.Struct<{
+                readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+                readonly value: Schema.Struct<{
+                    readonly footnotes: Schema.String;
+                    readonly text: Schema.String;
+                }>;
+            }>>;
+        }>>;
+    }>, Schema.Struct<{
+        readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+        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 kind: Schema.Literal<"quran-search">;
+        readonly route: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+        readonly surahNumber: Schema.Int;
+        readonly text: Schema.String;
+        readonly title: Schema.String;
+    }>]>;
+    readonly rowHash: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly snapshotId: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+export type QuranSnapshotRow = typeof QuranSnapshotRowSchema.Type;

package/dist/quran/snapshot/row.js

@@ -0,0 +1,91 @@
+import { Schema } from "effect";
+import { LearningGraphIdentitySchema } from "#contracts/graph/spec";
+import { PublicPathSchema, Sha256HashSchema } from "#contracts/ids";
+import { APP_LOCALE_CODES, AppLocaleSchema } from "#contracts/locale";
+import { QuranTranslationSchema } from "#contracts/quran/notes";
+import { QuranAttributionRowSchema } from "#contracts/quran/source";
+import { QURAN_CHUNK_SIZE, QuranSurahNumberSchema, QuranSurahRowSchema, QuranTafsirLocaleSchema, } from "#contracts/quran/spec";
+import { QuranMeaningfulTextSchema, QuranTextSchema, } from "#contracts/quran/text";
+/** One locale-indexed QuranEnc translation. */
+export const QuranLocalizedTranslationSchema = Schema.Struct({
+    appLocale: AppLocaleSchema,
+    value: QuranTranslationSchema,
+});
+/** Checks translation entries for unique canonical app-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 QuranTranslationListSchema = Schema.NonEmptyArray(QuranLocalizedTranslationSchema).pipe(Schema.check(Schema.makeFilter(hasCanonicalTranslations, {
+    message: "Quran translations must use unique canonical app-locale order.",
+})));
+/** Optional Tafsir entry available only for reviewed locales. */
+const QuranRuntimeTafsirSchema = Schema.Struct({
+    appLocale: QuranTafsirLocaleSchema,
+    footnotes: Schema.NullOr(Schema.String),
+    text: QuranMeaningfulTextSchema,
+});
+/** One exact verse with explicit translation locale entries. */
+export const QuranRuntimeVerseSchema = Schema.Struct({
+    meta: Schema.Struct({
+        hizbQuarter: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        juz: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        manzil: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        page: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        ruku: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        sajda: Schema.NullOr(Schema.Literals(["obligatory", "recommended"])),
+    }),
+    number: Schema.Struct({
+        inQuran: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+        inSurah: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    }),
+    tafsir: Schema.Array(QuranRuntimeTafsirSchema).pipe(Schema.check(Schema.isMaxLength(1))),
+    text: QuranTextSchema,
+    translations: QuranTranslationListSchema,
+});
+/** Checks one chunk's declared bounds against every ordered verse. */
+function hasCoherentChunk(input) {
+    if (input.lastVerse - input.firstVerse + 1 !== input.verses.length) {
+        return false;
+    }
+    return input.verses.every((verse, index) => verse.number.inSurah === input.firstVerse + index &&
+        verse.number.inQuran === input.firstQuranNumber + index);
+}
+/** Immutable bounded runtime row containing ordered verses. */
+export const QuranChunkRowSchema = Schema.Struct({
+    firstQuranNumber: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    firstVerse: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    kind: Schema.Literal("quran-chunk"),
+    lastVerse: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    surahNumber: QuranSurahNumberSchema,
+    verses: Schema.NonEmptyArray(QuranRuntimeVerseSchema).pipe(Schema.check(Schema.isMaxLength(QURAN_CHUNK_SIZE))),
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentChunk, {
+    message: "Expected one contiguous Quran runtime chunk.",
+})));
+/** One locale-specific Quran route and full-text search document. */
+export const QuranSearchRowSchema = Schema.Struct({
+    appLocale: AppLocaleSchema,
+    graph: LearningGraphIdentitySchema,
+    kind: Schema.Literal("quran-search"),
+    route: PublicPathSchema,
+    surahNumber: QuranSurahNumberSchema,
+    text: QuranMeaningfulTextSchema,
+    title: QuranMeaningfulTextSchema,
+});
+/** Complete structured Quran row vocabulary. */
+export const QuranRowPayloadSchema = Schema.Union([
+    QuranAttributionRowSchema,
+    QuranSurahRowSchema,
+    QuranChunkRowSchema,
+    QuranSearchRowSchema,
+]);
+/** One content-addressed row bound to an immutable Quran snapshot. */
+export const QuranSnapshotRowSchema = Schema.Struct({
+    payload: QuranRowPayloadSchema,
+    rowHash: Sha256HashSchema,
+    snapshotId: Sha256HashSchema,
+});

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

@@ -0,0 +1,50 @@
+import { Schema } from "effect";
+/** Semantic wire identity of the current localized Quran snapshot. */
+export declare const QURAN_SNAPSHOT_FORMAT = "localized-quran-snapshot";
+/** Production publication status derived from reviewed provenance records. */
+export declare const QuranProvenanceStatusSchema: Schema.Literals<readonly ["approved", "blocked"]>;
+export type QuranProvenanceStatus = typeof QuranProvenanceStatusSchema.Type;
+/** Immutable current Quran facts before content-addressed identity. */
+export declare const QuranSnapshotFactsSchema: Schema.Struct<{
+    activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+    attributionCount: Schema.Int;
+    chunkCount: Schema.Int;
+    projectionCount: Schema.Int;
+    projectionDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    provenanceDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    provenanceStatus: Schema.Literals<readonly ["approved", "blocked"]>;
+    runtimeCount: Schema.Int;
+    runtimeDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    searchCount: Schema.Int;
+    searchDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    sourceBytes: Schema.Int;
+    sourceDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    sourceFileCount: Schema.Int;
+    surahCount: Schema.Int;
+    tafsirLocales: Schema.$Array<Schema.Literal<"id">>;
+    verseCount: Schema.Int;
+}>;
+export type QuranSnapshotFacts = typeof QuranSnapshotFactsSchema.Type;
+/** Immutable identity and completeness proof for one Quran snapshot. */
+export declare const QuranSnapshotSchema: Schema.Struct<{
+    readonly activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+    readonly attributionCount: Schema.Int;
+    readonly chunkCount: Schema.Int;
+    readonly projectionCount: Schema.Int;
+    readonly projectionDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly provenanceDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly provenanceStatus: Schema.Literals<readonly ["approved", "blocked"]>;
+    readonly runtimeCount: Schema.Int;
+    readonly runtimeDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly searchCount: Schema.Int;
+    readonly searchDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly sourceBytes: Schema.Int;
+    readonly sourceDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly sourceFileCount: Schema.Int;
+    readonly surahCount: Schema.Int;
+    readonly tafsirLocales: Schema.$Array<Schema.Literal<"id">>;
+    readonly verseCount: Schema.Int;
+    readonly format: Schema.Literal<"localized-quran-snapshot">;
+    readonly snapshotId: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+}>;
+export type QuranSnapshot = typeof QuranSnapshotSchema.Type;