@nakafa/aksara-contracts 0.27.0

package/dist/quran/snapshot/spec.js

@@ -0,0 +1,66 @@
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { ActiveAppLocaleListSchema, AppLocaleSchema, } from "#contracts/locale";
+import { quranSourceFileCount } from "#contracts/quran/source";
+import { QURAN_ATTRIBUTION_COUNT, QURAN_SURAH_COUNT, QURAN_VERSE_COUNT, } from "#contracts/quran/spec";
+/** Semantic wire identity of the current localized Quran snapshot. */
+export const QURAN_SNAPSHOT_FORMAT = "localized-quran-snapshot";
+const CountSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+const SourceBytesSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)));
+/** Production publication status derived from reviewed provenance records. */
+export const QuranProvenanceStatusSchema = Schema.Literals([
+    "approved",
+    "blocked",
+]);
+const QuranSnapshotFactFields = {
+    activeAppLocales: ActiveAppLocaleListSchema,
+    attributionCount: CountSchema,
+    chunkCount: CountSchema,
+    projectionCount: CountSchema,
+    projectionDigest: Sha256HashSchema,
+    provenanceDigest: Sha256HashSchema,
+    provenanceStatus: QuranProvenanceStatusSchema,
+    runtimeCount: CountSchema,
+    runtimeDigest: Sha256HashSchema,
+    searchCount: CountSchema,
+    searchDigest: Sha256HashSchema,
+    sourceBytes: SourceBytesSchema,
+    sourceDigest: Sha256HashSchema,
+    sourceFileCount: CountSchema,
+    surahCount: CountSchema,
+    tafsirLocales: Schema.Array(Schema.Literal("id")).pipe(Schema.check(Schema.isMaxLength(1))),
+    verseCount: CountSchema,
+};
+/** Checks source, translation, and Tafsir counts against active locales. */
+function hasCompleteSnapshotCounts(input) {
+    const hasIndonesian = input.activeAppLocales.includes(AppLocaleSchema.make("id"));
+    return (input.attributionCount === QURAN_ATTRIBUTION_COUNT &&
+        input.surahCount === QURAN_SURAH_COUNT &&
+        input.verseCount === QURAN_VERSE_COUNT &&
+        input.searchCount === QURAN_SURAH_COUNT * input.activeAppLocales.length &&
+        input.sourceFileCount === quranSourceFileCount(input.activeAppLocales) &&
+        JSON.stringify(input.tafsirLocales) ===
+            JSON.stringify(hasIndonesian ? ["id"] : []));
+}
+/** Checks runtime and search arithmetic for complete projection inventory. */
+function hasCoherentProjectionCounts(input) {
+    return (input.runtimeCount ===
+        input.attributionCount + input.surahCount + input.chunkCount &&
+        input.projectionCount === input.runtimeCount + input.searchCount);
+}
+/** Immutable current Quran facts before content-addressed identity. */
+export const QuranSnapshotFactsSchema = Schema.Struct(QuranSnapshotFactFields).pipe(Schema.check(Schema.makeFilter(hasCompleteSnapshotCounts, {
+    message: "Expected complete active-locale Quran source counts.",
+})), Schema.check(Schema.makeFilter(hasCoherentProjectionCounts, {
+    message: "Expected Quran runtime and search counts to cover every projection.",
+})));
+/** Immutable identity and completeness proof for one Quran snapshot. */
+export const QuranSnapshotSchema = Schema.Struct({
+    ...QuranSnapshotFactFields,
+    format: Schema.Literal(QURAN_SNAPSHOT_FORMAT),
+    snapshotId: Sha256HashSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCompleteSnapshotCounts, {
+    message: "Expected complete active-locale Quran source counts.",
+})), Schema.check(Schema.makeFilter(hasCoherentProjectionCounts, {
+    message: "Expected Quran runtime and search counts to cover every projection.",
+})));

package/dist/quran/source.d.ts

