@nakafa/aksara-contracts 0.27.0

package/dist/question/item.js

@@ -0,0 +1,146 @@
+import { Effect, Schema, Struct } from "effect";
+import { AppLocaleCodeSchema, ArtifactLocaleSchema, artifactLocaleCode, } from "#contracts/locale";
+import { QuestionResponseContentSchema, QuestionResponseSchema, } from "#contracts/question/response";
+import { TryoutKeySchema } from "#contracts/tryout/key";
+const PositiveOrderSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)));
+/** One source-authored option before stable runtime identities are derived. */
+const QuestionOptionSourceSchema = Schema.Struct({
+    isCorrect: Schema.Boolean,
+    label: QuestionResponseContentSchema,
+}).mapFields(Struct.map(Schema.mutableKey));
+/** Requires enough options to present one meaningful choice interaction. */
+function hasAtLeastTwoOptions(options) {
+    return options.length >= 2;
+}
+/** Requires exactly one authored option to carry correctness. */
+function hasOneCorrectOption(options) {
+    return options.filter(({ isCorrect }) => isCorrect).length === 1;
+}
+/** Requires several correct options while retaining at least one distractor. */
+function hasSeveralCorrectOptions(options) {
+    const correct = options.filter(({ isCorrect }) => isCorrect).length;
+    return correct >= 2 && correct < options.length;
+}
+const QuestionOptionSourceListSchema = Schema.Array(QuestionOptionSourceSchema).pipe(Schema.mutable, Schema.check(Schema.makeFilter(hasAtLeastTwoOptions, {
+    message: "Expected at least two response options.",
+})));
+const SingleChoiceResponseSourceSchema = Schema.Struct({
+    kind: Schema.Literal("single-choice"),
+    options: QuestionOptionSourceListSchema.pipe(Schema.check(Schema.makeFilter(hasOneCorrectOption, {
+        message: "Single-choice responses require one correct option.",
+    }))),
+}).mapFields(Struct.map(Schema.mutableKey));
+const MultipleChoiceResponseSourceSchema = Schema.Struct({
+    kind: Schema.Literal("multiple-choice"),
+    options: QuestionOptionSourceListSchema.pipe(Schema.check(Schema.makeFilter(hasSeveralCorrectOptions, {
+        message: "Multiple-choice responses require several correct options and one distractor.",
+    }))),
+}).mapFields(Struct.map(Schema.mutableKey));
+const CategoryStatementSourceSchema = Schema.Struct({
+    correctCategoryOrder: PositiveOrderSchema,
+    label: QuestionResponseContentSchema,
+}).mapFields(Struct.map(Schema.mutableKey));
+/** Checks category cardinality and every statement's category reference. */
+function hasCoherentCategoryResponse(input) {
+    return (input.categories.length >= 2 &&
+        input.statements.length > 0 &&
+        input.statements.every(({ correctCategoryOrder }) => correctCategoryOrder <= input.categories.length));
+}
+const CategoryResponseSourceSchema = Schema.Struct({
+    categories: Schema.Array(QuestionResponseContentSchema).pipe(Schema.mutable),
+    kind: Schema.Literal("category"),
+    statements: Schema.Array(CategoryStatementSourceSchema).pipe(Schema.mutable),
+})
+    .mapFields(Struct.map(Schema.mutableKey))
+    .pipe(Schema.check(Schema.makeFilter(hasCoherentCategoryResponse, {
+    message: "Category responses require at least two categories and classified statements.",
+})));
+/** One locale-specific response authored without duplicated runtime keys. */
+export const QuestionResponseSourceSchema = Schema.Union([
+    CategoryResponseSourceSchema,
+    MultipleChoiceResponseSourceSchema,
+    SingleChoiceResponseSourceSchema,
+]);
+const QuestionResponseSourceMapSchema = Schema.Record(AppLocaleCodeSchema, Schema.optional(QuestionResponseSourceSchema));
+/** Editorial blueprint coordinates used to prove assessment coverage. */
+export const QuestionBlueprintSchema = Schema.Struct({
+    cognitiveLevel: TryoutKeySchema,
+    contentDomain: TryoutKeySchema,
+    topic: TryoutKeySchema,
+});
+/** Serializes response shape and answer-key positions for locale comparison. */
+function responseStructure(response) {
+    if (response.kind === "category") {
+        return JSON.stringify({
+            categories: response.categories.length,
+            kind: response.kind,
+            statements: response.statements.map(({ correctCategoryOrder }) => correctCategoryOrder),
+        });
+    }
+    return JSON.stringify({
+        correctness: response.options.map(({ isCorrect }) => isCorrect),
+        kind: response.kind,
+    });
+}
+/** Requires locale siblings to preserve one response format and answer key. */
+function hasCoherentLocalizedResponses(input) {
+    const responses = Object.values(input.responses).filter((response) => response !== undefined);
+    const [first] = responses;
+    return (first !== undefined &&
+        responses.every((response) => responseStructure(response) === responseStructure(first)));
+}
+/** Complete source-owned item, including optional shared-stimulus identity. */
+export const QuestionItemSchema = Schema.Struct({
+    blueprint: Schema.optionalKey(QuestionBlueprintSchema),
+    responses: QuestionResponseSourceMapSchema,
+    stimulusKey: Schema.optionalKey(TryoutKeySchema),
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentLocalizedResponses, {
+    message: "Localized responses must preserve one format, structure, and answer key.",
+})));
+/** Returns blueprint facts in stable field order for signed canonicalizers. */
+export function canonicalQuestionBlueprint(blueprint) {
+    return {
+        cognitiveLevel: blueprint.cognitiveLevel,
+        contentDomain: blueprint.contentDomain,
+        topic: blueprint.topic,
+    };
+}
+/** One item does not contain the exact artifact locale it must assess. */
+export class QuestionResponseLocaleMissingError extends Schema.TaggedError()("QuestionResponseLocaleMissingError", { artifactLocale: ArtifactLocaleSchema }) {
+}
+/** Derives stable option keys and orders from source-authored array order. */
+function freezeOptions(options) {
+    return options.map(({ isCorrect, label }, index) => ({
+        isCorrect,
+        label,
+        optionKey: `option-${index + 1}`,
+        order: index + 1,
+    }));
+}
+/** Resolves and freezes one exact-locale response from an authored item. */
+export const questionResponseFor = Effect.fn("AksaraContracts.questionResponseFor")(function* (item, artifactLocale) {
+    const response = item.responses[artifactLocaleCode(artifactLocale)];
+    if (response === undefined) {
+        return yield* new QuestionResponseLocaleMissingError({ artifactLocale });
+    }
+    if (response.kind !== "category") {
+        return QuestionResponseSchema.make({
+            kind: response.kind,
+            options: freezeOptions(response.options),
+        });
+    }
+    return QuestionResponseSchema.make({
+        categories: response.categories.map((label, index) => ({
+            categoryKey: `category-${index + 1}`,
+            label,
+            order: index + 1,
+        })),
+        kind: response.kind,
+        statements: response.statements.map(({ correctCategoryOrder, label }, index) => ({
+            correctCategoryKey: `category-${correctCategoryOrder}`,
+            label,
+            order: index + 1,
+            statementKey: `statement-${index + 1}`,
+        })),
+    });
+});

