@comms-id/asx 0.4.0 → 0.4.2

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

package/dist/refresh.d.ts

@@ -0,0 +1,126 @@
+import { Schema } from "effect";
+import { type AsxDataset } from "./snapshot.js";
+export declare const RefreshAttempt: Schema.Struct<{
+    readonly ticker: Schema.String;
+    readonly outcome: Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly status: Schema.Literal<"found">;
+        readonly observation: Schema.Struct<{
+            readonly company: Schema.Struct<{
+                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>>>;
+    }>]>, 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"]>;
+    }>]>;
+    readonly enrichment: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
+        readonly status: Schema.Literal<"confirmed">;
+        readonly enrichment: Schema.Struct<{
+            readonly ticker: Schema.String;
+            readonly sourceId: Schema.NonEmptyString;
+            readonly abn: Schema.String;
+            readonly acn: Schema.NullOr<Schema.String>;
+            readonly legalName: Schema.NonEmptyString;
+            readonly identityEvidence: Schema.Struct<{
+                readonly url: Schema.String;
+                readonly sha256: Schema.String;
+                readonly observedAt: Schema.String;
+                readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+            }>;
+            readonly abrEvidence: Schema.Struct<{
+                readonly source: Schema.Literals<readonly ["abr-live", "abr-snapshot"]>;
+                readonly observedAt: Schema.String;
+            }>;
+            readonly website: Schema.NullOr<Schema.Struct<{
+                readonly url: Schema.String;
+                readonly evidence: Schema.Struct<{
+                    readonly url: Schema.String;
+                    readonly sha256: Schema.String;
+                    readonly observedAt: Schema.String;
+                    readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+                }>;
+            }>>;
+        }>;
+    }>, Schema.Struct<{
+        readonly status: Schema.Literal<"unresolved">;
+        readonly reason: Schema.Literals<readonly ["NO_EVIDENCE", "AMBIGUOUS", "INVALID_EVIDENCE", "IDENTITY_MISMATCH"]>;
+    }>]>, 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"]>;
+    }>]>>;
+    readonly sources: Schema.optionalKey<Schema.Struct<{
+        readonly asx: Schema.optionalKey<Schema.Struct<{
+            readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+            readonly ticker: Schema.String;
+            readonly sourceUrl: Schema.String;
+            readonly sourceId: Schema.NonEmptyString;
+            readonly status: Schema.Literals<readonly ["found", "missing"]>;
+            readonly startedAt: Schema.String;
+            readonly observedAt: Schema.String;
+            readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly websites: Schema.$Array<Schema.String>;
+        }>>;
+        readonly morningstar: Schema.optionalKey<Schema.Struct<{
+            readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+            readonly ticker: Schema.String;
+            readonly sourceUrl: Schema.String;
+            readonly sourceId: Schema.NonEmptyString;
+            readonly status: Schema.Literals<readonly ["found", "missing"]>;
+            readonly startedAt: Schema.String;
+            readonly observedAt: Schema.String;
+            readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly websites: Schema.$Array<Schema.String>;
+        }>>;
+        readonly "google-finance": Schema.optionalKey<Schema.Struct<{
+            readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+            readonly ticker: Schema.String;
+            readonly sourceUrl: Schema.String;
+            readonly sourceId: Schema.NonEmptyString;
+            readonly status: Schema.Literals<readonly ["found", "missing"]>;
+            readonly startedAt: Schema.String;
+            readonly observedAt: Schema.String;
+            readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly websites: Schema.$Array<Schema.String>;
+        }>>;
+    }>>;
+}>;
+export type RefreshAttempt = typeof RefreshAttempt.Type;
+export interface RefreshReport {
+    readonly attempted: number;
+    readonly found: number;
+    readonly missing: number;
+    readonly failed: number;
+    readonly retained: number;
+    readonly unavailable: number;
+    readonly removedFromDirectory: number;
+    readonly superseded: number;
+}
+/** Pure publication preparation. All directory members must have an explicit attempt. */
+export declare function applyRefresh(previousInput: unknown, directoryInput: unknown, attemptsInput: unknown): {
+    dataset: AsxDataset;
+    report: RefreshReport;
+};

package/dist/refresh.js