@@ -0,0 +1,206 @@
+import { Schema } from "effect";
+import { type ActiveAppLocaleList } from "#contracts/locale";
+import { type QuranSourceId } from "#contracts/quran/identity";
+/** Derives the exact source identities required by one active locale set. */
+export declare function quranSourceIds(activeAppLocales: ActiveAppLocaleList): readonly [QuranSourceId, QuranSourceId, ...QuranSourceId[]];
+/** Counts exact source files required by one active locale set. */
+export declare function quranSourceFileCount(activeAppLocales: ActiveAppLocaleList): number;
+/** Content identity of one pinned official source or legal evidence artifact. */
+export declare const QuranSourceArtifactSchema: Schema.Struct<{
+    readonly byteCount: Schema.Int;
+    readonly digest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly fileCount: Schema.Int;
+}>;
+export type QuranSourceArtifact = typeof QuranSourceArtifactSchema.Type;
+/** Nakafa-owned source label and notice for one application locale. */
+export declare const QuranSourceCopySchema: Schema.Struct<{
+    readonly appLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">;
+    readonly notice: Schema.Trimmed;
+    readonly title: Schema.Trimmed;
+}>;
+export type QuranSourceCopy = typeof QuranSourceCopySchema.Type;
+/** Attribution for source bytes embedded and authenticated by Aksara. */
+export declare const QuranEmbeddedSourceAttributionSchema: 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;
+    }>;
+}>;
+export type QuranEmbeddedSourceAttribution = typeof QuranEmbeddedSourceAttributionSchema.Type;
+/** Attribution for an official edition that Aksara may only link to. */
+export declare const QuranExternalSourceAttributionSchema: 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;
+    }>;
+}>;
+export type QuranExternalSourceAttribution = typeof QuranExternalSourceAttributionSchema.Type;
+/** Public attribution that distinguishes embedded bytes from external links. */
+export declare const QuranSourceAttributionSchema: 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;
+    }>;
+}>]>;
+export type QuranSourceAttribution = typeof QuranSourceAttributionSchema.Type;
+/** Signed locale-specific access to embedded or official external Tafsir. */
+export declare const QuranTafsirAccessSchema: 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">;
+}>]>;
+export type QuranTafsirAccess = typeof QuranTafsirAccessSchema.Type;
+/** Checks every source copy against the exact active locale set and order. */
+export declare function hasCompleteQuranSourceCopy(source: QuranSourceAttribution, activeAppLocales: ActiveAppLocaleList): boolean;
+/** Checks exact Tafsir access coverage against one active locale set. */
+export declare function hasCompleteQuranTafsirAccess(access: readonly QuranTafsirAccess[], activeAppLocales: ActiveAppLocaleList): boolean;
+/** Visible attribution row carrying the active official source subset. */
+export declare const QuranAttributionRowSchema: 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">;
+    }>]>>;
+}>;
+export type QuranAttributionRow = typeof QuranAttributionRowSchema.Type;
+/** Checks exact source coverage against one active application-locale set. */
+export declare function hasRequiredQuranSources(sources: readonly QuranSourceAttribution[], activeAppLocales: ActiveAppLocaleList): boolean;

package/dist/quran/source.js

