@nakafa/aksara-contracts 0.27.0

package/dist/release/lifecycle.js

@@ -0,0 +1,97 @@
+import { Schema } from "effect";
+import { ReleaseIdSchema, Sha256HashSchema } from "#contracts/ids";
+import { PublicationReceiptSchema, SignedContentReleaseSchema, } from "#contracts/release/spec";
+import { RendererManifestEnvelopeSchema } from "#contracts/renderer/contract";
+const CleanupCountSchema = Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0)));
+/** Maximum rows the backend may delete in one cleanup transaction. */
+export const MAX_CLEANUP_PAGE_COUNT = 100;
+const CleanupRetrySchema = Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0)), Schema.check(Schema.isFinite()));
+/** Exact immutable release identity requested from durable target state. */
+export const ContentReleaseStatusRequestSchema = Schema.Struct({
+    manifestHash: Sha256HashSchema,
+    releaseId: ReleaseIdSchema,
+});
+/** Frozen renderer and signed release required for exact crash recovery. */
+export const ContentReleaseBundleSchema = Schema.Struct({
+    release: SignedContentReleaseSchema,
+    rendererManifest: RendererManifestEnvelopeSchema,
+}).pipe(Schema.check(Schema.makeFilter((bundle) => bundle.release.manifest.rendererManifestHash ===
+    bundle.rendererManifest.hash &&
+    bundle.release.manifest.rendererContractVersion ===
+        bundle.rendererManifest.rendererContractVersion, {
+    message: "Expected the signed release to bind the frozen renderer envelope.",
+})));
+/** Exact renderer-bound bundle accepted only for recovery publication. */
+export const RollbackContentReleaseBundleSchema = ContentReleaseBundleSchema.pipe(Schema.refine((bundle) => bundle.release.manifest.origin.kind === "rollback", { message: "Expected a renderer-bound rollback release." }));
+const ContentReleaseStatusIdentity = {
+    manifestHash: Sha256HashSchema,
+    releaseId: ReleaseIdSchema,
+};
+/** Checks completed evidence against the durable status identity. */
+function hasBoundReceipt(status) {
+    return (status.receipt.releaseId === status.releaseId &&
+        status.receipt.manifestHash === status.manifestHash);
+}
+const CompletedReleaseStatusSchema = Schema.Struct({
+    phase: Schema.Literal("completed"),
+    receipt: PublicationReceiptSchema,
+    ...ContentReleaseStatusIdentity,
+}).pipe(Schema.check(Schema.makeFilter(hasBoundReceipt, {
+    message: "Expected the completed receipt to match the release status identity.",
+})));
+/** Persisted release phase bound to one exact signed manifest identity. */
+export const ContentReleaseStatusSchema = Schema.Union([
+    Schema.Struct({
+        phase: Schema.Literal("missing"),
+        ...ContentReleaseStatusIdentity,
+    }),
+    Schema.Struct({
+        phase: Schema.Literals([
+            "staging",
+            "verifying",
+            "verified",
+            "aborting",
+            "aborted",
+        ]),
+        ...ContentReleaseStatusIdentity,
+    }),
+    CompletedReleaseStatusSchema,
+]);
+/** One invisible staged release whose rows should be abandoned. */
+export const ReleaseAbortRequestSchema = Schema.Struct({
+    releaseId: ReleaseIdSchema,
+});
+/** Identifies the active release and retained inverse accepted by an operator. */
+export const ReleaseAcceptRequestSchema = Schema.Struct({
+    recoveryId: ReleaseIdSchema,
+    releaseId: ReleaseIdSchema,
+}).pipe(Schema.check(Schema.makeFilter((request) => request.recoveryId !== request.releaseId, {
+    message: "Expected distinct active and recovery release identities.",
+})));
+/** Checks cumulative abort evidence against its durable total. */
+function hasCoherentAbortReceipt(receipt) {
+    return (receipt.processedItems <= receipt.totalItems &&
+        receipt.complete === (receipt.processedItems === receipt.totalItems));
+}
+/** Durable cumulative evidence from one server-owned abort page. */
+export const ReleaseAbortReceiptSchema = Schema.Struct({
+    complete: Schema.Boolean,
+    processedItems: CleanupCountSchema,
+    releaseId: ReleaseIdSchema,
+    totalItems: CleanupCountSchema,
+}).pipe(Schema.check(Schema.makeFilter(hasCoherentAbortReceipt, {
+    message: "Expected abort progress to match its durable release item total.",
+})));
+/** One release whose unreachable rows should advance through server-owned state. */
+export const ReleaseCleanupRequestSchema = Schema.Struct({
+    releaseId: ReleaseIdSchema,
+});
+/** Durable cumulative evidence returned after server-owned cleanup progress. */
+export const ReleaseCleanupReceiptSchema = Schema.Struct({
+    complete: Schema.Boolean,
+    deletedArtifacts: CleanupCountSchema,
+    releaseId: ReleaseIdSchema,
+    retryAt: Schema.optional(CleanupRetrySchema),
+}).pipe(Schema.check(Schema.makeFilter((receipt) => !(receipt.complete && receipt.retryAt !== undefined), {
+    message: "Expected completed cleanup evidence without a retry timestamp.",
+})));