package/dist/question/response.d.ts

@@ -0,0 +1,175 @@
+import { Schema } from "effect";
+/** One semantic text or mathematics fragment in a response label. */
+export declare const QuestionResponseContentPartSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+    readonly kind: Schema.Literal<"math">;
+    readonly math: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"text">;
+    readonly text: Schema.String;
+}>]>;
+export type QuestionResponseContentPart = typeof QuestionResponseContentPartSchema.Type;
+/** Ordered semantic content rendered without reparsing delimiter strings. */
+export declare const QuestionResponseContentSchema: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+    readonly display: Schema.Literals<readonly ["block", "inline"]>;
+    readonly kind: Schema.Literal<"math">;
+    readonly math: Schema.String;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"text">;
+    readonly text: Schema.String;
+}>]>>;
+export type QuestionResponseContent = typeof QuestionResponseContentSchema.Type;
+/** Response formats supported by one assessment item. */
+export declare const QuestionResponseKindSchema: Schema.Literals<readonly ["category", "multiple-choice", "single-choice"]>;
+export type QuestionResponseKind = typeof QuestionResponseKindSchema.Type;
+/** Frozen locale-specific response used from publication through review. */
+export declare const QuestionResponseSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly categories: Schema.$Array<Schema.Struct<{
+        readonly categoryKey: Schema.String;
+        readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly display: Schema.Literals<readonly ["block", "inline"]>;
+            readonly kind: Schema.Literal<"math">;
+            readonly math: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"text">;
+            readonly text: Schema.String;
+        }>]>>;
+        readonly order: Schema.Int;
+    }>>;
+    readonly kind: Schema.Literal<"category">;
+    readonly statements: Schema.$Array<Schema.Struct<{
+        readonly correctCategoryKey: Schema.String;
+        readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly display: Schema.Literals<readonly ["block", "inline"]>;
+            readonly kind: Schema.Literal<"math">;
+            readonly math: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"text">;
+            readonly text: Schema.String;
+        }>]>>;
+        readonly order: Schema.Int;
+        readonly statementKey: Schema.String;
+    }>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"multiple-choice">;
+    readonly options: Schema.$Array<Schema.Struct<{
+        readonly isCorrect: Schema.Boolean;
+        readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly display: Schema.Literals<readonly ["block", "inline"]>;
+            readonly kind: Schema.Literal<"math">;
+            readonly math: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"text">;
+            readonly text: Schema.String;
+        }>]>>;
+        readonly optionKey: Schema.String;
+        readonly order: Schema.Int;
+    }>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"single-choice">;
+    readonly options: Schema.$Array<Schema.Struct<{
+        readonly isCorrect: Schema.Boolean;
+        readonly label: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly display: Schema.Literals<readonly ["block", "inline"]>;
+            readonly kind: Schema.Literal<"math">;
+            readonly math: Schema.String;
+        }>, Schema.Struct<{
+            readonly kind: Schema.Literal<"text">;
+            readonly text: Schema.String;
+        }>]>>;
+        readonly optionKey: Schema.String;
+        readonly order: Schema.Int;
+    }>>;
+}>]>;
+export type QuestionResponse = typeof QuestionResponseSchema.Type;
+/** Returns response content in stable field order for signed canonicalizers. */
+export declare function canonicalQuestionResponseContent(content: QuestionResponseContent): ({
+    kind: "text";
+    text: string;
+    display?: never;
+    math?: never;
+} | {
+    text?: never;
+    display: "block" | "inline";
+    kind: "math";
+    math: string;
+})[];
+/** Returns locale-neutral response identity without localized label content. */
+export declare function canonicalQuestionResponseStructure(response: QuestionResponse): {
+    categories: {
+        categoryKey: string;
+        order: number;
+    }[];
+    kind: "category";
+    statements: {
+        correctCategoryKey: string;
+        order: number;
+        statementKey: string;
+    }[];
+    options?: never;
+} | {
+    categories?: never;
+    statements?: never;
+    kind: "multiple-choice" | "single-choice";
+    options: {
+        isCorrect: boolean;
+        optionKey: string;
+        order: number;
+    }[];
+};
+/** Returns response facts in stable field order for signed canonicalizers. */
+export declare function canonicalQuestionResponse(response: QuestionResponse): {
+    options?: never;
+    categories: {
+        categoryKey: string;
+        label: ({
+            kind: "text";
+            text: string;
+            display?: never;
+            math?: never;
+        } | {
+            text?: never;
+            display: "block" | "inline";
+            kind: "math";
+            math: string;
+        })[];
+        order: number;
+    }[];
+    kind: "category";
+    statements: {
+        correctCategoryKey: string;
+        label: ({
+            kind: "text";
+            text: string;
+            display?: never;
+            math?: never;
+        } | {
+            text?: never;
+            display: "block" | "inline";
+            kind: "math";
+            math: string;
+        })[];
+        order: number;
+        statementKey: string;
+    }[];
+} | {
+    categories?: never;
+    statements?: never;
+    kind: "multiple-choice" | "single-choice";
+    options: {
+        isCorrect: boolean;
+        label: ({
+            kind: "text";
+            text: string;
+            display?: never;
+            math?: never;
+        } | {
+            text?: never;
+            display: "block" | "inline";
+            kind: "math";
+            math: string;
+        })[];
+        optionKey: string;
+        order: number;
+    }[];
+};