@@ -0,0 +1,153 @@
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { ActiveAppLocaleListSchema, AppLocaleSchema, appLocaleLiteral, } from "#contracts/locale";
+import { QURAN_SOURCE_IDS, QuranEmbeddedSourceIdSchema, QuranExternalSourceIdSchema, quranNameSourceId, quranTafsirSourceId, quranTranslationSourceId, } from "#contracts/quran/identity";
+import { QURAN_SURAH_COUNT, QuranExternalTafsirLocaleSchema, QuranTafsirLocaleSchema, } from "#contracts/quran/spec";
+import { isHttpsUrl } from "#contracts/text/syntax";
+/** Derives the exact source identities required by one active locale set. */
+export function quranSourceIds(activeAppLocales) {
+    const sourceIds = activeAppLocales.flatMap((appLocale) => [
+        quranNameSourceId(appLocale),
+        quranTranslationSourceId(appLocale),
+        quranTafsirSourceId(appLocale),
+    ]);
+    return [
+        "tanzil-text",
+        "tanzil-metadata",
+        ...QURAN_SOURCE_IDS.slice(2).filter((sourceId) => sourceIds.includes(sourceId)),
+    ];
+}
+/** Counts exact source files required by one active locale set. */
+export function quranSourceFileCount(activeAppLocales) {
+    const supplementalNameFileCount = activeAppLocales.filter((appLocale) => quranNameSourceId(appLocale) !== "tanzil-metadata").length;
+    const tafsirFileCount = activeAppLocales.includes(AppLocaleSchema.make("id"))
+        ? QURAN_SURAH_COUNT
+        : 0;
+    return (2 + activeAppLocales.length + supplementalNameFileCount + tafsirFileCount);
+}
+const HttpsUrlSchema = Schema.String.pipe(Schema.check(Schema.makeFilter(isHttpsUrl, {
+    message: "Quran source links must use HTTPS.",
+})));
+const RetrievedAtSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/u, {
+    message: "Expected an exact UTC Quran source retrieval time.",
+})));
+/** Content identity of one pinned official source or legal evidence artifact. */
+export const QuranSourceArtifactSchema = Schema.Struct({
+    byteCount: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    digest: Sha256HashSchema,
+    fileCount: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+});
+/** Nakafa-owned source label and notice for one application locale. */
+export const QuranSourceCopySchema = Schema.Struct({
+    appLocale: AppLocaleSchema,
+    notice: Schema.Trimmed.check(Schema.isNonEmpty()),
+    title: Schema.Trimmed.check(Schema.isNonEmpty()),
+});
+const QuranSourceAttributionFields = {
+    copy: Schema.NonEmptyArray(QuranSourceCopySchema),
+    publisher: Schema.Trimmed.check(Schema.isNonEmpty()),
+    retrievedAt: RetrievedAtSchema,
+    sourceUrl: HttpsUrlSchema,
+    updateUrl: HttpsUrlSchema,
+    version: Schema.Trimmed.check(Schema.isNonEmpty()),
+};
+/** Attribution for source bytes embedded and authenticated by Aksara. */
+export const QuranEmbeddedSourceAttributionSchema = Schema.Struct({
+    ...QuranSourceAttributionFields,
+    artifact: QuranSourceArtifactSchema,
+    id: QuranEmbeddedSourceIdSchema,
+    kind: Schema.Literal("embedded"),
+    terms: Schema.Struct({
+        artifact: QuranSourceArtifactSchema,
+        url: HttpsUrlSchema,
+    }),
+});
+/** Attribution for an official edition that Aksara may only link to. */
+export const QuranExternalSourceAttributionSchema = Schema.Struct({
+    ...QuranSourceAttributionFields,
+    id: QuranExternalSourceIdSchema,
+    kind: Schema.Literal("external"),
+    terms: Schema.Struct({
+        access: Schema.Literal("link-only"),
+        url: HttpsUrlSchema,
+    }),
+});
+/** Public attribution that distinguishes embedded bytes from external links. */
+export const QuranSourceAttributionSchema = Schema.Union([
+    QuranEmbeddedSourceAttributionSchema,
+    QuranExternalSourceAttributionSchema,
+]);
+const QuranIndonesianTafsirAccessSchema = Schema.Struct({
+    appLocale: appLocaleLiteral(QuranTafsirLocaleSchema.literal),
+    kind: Schema.Literal("embedded"),
+    notice: Schema.Trimmed.check(Schema.isNonEmpty()),
+    sourceId: Schema.Literal(quranTafsirSourceId(QuranTafsirLocaleSchema.literal)),
+});
+const QuranEnglishTafsirAccessSchema = Schema.Struct({
+    appLocale: appLocaleLiteral(QuranExternalTafsirLocaleSchema.literals[0]),
+    kind: Schema.Literal("external"),
+    notice: Schema.Trimmed.check(Schema.isNonEmpty()),
+    sourceId: Schema.Literal(quranTafsirSourceId(QuranExternalTafsirLocaleSchema.literals[0])),
+});
+const QuranGermanTafsirAccessSchema = Schema.Struct({
+    appLocale: appLocaleLiteral(QuranExternalTafsirLocaleSchema.literals[1]),
+    kind: Schema.Literal("external"),
+    notice: Schema.Trimmed.check(Schema.isNonEmpty()),
+    sourceId: Schema.Literal(quranTafsirSourceId(QuranExternalTafsirLocaleSchema.literals[1])),
+});
+/** Signed locale-specific access to embedded or official external Tafsir. */
+export const QuranTafsirAccessSchema = Schema.Union([
+    QuranEnglishTafsirAccessSchema,
+    QuranIndonesianTafsirAccessSchema,
+    QuranGermanTafsirAccessSchema,
+]);
+/** Checks source identities for uniqueness and canonical contract order. */
+function hasCanonicalSources(sources) {
+    return sources.every((source, index) => {
+        const previous = sources[index - 1];
+        return (previous === undefined ||
+            QURAN_SOURCE_IDS.indexOf(previous.id) <
+                QURAN_SOURCE_IDS.indexOf(source.id));
+    });
+}
+/** Checks every source copy against the exact active locale set and order. */
+export function hasCompleteQuranSourceCopy(source, activeAppLocales) {
+    return (source.copy.length === activeAppLocales.length &&
+        source.copy.every(({ appLocale }, index) => appLocale === activeAppLocales[index]));
+}
+/** Checks localized copy closure across every selected official source. */
+function hasCompleteLocalizedCopy(input) {
+    return input.sources.every((source) => hasCompleteQuranSourceCopy(source, input.activeAppLocales));
+}
+/** Checks every signed Tafsir access record against one attributed source. */
+function hasAttributedTafsirSources(input) {
+    return input.tafsirAccess.every((access) => input.sources.some((source) => source.id === access.sourceId));
+}
+/** Checks exact Tafsir access coverage against one active locale set. */
+export function hasCompleteQuranTafsirAccess(access, activeAppLocales) {
+    return (access.length === activeAppLocales.length &&
+        access.every(({ appLocale }, index) => appLocale === activeAppLocales[index]));
+}
+/** Visible attribution row carrying the active official source subset. */
+export const QuranAttributionRowSchema = Schema.Struct({
+    activeAppLocales: ActiveAppLocaleListSchema,
+    kind: Schema.Literal("quran-attribution"),
+    sources: Schema.NonEmptyArray(QuranSourceAttributionSchema),
+    tafsirAccess: Schema.NonEmptyArray(QuranTafsirAccessSchema),
+}).pipe(Schema.check(Schema.makeFilter(({ sources }) => hasCanonicalSources(sources), {
+    message: "Expected unique Quran sources in canonical order.",
+})), Schema.check(Schema.makeFilter(({ activeAppLocales, sources }) => hasRequiredQuranSources(sources, activeAppLocales), {
+    message: "Expected exact Quran source coverage for the active locale set.",
+})), Schema.check(Schema.makeFilter(hasCompleteLocalizedCopy, {
+    message: "Expected localized Quran attribution copy for every active locale.",
+})), Schema.check(Schema.makeFilter(({ activeAppLocales, tafsirAccess }) => hasCompleteQuranTafsirAccess(tafsirAccess, activeAppLocales), {
+    message: "Expected exact Tafsir access for every active locale.",
+})), Schema.check(Schema.makeFilter(hasAttributedTafsirSources, {
+    message: "Expected every Tafsir access record to bind an attribution.",
+})));
+/** Checks exact source coverage against one active application-locale set. */
+export function hasRequiredQuranSources(sources, activeAppLocales) {
+    const expected = quranSourceIds(activeAppLocales);
+    return (sources.length === expected.length &&
+        sources.every(({ id }, index) => id === expected[index]));
+}