package/dist/release/origin.d.ts

@@ -0,0 +1,30 @@
+import { Schema } from "effect";
+/** Exact reviewed Git source used by a normal reproducible release. */
+export declare const GitReleaseOriginSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"git">;
+    readonly sha: Schema.brand<Schema.String, "@NakafaAI/AksaraGitCommitSha">;
+}>;
+/** Exact active release whose prior state is restored by a forward rollback. */
+export declare const RollbackReleaseOriginSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"rollback">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>;
+/** Signed provenance for either exact-Git compilation or artifact reuse. */
+export declare const ReleaseOriginSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"git">;
+    readonly sha: Schema.brand<Schema.String, "@NakafaAI/AksaraGitCommitSha">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"rollback">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>]>;
+export type ReleaseOrigin = typeof ReleaseOriginSchema.Type;
+/** Copies one release origin into deterministic manifest field order. */
+export declare function canonicalizeReleaseOrigin(origin: ReleaseOrigin): {
+    kind: "git";
+    sha: string & import("effect/Brand").Brand<"@NakafaAI/AksaraGitCommitSha">;
+    releaseId?: never;
+} | {
+    sha?: never;
+    kind: "rollback";
+    releaseId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraReleaseId">;
+};

package/dist/release/origin.js

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+import { GitCommitShaSchema, ReleaseIdSchema } from "#contracts/ids";
+/** Exact reviewed Git source used by a normal reproducible release. */
+export const GitReleaseOriginSchema = Schema.Struct({
+    kind: Schema.Literal("git"),
+    sha: GitCommitShaSchema,
+});
+/** Exact active release whose prior state is restored by a forward rollback. */
+export const RollbackReleaseOriginSchema = Schema.Struct({
+    kind: Schema.Literal("rollback"),
+    releaseId: ReleaseIdSchema,
+});
+/** Signed provenance for either exact-Git compilation or artifact reuse. */
+export const ReleaseOriginSchema = Schema.Union([
+    GitReleaseOriginSchema,
+    RollbackReleaseOriginSchema,
+]);
+/** Copies one release origin into deterministic manifest field order. */
+export function canonicalizeReleaseOrigin(origin) {
+    if (origin.kind === "git") {
+        return { kind: origin.kind, sha: origin.sha };
+    }
+    return { kind: origin.kind, releaseId: origin.releaseId };
+}

package/dist/release/policy.d.ts