package/dist/question/response.js

@@ -0,0 +1,150 @@
+import { Schema } from "effect";
+const OPTION_KEY_PATTERN = /^option-[1-9]\d*$/u;
+const CATEGORY_KEY_PATTERN = /^category-[1-9]\d*$/u;
+const STATEMENT_KEY_PATTERN = /^statement-[1-9]\d*$/u;
+const PositiveOrderSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)));
+const NonEmptyContentSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => value.length > 0, {
+    message: "Response content parts must not be empty.",
+})));
+const QuestionResponseTextPartSchema = Schema.Struct({
+    kind: Schema.Literal("text"),
+    text: NonEmptyContentSchema,
+});
+const QuestionResponseMathPartSchema = Schema.Struct({
+    display: Schema.Literals(["block", "inline"]),
+    kind: Schema.Literal("math"),
+    math: NonEmptyContentSchema,
+});
+/** One semantic text or mathematics fragment in a response label. */
+export const QuestionResponseContentPartSchema = Schema.Union([
+    QuestionResponseMathPartSchema,
+    QuestionResponseTextPartSchema,
+]);
+/** Ordered semantic content rendered without reparsing delimiter strings. */
+export const QuestionResponseContentSchema = Schema.NonEmptyArray(QuestionResponseContentPartSchema);
+/** Response formats supported by one assessment item. */
+export const QuestionResponseKindSchema = Schema.Literals([
+    "category",
+    "multiple-choice",
+    "single-choice",
+]);
+const QuestionOptionSchema = Schema.Struct({
+    isCorrect: Schema.Boolean,
+    label: QuestionResponseContentSchema,
+    optionKey: Schema.String.pipe(Schema.check(Schema.isPattern(OPTION_KEY_PATTERN))),
+    order: PositiveOrderSchema,
+});
+/** Checks stable option identities, order, and format-specific correctness. */
+function hasCanonicalOptions(options, kind) {
+    const correct = options.filter(({ isCorrect }) => isCorrect).length;
+    return (options.length >= 2 &&
+        options.every(({ optionKey, order }, index) => order === index + 1 && optionKey === `option-${order}`) &&
+        (kind === "single-choice"
+            ? correct === 1
+            : correct >= 2 && correct < options.length));
+}
+const SingleChoiceResponseSchema = Schema.Struct({
+    kind: Schema.Literal("single-choice"),
+    options: Schema.Array(QuestionOptionSchema),
+}).pipe(Schema.check(Schema.makeFilter(({ options }) => hasCanonicalOptions(options, "single-choice"), {
+    message: "Single-choice responses require canonical options and one correct answer.",
+})));
+const MultipleChoiceResponseSchema = Schema.Struct({
+    kind: Schema.Literal("multiple-choice"),
+    options: Schema.Array(QuestionOptionSchema),
+}).pipe(Schema.check(Schema.makeFilter(({ options }) => hasCanonicalOptions(options, "multiple-choice"), {
+    message: "Multiple-choice responses require canonical options, several correct answers, and one distractor.",
+})));
+const QuestionCategorySchema = Schema.Struct({
+    categoryKey: Schema.String.pipe(Schema.check(Schema.isPattern(CATEGORY_KEY_PATTERN))),
+    label: QuestionResponseContentSchema,
+    order: PositiveOrderSchema,
+});
+const QuestionCategoryStatementSchema = Schema.Struct({
+    correctCategoryKey: Schema.String.pipe(Schema.check(Schema.isPattern(CATEGORY_KEY_PATTERN))),
+    label: QuestionResponseContentSchema,
+    order: PositiveOrderSchema,
+    statementKey: Schema.String.pipe(Schema.check(Schema.isPattern(STATEMENT_KEY_PATTERN))),
+});
+/** Checks stable category and statement identities plus valid references. */
+function hasCanonicalCategories(input) {
+    const categoryKeys = new Set(input.categories.map(({ categoryKey }) => categoryKey));
+    return (input.categories.length >= 2 &&
+        input.statements.length > 0 &&
+        input.categories.every(({ categoryKey, order }, index) => order === index + 1 && categoryKey === `category-${order}`) &&
+        input.statements.every(({ correctCategoryKey, order, statementKey }, index) => order === index + 1 &&
+            statementKey === `statement-${order}` &&
+            categoryKeys.has(correctCategoryKey)));
+}
+const CategoryResponseSchema = Schema.Struct({
+    categories: Schema.Array(QuestionCategorySchema),
+    kind: Schema.Literal("category"),
+    statements: Schema.Array(QuestionCategoryStatementSchema),
+}).pipe(Schema.check(Schema.makeFilter(hasCanonicalCategories, {
+    message: "Category responses require canonical categories and classified statements.",
+})));
+/** Frozen locale-specific response used from publication through review. */
+export const QuestionResponseSchema = Schema.Union([
+    CategoryResponseSchema,
+    MultipleChoiceResponseSchema,
+    SingleChoiceResponseSchema,
+]);
+/** Returns response content in stable field order for signed canonicalizers. */
+export function canonicalQuestionResponseContent(content) {
+    return content.map((part) => part.kind === "text"
+        ? { kind: part.kind, text: part.text }
+        : { display: part.display, kind: part.kind, math: part.math });
+}
+/** Returns locale-neutral response identity without localized label content. */
+export function canonicalQuestionResponseStructure(response) {
+    if (response.kind === "category") {
+        return {
+            categories: response.categories.map(({ categoryKey, order }) => ({
+                categoryKey,
+                order,
+            })),
+            kind: response.kind,
+            statements: response.statements.map(({ correctCategoryKey, order, statementKey }) => ({
+                correctCategoryKey,
+                order,
+                statementKey,
+            })),
+        };
+    }
+    return {
+        kind: response.kind,
+        options: response.options.map(({ isCorrect, optionKey, order }) => ({
+            isCorrect,
+            optionKey,
+            order,
+        })),
+    };
+}
+/** Returns response facts in stable field order for signed canonicalizers. */
+export function canonicalQuestionResponse(response) {
+    if (response.kind === "category") {
+        return {
+            categories: response.categories.map(({ categoryKey, label, order }) => ({
+                categoryKey,
+                label: canonicalQuestionResponseContent(label),
+                order,
+            })),
+            kind: response.kind,
+            statements: response.statements.map(({ correctCategoryKey, label, order, statementKey }) => ({
+                correctCategoryKey,
+                label: canonicalQuestionResponseContent(label),
+                order,
+                statementKey,
+            })),
+        };
+    }
+    return {
+        kind: response.kind,
+        options: response.options.map(({ isCorrect, label, optionKey, order }) => ({
+            isCorrect,
+            label: canonicalQuestionResponseContent(label),
+            optionKey,
+            order,
+        })),
+    };
+}

