@comms-id/asx 0.4.1 → 0.4.2

package/dist/live.js

@@ -0,0 +1,129 @@
+import { suggestDirectory } from "./directory-search.js";
+import { Effect, Result, Schema } from "effect";
+import { boundedText } from "./http.js";
+import { failure, Failure } from "./model.js";
+import { normalizeTicker, parseCompany, parseDirectory } from "./parse.js";
+import { ASX_COMPANY_BASE, asxSourceObservation } from "./source-record.js";
+const BASE = ASX_COMPANY_BASE;
+const Missing = Schema.Struct({
+    error: Schema.Struct({
+        code: Schema.Literal(400),
+        message: Schema.Literal("Bad Request: Symbol not found"),
+    }),
+});
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw failure("PARSE_FAILED");
+    }
+}
+const request = Effect.fn("ASX.http")(function* (transport, path, limit) {
+    return yield* Effect.tryPromise({
+        try: async (signal) => {
+            const response = await transport(`${BASE}${path}`, {
+                signal,
+                redirect: "manual",
+                headers: { Accept: path === "directory/file" ? "text/csv" : "application/json" },
+            });
+            if (response.status === 401 || response.status === 403) {
+                await response.body?.cancel();
+                throw failure("ACCESS_DENIED");
+            }
+            if (response.status === 429) {
+                await response.body?.cancel();
+                throw failure("RATE_LIMITED");
+            }
+            if (response.status >= 500 || response.status === 408) {
+                await response.body?.cancel();
+                throw failure("UPSTREAM_UNAVAILABLE");
+            }
+            if (!response.ok && response.status !== 400) {
+                await response.body?.cancel();
+                throw failure("UPSTREAM_REJECTED");
+            }
+            const body = await boundedText(response, response.ok ? limit : 4096, signal);
+            return { status: response.status, body };
+        },
+        catch: (error) => Schema.is(Failure)(error) ? failure(error.code) : failure("TRANSPORT_FAILED"),
+    });
+});
+function run(program, timeoutMs, signal) {
+    return Effect.runPromise(Effect.result(program.pipe(Effect.timeoutOrElse({
+        duration: timeoutMs,
+        orElse: () => Effect.fail(failure("TIMEOUT")),
+    }))), { signal })
+        .then((result) => {
+        if (Result.isFailure(result))
+            throw result.failure;
+        return result.success;
+    })
+        .catch((error) => {
+        if (signal?.aborted)
+            throw failure("CANCELLED");
+        throw Schema.is(Failure)(error) ? failure(error.code) : failure("INTERNAL_ERROR");
+    });
+}
+/** No persistence, source composition, background work or network call at construction. */
+export function createAsxLive(config = {}) {
+    const timeoutMs = config.timeoutMs ?? 3000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+        throw failure("CONFIGURATION_ERROR");
+    const transport = config.fetch ?? globalThis.fetch;
+    const lookup = Effect.fn("ASX.profile")(function* (input) {
+        const ticker = yield* Effect.try({
+            try: () => normalizeTicker(input),
+            catch: () => failure("INVALID_INPUT"),
+        });
+        const startedAt = new Date().toISOString();
+        const response = yield* request(transport, `${ticker}/about`, 1024 * 1024);
+        const payload = yield* Effect.try({
+            try: () => parseJson(response.body),
+            catch: () => failure("PARSE_FAILED"),
+        });
+        const observedAt = new Date().toISOString();
+        if (response.status === 400) {
+            if (Schema.is(Missing)(payload) && Schema.is(Schema.JsonObject)(payload))
+                return { status: "missing", startedAt, observedAt, raw: structuredClone(payload) };
+            return yield* Effect.fail(failure("UPSTREAM_REJECTED"));
+        }
+        const company = yield* Effect.try({
+            try: () => parseCompany(ticker, payload),
+            catch: (error) => (Schema.is(Failure)(error) ? failure(error.code) : failure("PARSE_FAILED")),
+        });
+        return {
+            status: "found",
+            observation: { company, startedAt, observedAt, lastChangedAt: observedAt },
+        };
+    });
+    const directory = Effect.fn("ASX.directory")(function* () {
+        const response = yield* request(transport, "directory/file", 4 * 1024 * 1024);
+        if (response.status !== 200)
+            return yield* Effect.fail(failure("UPSTREAM_REJECTED"));
+        const entries = yield* Effect.try({
+            try: () => parseDirectory(response.body),
+            catch: () => failure("PARSE_FAILED"),
+        });
+        return { entries, observedAt: new Date().toISOString() };
+    });
+    return {
+        source: async (input, signal) => {
+            const ticker = normalizeTicker(input);
+            const result = await run(lookup(ticker), timeoutMs, signal);
+            return asxSourceObservation(ticker, result);
+        },
+        lookup: (ticker, signal) => run(lookup(ticker), timeoutMs, signal),
+        directory: (signal) => run(directory(), timeoutMs, signal),
+        suggest: async (query, limit = 8, signal) => {
+            // Validate before acquiring the directory.
+            suggestDirectory([], query, limit);
+            const value = await run(directory(), timeoutMs, signal);
+            return {
+                source: "live",
+                directoryObservedAt: value.observedAt,
+                suggestions: suggestDirectory(value.entries, query, limit),
+            };
+        },
+    };
+}