@@ -0,0 +1,157 @@
+import { Result, Schema } from "effect";
+import { DirectoryEntry, failure, Failure, isTimestamp, LiveOutcome, Ticker, validObservation, } from "./model.js";
+import { decodeDataset } from "./snapshot.js";
+import { EnrichmentResult, validEnrichment } from "./enrichment.js";
+import { CompanySources, mergeCompanySources } from "./source-record.js";
+const DirectoryObservation = Schema.Struct({
+    entries: Schema.Array(DirectoryEntry),
+    observedAt: Schema.String,
+});
+export const RefreshAttempt = Schema.Struct({
+    ticker: Ticker,
+    outcome: Schema.Union([LiveOutcome, Failure]),
+    enrichment: Schema.optionalKey(Schema.Union([EnrichmentResult, Failure])),
+    sources: Schema.optionalKey(CompanySources),
+});
+/** Pure publication preparation. All directory members must have an explicit attempt. */
+export function applyRefresh(previousInput, directoryInput, attemptsInput) {
+    const previous = previousInput === null ? null : decodeDataset(previousInput);
+    const directoryResult = Schema.decodeUnknownResult(DirectoryObservation)(directoryInput);
+    const attemptsResult = Schema.decodeUnknownResult(Schema.Array(RefreshAttempt))(attemptsInput);
+    if (Result.isFailure(directoryResult) || Result.isFailure(attemptsResult))
+        throw failure("PARSE_FAILED");
+    const directory = directoryResult.success;
+    if (!isTimestamp(directory.observedAt) ||
+        (previous && directory.observedAt < previous.directoryObservedAt))
+        throw failure("SOURCE_MISMATCH");
+    const attempts = new Map(attemptsResult.success.map((attempt) => [attempt.ticker, attempt]));
+    const directoryTickers = new Set(directory.entries.map((entry) => entry.ticker));
+    if (directory.entries.length === 0 ||
+        directory.entries.length > 20_000 ||
+        directoryTickers.size !== directory.entries.length ||
+        attempts.size !== attemptsResult.success.length ||
+        attempts.size !== directory.entries.length ||
+        [...attempts.keys()].some((ticker) => !directoryTickers.has(ticker)))
+        throw failure("PARSE_FAILED");
+    const old = new Map(previous?.records.map((record) => [record.directory.ticker, record]) ?? []);
+    const report = {
+        attempted: attempts.size,
+        found: 0,
+        missing: 0,
+        failed: 0,
+        retained: 0,
+        unavailable: 0,
+        removedFromDirectory: [...old.keys()].filter((ticker) => !directoryTickers.has(ticker)).length,
+        superseded: 0,
+    };
+    const records = directory.entries.map((entry) => {
+        const attempt = attempts.get(entry.ticker);
+        if (!attempt)
+            throw failure("PARSE_FAILED");
+        const { outcome } = attempt;
+        if (attempt.enrichment !== undefined) {
+            if ("_tag" in outcome || outcome.status !== "found")
+                throw failure("SOURCE_MISMATCH");
+            if (!("_tag" in attempt.enrichment) &&
+                attempt.enrichment.status === "confirmed" &&
+                !validEnrichment(attempt.enrichment.enrichment, outcome.observation.company))
+                throw failure("SOURCE_MISMATCH");
+        }
+        const prior = old.get(entry.ticker);
+        let acceptedProfile = false;
+        let observation = null;
+        let missingAt = prior?.missingAt;
+        if ("_tag" in outcome) {
+            report.failed += 1;
+            // A changed directory name cannot establish continuity of a reused ticker.
+            if (outcome.code !== "SOURCE_MISMATCH" &&
+                prior?.directory.companyName === entry.companyName &&
+                prior.observation) {
+                observation = prior.observation;
+                report.retained += 1;
+            }
+        }
+        else if (outcome.status === "missing") {
+            if (!isTimestamp(outcome.observedAt) ||
+                !isTimestamp(outcome.startedAt) ||
+                outcome.startedAt > outcome.observedAt)
+                throw failure("PARSE_FAILED");
+            report.missing += 1;
+            if (prior?.observation &&
+                outcome.startedAt < prior.observation.startedAt &&
+                prior.directory.companyName === entry.companyName) {
+                observation = prior.observation;
+                report.superseded += 1;
+            }
+            else if (!missingAt || outcome.startedAt >= missingAt.startedAt) {
+                missingAt = { startedAt: outcome.startedAt, observedAt: outcome.observedAt };
+            }
+        }
+        else {
+            if (!validObservation(outcome.observation) ||
+                outcome.observation.company.ticker !== entry.ticker)
+                throw failure("SOURCE_MISMATCH");
+            report.found += 1;
+            observation = outcome.observation;
+            acceptedProfile = true;
+            const oldObservation = prior?.observation;
+            if (missingAt && observation.startedAt <= missingAt.startedAt) {
+                observation = null;
+                acceptedProfile = false;
+                report.superseded += 1;
+            }
+            else if (oldObservation) {
+                missingAt = undefined;
+                if (observation.startedAt < oldObservation.startedAt) {
+                    acceptedProfile = false;
+                    observation = prior?.directory.companyName === entry.companyName ? oldObservation : null;
+                    report.superseded += 1;
+                }
+                else if (observation.company.sourceId === oldObservation.company.sourceId &&
+                    JSON.stringify(observation.company) === JSON.stringify(oldObservation.company)) {
+                    observation = { ...observation, lastChangedAt: oldObservation.lastChangedAt };
+                }
+            }
+            else {
+                missingAt = undefined;
+            }
+        }
+        if (observation === null)
+            report.unavailable += 1;
+        let enrichment = observation && prior?.enrichment && validEnrichment(prior.enrichment, observation.company)
+            ? prior.enrichment
+            : undefined;
+        if (acceptedProfile && attempt.enrichment && !("_tag" in attempt.enrichment)) {
+            // A completed check can remove an automatic match; transport failure cannot.
+            enrichment =
+                attempt.enrichment.status === "confirmed" ? attempt.enrichment.enrichment : undefined;
+        }
+        return {
+            directory: entry,
+            observation,
+            ...(attempt.sources || prior?.sources
+                ? {
+                    sources: mergeCompanySources(entry.ticker, prior?.directory.companyName === entry.companyName &&
+                        (!observation ||
+                            prior.observation?.company.sourceId === observation.company.sourceId)
+                        ? (prior.sources ?? {})
+                        : {}, attempt.sources ?? {}),
+                }
+                : {}),
+            ...(missingAt ? { missingAt } : {}),
+            ...(enrichment ? { enrichment } : {}),
+            // A name match belongs to the directory name it was made for (#385).
+            ...(prior?.abnNameMatch && prior.directory.companyName === entry.companyName
+                ? { abnNameMatch: prior.abnNameMatch }
+                : {}),
+        };
+    });
+    return {
+        dataset: decodeDataset({
+            formatVersion: 1,
+            directoryObservedAt: directory.observedAt,
+            records,
+        }),
+        report,
+    };
+}

