@nakafa/aksara-contracts 0.27.0

package/dist/release/snapshot/spec.js

@@ -0,0 +1,139 @@
+/** Signed structured snapshot transition contracts. */
+import { Schema } from "effect";
+import { Sha256HashSchema } from "#contracts/ids";
+import { ContentSnapshotKindSchema, publicationScopeSelectsSnapshot, } from "#contracts/release/snapshot/scope";
+/** Canonical digest for a release that stages no structured snapshot rows. */
+export const EMPTY_SNAPSHOT_ROW_DIGEST = Sha256HashSchema.make("sha256:eb27aa7f59e41b14a3f76d951c5a50cb954a19f3f6e6c44bc21a733f606e888f");
+const RowCountSchema = Schema.Int.pipe(Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+/** One family's immutable snapshot transition authenticated by a release. */
+export const ContentSnapshotStateSchema = Schema.Struct({
+    baseSnapshotId: Schema.NullOr(Sha256HashSchema),
+    mode: Schema.Literals(["inherit", "replace", "restore"]),
+    resultSnapshotId: Schema.NullOr(Sha256HashSchema),
+    rowCount: RowCountSchema,
+    rowDigest: Sha256HashSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentSnapshotState, {
+    message: "Expected a coherent structured snapshot transition.",
+})));
+/** Fixed snapshot states prevent a release from omitting one owned family. */
+export const ContentSnapshotSetSchema = Schema.Struct({
+    program: ContentSnapshotStateSchema,
+    quran: ContentSnapshotStateSchema,
+    tryout: ContentSnapshotStateSchema,
+});
+/** Requires every unselected structured family to remain inherited. */
+export function hasScopedSnapshotTransitions(scope, snapshots) {
+    return ContentSnapshotKindSchema.literals.every((family) => publicationScopeSelectsSnapshot(scope, family) ||
+        snapshots[family].mode === "inherit");
+}
+/** Checks inheritance, replacement, and forward restore row semantics. */
+export function hasCoherentSnapshotState(state) {
+    const changed = state.baseSnapshotId !== state.resultSnapshotId;
+    const empty = state.rowCount === 0 && state.rowDigest === EMPTY_SNAPSHOT_ROW_DIGEST;
+    if (state.mode === "inherit") {
+        return !changed && empty;
+    }
+    if (state.mode === "replace") {
+        return (changed &&
+            state.resultSnapshotId !== null &&
+            state.rowCount > 0 &&
+            state.rowDigest !== EMPTY_SNAPSHOT_ROW_DIGEST);
+    }
+    return changed && empty;
+}
+/** Builds a zero-row transition that preserves one immutable snapshot. */
+export function inheritContentSnapshot(snapshotId) {
+    return ContentSnapshotStateSchema.make({
+        baseSnapshotId: snapshotId,
+        mode: "inherit",
+        resultSnapshotId: snapshotId,
+        rowCount: 0,
+        rowDigest: EMPTY_SNAPSHOT_ROW_DIGEST,
+    });
+}
+/** Builds fixed inherited states from the prior release's result identities. */
+export function inheritContentSnapshots(previous) {
+    return ContentSnapshotSetSchema.make({
+        program: inheritContentSnapshot(previous?.program.resultSnapshotId ?? null),
+        quran: inheritContentSnapshot(previous?.quran.resultSnapshotId ?? null),
+        tryout: inheritContentSnapshot(previous?.tryout.resultSnapshotId ?? null),
+    });
+}
+/** Reconstructs inherited prior state from one signed transition's base IDs. */
+export function baseContentSnapshots(snapshots) {
+    return ContentSnapshotSetSchema.make({
+        program: inheritContentSnapshot(snapshots.program.baseSnapshotId),
+        quran: inheritContentSnapshot(snapshots.quran.baseSnapshotId),
+        tryout: inheritContentSnapshot(snapshots.tryout.baseSnapshotId),
+    });
+}
+/** Builds a full replacement transition for one prepared snapshot. */
+export function replaceContentSnapshot(input) {
+    return ContentSnapshotStateSchema.make({
+        ...input,
+        mode: "replace",
+    });
+}
+/** Builds a row-free forward restore to an existing or absent snapshot. */
+export function restoreContentSnapshot(baseSnapshotId, resultSnapshotId) {
+    return ContentSnapshotStateSchema.make({
+        baseSnapshotId,
+        mode: "restore",
+        resultSnapshotId,
+        rowCount: 0,
+        rowDigest: EMPTY_SNAPSHOT_ROW_DIGEST,
+    });
+}
+/** Builds the retained inverse without copying immutable snapshot rows. */
+export function invertContentSnapshots(snapshots) {
+    /** Inverts one changed family and preserves one unchanged family. */
+    const invert = (state) => state.baseSnapshotId === state.resultSnapshotId
+        ? inheritContentSnapshot(state.resultSnapshotId)
+        : restoreContentSnapshot(state.resultSnapshotId, state.baseSnapshotId);
+    return ContentSnapshotSetSchema.make({
+        program: invert(snapshots.program),
+        quran: invert(snapshots.quran),
+        tryout: invert(snapshots.tryout),
+    });
+}
+/** Checks that an initial release does not claim an unstated snapshot base. */
+export function hasEmptySnapshotBases(snapshots) {
+    return Object.values(snapshots).every(({ baseSnapshotId }) => baseSnapshotId === null);
+}
+/** Checks that a rollback only inherits or restores immutable snapshots. */
+export function hasRollbackSnapshotModes(snapshots) {
+    return Object.values(snapshots).every(({ mode }) => mode !== "replace");
+}
+/** Checks that reviewed Git sources only inherit or replace snapshots. */
+export function hasGitSnapshotModes(snapshots) {
+    return Object.values(snapshots).every(({ mode }) => mode !== "restore");
+}
+/** Returns the number of rows that must be staged for this release. */
+export function snapshotRowCount(snapshots) {
+    return (snapshots.program.rowCount +
+        snapshots.quran.rowCount +
+        snapshots.tryout.rowCount);
+}
+/** Serializes one snapshot transition with stable signed field order. */
+export function canonicalizeContentSnapshotState(state) {
+    return {
+        baseSnapshotId: state.baseSnapshotId,
+        mode: state.mode,
+        resultSnapshotId: state.resultSnapshotId,
+        rowCount: state.rowCount,
+        rowDigest: state.rowDigest,
+    };
+}
+/** Serializes all fixed snapshot families with stable signed field order. */
+export function canonicalizeContentSnapshotSet(snapshots) {
+    return {
+        program: canonicalizeContentSnapshotState(snapshots.program),
+        quran: canonicalizeContentSnapshotState(snapshots.quran),
+        tryout: canonicalizeContentSnapshotState(snapshots.tryout),
+    };
+}
+/** Compares two fixed snapshot sets through their stable signed form. */
+export function hasSameContentSnapshots(left, right) {
+    return (JSON.stringify(canonicalizeContentSnapshotSet(left)) ===
+        JSON.stringify(canonicalizeContentSnapshotSet(right)));
+}

