@superbee/core 0.1.6 → 0.2.0-pre.10

package/dist/platform.d.ts

@@ -0,0 +1,239 @@
+/**
+ * The platform contract an application programs against, above the two execution
+ * implementations: request-driven (every verb is a request to the shared authority) and
+ * browser-local (every verb runs against the page's own working copy, related to the authority
+ * by synchronization). A presentation receives a {@link PlatformRuntime} and nothing else; it
+ * never touches a backend, a transport, or a store.
+ *
+ * Provenance is the explicit result difference the two implementations are allowed to have.
+ * Every read, query row, validation, and commit states where its answer stands with respect to
+ * the shared authority:
+ *
+ * - `shared-confirmed`: the authority acknowledged or served exactly this content at the
+ *   runtime's last exchange with it. It may only be produced from an authority acknowledgement
+ *   (a write the authority answered, or an intent it acknowledged under its request identity)
+ *   or from an authority read (a request-driven read, or a working copy refreshed from the
+ *   authority with no local edit outstanding). A local write never produces it, so no
+ *   presentation can report shared confirmation without an acknowledgement. It says nothing
+ *   about what the authority holds now: request-driven's last exchange is the request itself,
+ *   browser-local's is its last sync, and the authority may have moved (or deleted the document)
+ *   since. A document the authority deleted disappears from a browser-local working copy at
+ *   its next sync (pull reconciles deletions against the authority's heads) unless a local
+ *   edit holds it, in which case pull retains the local content and rewrites its base to an
+ *   absent shared version, and the document reads `local-pending` until push delivers the edit
+ *   and settles the authority's conflict answer (a 412 whose actual version is `null`) as a
+ *   conflict against an absent remote, from which point it reads `local-conflict` with
+ *   `remote: null`; request-driven answers absence directly. Between syncs a deleted document
+ *   still reads `shared-confirmed` at its last served version, so a presentation must not read
+ *   `shared-confirmed` as proof of present existence.
+ * - `local-pending`: the working copy holds a local edit the authority has not accepted;
+ *   `requestId` names the journaled intent that will deliver it and `base` the shared version
+ *   the edit was made against.
+ * - `local-conflict`: the authority's head moved under a local edit; `remote` is the version the
+ *   authority held when the conflict was recorded, and the local content is retained. Any
+ *   conflict intent on a document decides its provenance, even after further local edits
+ *   chained behind it.
+ *
+ * One token space per runtime. In every provenance state `version` is the runtime's own premise
+ * token: the value an application may pass back as `expectedVersion`, equal to the `version` of
+ * a query row for the same document. For browser-local that is the working copy's document
+ * version; for request-driven it is the authority's. `shared-confirmed` also carries
+ * `acknowledged`, the token the authority mints for the same content, which differs from
+ * `version` whenever the authority hashes bytes the working copy normalizes differently (a
+ * filesystem authority over hand-authored files). An application compares `acknowledged` to the
+ * authority and `version` to its own runtime, never one to the other.
+ *
+ * Model semantics (what a document is, how a query filters, what a kind warns about, when a
+ * commit changes nothing) are identical across implementations; the contract kit in
+ * `@superbee/browser-local` proves that by running one row table against both.
+ *
+ * This module carries types and pure helpers only: no behaviour, no Node builtins, so it
+ * bundles for the browser (see `test/browser-bundle.test.ts`).
+ */
+import type { ConceptId, Frontmatter, OkfDocument, QueryFilter, Version } from "./types.js";
+import type { ValidationWarning } from "./validation.js";
+/** Which execution implementation answers a runtime's verbs. */
+export type ExecutionMode = "request-driven" | "browser-local";
+/** Where a result stands with respect to the shared authority. */
+export type Provenance = {
+    state: "shared-confirmed";
+    version: Version;
+    acknowledged: Version;
+} | {
+    state: "local-pending";
+    version: Version;
+    base: Version | null;
+    requestId: string;
+} | {
+    state: "local-conflict";
+    version: Version;
+    base: Version | null;
+    remote: Version | null;
+    requestId: string;
+};
+/** The three words a presentation shows for a provenance. */
+export type ProvenanceLabel = "shared" | "pending" | "conflict";
+/** What an implementation can do; a presentation adapts its affordances to these, never to the mode name. */
+export interface PlatformCapabilities {
+    mode: ExecutionMode;
+    /** Commits succeed without the authority reachable. */
+    offlineCommits: boolean;
+    /** Documents and pending edits survive a reload of the host. */
+    localPersistence: boolean;
+}
+export interface PlatformDocument {
+    doc: OkfDocument;
+    provenance: Provenance;
+}
+export interface PlatformQueryRow {
+    id: ConceptId;
+    version: Version;
+    frontmatter: Frontmatter;
+    provenance: Provenance;
+}
+export interface PlatformValidation {
+    id: ConceptId;
+    /** Kind warnings for this document against the bundle's own conventions; empty when it conforms or no kind governs it. */
+    warnings: ValidationWarning[];
+    provenance: Provenance;
+}
+/** A body edit; `expectedVersion` is the version the application read and is editing over. */
+export interface PlatformEdit {
+    body: string;
+    /**
+     * The version the edit was made against: the `version` a read, query row, or commit of this
+     * runtime reported. Omitted, the runtime reads, decides and writes with its own retry. Given,
+     * the commit is a single compare-and-swap at that premise: request-driven
+     * rejects a stale premise with `VersionConflict` at commit time; browser-local applies the edit
+     * to the working copy at that local premise and surfaces a moved shared head as
+     * `local-conflict` when it synchronizes.
+     */
+    expectedVersion?: Version;
+}
+export interface PlatformCommit {
+    id: ConceptId;
+    /** False when the engine found nothing to change; the provenance is then the document's existing one. */
+    changed: boolean;
+    provenance: Provenance;
+}
+/**
+ * Why a browser-local sync applied none of the deletions a verified listing implied:
+ * `empty-listing` names no document while the working copy holds some, `over-half` names so
+ * few that more than half of the working copy would go. Only a listing that would remove at
+ * least eight documents is bounded; fewer are applied on the authority's word.
+ */
+export type RefusedDeletionsReason = "empty-listing" | "over-half";
+/**
+ * The deletions a browser-local sync refused to apply, exactly as recorded on its last pull.
+ * `digest` names the listing that implied them; a caller that has judged the shrink genuine
+ * passes the record back as {@link PlatformSyncOptions.acceptRefusedDeletions}.
+ */
+export interface RefusedDeletions {
+    /** How many documents the listing would have removed from the working copy. */
+    deletions: number;
+    reason: RefusedDeletionsReason;
+    /** The heads digest of the listing that was refused. */
+    digest: string;
+}
+/** How the runtime's last sync ended; see {@link PlatformSyncStatus.lastSync}. */
+export interface PlatformSyncOutcome {
+    /** False when the sync rejected (a carrier failure, or an authority answer the runtime could not apply). */
+    ok: boolean;
+    /** The rejection's `name: message` when `ok` is false. */
+    error?: string;
+    /** The deletions the last completed pull refused; present until a pull applies or clears them. */
+    refusedDeletions?: RefusedDeletions;
+}
+export interface PlatformSyncOptions {
+    /**
+     * The refusal the last sync reported (`lastSync.refusedDeletions`), passed back to say the
+     * shrink it describes is genuine. Browser-local applies the deletions only when the
+     * authority's current listing still carries the same digest, count and reason; a listing
+     * that has moved since is refused afresh. When another realm holds the push role, a sync
+     * passing it applies nothing, records `lastSync.ok` false and rejects, so the caller can retry.
+     * One whose pull another realm supersedes twice also records `lastSync.ok` false and rejects,
+     * possibly with some deletions applied, and reports a refusal in `lastSync.refusedDeletions`
+     * for the retry to pass back: a fresh one when the listing moved, not necessarily the one
+     * passed. It is shown only while the superseding pull's marker is unfinished, and is held in
+     * memory only, so a page reload loses it; a later plain pull that refuses records it on its
+     * marker again.
+     * Request-driven ignores it: nothing is ever refused there.
+     */
+    acceptRefusedDeletions?: RefusedDeletions;
+}
+/**
+ * The runtime's relation to the authority as of its last exchange. `online` reports the
+ * carrier: it turns false only when a request could not reach the authority, never on an
+ * answer the authority gave. `lastSync` reports the sync verb itself, and is the field a
+ * presentation must show to distinguish "synchronized" from "tried and failed": `ok` is false
+ * whenever `sync` rejected, whatever the cause, with the rejection's text in `error`.
+ *
+ * Browser-local applies a verified heads listing on the authority's word, including the
+ * documents it no longer names, with one bound: a listing that would remove at least eight
+ * documents and more than half of the working copy (or every document) is refused as a whole.
+ * The refreshes in that sync still apply, nothing is removed, `lastSync.ok` stays true, and
+ * `lastSync.refusedDeletions` carries the refusal until a later pull applies or clears it. A
+ * genuine shrink of that size therefore never reconciles on its own; the recovery path is to
+ * pass the recorded refusal back as `sync({ acceptRefusedDeletions })`, which applies the
+ * deletions if the authority still lists the same state and refuses afresh if it has moved.
+ * Request-driven has no working copy and leaves `lastSync` undefined: the status is the answer
+ * to the request that produced it.
+ */
+export interface PlatformSyncStatus {
+    mode: ExecutionMode;
+    /** Whether the last request to the authority succeeded; `null` before any was made. */
+    online: boolean | null;
+    /** Local edits the authority has not yet acknowledged (pending, in flight, or of unknown outcome). */
+    pending: number;
+    conflicts: number;
+    refused: number;
+    /**
+     * Working-copy documents whose bytes neither a recorded shared base nor an intent accounts
+     * for: a defect in the working copy, since every local write journals an intent. `query`
+     * omits such a document and `read` rejects it; this count is where it surfaces. Always 0 in
+     * request-driven mode, which has no working copy.
+     */
+    unconfirmed: number;
+    /** Delivery is paused (an authorization refusal); `pausedReason` says why. */
+    paused: boolean;
+    pausedReason?: string;
+    /** The runtime's working set is complete: the authority's for request-driven, a finished bootstrap for browser-local. */
+    complete: boolean;
+    /**
+     * How the last sync ended, and any deletions its pull refused. Browser-local fills it from
+     * the sync's own outcome and the pull marker (so a refusal recorded before this runtime was
+     * created still shows); request-driven leaves it undefined. Absent before any sync.
+     */
+    lastSync?: PlatformSyncOutcome;
+}
+export interface PlatformRuntime {
+    capabilities(): PlatformCapabilities;
+    /** Rejects ENOENT-shaped for an absent id and with `InvalidInputError` for an invalid one. */
+    read(id: ConceptId): Promise<PlatformDocument>;
+    /** Rows ordered by id, as the engine orders them. */
+    query(filter?: QueryFilter): Promise<PlatformQueryRow[]>;
+    validate(id: ConceptId): Promise<PlatformValidation>;
+    commit(id: ConceptId, edit: PlatformEdit): Promise<PlatformCommit>;
+    syncStatus(): Promise<PlatformSyncStatus>;
+    /**
+     * Push pending work and pull the authority's changes; a no-op returning the status in
+     * request-driven mode. `options` carries the recovery path for refused deletions; see
+     * {@link PlatformSyncOptions}.
+     */
+    sync(options?: PlatformSyncOptions): Promise<PlatformSyncStatus>;
+}
+/** The word a presentation shows for a provenance. */
+export declare function provenanceLabel(provenance: Provenance): ProvenanceLabel;
+/** True only when the authority acknowledged or served this content at the runtime's last exchange with it. */
+export declare function isSharedConfirmed(provenance: Provenance): provenance is Extract<Provenance, {
+    state: "shared-confirmed";
+}>;
+/**
+ * A confirmation from an authority answer; callers must hold that answer, never infer it from a
+ * local write. `version` is the runtime's own premise token and `acknowledged` the authority's
+ * token for the same content; omitted, the two are the same token space.
+ */
+export declare function sharedConfirmed(version: Version, acknowledged?: Version): Provenance;
+export declare function localPending(version: Version, base: Version | null, requestId: string): Provenance;
+export declare function localConflict(version: Version, base: Version | null, remote: Version | null, requestId: string): Provenance;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

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

