@nakafa/aksara-contracts 0.27.0

package/dist/transport/snapshot.js

@@ -0,0 +1,70 @@
+import { Schema } from "effect";
+import { ReleaseIdSchema, Sha256HashSchema } from "#contracts/ids";
+import { ContentSnapshotManifestSchema, ContentSnapshotRowSchema, } from "#contracts/release/snapshot/data";
+import { ContentSnapshotKindSchema } from "#contracts/release/snapshot/scope";
+import { MAX_SNAPSHOT_BATCH_COUNT } from "#contracts/transport/limits";
+const BatchIndexSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+const BatchCountSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+const OutcomeCountSchema = Schema.Literals([0, 1]);
+const StageSnapshotFields = {
+    releaseId: ReleaseIdSchema,
+    snapshot: ContentSnapshotManifestSchema,
+};
+/** Canonical input for staging one immutable structured-family manifest. */
+export const StageSnapshotInputSchema = Schema.Struct(StageSnapshotFields);
+/** Stages one immutable structured-family manifest before any of its rows. */
+export const StageSnapshotRequestSchema = Schema.Struct({
+    ...StageSnapshotFields,
+    operation: Schema.Literal("stageSnapshot"),
+});
+const SnapshotRowBatchSchema = Schema.NonEmptyArray(ContentSnapshotRowSchema).pipe(Schema.check(Schema.isMaxLength(MAX_SNAPSHOT_BATCH_COUNT)));
+const StageSnapshotBatchFields = {
+    batchIndex: BatchIndexSchema,
+    family: ContentSnapshotKindSchema,
+    releaseId: ReleaseIdSchema,
+    rows: SnapshotRowBatchSchema,
+    snapshotId: Sha256HashSchema,
+};
+/** Checks that every row belongs to the envelope and Quran snapshot identity. */
+function hasBoundSnapshotRows(input) {
+    return input.rows.every((row) => {
+        if (row.family !== input.family) {
+            return false;
+        }
+        if (row.family !== "quran") {
+            return true;
+        }
+        return row.record.snapshotId === input.snapshotId;
+    });
+}
+const BoundSnapshotBatchSchema = Schema.Struct(StageSnapshotBatchFields).pipe(Schema.check(Schema.makeFilter(hasBoundSnapshotRows, {
+    message: "Expected snapshot rows bound to one family and snapshot identity.",
+})));
+/** Canonical input for one bounded structured-snapshot row batch. */
+export const StageSnapshotBatchInputSchema = BoundSnapshotBatchSchema;
+/** Stages one non-empty bounded structured-snapshot row batch. */
+export const StageSnapshotBatchRequestSchema = Schema.Struct({
+    ...StageSnapshotBatchFields,
+    operation: Schema.Literal("stageSnapshotBatch"),
+}).pipe(Schema.check(Schema.makeFilter(hasBoundSnapshotRows, {
+    message: "Expected snapshot rows bound to one family and snapshot identity.",
+})));
+/** Idempotent outcome bound to one exact structured-snapshot row batch. */
+export const StageSnapshotBatchReceiptSchema = Schema.Struct({
+    batchIndex: BatchIndexSchema,
+    created: BatchCountSchema,
+    family: ContentSnapshotKindSchema,
+    releaseId: ReleaseIdSchema,
+    snapshotId: Sha256HashSchema,
+    unchanged: BatchCountSchema,
+});
+/** Idempotent outcome for staging exactly one family manifest. */
+export const StageSnapshotReceiptSchema = Schema.Struct({
+    created: OutcomeCountSchema,
+    family: ContentSnapshotKindSchema,
+    releaseId: ReleaseIdSchema,
+    snapshotId: Sha256HashSchema,
+    unchanged: OutcomeCountSchema,
+}).pipe(Schema.check(Schema.makeFilter(({ created, unchanged }) => created + unchanged === 1, {
+    message: "Expected exactly one created or unchanged snapshot manifest.",
+})));

package/dist/tryout/canonical.d.ts

@@ -0,0 +1,2 @@
+/** Computes one domain-separated canonical try-out SHA-256 identity. */
+export declare function hashTryoutCanonical(domain: string, canonical: string): string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;