package/dist/release/snapshot/tryout-evidence.d.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { type SnapshotRowSource } from "#contracts/release/snapshot/evidence-requirement";
+/** Verifies all try-out hashes, digests, counts, routes, and identity. */
+export declare const verifyTryoutSnapshotRows: <E, R>(snapshot: {
+    readonly family: "tryout";
+    readonly manifest: {
+        readonly activeAppLocales: readonly [("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">, ...(("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraAppLocale">)[]];
+        readonly catalogDigest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+        readonly counts: {
+            readonly country: number;
+            readonly exam: number;
+            readonly section: number;
+            readonly set: number;
+            readonly track: number;
+        };
+        readonly placementCount: number;
+        readonly placementDigest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+        readonly routeCount: number;
+        readonly format: "localized-tryout-snapshot";
+        readonly snapshotId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    };
+}, rows: SnapshotRowSource<E, R>) => Effect.Effect<number, E | import("#contracts/release/snapshot/evidence-requirement").SnapshotEvidenceError | import("#contracts/tryout/locale-closure").TryoutClosureError | import("../../tryout/row-hash.js").TryoutDigestError, R>;

package/dist/release/snapshot/tryout-evidence.js

@@ -0,0 +1,86 @@
+import { Effect, Result, Stream } from "effect";
+import { requireSnapshotEvidence, } from "#contracts/release/snapshot/evidence-requirement";
+import { digestTryoutCatalog } from "#contracts/tryout/catalog-hash";
+import { verifyTryoutLocaleClosure } from "#contracts/tryout/locale-closure";
+import { digestTryoutPlacements } from "#contracts/tryout/placement-hash";
+import { makeTryoutSnapshot } from "#contracts/tryout/snapshot/hash";
+/** Selects current hierarchy rows while preserving source failures. */
+function currentTryoutCatalog(rows) {
+    return rows.pipe(Stream.filterMap((row) => row.family === "tryout" && row.rowKind === "catalog"
+        ? Result.succeed(row.record)
+        : Result.failVoid));
+}
+/** Selects current placements while preserving source failures. */
+function currentPlacements(rows) {
+    return rows.pipe(Stream.filterMap((row) => row.family === "tryout" && row.rowKind === "placement"
+        ? Result.succeed(row.record)
+        : Result.failVoid));
+}
+/** Derives signed per-kind and public-route counts from catalog rows. */
+function summarizeTryoutCatalog(records) {
+    const initial = {
+        counts: { country: 0, exam: 0, section: 0, set: 0, track: 0 },
+        routeCount: 0,
+    };
+    return records.pipe(Stream.runFold(() => initial, (state, { row }) => ({
+        counts: {
+            ...state.counts,
+            [row.kind]: state.counts[row.kind] + 1,
+        },
+        routeCount: state.routeCount + (row.publicPath === undefined ? 0 : 1),
+    })));
+}
+/** Verifies all try-out hashes, digests, counts, routes, and identity. */
+export const verifyTryoutSnapshotRows = Effect.fn("AksaraContracts.verifyTryoutSnapshotRows")(function* (snapshot, rows) {
+    const [placementDigest, catalogDigest, catalogEvidence] = yield* Effect.all([
+        digestTryoutPlacements(currentPlacements(rows)),
+        digestTryoutCatalog(currentTryoutCatalog(rows)),
+        summarizeTryoutCatalog(currentTryoutCatalog(rows)),
+    ]);
+    yield* verifyTryoutLocaleClosure({
+        activeAppLocales: snapshot.manifest.activeAppLocales,
+        catalog: currentTryoutCatalog(rows),
+        placements: currentPlacements(rows),
+    });
+    yield* requireSnapshotEvidence({
+        actual: catalogDigest.digest,
+        expected: snapshot.manifest.catalogDigest,
+        family: "tryout",
+        field: "catalogDigest",
+    });
+    yield* requireSnapshotEvidence({
+        actual: placementDigest.count,
+        expected: snapshot.manifest.placementCount,
+        family: "tryout",
+        field: "placementCount",
+    });
+    yield* requireSnapshotEvidence({
+        actual: placementDigest.digest,
+        expected: snapshot.manifest.placementDigest,
+        family: "tryout",
+        field: "placementDigest",
+    });
+    for (const kind of ["country", "exam", "section", "set", "track"]) {
+        yield* requireSnapshotEvidence({
+            actual: catalogEvidence.counts[kind],
+            expected: snapshot.manifest.counts[kind],
+            family: "tryout",
+            field: `${kind}Count`,
+        });
+    }
+    yield* requireSnapshotEvidence({
+        actual: catalogEvidence.routeCount,
+        expected: snapshot.manifest.routeCount,
+        family: "tryout",
+        field: "routeCount",
+    });
+    const { format: _format, snapshotId, ...facts } = snapshot.manifest;
+    const actualId = makeTryoutSnapshot(facts).snapshotId;
+    yield* requireSnapshotEvidence({
+        actual: actualId,
+        expected: snapshotId,
+        family: "tryout",
+        field: "snapshotId",
+    });
+    return catalogDigest.count + placementDigest.count;
+});