package/dist/platform.js

@@ -0,0 +1,82 @@
+/**
+ * The platform contract an application programs against, above the two execution
+ * implementations: request-driven (every verb is a request to the shared authority) and
+ * browser-local (every verb runs against the page's own working copy, related to the authority
+ * by synchronization). A presentation receives a {@link PlatformRuntime} and nothing else; it
+ * never touches a backend, a transport, or a store.
+ *
+ * Provenance is the explicit result difference the two implementations are allowed to have.
+ * Every read, query row, validation, and commit states where its answer stands with respect to
+ * the shared authority:
+ *
+ * - `shared-confirmed`: the authority acknowledged or served exactly this content at the
+ *   runtime's last exchange with it. It may only be produced from an authority acknowledgement
+ *   (a write the authority answered, or an intent it acknowledged under its request identity)
+ *   or from an authority read (a request-driven read, or a working copy refreshed from the
+ *   authority with no local edit outstanding). A local write never produces it, so no
+ *   presentation can report shared confirmation without an acknowledgement. It says nothing
+ *   about what the authority holds now: request-driven's last exchange is the request itself,
+ *   browser-local's is its last sync, and the authority may have moved (or deleted the document)
+ *   since. A document the authority deleted disappears from a browser-local working copy at
+ *   its next sync (pull reconciles deletions against the authority's heads) unless a local
+ *   edit holds it, in which case pull retains the local content and rewrites its base to an
+ *   absent shared version, and the document reads `local-pending` until push delivers the edit
+ *   and settles the authority's conflict answer (a 412 whose actual version is `null`) as a
+ *   conflict against an absent remote, from which point it reads `local-conflict` with
+ *   `remote: null`; request-driven answers absence directly. Between syncs a deleted document
+ *   still reads `shared-confirmed` at its last served version, so a presentation must not read
+ *   `shared-confirmed` as proof of present existence.
+ * - `local-pending`: the working copy holds a local edit the authority has not accepted;
+ *   `requestId` names the journaled intent that will deliver it and `base` the shared version
+ *   the edit was made against.
+ * - `local-conflict`: the authority's head moved under a local edit; `remote` is the version the
+ *   authority held when the conflict was recorded, and the local content is retained. Any
+ *   conflict intent on a document decides its provenance, even after further local edits
+ *   chained behind it.
+ *
+ * One token space per runtime. In every provenance state `version` is the runtime's own premise
+ * token: the value an application may pass back as `expectedVersion`, equal to the `version` of
+ * a query row for the same document. For browser-local that is the working copy's document
+ * version; for request-driven it is the authority's. `shared-confirmed` also carries
+ * `acknowledged`, the token the authority mints for the same content, which differs from
+ * `version` whenever the authority hashes bytes the working copy normalizes differently (a
+ * filesystem authority over hand-authored files). An application compares `acknowledged` to the
+ * authority and `version` to its own runtime, never one to the other.
+ *
+ * Model semantics (what a document is, how a query filters, what a kind warns about, when a
+ * commit changes nothing) are identical across implementations; the contract kit in
+ * `@superbee/browser-local` proves that by running one row table against both.
+ *
+ * This module carries types and pure helpers only: no behaviour, no Node builtins, so it
+ * bundles for the browser (see `test/browser-bundle.test.ts`).
+ */
+/** The word a presentation shows for a provenance. */
+export function provenanceLabel(provenance) {
+    switch (provenance.state) {
+        case "shared-confirmed":
+            return "shared";
+        case "local-pending":
+            return "pending";
+        case "local-conflict":
+            return "conflict";
+    }
+}
+/** True only when the authority acknowledged or served this content at the runtime's last exchange with it. */
+export function isSharedConfirmed(provenance) {
+    return provenance.state === "shared-confirmed";
+}
+/**
+ * A confirmation from an authority answer; callers must hold that answer, never infer it from a
+ * local write. `version` is the runtime's own premise token and `acknowledged` the authority's
+ * token for the same content; omitted, the two are the same token space.
+ */
+export function sharedConfirmed(version, acknowledged = version) {
+    return { state: "shared-confirmed", version, acknowledged };
+}
+export function localPending(version, base, requestId) {
+    return { state: "local-pending", version, base, requestId };
+}
+export function localConflict(version, base, remote, requestId) {
+    return { state: "local-conflict", version, base, remote, requestId };
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAkLH,sDAAsD;AACtD,MAAM,UAAU,eAAe,CAAC,UAAsB;IACpD,QAAQ,UAAU,CAAC,KAAK,EAAE,CAAC;QACzB,KAAK,kBAAkB;YACrB,OAAO,QAAQ,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,SAAS,CAAC;QACnB,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,MAAM,UAAU,iBAAiB,CAAC,UAAsB;IACtD,OAAO,UAAU,CAAC,KAAK,KAAK,kBAAkB,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,eAAwB,OAAO;IAC/E,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAoB,EAAE,SAAiB;IACpF,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,IAAoB,EAAE,MAAsB,EAAE,SAAiB;IAC7G,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvE,CAAC"}

package/dist/portable-export.d.ts

@@ -0,0 +1,119 @@
+export declare const EXPORT_MANIFEST = "superbee-export.json";
+export declare const EXPORT_FORMAT = "superbee-export/1";
+/** The host's own bounds (20,000 objects, 64 MiB stored), plus room for headers and the manifest. */
+export declare const MAX_EXPORT_ENTRIES = 20001;
+export declare const MAX_EXPORT_BYTES: number;
+/** Why an archive was refused: `incomplete` is an export the host stopped; the rest are contract failures. */
+export type ArchiveProblem = "incomplete" | "malformed" | "unsafe_path" | "manifest_mismatch" | "wrong_bundle" | "unsupported_format";
+export declare class ExportArchiveError extends Error {
+    readonly name = "ExportArchiveError";
+    readonly problem: ArchiveProblem;
+    constructor(problem: ArchiveProblem, message: string);
+}
+export type EntryKind = "document" | "reserved" | "blob";
+export interface ArchiveEntry {
+    /** The bundle-relative path the entry is placed at. */
+    readonly path: string;
+    readonly kind: EntryKind;
+    readonly bytes: Uint8Array;
+}
+export interface ExportSource {
+    readonly tenantId: string;
+    readonly bundleId: string;
+    readonly revision: number;
+    readonly okfEdition: string | null;
+}
+export interface VerifiedExport {
+    readonly source: ExportSource;
+    readonly exportedAt: string;
+    readonly counts: {
+        readonly documents: number;
+        readonly reserved: number;
+        readonly blobs: number;
+    };
+    /** Every entry but the manifest, in archive order. */
+    readonly entries: readonly ArchiveEntry[];
+    /** Stored bytes, the manifest excluded. */
+    readonly bytes: number;
+    /** A paged export's page; absent on the whole archive (and on pages once joined). */
+    readonly page?: ExportPage;
+}
+/** What one page of a paged export states (`page` in its manifest). */
+export interface ExportPage {
+    /** The inventory position of the page's first object. */
+    readonly from: number;
+    /** Objects the page carries. */
+    readonly count: number;
+    /** Objects in the whole bundle. */
+    readonly total: number;
+    /** The cursor of the next page; absent on the last. */
+    readonly next?: string;
+    /** The whole bundle's counts, as every page's manifest states them. */
+    readonly counts: VerifiedExport["counts"];
+}
+export declare function crc32(bytes: Uint8Array): number;
+interface RawEntry {
+    readonly name: string;
+    readonly data: Uint8Array;
+}
+/**
+ * The entries of a store-only zip, strictly: one end record at the very end, a central directory
+ * that ends where it starts it, and local records laid end to end from offset zero, each stored,
+ * uncompressed, with no data descriptor and a matching CRC.
+ */
+export declare function readStoredZip(archive: Uint8Array): RawEntry[];
+/** What an archive path is in a bundle, or an `unsafe_path` refusal. The core guards decide. */
+export declare function classifyEntryPath(entryPath: string): EntryKind;
+/**
+ * The first two paths that one folder cannot hold apart: the same file under folding, a file where
+ * a folder must be, or one folder spelled two ways (a case-insensitive disk would merge them, and
+ * the files in it would no longer be at the paths their ids name).
+ */
+export declare function findEntryCollision(paths: readonly string[]): readonly [string, string] | null;
+/**
+ * Verify a whole export archive for `bundleId` and return its entries. Any failure is an
+ * {@link ExportArchiveError}; nothing is returned for an archive that is not complete and exact.
+ */
+export declare function verifyExport(archive: Uint8Array, bundleId: string, options?: {
+    readonly paged?: boolean;
+}): VerifiedExport;
+/**
+ * The pages of one paged export, checked as each arrives and joined once the last has: every page
+ * must name the first page's source (one revision, one edition), state the same whole (its total,
+ * at most an export's entries, and its counts), start where the one before ended, and only the
+ * last may name no next page. So a host that repeats or skips a page is refused at that page, and
+ * a run of pages is at most `total` long. Joined, the pages must hold every object once, add up to
+ * the bundle's counts, and keep every path apart from the others in one folder.
+ */
+export declare class ExportPageChain {
+    #private;
+    /** Adds the next page; answers its next cursor, or undefined once the export is whole. */
+    add(verified: VerifiedExport): string | undefined;
+    /** The whole bundle, as one archive would have carried it. */
+    joined(): VerifiedExport;
+}
+/** Join the verified pages of one paged export ({@link ExportPageChain}). */
+export declare function joinExportPages(pages: readonly VerifiedExport[]): VerifiedExport;
+/** Exact transport evidence, kept outside any materialized OKF bundle. */
+export interface ExportProvenance {
+    readonly source: ExportSource;
+    readonly exportedAt: string;
+    /** SHA-256 and byte length of each accepted raw manifest, in page order. */
+    readonly manifests: readonly {
+        readonly sha256: string;
+        readonly bytes: number;
+    }[];
+    /** SHA-256 of UTF-8 JSON for path-sorted {path,kind,bytes,sha256} inventory rows. */
+    readonly inventorySha256: string;
+}
+/** Evidence for an accepted handle; refuses forged or subsequently mutated values. */
+export declare function exportProvenance(verified: VerifiedExport): ExportProvenance;
+/**
+ * Materialize a complete verified export in a fresh private child of an existing caller-owned
+ * parent. Returns only after every file is written. The caller owns cleanup of the returned
+ * directory and must keep that parent private while using the result. No target is overwritten,
+ * no transport metadata is written, and failure removes only this call's newly created child.
+ */
+export declare function materializeExport(verified: VerifiedExport, parentDirectory: string): Promise<string>;
+export {};
+//# sourceMappingURL=portable-export.d.ts.map

package/dist/portable-export.d.ts.map

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