package/dist/quran/spec.d.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+/** Tafsir locale whose complete reviewed source may enter runtime rows. */
+export declare const QuranTafsirLocaleSchema: Schema.Literal<"id">;
+/** App locales whose official Tafsir edition remains an external link. */
+export declare const QuranExternalTafsirLocaleSchema: Schema.Literals<readonly ["en", "de"]>;
+/** Exact number of reviewed surahs in the authored Quran source. */
+export declare const QURAN_SURAH_COUNT = 114;
+/** Exact number of reviewed verses in the authored Quran source. */
+export declare const QURAN_VERSE_COUNT = 6236;
+/** One visible source-attribution row required before Quran runtime content. */
+export declare const QURAN_ATTRIBUTION_COUNT = 1;
+/** Maximum verses stored in one independently verifiable runtime chunk. */
+export declare const QURAN_CHUNK_SIZE = 6;
+/** Valid Quran surah number in canonical order. */
+export declare const QuranSurahNumberSchema: Schema.Int;
+/** Complete reviewed surah-name meaning map in canonical app-locale keys. */
+export declare const QuranSurahNameMeaningSchema: Schema.$Record<Schema.Literals<readonly ["en", "id", "de"]>, Schema.String>;
+/** Shared authored and published metadata for one reviewed Quran surah. */
+export declare const QuranSurahMetadataSchema: 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"]>;
+    }>;
+}>;
+/** Immutable metadata row for one reviewed Quran surah. */
+export declare const QuranSurahRowSchema: 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">;
+}>;
+export type QuranSurahRow = typeof QuranSurahRowSchema.Type;