package/dist/model.d.ts

@@ -0,0 +1,112 @@
+import { Schema } from "effect";
+export declare const Ticker: Schema.String;
+export declare const Person: Schema.Struct<{
+    readonly sourceName: Schema.String;
+    readonly displayName: Schema.String;
+    readonly title: Schema.String;
+    readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+}>;
+export interface Person extends Schema.Schema.Type<typeof Person> {
+}
+export declare const Company: Schema.Struct<{
+    /** Complete public ASX profile response, including fields unknown to this package version. */
+    readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly ticker: Schema.String;
+    readonly sourceId: Schema.String;
+    readonly companyName: Schema.String;
+    readonly address: Schema.NullOr<Schema.String>;
+    readonly tel: Schema.NullOr<Schema.String>;
+    readonly fax: Schema.NullOr<Schema.String>;
+    readonly website: Schema.NullOr<Schema.String>;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly issueType: Schema.NullOr<Schema.String>;
+    readonly foreignExempt: Schema.NullOr<Schema.Boolean>;
+    readonly people: Schema.$Array<Schema.Struct<{
+        readonly sourceName: Schema.String;
+        readonly displayName: Schema.String;
+        readonly title: Schema.String;
+        readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+    }>>;
+}>;
+export interface Company extends Schema.Schema.Type<typeof Company> {
+}
+export declare const DirectoryEntry: Schema.Struct<{
+    readonly ticker: Schema.String;
+    readonly companyName: Schema.String;
+    readonly industryGroup: Schema.NullOr<Schema.String>;
+    readonly listingDate: Schema.NullOr<Schema.String>;
+    readonly marketCapitalisation: Schema.NullOr<Schema.Number>;
+}>;
+export interface DirectoryEntry extends Schema.Schema.Type<typeof DirectoryEntry> {
+}
+export declare const Failure: Schema.Struct<{
+    readonly _tag: Schema.Literal<"AsxError">;
+    readonly code: Schema.Literals<readonly ["INVALID_INPUT", "PARSE_FAILED", "SOURCE_MISMATCH", "TRANSPORT_FAILED", "TIMEOUT", "RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "CONFIGURATION_ERROR", "SNAPSHOT_UNAVAILABLE", "CANCELLED", "INTERNAL_ERROR", "ACCESS_DENIED", "UPSTREAM_REJECTED", "PERSISTENCE_FAILED", "PUBLICATION_CONFLICT", "COVERAGE_REJECTED"]>;
+}>;
+export type AsxError = typeof Failure.Type;
+export declare const failure: (code: AsxError["code"]) => AsxError;
+export declare const isFallbackEligible: (code: AsxError["code"]) => boolean;
+export declare const Timestamp: Schema.String;
+export declare const Observation: Schema.Struct<{
+    readonly company: Schema.Struct<{
+        /** Complete public ASX profile response, including fields unknown to this package version. */
+        readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+        readonly ticker: Schema.String;
+        readonly sourceId: Schema.String;
+        readonly companyName: Schema.String;
+        readonly address: Schema.NullOr<Schema.String>;
+        readonly tel: Schema.NullOr<Schema.String>;
+        readonly fax: Schema.NullOr<Schema.String>;
+        readonly website: Schema.NullOr<Schema.String>;
+        readonly description: Schema.NullOr<Schema.String>;
+        readonly issueType: Schema.NullOr<Schema.String>;
+        readonly foreignExempt: Schema.NullOr<Schema.Boolean>;
+        readonly people: Schema.$Array<Schema.Struct<{
+            readonly sourceName: Schema.String;
+            readonly displayName: Schema.String;
+            readonly title: Schema.String;
+            readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+        }>>;
+    }>;
+    readonly startedAt: Schema.String;
+    readonly observedAt: Schema.String;
+    readonly lastChangedAt: Schema.String;
+}>;
+export interface Observation extends Schema.Schema.Type<typeof Observation> {
+}
+export declare const LiveOutcome: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"found">;
+    readonly observation: Schema.Struct<{
+        readonly company: Schema.Struct<{
+            /** Complete public ASX profile response, including fields unknown to this package version. */
+            readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            readonly ticker: Schema.String;
+            readonly sourceId: Schema.String;
+            readonly companyName: Schema.String;
+            readonly address: Schema.NullOr<Schema.String>;
+            readonly tel: Schema.NullOr<Schema.String>;
+            readonly fax: Schema.NullOr<Schema.String>;
+            readonly website: Schema.NullOr<Schema.String>;
+            readonly description: Schema.NullOr<Schema.String>;
+            readonly issueType: Schema.NullOr<Schema.String>;
+            readonly foreignExempt: Schema.NullOr<Schema.Boolean>;
+            readonly people: Schema.$Array<Schema.Struct<{
+                readonly sourceName: Schema.String;
+                readonly displayName: Schema.String;
+                readonly title: Schema.String;
+                readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+            }>>;
+        }>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly lastChangedAt: Schema.String;
+    }>;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"missing">;
+    readonly startedAt: Schema.String;
+    readonly observedAt: Schema.String;
+    readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>]>;
+export type LiveOutcome = typeof LiveOutcome.Type;
+export declare function isTimestamp(value: string): boolean;
+export declare function validObservation(value: Observation): boolean;