@@ -0,0 +1,45 @@
+import { Effect, Schema } from "effect";
+import type { Sha256Hash } from "#contracts/ids";
+import type { ContentSnapshotManifest } from "#contracts/release/snapshot/data";
+import { type PublicationScope } from "#contracts/release/snapshot/scope";
+/** Locale policy shared by one release and its structured snapshots. */
+export declare const ReleasePolicySchema: Schema.Struct<{
+    readonly activeAppLocales: Schema.NonEmptyArray<Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraAppLocale">>;
+}>;
+export type ReleasePolicy = typeof ReleasePolicySchema.Type;
+declare const ReleasePolicyClosureError_base: Schema.Class<ReleasePolicyClosureError, Schema.TaggedStruct<"ReleasePolicyClosureError", {
+    readonly actual: Schema.String;
+    readonly expected: Schema.String;
+    readonly family: Schema.Union<readonly [Schema.Literals<readonly ["program", "quran", "tryout"]>, Schema.Literals<readonly ["article", "material", "page", "question"]>]>;
+    readonly field: Schema.Literals<readonly ["activeAppLocales", "manifest", "scope"]>;
+}>, import("effect/Cause").YieldableError>;
+/** One structured scope does not close over the current release policy. */
+export declare class ReleasePolicyClosureError extends ReleasePolicyClosureError_base {
+}
+/**
+ * Verifies snapshot replacement policy for one release transition.
+ *
+ * Genesis and policy changes must replace every structured snapshot. An
+ * unchanged policy may inherit prior snapshots while validating every supplied
+ * replacement against the current release identity.
+ */
+export declare const verifyReleasePolicyTransition: (input: {
+    readonly basePolicy: ReleasePolicy | null;
+    readonly manifests: readonly ContentSnapshotManifest[];
+    readonly policy: ReleasePolicy;
+    readonly scope: PublicationScope;
+}) => Effect.Effect<undefined, ReleasePolicyClosureError, never>;
+/**
+ * Requires a renderer change to prove every retained content artifact.
+ *
+ * Selecting every content family inspects the complete desired corpus against
+ * the candidate renderer. An active try-out also requires its structured
+ * snapshot so the new runtime pair cannot retain superseded artifact hashes.
+ */
+export declare const verifyRendererPolicyTransition: (input: {
+    readonly baseRendererManifestHash: Sha256Hash | null;
+    readonly baseTryoutSnapshotId: Sha256Hash | null;
+    readonly rendererManifestHash: Sha256Hash;
+    readonly scope: PublicationScope;
+}) => Effect.Effect<undefined, ReleasePolicyClosureError, never>;
+export {};

package/dist/release/policy.js