package/dist/requests.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+export declare const AsxLookupRequestSchema: Schema.Struct<{
+    readonly ticker: Schema.String;
+    readonly mode: Schema.optionalKey<Schema.Literals<readonly ["live", "snapshot", "live-first"]>>;
+}>;
+export declare const AsxSuggestRequestSchema: Schema.Struct<{
+    readonly mode: Schema.optionalKey<Schema.Literals<readonly ["live", "snapshot", "live-first"]>>;
+    readonly query: Schema.String;
+    readonly limit: Schema.optionalKey<Schema.Number>;
+}>;

package/dist/requests.js

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+// Request bodies for the hosted ASX service (platform #515): the worker decodes with these,
+// and the v1 contract is built from them.
+const Mode = Schema.Literals(["live", "snapshot", "live-first"]).annotate({
+    description: "live: ASX now; snapshot: the stored directory; live-first: ASX, then the snapshot on failure.",
+});
+export const AsxLookupRequestSchema = Schema.Struct({
+    ticker: Schema.String.check(Schema.isMaxLength(128)).annotate({
+        description: "The ASX ticker, for example 'BHP'.",
+    }),
+    mode: Schema.optionalKey(Mode),
+});
+export const AsxSuggestRequestSchema = Schema.Struct({
+    mode: Schema.optionalKey(Mode),
+    query: Schema.String.check(Schema.isMaxLength(200)).annotate({
+        description: "A ticker or company name prefix.",
+    }),
+    limit: Schema.optionalKey(Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: 10 })).annotate({
+        description: "How many suggestions to return, 1 to 10.",
+    })),
+});

package/dist/runtime/http.js

@@ -142,7 +142,9 @@ const prepare = (operation, input) => {
 /** Sends one operation and returns its decoded reply, or throws a CommsIdError. */
 export const call = async (transport, operation, input, options = {}) => {
     const body = prepare(operation, input);
-    const deadline = AbortSignal.timeout(options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const deadlineMs = options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    const startedAt = performance.now();
+    const deadline = AbortSignal.timeout(deadlineMs);
     const signal = options.signal === undefined ? deadline : AbortSignal.any([options.signal, deadline]);
     const maxRetries = operation.safeToRetry ? (transport.maxRetries ?? DEFAULT_MAX_RETRIES) : 0;
     const sleep = transport.sleep ?? defaultSleep;
@@ -155,6 +157,11 @@ export const call = async (transport, operation, input, options = {}) => {
             throw result.error;
         }
         const delay = result.retryAfterMs ?? Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+        // A retry that cannot start within this call's budget must not replace a real
+        // service failure (notably 429) with a later timeout or violate Retry-After.
+        if (delay >= deadlineMs - (performance.now() - startedAt)) {
+            throw result.error;
+        }
         try {
             await sleep(delay, signal);
         }

package/dist/search-service.d.ts

@@ -0,0 +1,16 @@
+import { type SuggestionsReply } from "./client-replies.js";
+import type { LookupMode } from "./service.js";
+type Source = (query: string, limit: number, signal: AbortSignal) => Promise<unknown>;
+export interface AsxSearchSources {
+    readonly live?: Source;
+    readonly snapshot?: Source;
+}
+/** Read-only search composition. Live-first acquires saved evidence only after an eligible outage. */
+export declare function createAsxSearchService(sources: AsxSearchSources): {
+    suggest: (query: string, options?: {
+        mode?: LookupMode;
+        limit?: number;
+        signal?: AbortSignal;
+    }) => Promise<SuggestionsReply>;
+};
+export {};