package/dist/model.js

@@ -0,0 +1,86 @@
+import { Schema } from "effect";
+export const Ticker = Schema.String.check(Schema.isPattern(/^[A-Z0-9]{1,12}$/));
+const Text = Schema.NullOr(Schema.String);
+export const Person = Schema.Struct({
+    sourceName: Schema.String,
+    displayName: Schema.String,
+    title: Schema.String,
+    sourceCategory: Schema.Literals(["directors", "secretaries"]),
+});
+export const Company = Schema.Struct({
+    /** Complete public ASX profile response, including fields unknown to this package version. */
+    raw: Schema.optionalKey(Schema.JsonObject),
+    ticker: Ticker,
+    sourceId: Schema.String,
+    companyName: Schema.String,
+    address: Text,
+    tel: Text,
+    fax: Text,
+    website: Text,
+    description: Text,
+    issueType: Text,
+    foreignExempt: Schema.NullOr(Schema.Boolean),
+    people: Schema.Array(Person),
+});
+export const DirectoryEntry = Schema.Struct({
+    ticker: Ticker,
+    companyName: Schema.String,
+    industryGroup: Text,
+    listingDate: Text,
+    marketCapitalisation: Schema.NullOr(Schema.Number),
+});
+export const Failure = Schema.Struct({
+    _tag: Schema.Literal("AsxError"),
+    code: Schema.Literals([
+        "INVALID_INPUT",
+        "PARSE_FAILED",
+        "SOURCE_MISMATCH",
+        "TRANSPORT_FAILED",
+        "TIMEOUT",
+        "RATE_LIMITED",
+        "UPSTREAM_UNAVAILABLE",
+        "CONFIGURATION_ERROR",
+        "SNAPSHOT_UNAVAILABLE",
+        "CANCELLED",
+        "INTERNAL_ERROR",
+        "ACCESS_DENIED",
+        "UPSTREAM_REJECTED",
+        "PERSISTENCE_FAILED",
+        "PUBLICATION_CONFLICT",
+        "COVERAGE_REJECTED",
+    ]),
+});
+export const failure = (code) => ({ _tag: "AsxError", code });
+export const isFallbackEligible = (code) => ["TIMEOUT", "TRANSPORT_FAILED", "PARSE_FAILED", "RATE_LIMITED", "UPSTREAM_UNAVAILABLE"].includes(code);
+export const Timestamp = Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/));
+export const Observation = Schema.Struct({
+    company: Company,
+    startedAt: Timestamp,
+    observedAt: Timestamp,
+    lastChangedAt: Timestamp,
+});
+export const LiveOutcome = Schema.Union([
+    Schema.Struct({ status: Schema.Literal("found"), observation: Observation }),
+    Schema.Struct({
+        status: Schema.Literal("missing"),
+        startedAt: Timestamp,
+        observedAt: Timestamp,
+        raw: Schema.optionalKey(Schema.JsonObject),
+    }),
+]);
+export function isTimestamp(value) {
+    if (!Schema.is(Timestamp)(value))
+        return false;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) && date.toISOString() === value;
+}
+export function validObservation(value) {
+    return (isTimestamp(value.startedAt) &&
+        isTimestamp(value.observedAt) &&
+        isTimestamp(value.lastChangedAt) &&
+        value.lastChangedAt <= value.observedAt &&
+        value.startedAt <= value.observedAt &&
+        value.company.sourceId.trim().length > 0 &&
+        value.company.companyName.trim().length > 0 &&
+        value.company.people.every((person) => person.sourceName.trim() && person.displayName.trim() && person.title.trim()));
+}