@@ -0,0 +1,124 @@
+import { Effect, Schema } from "effect";
+import { ContentFamilySchema } from "#contracts/content";
+import { ActiveAppLocaleListSchema } from "#contracts/locale";
+import { ContentSnapshotKindSchema, } from "#contracts/release/snapshot/scope";
+const ClosureFieldSchema = Schema.Literals([
+    "activeAppLocales",
+    "manifest",
+    "scope",
+]);
+/** Locale policy shared by one release and its structured snapshots. */
+export const ReleasePolicySchema = Schema.Struct({
+    activeAppLocales: ActiveAppLocaleListSchema,
+});
+/** One structured scope does not close over the current release policy. */
+export class ReleasePolicyClosureError extends Schema.TaggedError()("ReleasePolicyClosureError", {
+    actual: Schema.String,
+    expected: Schema.String,
+    family: Schema.Union([ContentSnapshotKindSchema, ContentFamilySchema]),
+    field: ClosureFieldSchema,
+}) {
+}
+/** Compares locale lists without exchanging their branded element roles. */
+function hasSameLocaleCodes(left, right) {
+    return (left.length === right.length &&
+        left.every((locale, index) => locale === right[index]));
+}
+/** Returns whether two release policies have the same signed identity. */
+function hasSamePolicy(left, right) {
+    return hasSameLocaleCodes(left.activeAppLocales, right.activeAppLocales);
+}
+/** Fails with one exact structured-scope policy mismatch. */
+function failClosure(input) {
+    return Effect.fail(new ReleasePolicyClosureError(input));
+}
+/** Verifies one replacement snapshot against the new release policy. */
+function verifyManifestPolicy(manifest, policy) {
+    if (!hasSameLocaleCodes(manifest.manifest.activeAppLocales, policy.activeAppLocales)) {
+        return failClosure({
+            actual: manifest.manifest.activeAppLocales.join(","),
+            expected: policy.activeAppLocales.join(","),
+            family: manifest.family,
+            field: "activeAppLocales",
+        });
+    }
+    return Effect.void;
+}
+/**
+ * Verifies snapshot replacement policy for one release transition.
+ *
+ * Genesis and policy changes must replace every structured snapshot. An
+ * unchanged policy may inherit prior snapshots while validating every supplied
+ * replacement against the current release identity.
+ */
+export const verifyReleasePolicyTransition = Effect.fn("AksaraContracts.verifyReleasePolicyTransition")(function* (input) {
+    const requiresCompleteReplacement = input.basePolicy === null || !hasSamePolicy(input.basePolicy, input.policy);
+    if (requiresCompleteReplacement) {
+        for (const family of ContentFamilySchema.literals) {
+            if (!input.scope.families.includes(family)) {
+                return yield* failClosure({
+                    actual: "partial",
+                    expected: "complete-family",
+                    family,
+                    field: "scope",
+                });
+            }
+        }
+    }
+    for (const family of ContentSnapshotKindSchema.literals) {
+        const manifests = input.manifests.filter((candidate) => candidate.family === family);
+        if (manifests.length > 1) {
+            return yield* failClosure({
+                actual: String(manifests.length),
+                expected: "at-most-one",
+                family,
+                field: "manifest",
+            });
+        }
+        const [manifest] = manifests;
+        if (manifest !== undefined) {
+            yield* verifyManifestPolicy(manifest, input.policy);
+            continue;
+        }
+        if (requiresCompleteReplacement) {
+            return yield* failClosure({
+                actual: "missing",
+                expected: "exactly-one",
+                family,
+                field: "manifest",
+            });
+        }
+    }
+});
+/**
+ * Requires a renderer change to prove every retained content artifact.
+ *
+ * Selecting every content family inspects the complete desired corpus against
+ * the candidate renderer. An active try-out also requires its structured
+ * snapshot so the new runtime pair cannot retain superseded artifact hashes.
+ */
+export const verifyRendererPolicyTransition = Effect.fn("AksaraContracts.verifyRendererPolicyTransition")(function* (input) {
+    if (input.baseRendererManifestHash === null ||
+        input.baseRendererManifestHash === input.rendererManifestHash) {
+        return;
+    }
+    for (const family of ContentFamilySchema.literals) {
+        if (!input.scope.families.includes(family)) {
+            return yield* failClosure({
+                actual: "partial",
+                expected: "complete-family",
+                family,
+                field: "scope",
+            });
+        }
+    }
+    if (input.baseTryoutSnapshotId !== null &&
+        !input.scope.snapshots.includes("tryout")) {
+        return yield* failClosure({
+            actual: "missing",
+            expected: "renderer-refresh",
+            family: "tryout",
+            field: "scope",
+        });
+    }
+});

package/dist/release/result/digest.d.ts

