@comms-id/asx 0.4.1 → 1.0.0

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/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),
+    };
+}

package/dist/refresh-coordinator.d.ts

@@ -0,0 +1,96 @@
+import { type CollectionSource, type RefreshCheckpoint } from "./collection.js";
+import { Failure } from "./model.js";
+import { type SnapshotPublicationStore } from "./publication.js";
+export interface RefreshState {
+    readonly nextAttemptAt: string;
+    readonly checkpoint: RefreshCheckpoint | null;
+    readonly lastCompletedAt: string | null;
+    readonly halted: typeof Failure.Type | null;
+}
+export interface RefreshStateStore {
+    readonly read: (signal: AbortSignal) => Promise<{
+        value: unknown;
+        version: string;
+    } | null>;
+    /** Atomic conditional write; return the new version, or null if another writer won. */
+    readonly save: (expectedVersion: string | null, value: RefreshState, signal: AbortSignal) => Promise<string | null>;
+}
+export interface RefreshCoordinatorOptions {
+    readonly enabled: boolean;
+    readonly batchSize: number;
+    readonly intervalMs: number;
+    readonly retryAfterMs: number;
+}
+export interface RefreshRecovery {
+    /** Version observed by the operator; stale recovery commands must not change newer progress. */
+    readonly expectedVersion: string;
+    readonly action: "resume" | "restart";
+}
+export declare function decodeRefreshState(input: unknown): RefreshState;
+/** One step per scheduled tick. The host supplies admitted storage, source permission and pacing. */
+export declare function createRefreshCoordinator(source: CollectionSource, progress: RefreshStateStore, publication: SnapshotPublicationStore): {
+    /** The host authenticates the operator and serializes this with maintenance. No source or pointer I/O. */
+    recover: (input: RefreshRecovery, now: string, signal?: AbortSignal) => Promise<{
+        status: "recovered";
+        action: "restart" | "resume";
+        version: string;
+        nextAttemptAt: string;
+    }>;
+    step: (options: RefreshCoordinatorOptions, now: string, signal?: AbortSignal) => Promise<{
+        status: "disabled";
+        nextAttemptAt?: undefined;
+        completed?: undefined;
+        total?: undefined;
+        reason?: undefined;
+        generation?: undefined;
+        report?: undefined;
+    } | {
+        status: "halted";
+        reason: "ACCESS_DENIED" | "CANCELLED" | "CONFIGURATION_ERROR" | "COVERAGE_REJECTED" | "INTERNAL_ERROR" | "INVALID_INPUT" | "PARSE_FAILED" | "PERSISTENCE_FAILED" | "PUBLICATION_CONFLICT" | "SNAPSHOT_UNAVAILABLE" | "SOURCE_MISMATCH" | "TIMEOUT" | "TRANSPORT_FAILED" | "UPSTREAM_REJECTED" | "UPSTREAM_UNAVAILABLE";
+        nextAttemptAt?: undefined;
+        completed?: undefined;
+        total?: undefined;
+        generation?: undefined;
+        report?: undefined;
+    } | {
+        status: "waiting";
+        nextAttemptAt: string;
+        completed?: undefined;
+        total?: undefined;
+        reason?: undefined;
+        generation?: undefined;
+        report?: undefined;
+    } | {
+        nextAttemptAt?: undefined;
+        status: "collecting" | "halted";
+        completed: number;
+        total: number;
+        reason?: undefined;
+        generation?: undefined;
+        report?: undefined;
+    } | {
+        nextAttemptAt?: undefined;
+        completed?: undefined;
+        total?: undefined;
+        status: "halted";
+        reason: "COVERAGE_REJECTED";
+        report: import("./refresh.js").RefreshReport;
+        generation?: undefined;
+    } | {
+        nextAttemptAt?: undefined;
+        completed?: undefined;
+        total?: undefined;
+        reason?: undefined;
+        status: "retrying";
+        report: import("./refresh.js").RefreshReport;
+        generation?: undefined;
+    } | {
+        nextAttemptAt?: undefined;
+        completed?: undefined;
+        total?: undefined;
+        reason?: undefined;
+        status: "published";
+        generation: string;
+        report: import("./refresh.js").RefreshReport;
+    }>;
+};

package/dist/refresh-coordinator.js