package/dist/parse.d.ts

@@ -0,0 +1,4 @@
+import { type Company, type DirectoryEntry } from "./model.js";
+export declare function normalizeTicker(input: string): string;
+export declare function parseCompany(tickerInput: string, input: unknown): Company;
+export declare function parseDirectory(input: string): readonly DirectoryEntry[];

package/dist/parse.js

@@ -0,0 +1,130 @@
+import { parse } from "csv-parse/browser/esm/sync";
+import { Result, Schema } from "effect";
+import { failure, Ticker } from "./model.js";
+const SourcePerson = Schema.Struct({ name: Schema.String, title: Schema.String });
+const OptionalText = Schema.optionalKey(Schema.NullOr(Schema.String));
+const Payload = Schema.Struct({
+    data: Schema.Struct({
+        symbol: Ticker,
+        xid: Schema.String,
+        displayName: Schema.String,
+        addressContact: Schema.Struct({
+            address: OptionalText,
+            phone: OptionalText,
+            fax: OptionalText,
+        }),
+        websiteUrl: OptionalText,
+        description: OptionalText,
+        issueType: OptionalText,
+        foreignExempt: Schema.optionalKey(Schema.NullOr(Schema.Boolean)),
+        directors: Schema.Array(SourcePerson),
+        secretaries: Schema.Array(SourcePerson),
+    }),
+});
+const text = (value) => (value?.trim() ? value : null);
+export function normalizeTicker(input) {
+    if (typeof input !== "string" || input.length > 128)
+        throw failure("INVALID_INPUT");
+    const ticker = input.trim().toUpperCase();
+    if (!Schema.is(Ticker)(ticker))
+        throw failure("INVALID_INPUT");
+    return ticker;
+}
+function person(value, sourceCategory) {
+    if (!value.name.trim() || !value.title.trim())
+        throw failure("PARSE_FAILED");
+    return {
+        sourceName: value.name,
+        displayName: value.name.trim().replace(/^(?:Mr|Mrs|Ms|Miss|Dr|Prof|Sir|Dame)\.?\s+/i, ""),
+        title: value.title,
+        sourceCategory,
+    };
+}
+export function parseCompany(tickerInput, input) {
+    const ticker = normalizeTicker(tickerInput);
+    const decoded = Schema.decodeUnknownResult(Payload)(input);
+    if (Result.isFailure(decoded))
+        throw failure("PARSE_FAILED");
+    const data = decoded.success.data;
+    if (data.symbol !== ticker)
+        throw failure("SOURCE_MISMATCH");
+    if (!data.xid.trim() || !data.displayName.trim())
+        throw failure("PARSE_FAILED");
+    const raw = Schema.decodeUnknownResult(Schema.JsonObject)(input);
+    if (Result.isFailure(raw))
+        throw failure("PARSE_FAILED");
+    return {
+        raw: structuredClone(raw.success),
+        ticker,
+        sourceId: data.xid,
+        companyName: data.displayName,
+        address: text(data.addressContact.address),
+        tel: text(data.addressContact.phone),
+        fax: text(data.addressContact.fax),
+        website: text(data.websiteUrl),
+        description: text(data.description),
+        issueType: text(data.issueType),
+        foreignExempt: data.foreignExempt ?? null,
+        people: [
+            ...data.directors.map((value) => person(value, "directors")),
+            ...data.secretaries.map((value) => person(value, "secretaries")),
+        ],
+    };
+}
+const HEADERS = ["ASX code", "Company name", "GICs industry group", "Listing date", "Market Cap"];
+function listingDate(value) {
+    if (!value.trim())
+        return null;
+    const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(value);
+    if (!match)
+        throw failure("PARSE_FAILED");
+    const iso = `${match[3]}-${match[2]}-${match[1]}`;
+    const date = new Date(`${iso}T00:00:00.000Z`);
+    if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== iso)
+        throw failure("PARSE_FAILED");
+    return iso;
+}
+function directoryRow(row) {
+    if (row.length !== HEADERS.length || !row[1]?.trim())
+        throw failure("PARSE_FAILED");
+    const ticker = row[0];
+    if (!Schema.is(Ticker)(ticker))
+        throw failure("PARSE_FAILED");
+    const cap = row[4].trim();
+    const marketCapitalisation = cap === "" || cap === "--" ? null : Number(cap);
+    if (marketCapitalisation !== null &&
+        (!/^\d+(?:\.\d+)?$/.test(cap) || !Number.isFinite(marketCapitalisation)))
+        throw failure("PARSE_FAILED");
+    return {
+        ticker,
+        companyName: row[1],
+        industryGroup: text(row[2]),
+        listingDate: listingDate(row[3]),
+        marketCapitalisation,
+    };
+}
+export function parseDirectory(input) {
+    if (typeof input !== "string" || input.length > 4 * 1024 * 1024)
+        throw failure("PARSE_FAILED");
+    let raw;
+    try {
+        raw = parse(input, { bom: true, skip_empty_lines: true, max_record_size: 16_384 });
+    }
+    catch {
+        throw failure("PARSE_FAILED");
+    }
+    const decoded = Schema.decodeUnknownResult(Schema.Array(Schema.Array(Schema.String)))(raw);
+    if (Result.isFailure(decoded))
+        throw failure("PARSE_FAILED");
+    const [headers, ...rows] = decoded.success;
+    if (!headers ||
+        headers.length !== HEADERS.length ||
+        HEADERS.some((header, i) => headers[i] !== header) ||
+        rows.length === 0 ||
+        rows.length > 20_000)
+        throw failure("PARSE_FAILED");
+    const entries = rows.map(directoryRow);
+    if (new Set(entries.map((entry) => entry.ticker)).size !== entries.length)
+        throw failure("PARSE_FAILED");
+    return entries;
+}