package/dist/quran/attribution.d.ts

@@ -0,0 +1,48 @@
+import type { QuranSourceAttribution } from "#contracts/quran/source";
+/** Serializes one source attribution without trusting object insertion order. */
+export declare function canonicalizeQuranAttribution(attribution: QuranSourceAttribution): {
+    copy: {
+        appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        notice: string;
+        title: string;
+    }[];
+    id: "bubenheim-names" | "kemenag-names" | "mokhtasar-english" | "mokhtasar-german" | "quranenc-english" | "quranenc-german" | "quranenc-indonesian" | "quranenc-tafsir" | "tanzil-metadata" | "tanzil-text";
+    kind: "embedded" | "external";
+    publisher: string;
+    retrievedAt: string;
+    sourceUrl: string;
+    terms: {
+        access: "link-only";
+        url: string;
+        artifact?: never;
+    };
+    updateUrl: string;
+    version: string;
+} | {
+    copy: {
+        appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        notice: string;
+        title: string;
+    }[];
+    id: "bubenheim-names" | "kemenag-names" | "mokhtasar-english" | "mokhtasar-german" | "quranenc-english" | "quranenc-german" | "quranenc-indonesian" | "quranenc-tafsir" | "tanzil-metadata" | "tanzil-text";
+    kind: "embedded" | "external";
+    publisher: string;
+    retrievedAt: string;
+    sourceUrl: string;
+    artifact: {
+        byteCount: number;
+        digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+        fileCount: number;
+    };
+    terms: {
+        access?: never;
+        artifact: {
+            byteCount: number;
+            digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+            fileCount: number;
+        };
+        url: string;
+    };
+    updateUrl: string;
+    version: string;
+};