@@ -0,0 +1,194 @@
+import { Effect, Result, Schema } from "effect";
+import { createRefreshCollector, decodeRefreshCheckpoint, } from "./collection.js";
+import { failure, Failure, isTimestamp, Timestamp } from "./model.js";
+import { createSnapshotPublisher } from "./publication.js";
+import { applyRefresh } from "./refresh.js";
+import { openSnapshot } from "./snapshot.js";
+const State = Schema.Struct({
+    nextAttemptAt: Timestamp,
+    checkpoint: Schema.NullOr(Schema.Unknown),
+    lastCompletedAt: Schema.NullOr(Timestamp),
+    halted: Schema.NullOr(Failure),
+});
+export function decodeRefreshState(input) {
+    const decoded = Schema.decodeUnknownResult(State)(input);
+    if (Result.isFailure(decoded) ||
+        !isTimestamp(decoded.success.nextAttemptAt) ||
+        (decoded.success.lastCompletedAt !== null && !isTimestamp(decoded.success.lastCompletedAt)))
+        throw failure("PERSISTENCE_FAILED");
+    return {
+        ...decoded.success,
+        checkpoint: decoded.success.checkpoint === null
+            ? null
+            : decodeRefreshCheckpoint(decoded.success.checkpoint),
+    };
+}
+const safe = (error) => Schema.is(Failure)(error) ? error : failure("PERSISTENCE_FAILED");
+const io = (operation) => Effect.tryPromise({ try: operation, catch: safe });
+const save = Effect.fn("ASX.refresh.save")(function* (store, version, state) {
+    const next = yield* io((signal) => store.save(version, state, signal));
+    if (!next)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    return next;
+});
+const recover = Effect.fn("ASX.refresh.recover")(function* (progress, input, now) {
+    if (!isTimestamp(now) ||
+        typeof input.expectedVersion !== "string" ||
+        !input.expectedVersion.trim() ||
+        input.expectedVersion.length > 1024 ||
+        !["resume", "restart"].includes(input.action))
+        return yield* Effect.fail(failure("INVALID_INPUT"));
+    const stored = yield* io(progress.read);
+    if (stored === null || stored.version !== input.expectedVersion)
+        return yield* Effect.fail(failure("PUBLICATION_CONFLICT"));
+    const state = yield* Effect.try({ try: () => decodeRefreshState(stored.value), catch: safe });
+    if (!state.halted || !state.checkpoint)
+        return yield* Effect.fail(failure("INVALID_INPUT"));
+    // A rejected directory must be fetched again; recovery never waives publication validation.
+    if (state.halted.code === "COVERAGE_REJECTED" && input.action === "resume")
+        return yield* Effect.fail(failure("COVERAGE_REJECTED"));
+    const nextAttemptAt = state.halted.code === "RATE_LIMITED" && state.nextAttemptAt > now ? state.nextAttemptAt : now;
+    const version = yield* save(progress, stored.version, {
+        ...state,
+        checkpoint: input.action === "restart" ? null : state.checkpoint,
+        halted: null,
+        nextAttemptAt,
+    });
+    return { status: "recovered", action: input.action, version, nextAttemptAt };
+});
+const step = Effect.fn("ASX.refresh.step")(function* (source, progress, publication, options, now) {
+    if (!options.enabled)
+        return { status: "disabled" };
+    if (!isTimestamp(now) ||
+        !Number.isInteger(options.batchSize) ||
+        options.batchSize < 1 ||
+        options.batchSize > 100 ||
+        !Number.isInteger(options.intervalMs) ||
+        options.intervalMs < 0 ||
+        options.intervalMs > 60_000 ||
+        !Number.isInteger(options.retryAfterMs) ||
+        options.retryAfterMs < 60_000 ||
+        options.retryAfterMs > 86_400_000)
+        return yield* Effect.fail(failure("CONFIGURATION_ERROR"));
+    const stored = yield* io(progress.read);
+    let state = stored === null
+        ? { nextAttemptAt: now, checkpoint: null, lastCompletedAt: null, halted: null }
+        : yield* Effect.try({ try: () => decodeRefreshState(stored.value), catch: safe });
+    if (state.halted && state.halted.code !== "RATE_LIMITED")
+        return { status: "halted", reason: state.halted.code };
+    if (now < state.nextAttemptAt)
+        return { status: "waiting", nextAttemptAt: state.nextAttemptAt };
+    let version = stored?.version ?? null;
+    const collector = createRefreshCollector(source);
+    if (state.checkpoint === null) {
+        const pointerInput = yield* io(publication.readCurrent);
+        const pointer = yield* Schema.decodeUnknownEffect(Schema.NullOr(Schema.Struct({
+            generation: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+            version: Schema.NonEmptyString,
+        })))(pointerInput).pipe(Effect.mapError(() => failure("PERSISTENCE_FAILED")));
+        const checkpoint = yield* io((signal) => collector.begin(pointer?.generation ?? null, signal));
+        state = { ...state, checkpoint, halted: null };
+        version = yield* save(progress, version, state);
+    }
+    const checkpoint = state.checkpoint;
+    if (!checkpoint)
+        return yield* Effect.fail(failure("INTERNAL_ERROR"));
+    const collected = yield* io((signal) => collector.batch(checkpoint, { ...options, signal }));
+    state = {
+        ...state,
+        checkpoint: collected.checkpoint,
+        halted: collected.halted,
+        nextAttemptAt: collected.halted
+            ? new Date(Date.parse(now) + options.retryAfterMs).toISOString()
+            : now,
+    };
+    version = yield* save(progress, version, state);
+    if (!collected.complete)
+        return {
+            status: collected.halted ? "halted" : "collecting",
+            completed: collected.checkpoint.attempts.length,
+            total: collected.checkpoint.directory.entries.length,
+        };
+    let previous = null;
+    let previousCount = 0;
+    if (checkpoint.baseGeneration) {
+        const text = yield* io((signal) => publication.readGeneration(checkpoint.baseGeneration ?? "", signal));
+        if (text === null)
+            return yield* Effect.fail(failure("SNAPSHOT_UNAVAILABLE"));
+        const priorSnapshot = yield* io(() => openSnapshot(text, checkpoint.baseGeneration ?? ""));
+        previousCount = priorSnapshot.metadata().records;
+        previous = yield* Effect.try({
+            try: () => JSON.parse(text),
+            catch: () => failure("SNAPSHOT_UNAVAILABLE"),
+        });
+    }
+    const prepared = yield* Effect.try({
+        try: () => applyRefresh(previous, collected.checkpoint.directory, collected.checkpoint.attempts),
+        catch: safe,
+    });
+    // A syntactically valid truncated directory must not silently withdraw many issuers.
+    // This is a publication safety limit, not an ASX completeness or freshness guarantee.
+    if (previousCount > 0 && prepared.report.removedFromDirectory / previousCount > 0.05) {
+        yield* save(progress, version, { ...state, halted: failure("COVERAGE_REJECTED") });
+        return {
+            status: "halted",
+            reason: "COVERAGE_REJECTED",
+            report: prepared.report,
+        };
+    }
+    // An initial directory is useful even with missing profiles. Health reports its actual coverage.
+    // A completely failed later profile pass keeps the existing selected dataset.
+    if (previous !== null && prepared.report.found === 0) {
+        yield* save(progress, version, {
+            ...state,
+            checkpoint: null,
+            halted: null,
+            nextAttemptAt: new Date(Date.parse(now) + options.retryAfterMs).toISOString(),
+        });
+        return { status: "retrying", report: prepared.report };
+    }
+    const published = yield* io((signal) => createSnapshotPublisher(publication).publish(prepared.dataset, checkpoint.baseGeneration, signal));
+    yield* save(progress, version, {
+        checkpoint: null,
+        lastCompletedAt: now,
+        halted: null,
+        nextAttemptAt: new Date(Date.parse(collected.checkpoint.directory.observedAt) + 86_400_000).toISOString(),
+    });
+    return {
+        status: "published",
+        generation: published.generation,
+        report: prepared.report,
+    };
+});
+/** One step per scheduled tick. The host supplies admitted storage, source permission and pacing. */
+export function createRefreshCoordinator(source, progress, publication) {
+    return {
+        /** The host authenticates the operator and serializes this with maintenance. No source or pointer I/O. */
+        recover: async (input, now, signal) => {
+            if (signal?.aborted)
+                throw failure("CANCELLED");
+            try {
+                const result = await Effect.runPromise(Effect.result(recover(progress, input, now)), {
+                    signal,
+                });
+                if (Result.isFailure(result))
+                    throw result.failure;
+                return result.success;
+            }
+            catch (error) {
+                throw signal?.aborted ? failure("CANCELLED") : safe(error);
+            }
+        },
+        step: async (options, now, signal) => {
+            try {
+                const result = await Effect.runPromise(Effect.result(step(source, progress, publication, options, now)), { signal });
+                if (Result.isFailure(result))
+                    throw result.failure;
+                return result.success;
+            }
+            catch (error) {
+                throw signal?.aborted ? failure("CANCELLED") : safe(error);
+            }
+        },
+    };
+}