package/dist/profile-contact.d.ts

@@ -0,0 +1,13 @@
+import type { CompanySources, SourceName } from "./source-record.js";
+export interface ProfileContact {
+    readonly address: string | null;
+    readonly tel: string | null;
+    readonly website: string | null;
+    /** Which collected source supplied each value; absent when the value is null. */
+    readonly sources: Partial<Record<"address" | "tel" | "website", SourceName>>;
+}
+/**
+ * Contact details from collected public profiles, used only where the ASX profile is blank.
+ * Values are never inferred: each comes verbatim from one named source.
+ */
+export declare function profileContact(sources: CompanySources): ProfileContact;

package/dist/profile-contact.js

@@ -0,0 +1,66 @@
+const PHONE = /^T\s+(\+?[\d\s()-]{6,})$/;
+const WEB = /^(https?:\/\/|www\.)/i;
+const AU_TAIL = /^(.+),\s*([^,]+?),?\s+(ACT|NSW|NT|QLD|SA|TAS|VIC|WA)\s+(\d{4})$/i;
+/** Morningstar writes "street, suburb, STATE 3000"; ASX's own field is "street, suburb, STATE, Australia, 3000". */
+const asxAddressFormat = (line) => {
+    const match = AU_TAIL.exec(line);
+    return match
+        ? `${match[1]}, ${match[2]}, ${match[3].toUpperCase()}, Australia, ${match[4]}`
+        : line;
+};
+const profileText = (payload, selector) => {
+    const response = payload?.response;
+    const match = response?.result?.find((entry) => entry.selector === selector);
+    return match?.results?.map((result) => result.text ?? "").join("\n") ?? "";
+};
+/** Morningstar's contact block: "Contact", the address line, "T <phone>", then the website. */
+const morningstarContact = (payload) => {
+    const lines = profileText(payload, ".sal-component-body:has(.sal-dp-pair-contact)")
+        .split("\n")
+        .map((line) => line.trim());
+    const start = lines.indexOf("Contact");
+    if (start < 0) {
+        return { address: null, tel: null };
+    }
+    let address = null;
+    let tel = null;
+    for (const line of lines.slice(start + 1, start + 5)) {
+        const phone = PHONE.exec(line);
+        if (phone?.[1]) {
+            tel = phone[1].trim();
+        }
+        else if (!(address || WEB.test(line)) && line.length > 5 && /\d/.test(line)) {
+            address = asxAddressFormat(line);
+        }
+    }
+    return { address, tel };
+};
+/**
+ * Contact details from collected public profiles, used only where the ASX profile is blank.
+ * Values are never inferred: each comes verbatim from one named source.
+ */
+export function profileContact(sources) {
+    const found = (name) => sources[name]?.status === "found" ? sources[name] : undefined;
+    const morningstar = found("morningstar");
+    const google = found("google-finance");
+    const contact = morningstar
+        ? morningstarContact(morningstar.payload)
+        : { address: null, tel: null };
+    const website = morningstar?.websites[0] ?? google?.websites[0] ?? null;
+    return {
+        address: contact.address,
+        tel: contact.tel,
+        website,
+        sources: {
+            ...(contact.address ? { address: "morningstar" } : {}),
+            ...(contact.tel ? { tel: "morningstar" } : {}),
+            ...(website
+                ? {
+                    website: morningstar?.websites[0]
+                        ? "morningstar"
+                        : "google-finance",
+                }
+                : {}),
+        },
+    };
+}