package/dist/tryout/canonical.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+import { Sha256HashSchema } from "#contracts/ids";
+/** Computes one domain-separated canonical try-out SHA-256 identity. */
+export function hashTryoutCanonical(domain, canonical) {
+    const digest = createHash("sha256")
+        .update(domain)
+        .update("\n")
+        .update(canonical)
+        .digest("hex");
+    return Sha256HashSchema.make(`sha256:${digest}`);
+}

package/dist/tryout/catalog-hash.d.ts

@@ -0,0 +1,134 @@
+import { Effect, type Stream } from "effect";
+import { type TryoutCatalogRecord, type TryoutCatalogRow } from "#contracts/tryout/catalog";
+/** Compares localized hierarchy rows in their canonical digest order. */
+export declare function compareTryoutCatalog(left: TryoutCatalogRow, right: TryoutCatalogRow): -1 | 0 | 1;
+/** Builds one locale-neutral hierarchy identity for closure checks. */
+export declare function tryoutCatalogLogicalIdentity(row: TryoutCatalogRow): string;
+/** Builds the locale-neutral catalog identity of one section reference. */
+export declare function tryoutSectionLogicalIdentity(input: {
+    readonly countryKey: string;
+    readonly examKey: string;
+    readonly sectionKey: string;
+    readonly setKey: string;
+    readonly trackKey: string;
+}): string;
+/** Serializes locale-neutral catalog facts for cross-locale closure checks. */
+export declare function canonicalizeTryoutCatalogFacts(row: TryoutCatalogRow): string;
+/** Serializes one current hierarchy row in stable field order. */
+export declare function canonicalizeTryoutCatalog(row: TryoutCatalogRow): string;
+/** Creates one authenticated current hierarchy record. */
+export declare function makeTryoutCatalogRecord(row: TryoutCatalogRow): TryoutCatalogRecord;
+/** Digests canonically ordered current hierarchy records. */
+export declare const digestTryoutCatalog: <E, R>(records: Stream.Stream<{
+    readonly row: {
+        readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        readonly description?: string | undefined;
+        readonly graph: {
+            readonly alignmentId: string;
+            readonly assetId: string;
+            readonly conceptId: string;
+            readonly learningObjectId: string;
+            readonly lensId: string;
+        };
+        readonly sourceRevision: string;
+        readonly title: string;
+        readonly countryKey: string;
+        readonly examKey: string;
+        readonly kind: "track";
+        readonly order: number;
+        readonly publicPath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">;
+        readonly questionCount: number;
+        readonly sectionCount: number;
+        readonly setCount: number;
+        readonly trackKey: string;
+        readonly trackKind: "subject" | "year";
+        readonly visibleSectionCount: number;
+    } | {
+        readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        readonly description?: string | undefined;
+        readonly graph: {
+            readonly alignmentId: string;
+            readonly assetId: string;
+            readonly conceptId: string;
+            readonly learningObjectId: string;
+            readonly lensId: string;
+        };
+        readonly sourceRevision: string;
+        readonly title: string;
+        readonly countryKey: string;
+        readonly examKey: string;
+        readonly internalEntrySectionKey?: string | undefined;
+        readonly kind: "set";
+        readonly order: number;
+        readonly publicPath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">;
+        readonly questionCount: number;
+        readonly scoringStrategy: "irt" | "raw";
+        readonly sectionCount: number;
+        readonly setKey: string;
+        readonly trackKey: string;
+        readonly visibleSectionCount: number;
+    } | {
+        readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        readonly description?: string | undefined;
+        readonly graph: {
+            readonly alignmentId: string;
+            readonly assetId: string;
+            readonly conceptId: string;
+            readonly learningObjectId: string;
+            readonly lensId: string;
+        };
+        readonly sourceRevision: string;
+        readonly title: string;
+        readonly countryKey: string;
+        readonly examKey: string;
+        readonly kind: "section";
+        readonly order: number;
+        readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+        readonly questionCount: number;
+        readonly questionSourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+        readonly sectionKey: string;
+        readonly setKey: string;
+        readonly timeLimitSeconds: number;
+        readonly trackKey: string;
+        readonly visibility: "internal-entry" | "visible";
+    } | {
+        readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        readonly description?: string | undefined;
+        readonly graph: {
+            readonly alignmentId: string;
+            readonly assetId: string;
+            readonly conceptId: string;
+            readonly learningObjectId: string;
+            readonly lensId: string;
+        };
+        readonly sourceRevision: string;
+        readonly title: string;
+        readonly countryCode: string;
+        readonly countryKey: string;
+        readonly kind: "country";
+        readonly order: number;
+        readonly publicPath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">;
+    } | {
+        readonly appLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">;
+        readonly description?: string | undefined;
+        readonly graph: {
+            readonly alignmentId: string;
+            readonly assetId: string;
+            readonly conceptId: string;
+            readonly learningObjectId: string;
+            readonly lensId: string;
+        };
+        readonly sourceRevision: string;
+        readonly title: string;
+        readonly countryKey: string;
+        readonly examKey: string;
+        readonly kind: "exam";
+        readonly order: number;
+        readonly publicPath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">;
+        readonly scoringStrategy: "irt" | "raw";
+    };
+    readonly rowHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E, R>) => Effect.Effect<{
+    count: number;
+    digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E | import("#contracts/tryout/row-hash").TryoutDigestError, R>;

package/dist/tryout/catalog-hash.js

@@ -0,0 +1,203 @@
+import { Effect } from "effect";
+import { canonicalizeLearningGraphIdentity } from "#contracts/graph/spec";
+import { compareCodeUnits } from "#contracts/text/order";
+import { hashTryoutCanonical } from "#contracts/tryout/canonical";
+import { TryoutCatalogRecordSchema, } from "#contracts/tryout/catalog";
+import { tryoutCatalogIdentity } from "#contracts/tryout/identity";
+import { digestTryoutRecords } from "#contracts/tryout/row-hash";
+const CATALOG_DOMAIN = "nakafa.aksara.tryout-catalog";
+/** Includes an optional field without serializing absence as null. */
+function optionalField(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/** Compares localized hierarchy rows in their canonical digest order. */
+export function compareTryoutCatalog(left, right) {
+    return compareCodeUnits(tryoutCatalogIdentity(left), tryoutCatalogIdentity(right));
+}
+/** Builds one locale-neutral hierarchy identity for closure checks. */
+export function tryoutCatalogLogicalIdentity(row) {
+    return [
+        row.kind,
+        row.countryKey,
+        "examKey" in row ? row.examKey : "",
+        "trackKey" in row ? row.trackKey : "",
+        "setKey" in row ? row.setKey : "",
+        "sectionKey" in row ? row.sectionKey : "",
+    ].join("\0");
+}
+/** Builds the locale-neutral catalog identity of one section reference. */
+export function tryoutSectionLogicalIdentity(input) {
+    return [
+        "section",
+        input.countryKey,
+        input.examKey,
+        input.trackKey,
+        input.setKey,
+        input.sectionKey,
+    ].join("\0");
+}
+/** Serializes locale-neutral catalog facts for cross-locale closure checks. */
+export function canonicalizeTryoutCatalogFacts(row) {
+    const graph = {
+        alignmentId: row.graph.alignmentId,
+        conceptId: row.graph.conceptId,
+        learningObjectId: row.graph.learningObjectId,
+        lensId: row.graph.lensId,
+    };
+    const shared = {
+        graph,
+        kind: row.kind,
+        order: row.order,
+        sourceRevision: row.sourceRevision,
+    };
+    if (row.kind === "country") {
+        return JSON.stringify({
+            ...shared,
+            countryCode: row.countryCode,
+            countryKey: row.countryKey,
+        });
+    }
+    if (row.kind === "exam") {
+        return JSON.stringify({
+            ...shared,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            scoringStrategy: row.scoringStrategy,
+        });
+    }
+    if (row.kind === "track") {
+        return JSON.stringify({
+            ...shared,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            questionCount: row.questionCount,
+            sectionCount: row.sectionCount,
+            setCount: row.setCount,
+            trackKey: row.trackKey,
+            trackKind: row.trackKind,
+            visibleSectionCount: row.visibleSectionCount,
+        });
+    }
+    if (row.kind === "set") {
+        return JSON.stringify({
+            ...shared,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            ...optionalField("internalEntrySectionKey", row.internalEntrySectionKey),
+            questionCount: row.questionCount,
+            scoringStrategy: row.scoringStrategy,
+            sectionCount: row.sectionCount,
+            setKey: row.setKey,
+            trackKey: row.trackKey,
+            visibleSectionCount: row.visibleSectionCount,
+        });
+    }
+    return JSON.stringify({
+        ...shared,
+        countryKey: row.countryKey,
+        examKey: row.examKey,
+        questionCount: row.questionCount,
+        questionSourcePath: row.questionSourcePath,
+        sectionKey: row.sectionKey,
+        setKey: row.setKey,
+        timeLimitSeconds: row.timeLimitSeconds,
+        trackKey: row.trackKey,
+        visibility: row.visibility,
+    });
+}
+/** Serializes one current hierarchy row in stable field order. */
+export function canonicalizeTryoutCatalog(row) {
+    const localized = {
+        appLocale: row.appLocale,
+        ...optionalField("description", row.description),
+        graph: canonicalizeLearningGraphIdentity(row.graph),
+        sourceRevision: row.sourceRevision,
+        title: row.title,
+    };
+    if (row.kind === "country") {
+        return JSON.stringify({
+            ...localized,
+            countryCode: row.countryCode,
+            countryKey: row.countryKey,
+            kind: row.kind,
+            order: row.order,
+            publicPath: row.publicPath,
+        });
+    }
+    if (row.kind === "exam") {
+        return JSON.stringify({
+            ...localized,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            kind: row.kind,
+            order: row.order,
+            publicPath: row.publicPath,
+            scoringStrategy: row.scoringStrategy,
+        });
+    }
+    if (row.kind === "track") {
+        return JSON.stringify({
+            ...localized,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            kind: row.kind,
+            order: row.order,
+            publicPath: row.publicPath,
+            questionCount: row.questionCount,
+            sectionCount: row.sectionCount,
+            setCount: row.setCount,
+            trackKey: row.trackKey,
+            trackKind: row.trackKind,
+            visibleSectionCount: row.visibleSectionCount,
+        });
+    }
+    if (row.kind === "set") {
+        return JSON.stringify({
+            ...localized,
+            countryKey: row.countryKey,
+            examKey: row.examKey,
+            ...optionalField("internalEntrySectionKey", row.internalEntrySectionKey),
+            kind: row.kind,
+            order: row.order,
+            publicPath: row.publicPath,
+            questionCount: row.questionCount,
+            scoringStrategy: row.scoringStrategy,
+            sectionCount: row.sectionCount,
+            setKey: row.setKey,
+            trackKey: row.trackKey,
+            visibleSectionCount: row.visibleSectionCount,
+        });
+    }
+    return JSON.stringify({
+        ...localized,
+        countryKey: row.countryKey,
+        examKey: row.examKey,
+        kind: row.kind,
+        order: row.order,
+        ...optionalField("publicPath", row.publicPath),
+        questionCount: row.questionCount,
+        questionSourcePath: row.questionSourcePath,
+        sectionKey: row.sectionKey,
+        setKey: row.setKey,
+        timeLimitSeconds: row.timeLimitSeconds,
+        trackKey: row.trackKey,
+        visibility: row.visibility,
+    });
+}
+/** Creates one authenticated current hierarchy record. */
+export function makeTryoutCatalogRecord(row) {
+    return TryoutCatalogRecordSchema.make({
+        row,
+        rowHash: hashTryoutCanonical(CATALOG_DOMAIN, canonicalizeTryoutCatalog(row)),
+    });
+}
+/** Digests canonically ordered current hierarchy records. */
+export const digestTryoutCatalog = Effect.fn("AksaraContracts.digestTryoutCatalog")(function* (records) {
+    return yield* digestTryoutRecords({
+        canonicalize: canonicalizeTryoutCatalog,
+        domain: CATALOG_DOMAIN,
+        identity: tryoutCatalogIdentity,
+        records,
+        rowHash: (row) => makeTryoutCatalogRecord(row).rowHash,
+    });
+});