@@ -0,0 +1,127 @@
+import { Effect, Schema, Stream } from "effect";
+import { type PublicPath, type ReleaseId, Sha256HashSchema } from "#contracts/ids";
+import { type ArtifactLocale } from "#contracts/locale";
+import { type ContentHead } from "#contracts/release/head";
+declare const ResultCatalogHashError_base: Schema.Class<ResultCatalogHashError, Schema.TaggedStruct<"ResultCatalogHashError", {
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** SHA-256 computation failed before result-catalog integrity was established. */
+export declare class ResultCatalogHashError extends ResultCatalogHashError_base {
+}
+declare const ResultCatalogOrderError_base: Schema.Class<ResultCatalogOrderError, Schema.TaggedStruct<"ResultCatalogOrderError", {
+    readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+    readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** A result catalog is duplicated or outside canonical content-head order. */
+export declare class ResultCatalogOrderError extends ResultCatalogOrderError_base {
+}
+declare const ResultCatalogRouteError_base: Schema.Class<ResultCatalogRouteError, Schema.TaggedStruct<"ResultCatalogRouteError", {
+    readonly artifactLocale: Schema.brand<Schema.Literals<readonly ["en", "id", "de"]>, "@NakafaAI/AksaraArtifactLocale">;
+    readonly contentKey: Schema.brand<Schema.String, "@NakafaAI/AksaraContentKey">;
+    readonly publicPath: Schema.brand<Schema.String, "@NakafaAI/AksaraPublicPath">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** Two complete result heads claim the same locale-specific public route. */
+export declare class ResultCatalogRouteError extends ResultCatalogRouteError_base {
+}
+declare const ResultCatalogCountMismatchError_base: Schema.Class<ResultCatalogCountMismatchError, Schema.TaggedStruct<"ResultCatalogCountMismatchError", {
+    readonly actualCount: Schema.Finite;
+    readonly expectedCount: Schema.Finite;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** A replayed result catalog has a different signed head count. */
+export declare class ResultCatalogCountMismatchError extends ResultCatalogCountMismatchError_base {
+}
+declare const ResultCatalogDigestMismatchError_base: Schema.Class<ResultCatalogDigestMismatchError, Schema.TaggedStruct<"ResultCatalogDigestMismatchError", {
+    readonly actualDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly expectedDigest: Schema.brand<Schema.String, "@NakafaAI/AksaraSha256Hash">;
+    readonly releaseId: Schema.brand<Schema.String, "@NakafaAI/AksaraReleaseId">;
+}>, import("effect/Cause").YieldableError>;
+/** A replayed result catalog does not match its signed digest. */
+export declare class ResultCatalogDigestMismatchError extends ResultCatalogDigestMismatchError_base {
+}
+/** Keeps mutable hash and ordering state private to one catalog replay. */
+declare class ResultCatalogDigestState {
+    #private;
+    count: number;
+    previous: ContentHead | undefined;
+    /** Initializes one domain-separated result-catalog hash. */
+    constructor();
+    /** Claims one public route and reports whether it was globally unique. */
+    claimRoute(artifactLocale: ArtifactLocale, publicPath: PublicPath): boolean;
+    /** Adds one canonical compact head and advances ordering evidence. */
+    update(head: ContentHead): void;
+    /** Consumes the hash and returns its branded immutable identity. */
+    digest(): string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}
+/** Creates a fresh domain-separated digest state for one result catalog. */
+export declare function createResultCatalogDigest(releaseId: ReleaseId): Effect.Effect<ResultCatalogDigestState, ResultCatalogHashError, never>;
+/** Adds one canonically ordered compact head to a result digest. */
+export declare function updateResultCatalogDigest(releaseId: ReleaseId, state: ResultCatalogDigestState, head: ContentHead): Effect.Effect<ResultCatalogDigestState, ResultCatalogHashError | ResultCatalogOrderError | ResultCatalogRouteError>;
+/** Finalizes one incremental result-catalog digest. */
+export declare function finalizeResultCatalogDigest(releaseId: ReleaseId, state: ResultCatalogDigestState): Effect.Effect<string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">, ResultCatalogHashError, never>;
+/** Digests one complete compact-head stream without retaining the catalog. */
+export declare const digestResultCatalog: <E, R>(releaseId: string & import("effect/Brand").Brand<"@NakafaAI/AksaraReleaseId">, heads: Stream.Stream<{
+    readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    readonly delivery: "authenticated" | "entitled" | "public";
+    readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+    readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+    readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+    readonly family: "page";
+} | {
+    readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    readonly delivery: "authenticated" | "entitled" | "public";
+    readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+    readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+    readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+    readonly family: "question";
+} | {
+    readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    readonly delivery: "authenticated" | "entitled" | "public";
+    readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+    readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+    readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+    readonly family: "article";
+} | {
+    readonly artifactHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly artifactLocale: ("de" | "en" | "id") & import("effect/Brand").Brand<"@NakafaAI/AksaraArtifactLocale">;
+    readonly compilerConfigHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly contentKey: string & import("effect/Brand").Brand<"@NakafaAI/AksaraContentKey">;
+    readonly delivery: "authenticated" | "entitled" | "public";
+    readonly projectionHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly publicPath?: (string & import("effect/Brand").Brand<"@NakafaAI/AksaraPublicPath">) | undefined;
+    readonly rendererDomain: "ai-ds" | "biology" | "chemistry" | "mathematics" | "physics" | "politics" | "site" | "snbt-general" | "snbt-math" | "snbt-plain" | "snbt-quant" | "tka-math";
+    readonly sourceHash: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+    readonly sourcePath: string & import("effect/Brand").Brand<"@NakafaAI/AksaraCorpusSourcePath">;
+    readonly family: "material";
+}, E, R>) => Effect.Effect<{
+    count: number;
+    digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E | ResultCatalogHashError | ResultCatalogOrderError | ResultCatalogRouteError, R>;
+/** Authenticates one complete replayed catalog against its signed result root. */
+export declare const verifyResultCatalog: <E, R>(input: {
+    readonly expectedCount: number;
+    readonly expectedDigest: typeof Sha256HashSchema.Type;
+    readonly heads: Stream.Stream<ContentHead, E, R>;
+    readonly releaseId: ReleaseId;
+}) => Effect.Effect<{
+    count: number;
+    digest: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;
+}, E | ResultCatalogCountMismatchError | ResultCatalogDigestMismatchError | ResultCatalogHashError | ResultCatalogOrderError | ResultCatalogRouteError, R>;
+export {};

package/dist/release/result/digest.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { Effect, Schema, Stream } from "effect";
+import { compareContentHeads, routeIdentity } from "#contracts/content";
+import { ContentKeySchema, PublicPathSchema, ReleaseIdSchema, Sha256HashSchema, } from "#contracts/ids";
+import { AppLocaleSchema, ArtifactLocaleSchema, } from "#contracts/locale";
+import { canonicalizeContentHead, } from "#contracts/release/head";
+import { RESULT_CATALOG_DIGEST_DOMAIN } from "#contracts/release/result/spec";
+/** SHA-256 computation failed before result-catalog integrity was established. */
+export class ResultCatalogHashError extends Schema.TaggedError()("ResultCatalogHashError", { releaseId: ReleaseIdSchema }) {
+}
+/** A result catalog is duplicated or outside canonical content-head order. */
+export class ResultCatalogOrderError extends Schema.TaggedError()("ResultCatalogOrderError", {
+    artifactLocale: ArtifactLocaleSchema,
+    contentKey: ContentKeySchema,
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** Two complete result heads claim the same locale-specific public route. */
+export class ResultCatalogRouteError extends Schema.TaggedError()("ResultCatalogRouteError", {
+    artifactLocale: ArtifactLocaleSchema,
+    contentKey: ContentKeySchema,
+    publicPath: PublicPathSchema,
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** A replayed result catalog has a different signed head count. */
+export class ResultCatalogCountMismatchError extends Schema.TaggedError()("ResultCatalogCountMismatchError", {
+    actualCount: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    expectedCount: Schema.Finite.pipe(Schema.check(Schema.isInt()), Schema.check(Schema.isGreaterThanOrEqualTo(0))),
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** A replayed result catalog does not match its signed digest. */
+export class ResultCatalogDigestMismatchError extends Schema.TaggedError()("ResultCatalogDigestMismatchError", {
+    actualDigest: Sha256HashSchema,
+    expectedDigest: Sha256HashSchema,
+    releaseId: ReleaseIdSchema,
+}) {
+}
+/** Keeps mutable hash and ordering state private to one catalog replay. */
+class ResultCatalogDigestState {
+    #hash = createHash("sha256");
+    #routes = new Set();
+    count = 0;
+    previous;
+    /** Initializes one domain-separated result-catalog hash. */
+    constructor() {
+        this.#hash.update(RESULT_CATALOG_DIGEST_DOMAIN);
+        this.#hash.update("\n");
+    }
+    /** Claims one public route and reports whether it was globally unique. */
+    claimRoute(artifactLocale, publicPath) {
+        const identity = routeIdentity({
+            appLocale: AppLocaleSchema.make(artifactLocale),
+            publicPath,
+        });
+        if (this.#routes.has(identity)) {
+            return false;
+        }
+        this.#routes.add(identity);
+        return true;
+    }
+    /** Adds one canonical compact head and advances ordering evidence. */
+    update(head) {
+        this.#hash.update(canonicalizeContentHead(head));
+        this.#hash.update("\n");
+        this.count += 1;
+        this.previous = head;
+    }
+    /** Consumes the hash and returns its branded immutable identity. */
+    digest() {
+        return Sha256HashSchema.make(`sha256:${this.#hash.digest("hex")}`);
+    }
+}
+/** Creates a fresh domain-separated digest state for one result catalog. */
+export function createResultCatalogDigest(releaseId) {
+    return Effect.try({
+        catch: () => new ResultCatalogHashError({ releaseId }),
+        try: () => new ResultCatalogDigestState(),
+    });
+}
+/** Adds one canonically ordered compact head to a result digest. */
+export function updateResultCatalogDigest(releaseId, state, head) {
+    if (state.previous && compareContentHeads(state.previous, head) >= 0) {
+        return Effect.fail(new ResultCatalogOrderError({
+            artifactLocale: head.artifactLocale,
+            contentKey: head.contentKey,
+            releaseId,
+        }));
+    }
+    if (head.publicPath !== undefined &&
+        !state.claimRoute(head.artifactLocale, head.publicPath)) {
+        return Effect.fail(new ResultCatalogRouteError({
+            artifactLocale: head.artifactLocale,
+            contentKey: head.contentKey,
+            publicPath: head.publicPath,
+            releaseId,
+        }));
+    }
+    return Effect.try({
+        catch: () => new ResultCatalogHashError({ releaseId }),
+        try: () => {
+            state.update(head);
+            return state;
+        },
+    });
+}
+/** Finalizes one incremental result-catalog digest. */
+export function finalizeResultCatalogDigest(releaseId, state) {
+    return Effect.try({
+        catch: () => new ResultCatalogHashError({ releaseId }),
+        try: () => state.digest(),
+    });
+}
+/** Digests one complete compact-head stream without retaining the catalog. */
+export const digestResultCatalog = Effect.fn("AksaraContracts.digestResultCatalog")(function* (releaseId, heads) {
+    const initial = yield* createResultCatalogDigest(releaseId);
+    const state = yield* heads.pipe(Stream.runFoldEffect(() => initial, (current, head) => updateResultCatalogDigest(releaseId, current, head)));
+    const digest = yield* finalizeResultCatalogDigest(releaseId, state);
+    return { count: state.count, digest };
+});
+/** Authenticates one complete replayed catalog against its signed result root. */
+export const verifyResultCatalog = Effect.fn("AksaraContracts.verifyResultCatalog")(function* (input) {
+    const summary = yield* digestResultCatalog(input.releaseId, input.heads);
+    if (summary.count !== input.expectedCount) {
+        return yield* new ResultCatalogCountMismatchError({
+            actualCount: summary.count,
+            expectedCount: input.expectedCount,
+            releaseId: input.releaseId,
+        });
+    }
+    if (summary.digest !== input.expectedDigest) {
+        return yield* new ResultCatalogDigestMismatchError({
+            actualDigest: summary.digest,
+            expectedDigest: input.expectedDigest,
+            releaseId: input.releaseId,
+        });
+    }
+    return summary;
+});

package/dist/release/result/spec.d.ts

@@ -0,0 +1,4 @@
+/** Domain separator shared by canonical result-catalog digest implementations. */
+export declare const RESULT_CATALOG_DIGEST_DOMAIN = "nakafa.aksara.result-catalog";
+/** Canonical signed root for a release whose complete result catalog is empty. */
+export declare const EMPTY_RESULT_CATALOG_DIGEST: string & import("effect/Brand").Brand<"@NakafaAI/AksaraSha256Hash">;

package/dist/release/result/spec.js

@@ -0,0 +1,5 @@
+import { Sha256HashSchema } from "#contracts/ids";
+/** Domain separator shared by canonical result-catalog digest implementations. */
+export const RESULT_CATALOG_DIGEST_DOMAIN = "nakafa.aksara.result-catalog";
+/** Canonical signed root for a release whose complete result catalog is empty. */
+export const EMPTY_RESULT_CATALOG_DIGEST = Sha256HashSchema.make("sha256:ed7d49e237dadbd311a1599264b00852ae18657d123c8f9cbc26c1c62c8f81cd");