package/dist/publication.d.ts

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+declare const Current: Schema.Struct<{
+    readonly generation: Schema.String;
+    readonly version: Schema.NonEmptyString;
+}>;
+export type SnapshotPointer = typeof Current.Type;
+/** Implementations must use immutable writes and an atomic conditional pointer update. */
+export interface SnapshotPublicationStore {
+    readonly readCurrent: (signal: AbortSignal) => Promise<unknown>;
+    readonly readGeneration: (generation: string, signal: AbortSignal) => Promise<string | null>;
+    readonly writeGeneration: (generation: string, text: string, signal: AbortSignal) => Promise<void>;
+    readonly selectGeneration: (expectedVersion: string | null, generation: string, signal: AbortSignal) => Promise<boolean>;
+}
+export declare function createSnapshotPublisher(store: SnapshotPublicationStore): {
+    publish: (dataset: unknown, expectedGeneration: string | null, signal?: AbortSignal) => Promise<{
+        generation: string;
+        status: "published" | "already-current";
+    }>;
+    /** Restore retained bytes after full validation; never rewrite a historical generation. */
+    rollback: (generation: string, expectedGeneration: string, signal?: AbortSignal) => Promise<{
+        generation: string;
+        status: "restored" | "already-current";
+    }>;
+};
+export {};

package/dist/publication.js