package/dist/quran/attribution.js

@@ -0,0 +1,44 @@
+/** Serializes one source attribution without trusting object insertion order. */
+export function canonicalizeQuranAttribution(attribution) {
+    const common = {
+        copy: attribution.copy.map((entry) => ({
+            appLocale: entry.appLocale,
+            notice: entry.notice,
+            title: entry.title,
+        })),
+        id: attribution.id,
+        kind: attribution.kind,
+        publisher: attribution.publisher,
+        retrievedAt: attribution.retrievedAt,
+        sourceUrl: attribution.sourceUrl,
+    };
+    if (attribution.kind === "external") {
+        return {
+            ...common,
+            terms: {
+                access: attribution.terms.access,
+                url: attribution.terms.url,
+            },
+            updateUrl: attribution.updateUrl,
+            version: attribution.version,
+        };
+    }
+    return {
+        artifact: {
+            byteCount: attribution.artifact.byteCount,
+            digest: attribution.artifact.digest,
+            fileCount: attribution.artifact.fileCount,
+        },
+        ...common,
+        terms: {
+            artifact: {
+                byteCount: attribution.terms.artifact.byteCount,
+                digest: attribution.terms.artifact.digest,
+                fileCount: attribution.terms.artifact.fileCount,
+            },
+            url: attribution.terms.url,
+        },
+        updateUrl: attribution.updateUrl,
+        version: attribution.version,
+    };
+}

