@superbee/core 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/hosted-transport/answer-rows.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The hosted answer grammar, once: how every identified-write answer, every outcome-lookup
+ * answer and every read-route answer is classified, whichever client sent the request. The
+ * browser editor's body delivery and the CLI's whole-document sync read these same tables, so
+ * "recorded", "unknown" and "absent past retention" mean one thing in both.
+ *
+ * The update rows are hosted's browser table plus the sync quota rows (`request_capacity`),
+ * which only the `/sync/v1` routes answer. Until the hosted browser imports this module, hosted's golden exchanges
+ * (`test/fixtures/hosted-transport/`, produced from the hosted encoders) pin that these rows
+ * classify exactly what the host emits.
+ *
+ * The rows keep three facts apart: a refusal the host recorded under the request identity is
+ * definitive; a refusal answered before dispatch is definitive but unrecorded; and anything the
+ * host may have applied without saying so is unknown. Only two refusal codes reach the shared
+ * primitive's authorization set and pause the store: `AUTH_REQUIRED` (the carrier denied the
+ * request) and `PERMISSION_DENIED` (the host refused the caller's access to the bundle).
+ */
+import { type BlobWriteExpected, type BlobWriteSuccess, type BlobWriteFailure, type BlobWriteResult } from "../blob-contract.js";
+import type { Version } from "../types.js";
+import type { HostedAnswer } from "./carrier.js";
+/** A refusal code the shared primitive treats as lost authorization, pausing the store. */
+export type AuthorizationCode = "AUTH_REQUIRED" | "PERMISSION_DENIED";
+/**
+ * The refusal codes of a sync quota the host enforces on identified writes (`request_capacity`),
+ * one per scope it names: the person's rolling daily bound in this bundle, or the bundle's own
+ * bound. The shared primitive counts both as pausing refusals, so the store pauses with nothing
+ * lost and `resume` requeues the refused intents once the quota resets.
+ */
+export declare const CAPACITY_REFUSAL_CODES: Readonly<{
+    readonly principal: "REQUEST_CAPACITY_PRINCIPAL";
+    readonly bundle: "REQUEST_CAPACITY_BUNDLE";
+}>;
+export type CapacityScope = keyof typeof CAPACITY_REFUSAL_CODES;
+/**
+ * The refusal code of the host's mass-delete hold (`428 deletions_held`): a delete that would take
+ * over half of the bundle's documents within 24 hours, counted over every person and checkout. It
+ * never pauses: only a person's typed acknowledgment releases it, never time or a plain resend.
+ */
+export declare const DELETIONS_HELD_REFUSAL_CODE = "DELETIONS_HELD";
+/** The quota scope a refused outcome names, or `null` when it is not a capacity refusal. */
+export declare function capacityScopeOf(outcome: {
+    kind: string;
+    code?: string;
+}): CapacityScope | null;
+/**
+ * One identified-write answer and how the shared primitive sees it. `answer` names the hosted
+ * answer: the status, and for a `200` the definitive refusal code, `ok`, or `other` for a code,
+ * shape or size the client does not admit. `recorded` says whether the host holds the answer
+ * under the request identity: always, never (refused before dispatch), only when the settled
+ * header names the request, maybe (the write may have left), or unknown. `outcome` is the shared
+ * outcome kind once the answer is recorded. `code` is the authorization code a refusal carries
+ * when the host's own code must not reach the primitive.
+ */
+export type UpdateAnswerRow = Readonly<{
+    answer: string;
+    recorded: "yes" | "no" | "settled-only" | "maybe" | "unknown";
+    outcome: "committed" | "conflict" | "refused" | "unknown";
+    code?: AuthorizationCode;
+}>;
+export declare const UPDATE_ANSWER_ROWS: readonly UpdateAnswerRow[];
+/**
+ * One outcome-lookup answer and what the shared primitive receives: `null` says the host never
+ * recorded the identity, `pending` that it holds a claim without a result (a delivery was
+ * admitted and may still commit), an outcome is the recorded evidence,
+ * and `throws` leaves the intent recoverable because the evidence was unavailable. `absent` past
+ * the host's retention window, less the skew margin, is `unknown` rather than `null`: an expired
+ * identity looks absent, and absence must never let an old intent be resubmitted as if never
+ * delivered.
+ */
+export type OutcomeAnswerRow = Readonly<{
+    answer: string;
+    result: "null" | "pending" | "committed" | "recorded" | "unknown" | "throws";
+}>;
+export declare const OUTCOME_ANSWER_ROWS: readonly OutcomeAnswerRow[];
+/**
+ * One read-route answer (capabilities, heads, snapshot, document read) and what the working
+ * copy's pull sees. `admitted` is decoded; `not-modified` is a heads `304`; `truncated` is a
+ * snapshot that ended before its terminator, which the pull re-requests; `authority` is a
+ * refusal about the bundle or the caller, surfaced with the host's status and code; `offline`
+ * says nothing about the bundle (a `503`) and pauses the pull as a carrier failure; `restart`
+ * is a page the host refused because the bundle moved since the first page pinned it, so the
+ * reader starts the listing again from the first page (a snapshot reports it as truncation).
+ * A `page` answer is one page of a paged listing that names the next; the reader follows it.
+ */
+export type ReadAnswerRow = Readonly<{
+    answer: string;
+    result: "admitted" | "not-modified" | "truncated" | "authority" | "offline" | "restart";
+}>;
+export declare const READ_ANSWER_ROWS: readonly ReadAnswerRow[];
+/** The codes a write refusal may carry: the hosted write schema's closed set. */
+export declare const WRITE_ERROR_CODES: readonly ["field_action_refused", "invalid_input", "insufficient_scope", "bundle_not_found", "backend_unavailable", "document_not_found", "document_exists", "version_conflict", "body_edit_mismatch", "validation_failed", "result_too_large", "cancelled", "deadline_exceeded", "concurrent_change", "write_outcome_unknown", "internal_error", "candidate_unavailable", "candidate_recovery_unavailable", "document_id_not_canonical", "document_id_collision", "request_capacity", "deletions_held", "definition_incompatible"];
+export type WriteErrorCode = (typeof WRITE_ERROR_CODES)[number];
+/** The whole-document delete: its success names the tombstone as `version`, and the version that left. */
+export declare const DELETE_OPERATION_ID = "documents.delete.v1";
+export type WriteSuccess = {
+    ok: true;
+    operationId: string;
+    /**
+     * `version` is what committed: the document's new version, or for a delete the tombstone
+     * version. A delete's data alone also carries `deletedVersion` (the version that left, which
+     * is the request's `expectedVersion`) and `deleted: true`; `changed: false` there says the
+     * document had already left at exactly that base, and `version` names that deletion.
+     */
+    data: {
+        bundleId: string;
+        documentId: string;
+        version: Version;
+        changed: boolean;
+        scope?: unknown;
+        deletedVersion?: Version;
+        deleted?: true;
+    };
+};
+export type WriteFailure = {
+    ok: false;
+    operationId: string;
+    error: {
+        code: WriteErrorCode;
+        message: string;
+        retryable: false;
+        writeState: "not_applied" | "unknown";
+        currentVersion?: Version;
+        /** On `request_capacity` only: which bound refused. */
+        scope?: CapacityScope;
+        /** On `request_capacity` only, when the host states it: when the bound admits writes again (ISO instant). */
+        resetAt?: string;
+        /** On `deletions_held` only: the bundle's deletions in 24 hours with this one, and the documents it held when that window opened. */
+        deletions?: number;
+        baseline?: number;
+        /**
+         * On `definition_incompatible` only: the host's compatibility findings, carried as sent and
+         * read leniently by {@link definitionFindingsText} (as `fieldActionDetails` is carried), so a
+         * field the host adds later never makes the recorded refusal unreadable.
+         */
+        definitionDetails?: unknown;
+    };
+};
+export type WriteResult = WriteSuccess | WriteFailure;
+/** The bound on the findings text: the refusal message is journaled, so it stays small. */
+export declare const DEFINITION_FINDINGS_TEXT_BYTES = 2048;
+/**
+ * A model-change refusal's findings (`definitionDetails`) as text a person reads: one clause per
+ * finding, naming the rule, the Kind's type and field, the core code, and up to five documents
+ * with the full count, within {@link DEFINITION_FINDINGS_TEXT_BYTES}. Read leniently: a finding
+ * without a rule, or a part that is not short text, is left out; anything else the host sends is
+ * ignored. Empty when nothing is readable. The findings carry no values, bodies or authors, so
+ * neither does this.
+ */
+export declare function definitionFindingsText(details: unknown): string;
+export declare class HostedAnswerError extends Error {
+    readonly name = "HostedAnswerError";
+}
+/**
+ * A write operation's result envelope, admitted or refused as one: the operation it answers,
+ * the document it names, and a success with a content version or a refusal with a known code
+ * and write state. A refusal's detail blocks (diagnostics, corrective details) are carried but
+ * not interpreted here. `write_outcome_unknown` must say its write state is unknown.
+ */
+export declare function parseWriteResult(raw: unknown, expected: {
+    operationIds: readonly string[];
+    documentId: string;
+    bundleId?: string;
+}): WriteResult;
+/** The row named `answer`; every name this module uses is in the table. */
+export declare function updateRow(answer: string): UpdateAnswerRow;
+/** The row an identified-write answer falls under, and the validated envelope when it carries one. */
+export declare function classifyWriteAnswer(answer: HostedAnswer, expected: {
+    operationIds: readonly string[];
+    documentId: string;
+    bundleId?: string;
+}): {
+    row: UpdateAnswerRow;
+    result?: WriteResult;
+};
+/** Why an outcome lookup could not produce evidence; the primitive counts it as a failed lookup. */
+export declare class HostedOutcomeError extends Error {
+    readonly name = "HostedOutcomeError";
+    readonly reason: "refused" | "malformed" | "contradiction" | "unavailable";
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    constructor(reason: "refused" | "malformed" | "contradiction" | "unavailable", status?: number, code?: string);
+}
+/** A decoded outcome answer: one of the four observations the route makes. */
+export type OutcomeAnswer = {
+    status: "absent";
+} | {
+    status: "pending";
+}
+/** `content` is the committed bytes; `null` for a delete alone, whose tombstone has no bytes. */
+ | {
+    status: "committed";
+    result: WriteSuccess;
+    content: {
+        version: Version;
+        bytes: Uint8Array;
+    } | null;
+} | {
+    status: "refused";
+    result: WriteFailure;
+};
+/** An outcome answer carries the committed document's exact bytes under this bound. */
+export declare const OUTCOME_CONTENT_BYTES: number;
+/**
+ * The lookup route's `200` answer, admitted or refused as one: `schemaVersion` 1, the request
+ * identity and binding it answers for, and one status. A committed answer carries the original
+ * validated success and the committed document's exact bytes as base64 at the receipt's
+ * version (a delete's carries none: a tombstone has no bytes); a refused answer carries the
+ * original definitive failure. Anything else, including a
+ * stored result whose write state is not definitive, is malformed evidence.
+ */
+export declare function decodeOutcomeAnswer(value: unknown, expected: {
+    requestId: string;
+    binding: string;
+    bundleId: string;
+    documentId: string;
+    operationIds: readonly string[];
+}): OutcomeAnswer;
+export { BLOB_OPERATION_IDS } from "../blob-contract.js";
+export type { BlobOperationId, BlobWriteExpected, BlobWriteSuccess, BlobWriteErrorCode, BlobWriteFailure, BlobWriteResult } from "../blob-contract.js";
+export type BlobOutcomeAnswer = {
+    status: "absent";
+} | {
+    status: "committed";
+    result: BlobWriteSuccess;
+} | {
+    status: "refused";
+    result: BlobWriteFailure;
+};
+/** Preserve the hosted answer error facade around the neutral result grammar. */
+export declare function parseBlobWriteResult(raw: unknown, expected: BlobWriteExpected): BlobWriteResult;
+/** Blob operations share the document carrier rows, while retaining their separate result
+ * grammar. Malformed 200 answers stay unknown, never settling a possible delivery. */
+export declare function classifyBlobWriteAnswer(answer: HostedAnswer, expected: BlobWriteExpected): {
+    row: UpdateAnswerRow;
+    result?: BlobWriteResult;
+};
+/** Immutable blob evidence uses the common status/identity envelope without content bytes.
+ * A terminal result is checked against the original intent, never a later head observation. */
+export declare function decodeBlobOutcomeAnswer(value: unknown, expected: BlobWriteExpected & {
+    requestId: string;
+    binding: string;
+}): BlobOutcomeAnswer;
+//# sourceMappingURL=answer-rows.d.ts.map

package/dist/hosted-transport/answer-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-rows.d.ts","sourceRoot":"","sources":["../../src/hosted-transport/answer-rows.ts"],"names":[],"mappings":"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"}