@@ -0,0 +1,89 @@
+import { Effect, Result, Schema } from "effect";
+import { failure, Failure } from "./model.js";
+import { encodeSnapshot, openSnapshot } from "./snapshot.js";
+const Current = Schema.Struct({
+    generation: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+    version: Schema.NonEmptyString,
+});
+const io = (operation) => Effect.tryPromise({ try: operation, catch: () => failure("PERSISTENCE_FAILED") });
+const readCurrent = Effect.fn("ASX.publication.current")(function* (store) {
+    const current = yield* io(store.readCurrent);
+    return yield* Schema.decodeUnknownEffect(Schema.NullOr(Current))(current).pipe(Effect.mapError(() => failure("PERSISTENCE_FAILED")));
+});
+const verify = Effect.fn("ASX.publication.verify")(function* (store, generation, expectedText) {
+    const text = yield* io((signal) => store.readGeneration(generation, signal));
+    if (text !== expectedText)
+        return yield* Effect.fail(failure("PERSISTENCE_FAILED"));
+    yield* Effect.tryPromise({
+        try: () => openSnapshot(text, generation),
+        catch: () => failure("PERSISTENCE_FAILED"),
+    });
+});
+const publish = Effect.fn("ASX.publication.publish")(function* (store, dataset, expectedGeneration) {
+    const candidate = yield* Effect.tryPromise({
+        try: () => encodeSnapshot(dataset),
+        catch: () => failure("SNAPSHOT_UNAVAILABLE"),
+    });
+    const current = yield* readCurrent(store);
+    if (current?.generation === candidate.generation) {
+        yield* verify(store, candidate.generation, candidate.text);
+        return { generation: candidate.generation, status: "already-current" };
+    }
+    if ((current?.generation ?? null) !== expectedGeneration)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    yield* io((signal) => store.writeGeneration(candidate.generation, candidate.text, signal));
+    yield* verify(store, candidate.generation, candidate.text);
+    const selected = yield* io((signal) => store.selectGeneration(current?.version ?? null, candidate.generation, signal));
+    if (!selected)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    const selectedPointer = yield* readCurrent(store);
+    if (selectedPointer?.generation !== candidate.generation)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    return { generation: candidate.generation, status: "published" };
+});
+const rollback = Effect.fn("ASX.publication.rollback")(function* (store, generation, expectedGeneration) {
+    if (!/^[a-f0-9]{64}$/.test(generation) || !/^[a-f0-9]{64}$/.test(expectedGeneration))
+        return yield* Effect.fail(failure("INVALID_INPUT"));
+    const current = yield* readCurrent(store);
+    if (current?.generation !== generation && current?.generation !== expectedGeneration)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    const text = yield* io((signal) => store.readGeneration(generation, signal));
+    if (text === null)
+        return yield* Effect.fail(failure("SNAPSHOT_UNAVAILABLE"));
+    yield* Effect.tryPromise({
+        try: () => openSnapshot(text, generation),
+        catch: () => failure("SNAPSHOT_UNAVAILABLE"),
+    });
+    if (current?.generation === generation)
+        return { generation, status: "already-current" };
+    const selected = yield* io((signal) => store.selectGeneration(current?.version ?? null, generation, signal));
+    if (!selected)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    const selectedPointer = yield* readCurrent(store);
+    if (selectedPointer?.generation !== generation)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    return { generation, status: "restored" };
+});
+async function run(program, signal) {
+    try {
+        const result = await Effect.runPromise(Effect.result(program), { signal });
+        if (Result.isFailure(result))
+            throw result.failure;
+        return result.success;
+    }
+    catch (error) {
+        const code = signal?.aborted
+            ? "CANCELLED"
+            : Schema.is(Failure)(error)
+                ? error.code
+                : "INTERNAL_ERROR";
+        throw failure(code);
+    }
+}
+export function createSnapshotPublisher(store) {
+    return {
+        publish: (dataset, expectedGeneration, signal) => run(publish(store, dataset, expectedGeneration), signal),
+        /** Restore retained bytes after full validation; never rewrite a historical generation. */
+        rollback: (generation, expectedGeneration, signal) => run(rollback(store, generation, expectedGeneration), signal),
+    };
+}