package/dist/quran/spec.js

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+import { AppLocaleCodeSchema, ENGLISH_APP_LOCALE_CODE, GERMAN_APP_LOCALE_CODE, INDONESIAN_APP_LOCALE_CODE, } from "#contracts/locale";
+import { QuranMeaningfulTextSchema } from "#contracts/quran/text";
+/** Tafsir locale whose complete reviewed source may enter runtime rows. */
+export const QuranTafsirLocaleSchema = Schema.Literal(INDONESIAN_APP_LOCALE_CODE);
+/** App locales whose official Tafsir edition remains an external link. */
+export const QuranExternalTafsirLocaleSchema = Schema.Literals([
+    ENGLISH_APP_LOCALE_CODE,
+    GERMAN_APP_LOCALE_CODE,
+]);
+/** Exact number of reviewed surahs in the authored Quran source. */
+export const QURAN_SURAH_COUNT = 114;
+/** Exact number of reviewed verses in the authored Quran source. */
+export const QURAN_VERSE_COUNT = 6236;
+/** One visible source-attribution row required before Quran runtime content. */
+export const QURAN_ATTRIBUTION_COUNT = 1;
+/** Maximum verses stored in one independently verifiable runtime chunk. */
+export const QURAN_CHUNK_SIZE = 6;
+/** Valid Quran surah number in canonical order. */
+export const QuranSurahNumberSchema = Schema.Int.pipe(Schema.check(Schema.isBetween({ maximum: QURAN_SURAH_COUNT, minimum: 1 })));
+/** Complete reviewed surah-name meaning map in canonical app-locale keys. */
+export const QuranSurahNameMeaningSchema = Schema.Record(AppLocaleCodeSchema, QuranMeaningfulTextSchema);
+/** Shared authored and published metadata for one reviewed Quran surah. */
+export const QuranSurahMetadataSchema = Schema.Struct({
+    name: Schema.Struct({
+        arabic: QuranMeaningfulTextSchema,
+        meaning: QuranSurahNameMeaningSchema,
+        transliteration: QuranMeaningfulTextSchema,
+    }),
+    number: QuranSurahNumberSchema,
+    numberOfVerses: Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))),
+    revelation: Schema.Struct({
+        order: QuranSurahNumberSchema,
+        place: Schema.Literals(["Meccan", "Medinan"]),
+    }),
+});
+/** Immutable metadata row for one reviewed Quran surah. */
+export const QuranSurahRowSchema = Schema.Struct({
+    kind: Schema.Literal("quran-surah"),
+    ...QuranSurahMetadataSchema.fields,
+});

package/dist/quran/text.d.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** Non-empty Quran text shared by authored and published row contracts. */
+export declare const QuranMeaningfulTextSchema: Schema.String;
+/** Verbatim Tanzil Arabic text without compatibility fields. */
+export declare const QuranTextSchema: Schema.Struct<{
+    readonly arabic: Schema.String;
+}>;

package/dist/quran/text.js

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+/** Non-empty Quran text shared by authored and published row contracts. */
+export const QuranMeaningfulTextSchema = Schema.String.pipe(Schema.check(Schema.isPattern(/\S/u, {
+    description: "Authored Quran text containing at least one visible character.",
+    identifier: "QuranText",
+    message: "Quran text cannot be empty.",
+})));
+/** Verbatim Tanzil Arabic text without compatibility fields. */
+export const QuranTextSchema = Schema.Struct({
+    arabic: QuranMeaningfulTextSchema,
+});

package/dist/release/canonical.d.ts

@@ -0,0 +1,23 @@
+import type { ContentChange, ContentReleaseItem } from "#contracts/release/spec";
+/** Serializes one change with stable fields for item digest computation. */
+export declare function canonicalizeContentChange(change: ContentChange): {
+    artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    delivery: "authenticated" | "entitled" | "public";
+    family: "article" | "material" | "page" | "question";
+    operation: "upsert";
+    rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+    sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+} | {
+    artifactHash?: never;
+    delivery?: never;
+    rendererDomain?: never;
+    sourcePath?: never;
+    artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    family: "article" | "material" | "page" | "question";
+    operation: "delete";
+};
+/** Serializes one release item with stable identity, order, and content. */
+export declare function canonicalizeContentReleaseItem(item: ContentReleaseItem): string;

package/dist/release/canonical.js

@@ -0,0 +1,29 @@
+/** Serializes one change with stable fields for item digest computation. */
+export function canonicalizeContentChange(change) {
+    if (change.operation === "upsert") {
+        return {
+            artifactHash: change.artifactHash,
+            artifactLocale: change.artifactLocale,
+            contentKey: change.contentKey,
+            delivery: change.delivery,
+            family: change.family,
+            operation: change.operation,
+            rendererDomain: change.rendererDomain,
+            sourcePath: change.sourcePath,
+        };
+    }
+    return {
+        artifactLocale: change.artifactLocale,
+        contentKey: change.contentKey,
+        family: change.family,
+        operation: change.operation,
+    };
+}
+/** Serializes one release item with stable identity, order, and content. */
+export function canonicalizeContentReleaseItem(item) {
+    return JSON.stringify({
+        change: canonicalizeContentChange(item.change),
+        index: item.index,
+        releaseId: item.releaseId,
+    });
+}