package/dist/quran/identity.d.ts

@@ -0,0 +1,105 @@
+import { Schema } from "effect";
+import { type AppLocaleCode, ENGLISH_APP_LOCALE_CODE, GERMAN_APP_LOCALE_CODE, INDONESIAN_APP_LOCALE_CODE } from "#contracts/locale";
+/** Official source identities whose bytes are pinned inside Aksara. */
+export declare const QuranEmbeddedSourceIdSchema: Schema.Literals<readonly ["tanzil-text", "tanzil-metadata", "kemenag-names", "bubenheim-names", "quranenc-english", "quranenc-indonesian", "quranenc-german", "quranenc-tafsir"]>;
+export type QuranEmbeddedSourceId = typeof QuranEmbeddedSourceIdSchema.Type;
+/** Official source identities that Aksara may link to but not republish. */
+export declare const QuranExternalSourceIdSchema: Schema.Literals<readonly ["mokhtasar-english", "mokhtasar-german"]>;
+export type QuranExternalSourceId = typeof QuranExternalSourceIdSchema.Type;
+/** Exact official Quran source identities in visible attribution order. */
+export declare const QuranSourceIdSchema: Schema.Literals<readonly ["tanzil-text", "tanzil-metadata", "kemenag-names", "bubenheim-names", "quranenc-english", "quranenc-indonesian", "quranenc-german", "quranenc-tafsir", "mokhtasar-english", "mokhtasar-german"]>;
+export type QuranSourceId = typeof QuranSourceIdSchema.Type;
+/** Canonical order of every official source supported by the contract. */
+export declare const QURAN_SOURCE_IDS: readonly ["tanzil-text", "tanzil-metadata", "kemenag-names", "bubenheim-names", "quranenc-english", "quranenc-indonesian", "quranenc-german", "quranenc-tafsir", "mokhtasar-english", "mokhtasar-german"];
+/** Locale-specific translation field in Quran source provenance. */
+export declare const QuranTranslationProvenanceScopeSchema: Schema.TemplateLiteral<readonly [Schema.Literals<readonly ["en", "id", "de"]>, "-translation"]>;
+export type QuranTranslationProvenanceScope = typeof QuranTranslationProvenanceScopeSchema.Type;
+/** Locale-specific surah-name field in Quran source provenance. */
+export declare const QuranNameProvenanceScopeSchema: Schema.TemplateLiteral<readonly [Schema.Literals<readonly ["en", "id", "de"]>, "-surah-name"]>;
+export type QuranNameProvenanceScope = typeof QuranNameProvenanceScopeSchema.Type;
+declare const QURAN_NAME_BY_LOCALE: {
+    readonly en: {
+        readonly scope: "en-surah-name";
+        readonly sourceId: "tanzil-metadata";
+    };
+    readonly de: {
+        readonly scope: "de-surah-name";
+        readonly sourceId: "bubenheim-names";
+    };
+    readonly id: {
+        readonly scope: "id-surah-name";
+        readonly sourceId: "kemenag-names";
+    };
+};
+declare const QURAN_TRANSLATION_BY_LOCALE: {
+    readonly en: {
+        readonly scope: "en-translation";
+        readonly sourceId: "quranenc-english";
+    };
+    readonly de: {
+        readonly scope: "de-translation";
+        readonly sourceId: "quranenc-german";
+    };
+    readonly id: {
+        readonly scope: "id-translation";
+        readonly sourceId: "quranenc-indonesian";
+    };
+};
+declare const QURAN_TAFSIR_BY_LOCALE: {
+    readonly en: {
+        readonly sourceId: "mokhtasar-english";
+    };
+    readonly de: {
+        readonly sourceId: "mokhtasar-german";
+    };
+    readonly id: {
+        readonly sourceId: "quranenc-tafsir";
+    };
+};
+/** Selects the reviewed surah-name source for an application locale. */
+export declare function quranNameSourceId(appLocale: typeof ENGLISH_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof ENGLISH_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the Indonesian surah-name source identity. */
+export declare function quranNameSourceId(appLocale: typeof INDONESIAN_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof INDONESIAN_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the German surah-name source identity. */
+export declare function quranNameSourceId(appLocale: typeof GERMAN_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof GERMAN_APP_LOCALE_CODE]["sourceId"];
+/** Selects a surah-name source from a dynamic supported locale. */
+export declare function quranNameSourceId(appLocale: AppLocaleCode): QuranEmbeddedSourceId;
+/** Selects the surah-name provenance scope for an application locale. */
+export declare function quranNameProvenanceScope(appLocale: typeof ENGLISH_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof ENGLISH_APP_LOCALE_CODE]["scope"];
+/** Narrows the Indonesian surah-name provenance scope. */
+export declare function quranNameProvenanceScope(appLocale: typeof INDONESIAN_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof INDONESIAN_APP_LOCALE_CODE]["scope"];
+/** Narrows the German surah-name provenance scope. */
+export declare function quranNameProvenanceScope(appLocale: typeof GERMAN_APP_LOCALE_CODE): (typeof QURAN_NAME_BY_LOCALE)[typeof GERMAN_APP_LOCALE_CODE]["scope"];
+/** Selects a surah-name provenance scope from a dynamic locale. */
+export declare function quranNameProvenanceScope(appLocale: AppLocaleCode): QuranNameProvenanceScope;
+/** Selects the one pinned translation source for an application locale. */
+export declare function quranTranslationSourceId(appLocale: typeof ENGLISH_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof ENGLISH_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the Indonesian translation source identity. */
+export declare function quranTranslationSourceId(appLocale: typeof INDONESIAN_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof INDONESIAN_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the German translation source identity. */
+export declare function quranTranslationSourceId(appLocale: typeof GERMAN_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof GERMAN_APP_LOCALE_CODE]["sourceId"];
+/** Selects a translation source from a dynamic supported locale. */
+export declare function quranTranslationSourceId(appLocale: AppLocaleCode): QuranEmbeddedSourceId;
+/** Selects the one signed Tafsir source or access record for a locale. */
+export declare function quranTafsirSourceId(appLocale: typeof ENGLISH_APP_LOCALE_CODE): (typeof QURAN_TAFSIR_BY_LOCALE)[typeof ENGLISH_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the Indonesian Tafsir source identity. */
+export declare function quranTafsirSourceId(appLocale: typeof INDONESIAN_APP_LOCALE_CODE): (typeof QURAN_TAFSIR_BY_LOCALE)[typeof INDONESIAN_APP_LOCALE_CODE]["sourceId"];
+/** Narrows the German Tafsir source identity. */
+export declare function quranTafsirSourceId(appLocale: typeof GERMAN_APP_LOCALE_CODE): (typeof QURAN_TAFSIR_BY_LOCALE)[typeof GERMAN_APP_LOCALE_CODE]["sourceId"];
+/** Selects a Tafsir source from a dynamic supported locale. */
+export declare function quranTafsirSourceId(appLocale: AppLocaleCode): QuranSourceId;
+/** Selects the one provenance scope for an application locale. */
+export declare function quranTranslationProvenanceScope(appLocale: typeof ENGLISH_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof ENGLISH_APP_LOCALE_CODE]["scope"];
+/** Narrows the Indonesian translation provenance scope. */
+export declare function quranTranslationProvenanceScope(appLocale: typeof INDONESIAN_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof INDONESIAN_APP_LOCALE_CODE]["scope"];
+/** Narrows the German translation provenance scope. */
+export declare function quranTranslationProvenanceScope(appLocale: typeof GERMAN_APP_LOCALE_CODE): (typeof QURAN_TRANSLATION_BY_LOCALE)[typeof GERMAN_APP_LOCALE_CODE]["scope"];
+/** Selects a translation provenance scope from a dynamic locale. */
+export declare function quranTranslationProvenanceScope(appLocale: AppLocaleCode): QuranTranslationProvenanceScope;
+/** Resolves a translation provenance scope through the canonical locale map. */
+export declare function quranTranslationSourceForScope(scope: QuranTranslationProvenanceScope): "quranenc-english" | "quranenc-german" | "quranenc-indonesian";
+/** Resolves a surah-name provenance scope through the canonical locale map. */
+export declare function quranNameSourceForScope(scope: QuranNameProvenanceScope): "bubenheim-names" | "kemenag-names" | "tanzil-metadata";
+/** Selects the signed Arabic and localized translation reading sources. */
+export declare function quranReadingSourceIds(appLocale: AppLocaleCode): readonly ["tanzil-text", "bubenheim-names" | "kemenag-names" | "quranenc-english" | "quranenc-german" | "quranenc-indonesian" | "quranenc-tafsir" | "tanzil-metadata" | "tanzil-text"];
+export {};