@superbee/core 0.1.6 → 0.2.0-pre.10

package/README.md

@@ -0,0 +1,127 @@
+# @superbee/core
+
+The Superbee knowledge engine reads and writes Open Knowledge Format bundles, with versioned
+writes, cross-links and storage backends. It is a library; installing it does not install the
+`superbee` executable.
+
+Core and `@superbee/server` are released together, independently of the `superbee` CLI. A CLI
+release bundles the engine source selected at build time; it does not load `@superbee/core@latest`.
+
+## Document presentation values
+
+The additive `@superbee/core/artifact-contract` subpath provides pure v1 document target,
+observation, request, receipt and capability decoders. See the [contract reference](https://github.com/Holaxis-ai/superbee/blob/main/packages/core/ARTIFACT-CONTRACT.md)
+for identity, provenance, lifecycle and host responsibilities.
+
+## Mutation attribution and local history
+
+`mutateDocument` and `prepareDocumentMutationCandidate` persist a supplied `actor` by default:
+`actor` in OKF v0.1, `superbee_updated_by` in v0.2 (plus `actor` when the Kind requires it).
+Use `persistActor: false` to keep candidate attribution unchanged, or `persistActor: true` to apply
+the attribution policy even without a supplied actor. Supplying the actor option alone leaves an
+otherwise unchanged candidate a no-op, preserving its original attribution and bytes. In v0.1,
+deliberate edits to the candidate's legacy `actor` field still count as authored changes in `patch`
+and `replace-document` modes; overwrite retains its automatic attribution comparison. The pure preview
+prepares patches. This default changes library writes that previously
+required `persistActor: true`; callers needing the old opt-in behavior can explicitly pass false.
+
+`producer` controls `generated.by` independently of the version mutator. Local filesystem history
+returns only the current revision, including for Git-tracked bundles. It reads mutation attribution
+from `superbee_updated_by`, legacy `updated_by`, or `actor`; when absent it returns the stable string
+`unattributed`. It does not infer an identity from the reader's environment or the content producer.
+History-keeping backends retain their existing per-write attribution.
+
+## Filesystem platform migration
+
+The Windows extraction changes the default Node.js filesystem backend. Its built-in host policy
+supports macOS and Linux. On native Windows or another unsupported host, filesystem construction
+requires an explicit `FilesystemHostPolicy`; there is no automatic Windows fallback.
+
+| Entry point | Default on macOS/Linux | On other hosts |
+| --- | --- | --- |
+| `new FilesystemBackend(root)` | Uses the built-in policy | Pass `{ hostPolicy }` as the second argument |
+| `initBundle(root, options)` | Uses the built-in policy | Pass `{ hostPolicy }` as the third argument |
+| `createFilesystemRuntime()` | Captures the built-in policy | Pass a host policy as its argument |
+| `withFilesystemMutationLock(target, body, options)` | Uses the built-in policy | Include `hostPolicy` in `options` |
+| `filesystemMutationLockPath(target, portableRoot)` | Uses the built-in policy | Pass a host policy as the third argument |
+
+Without that policy, these filesystem entry points throw `InvalidInputError` on unsupported hosts;
+backend construction and bundle initialization refuse before creating or modifying the target.
+The package has no npm `os` restriction: storage contracts and non-filesystem backends remain
+available independently of the default filesystem policy. Choose a backend and imports appropriate
+to your runtime; installing the library alone does not establish native filesystem support.
+
+There is no Windows adapter on npm to install. The experimental first-party adapters are built
+from source in a separate repository, https://github.com/Holaxis-ai/superbee-windows-cli.
+Supplying a policy is an integration contract for an adapter owner, not a promise that arbitrary
+policies make Windows supported.
+
+## Keep the backend returned by initBundle
+
+`initBundle` now returns `{ root, backend }`. Pass that returned bundle to engine operations so they
+retain the backend and host policy selected during initialization:
+
+```ts
+import { initBundle, readDoc, writeDoc } from '@superbee/core';
+
+const bundle = await initBundle('./knowledge'); // Default filesystem: macOS/Linux.
+await writeDoc(bundle, {
+  id: 'notes/example',
+  frontmatter: { type: 'Note', title: 'Example' },
+  body: 'Shared knowledge.\n',
+});
+const document = await readDoc(bundle, 'notes/example');
+```
+
+Reading `bundle.root` still works. Code that assumes the return value has exactly one property,
+serializes the whole return value, or uses backend presence as a synonym for a remote bundle must
+be updated. A filesystem bundle now has a backend too. Serialize only the fields your application
+intends to persist; do not reconstruct `{ root: bundle.root }` when continuing engine operations
+that need the selected backend.
+
+## Integrating an explicit filesystem policy
+
+`@superbee/core/filesystem` exports `createFilesystemRuntime`, `FilesystemBackend`, and the
+`FilesystemHostPolicy` type. An application that owns its host adapter can bind it once:
+
+```ts
+import { createFilesystemRuntime, type FilesystemHostPolicy } from '@superbee/core/filesystem';
+
+export async function openFilesystemBundle(root: string, hostPolicy: FilesystemHostPolicy) {
+  const filesystem = createFilesystemRuntime(hostPolicy);
+  return filesystem.initBundle(root);
+}
+```
+
+The resulting runtime supplies `backend`, `initBundle`, `withMutationLock`, and `mutationLockPath`
+with the same captured policy. Direct backend construction uses
+`new FilesystemBackend(root, { hostPolicy })`. Lock helpers are also exported from `@superbee/core`.
+
+A policy supplies the lock-parent directory, owner-namespace key, private-mode enforcement choice,
+and host error classifications. Core still owns lock ownership, version checks, retry bounds and
+cleanup. Policies are structural snapshots: public data and methods are captured, while callbacks
+may continue to observe live operating-system facts. Do not use opaque private fields or methods
+pre-bound to a mutable receiver.
+
+## Release compatibility
+
+This migration describes the source after the Windows extraction. Previously published versions
+are unchanged. Consult the release notes for the first affected version before upgrading a pinned
+consumer. CLI and engine version numbers are independent; do not infer matching embedded code from
+package names or version labels.
+
+[Source and contribution guide](https://github.com/Holaxis-ai/superbee)
+
+### Node portable export boundary
+
+`@superbee/core/portable-export` (also bundled as `superbee/portable-export`) exposes the same
+store-only archive verifier used by the CLI: `verifyExport`, `ExportPageChain` and
+`joinExportPages`. The page chain charges the sum of complete ZIP sizes, including manifests
+and headers, against `MAX_EXPORT_BYTES` before retaining a page; returned `bytes` counts only
+stored bundle content. It performs no acquisition, sign-in or network access. A complete accepted
+handle can be passed to `materializeExport(handle, existingPrivateParent)` to create a fresh
+private directory; callers own its cleanup and isolation while publishing. No target is replaced.
+`exportProvenance(handle)` returns exact ordered raw-manifest SHA-256/size evidence plus a combined
+inventory SHA-256. Keep that evidence outside the directory and private when it identifies a
+private source. Handles cannot be reconstructed from JSON or moved between independently bundled
+module instances; modified handles are refused. This surface requires Node, not a browser or Worker.

package/dist/artifact-contract.d.ts

@@ -0,0 +1,90 @@
+/** Portable document identity and presentation evidence. No host selection or effects. */
+import type { ConceptId, Version } from "./types.js";
+import type { Provenance } from "./platform.js";
+export type ArtifactAuthorityV1 = {
+    mode: "local";
+    authorityKey: string;
+} | {
+    mode: "hosted";
+    authorityKey: string;
+    workspaceKey: string;
+};
+export interface DocumentTargetV1 {
+    schemaVersion: "superbee.document-target.v1";
+    authority: ArtifactAuthorityV1;
+    bundleKey: string;
+    documentId: ConceptId;
+}
+export type ArtifactLifecycleV1 = {
+    state: "unverified";
+} | {
+    state: "bound";
+    sourceToken: string;
+    documentToken: string;
+};
+export interface DocumentObservationV1 {
+    schemaVersion: "superbee.document-observation.v1";
+    target: DocumentTargetV1;
+    provenance: Provenance;
+    lifecycle: ArtifactLifecycleV1;
+}
+export interface PresentDocumentRequestV1 {
+    schemaVersion: "superbee.present-document.v1";
+    operation: "present_document";
+    invocationId: string;
+    target: DocumentTargetV1;
+    referenceVersion?: Version;
+    expectedLifecycle?: Extract<ArtifactLifecycleV1, {
+        state: "bound";
+    }>;
+}
+export type PresentationStateV1 = {
+    state: "open_requested";
+    observation?: DocumentObservationV1;
+} | {
+    state: "payload_prepared";
+    observation: DocumentObservationV1;
+} | {
+    state: "offered";
+    expiresAt: number;
+    observation?: DocumentObservationV1;
+} | {
+    state: "navigated";
+    observation?: DocumentObservationV1;
+};
+export type PresentationErrorCodeV1 = "invalid_input" | "unsupported_version" | "unsupported_operation" | "unsupported_host" | "unavailable" | "unavailable_stale_target" | "context_changed" | "presentation_disabled" | "busy";
+export type PresentDocumentReceiptV1 = {
+    schemaVersion: "superbee.present-document-receipt.v1";
+    operation: "present_document";
+    invocationId: string;
+    target: DocumentTargetV1;
+} & ({
+    ok: true;
+    presentation: PresentationStateV1;
+} | {
+    ok: false;
+    error: {
+        code: PresentationErrorCodeV1;
+        retryable: boolean;
+    };
+});
+export interface DocumentPresentationCapabilitiesV1 {
+    schemaVersion: "superbee.document-presentation-capabilities.v1";
+    states: Array<PresentationStateV1["state"]>;
+}
+export type ArtifactDecodeResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    code: "invalid_input" | "unsupported_version" | "receipt_mismatch";
+};
+export declare function decodeDocumentTargetV1(value: unknown): ArtifactDecodeResult<DocumentTargetV1>;
+export declare function decodeDocumentObservationV1(value: unknown): ArtifactDecodeResult<DocumentObservationV1>;
+export declare function decodePresentDocumentRequestV1(value: unknown): ArtifactDecodeResult<PresentDocumentRequestV1>;
+/** expected is caller-owned decoded data or an equivalent trusted constructor value. */
+export declare function decodePresentDocumentReceiptV1(value: unknown, expected: PresentDocumentRequestV1): ArtifactDecodeResult<PresentDocumentReceiptV1>;
+export declare function decodeDocumentPresentationCapabilitiesV1(value: unknown): ArtifactDecodeResult<DocumentPresentationCapabilitiesV1>;
+export declare function sameDocumentTargetV1(a: DocumentTargetV1, b: DocumentTargetV1): boolean;
+export declare function compareAuthorityVersionV1(observed: DocumentObservationV1, reference: Version): "same" | "different" | "unconfirmed";
+//# sourceMappingURL=artifact-contract.d.ts.map

package/dist/artifact-contract.d.ts.map

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

package/dist/artifact-contract.js

@@ -0,0 +1,205 @@
+import { assertSafeConceptId } from "./paths.js";
+import { isContentVersion } from "./version-transport.js";
+class DecodeFailure {
+    code;
+    constructor(code) { this.code = code; }
+}
+function requireValue(condition, code = "invalid_input") {
+    if (!condition)
+        throw new DecodeFailure(code);
+}
+/** Reflect first, before schema classification. Own accessors are never read. Reflection can
+ * invoke Proxy traps; failures are caught by the decoder, not treated as trusted data. */
+function snapshot(value, ancestors = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        requireValue(Number.isFinite(value));
+        return value;
+    }
+    requireValue(typeof value === "object");
+    requireValue(!ancestors.has(value));
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    requireValue(array ? prototype === Array.prototype : prototype === null || prototype === Object.prototype);
+    ancestors.add(value);
+    try {
+        const copy = Object.create(null);
+        const keys = Reflect.ownKeys(value);
+        for (const key of keys) {
+            requireValue(typeof key === "string");
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            requireValue(descriptor && Object.hasOwn(descriptor, "value"));
+            copy[key] = snapshot(descriptor.value, ancestors);
+        }
+        if (!array)
+            return copy;
+        const length = copy.length;
+        requireValue(typeof length === "number" && Number.isSafeInteger(length) && length >= 0);
+        requireValue(keys.length === length + 1);
+        const items = [];
+        for (let i = 0; i < length; i++) {
+            requireValue(Object.hasOwn(copy, String(i)));
+            items.push(copy[String(i)]);
+        }
+        return items;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function record(value) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value));
+    return value;
+}
+function fields(value, required, optional = []) {
+    requireValue(required.every(key => Object.hasOwn(value, key)));
+    requireValue(Object.keys(value).every(key => required.includes(key) || optional.includes(key)));
+}
+function envelope(value, schema) {
+    const data = record(value);
+    requireValue(typeof data.schemaVersion === "string");
+    requireValue(data.schemaVersion === schema, "unsupported_version");
+    return data;
+}
+function key(value) {
+    requireValue(typeof value === "string" && /^[\x21-\x7e]{1,256}$/.test(value) && !/[\\/]/.test(value));
+    return value;
+}
+function version(value) { requireValue(isContentVersion(value)); return value; }
+function nullableVersion(value) { return value === null ? null : version(value); }
+function target(value) {
+    const data = envelope(value, "superbee.document-target.v1");
+    fields(data, ["schemaVersion", "authority", "bundleKey", "documentId"]);
+    const authority = record(data.authority);
+    let parsedAuthority;
+    if (authority.mode === "local") {
+        fields(authority, ["mode", "authorityKey"]);
+        parsedAuthority = { mode: "local", authorityKey: key(authority.authorityKey) };
+    }
+    else {
+        requireValue(authority.mode === "hosted");
+        fields(authority, ["mode", "authorityKey", "workspaceKey"]);
+        parsedAuthority = { mode: "hosted", authorityKey: key(authority.authorityKey), workspaceKey: key(authority.workspaceKey) };
+    }
+    requireValue(typeof data.documentId === "string");
+    assertSafeConceptId(data.documentId);
+    return { schemaVersion: "superbee.document-target.v1", authority: parsedAuthority, bundleKey: key(data.bundleKey), documentId: data.documentId };
+}
+function lifecycle(value) {
+    const data = record(value);
+    if (data.state === "unverified") {
+        fields(data, ["state"]);
+        return { state: "unverified" };
+    }
+    requireValue(data.state === "bound");
+    fields(data, ["state", "sourceToken", "documentToken"]);
+    return { state: "bound", sourceToken: key(data.sourceToken), documentToken: key(data.documentToken) };
+}
+function provenance(value) {
+    const data = record(value);
+    if (data.state === "shared-confirmed") {
+        fields(data, ["state", "version", "acknowledged"]);
+        return { state: "shared-confirmed", version: version(data.version), acknowledged: version(data.acknowledged) };
+    }
+    requireValue(data.state === "local-pending" || data.state === "local-conflict");
+    fields(data, ["state", "version", "base", "requestId", ...(data.state === "local-conflict" ? ["remote"] : [])]);
+    requireValue(typeof data.requestId === "string");
+    const common = { version: version(data.version), base: nullableVersion(data.base), requestId: data.requestId };
+    return data.state === "local-pending"
+        ? { state: "local-pending", ...common }
+        : { state: "local-conflict", ...common, remote: nullableVersion(data.remote) };
+}
+function observation(value) {
+    const data = envelope(value, "superbee.document-observation.v1");
+    fields(data, ["schemaVersion", "target", "provenance", "lifecycle"]);
+    return { schemaVersion: "superbee.document-observation.v1", target: target(data.target), provenance: provenance(data.provenance), lifecycle: lifecycle(data.lifecycle) };
+}
+function request(value) {
+    const data = envelope(value, "superbee.present-document.v1");
+    fields(data, ["schemaVersion", "operation", "invocationId", "target"], ["referenceVersion", "expectedLifecycle"]);
+    requireValue(data.operation === "present_document");
+    const expectedLifecycle = Object.hasOwn(data, "expectedLifecycle") ? lifecycle(data.expectedLifecycle) : undefined;
+    requireValue(expectedLifecycle === undefined || expectedLifecycle.state === "bound");
+    return {
+        schemaVersion: "superbee.present-document.v1", operation: "present_document",
+        invocationId: key(data.invocationId), target: target(data.target),
+        ...(Object.hasOwn(data, "referenceVersion") ? { referenceVersion: version(data.referenceVersion) } : {}),
+        ...(expectedLifecycle?.state === "bound" ? { expectedLifecycle } : {}),
+    };
+}
+const states = ["open_requested", "payload_prepared", "offered", "navigated"];
+function presentation(value) {
+    const data = record(value);
+    requireValue(states.includes(data.state));
+    fields(data, ["state", ...(data.state === "offered" ? ["expiresAt"] : []), ...(data.state === "payload_prepared" ? ["observation"] : [])], ["observation"]);
+    const observed = Object.hasOwn(data, "observation") ? { observation: observation(data.observation) } : {};
+    switch (data.state) {
+        case "offered":
+            requireValue(typeof data.expiresAt === "number" && Number.isSafeInteger(data.expiresAt) && data.expiresAt >= 0);
+            return { state: "offered", expiresAt: data.expiresAt, ...observed };
+        case "payload_prepared": return { state: "payload_prepared", observation: observation(data.observation) };
+        case "open_requested": return { state: "open_requested", ...observed };
+        default: return { state: "navigated", ...observed };
+    }
+}
+const errors = ["invalid_input", "unsupported_version", "unsupported_operation", "unsupported_host", "unavailable", "unavailable_stale_target", "context_changed", "presentation_disabled", "busy"];
+function receipt(value, expected) {
+    const data = envelope(value, "superbee.present-document-receipt.v1");
+    requireValue(typeof data.ok === "boolean");
+    fields(data, ["schemaVersion", "operation", "invocationId", "target", "ok", data.ok ? "presentation" : "error"]);
+    requireValue(data.operation === "present_document");
+    const common = { schemaVersion: "superbee.present-document-receipt.v1", operation: "present_document", invocationId: key(data.invocationId), target: target(data.target) };
+    let parsed;
+    if (data.ok)
+        parsed = { ...common, ok: true, presentation: presentation(data.presentation) };
+    else {
+        const error = record(data.error);
+        fields(error, ["code", "retryable"]);
+        requireValue(errors.includes(error.code) && typeof error.retryable === "boolean");
+        requireValue(!error.retryable || error.code === "busy" || error.code === "unavailable");
+        parsed = { ...common, ok: false, error: { code: error.code, retryable: error.retryable } };
+    }
+    requireValue(parsed.invocationId === expected.invocationId && sameDocumentTargetV1(parsed.target, expected.target), "receipt_mismatch");
+    if (parsed.ok) {
+        const observed = parsed.presentation.observation;
+        requireValue(!observed || sameDocumentTargetV1(observed.target, expected.target), "receipt_mismatch");
+        if (expected.expectedLifecycle) {
+            const actual = observed?.lifecycle;
+            requireValue(actual?.state === "bound" && actual.sourceToken === expected.expectedLifecycle.sourceToken && actual.documentToken === expected.expectedLifecycle.documentToken, "receipt_mismatch");
+        }
+    }
+    return parsed;
+}
+function decode(value, parse) {
+    try {
+        return { ok: true, value: parse(snapshot(value)) };
+    }
+    catch (error) {
+        return { ok: false, code: error instanceof DecodeFailure ? error.code : "invalid_input" };
+    }
+}
+export function decodeDocumentTargetV1(value) { return decode(value, target); }
+export function decodeDocumentObservationV1(value) { return decode(value, observation); }
+export function decodePresentDocumentRequestV1(value) { return decode(value, request); }
+/** expected is caller-owned decoded data or an equivalent trusted constructor value. */
+export function decodePresentDocumentReceiptV1(value, expected) {
+    return decode(value, data => receipt(data, expected));
+}
+export function decodeDocumentPresentationCapabilitiesV1(value) {
+    return decode(value, value => {
+        const data = envelope(value, "superbee.document-presentation-capabilities.v1");
+        fields(data, ["schemaVersion", "states"]);
+        requireValue(Array.isArray(data.states) && data.states.every(state => states.includes(state)) && new Set(data.states).size === data.states.length);
+        return { schemaVersion: "superbee.document-presentation-capabilities.v1", states: [...data.states] };
+    });
+}
+export function sameDocumentTargetV1(a, b) {
+    return a.authority.mode === b.authority.mode && a.authority.authorityKey === b.authority.authorityKey
+        && (a.authority.mode !== "hosted" || (b.authority.mode === "hosted" && a.authority.workspaceKey === b.authority.workspaceKey))
+        && a.bundleKey === b.bundleKey && a.documentId === b.documentId;
+}
+export function compareAuthorityVersionV1(observed, reference) {
+    return observed.provenance.state !== "shared-confirmed" ? "unconfirmed" : observed.provenance.acknowledged === reference ? "same" : "different";
+}
+//# sourceMappingURL=artifact-contract.js.map

package/dist/artifact-contract.js.map

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

package/dist/backend.d.ts

@@ -24,6 +24,7 @@
  * at all — parsing is an implementation detail of THIS adapter, not of the seam.
  */
 import type { BlobKey, ConceptId, DeleteOptions, OkfDocument, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
+import type { FilesystemBackendOptions } from "./filesystem-host.js";
 /**
  * The default {@link StorageBackend}: a filesystem-backed OKF bundle rooted at an
  * absolute directory. Concept documents are markdown files at `<id>.md`; reserved
@@ -36,7 +37,7 @@ export declare class FilesystemBackend implements StorageBackend {
      * process's current directory on every operation, so a later `chdir` would silently move the
      * bundle and derive a different identity key.
      */
-    constructor(root: string);
+    constructor(root: string, options?: FilesystemBackendOptions);
     read(id: ConceptId): Promise<ReadResult>;
     readMany(ids: ConceptId[]): Promise<ReadResult[]>;
     write(id: ConceptId, doc: OkfDocument, options?: WriteOptions): Promise<Version>;
@@ -64,6 +65,20 @@ export declare function readRawFilesystemDocument(backend: FilesystemBackend, id
     bytes: Uint8Array;
     version: Version;
 }>;
+/**
+ * {@link readRawFilesystemDocument} for many documents in one observation pass, so a capture
+ * lists each directory once instead of twice per document. `read` answers exactly what
+ * `readRawFilesystemDocument` would, in the caller's order; `finish` ends the pass and returns
+ * the ids whose answers the end-of-pass check could not confirm, for the caller to read again
+ * with `readRawFilesystemDocument`.
+ */
+export declare function openRawFilesystemDocumentPass(backend: FilesystemBackend): {
+    read(id: ConceptId): Promise<{
+        bytes: Uint8Array;
+        version: Version;
+    }>;
+    finish(): Promise<ConceptId[]>;
+};
 /** Internal exact-byte authority for reserved publication objects. */
 export declare function readRawFilesystemReserved(backend: FilesystemBackend, dir: string, name: ReservedFilename): Promise<{
     bytes: Uint8Array;

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAyBH,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAqEpB;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,cAAc;;IAGtD;;;;OAIG;gBACS,IAAI,EAAE,MAAM;IAKlB,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAUxC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAWjD,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BpF,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBpE,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA6B/C,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmB3C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAUrF,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAoBb,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAatD,SAAS,CACb,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAuBb,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvE,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1C,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAWpD,YAAY;;;;;;;CASb;AAQD,6FAA6F;AAC7F,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAQlD;AAED,sEAAsE;AACtE,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CASzD;AAED,oEAAoE;AACpE,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC,CAYzD"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA+BH,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,aAAa,EACb,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAoErE;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,cAAc;;IAItD;;;;OAIG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAM1D,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BxC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwBjD,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BpF,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBpE,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA6B/C,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmB3C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAWrF,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAqBb,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAatD,SAAS,CACb,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAuBb,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvE,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1C,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAWpD,YAAY;;;;;;;CASb;AAQD,6FAA6F;AAC7F,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,SAAS,GACZ,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAElD;AAiBD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,iBAAiB,GAAG;IACzE,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CAChC,CAiBA;AAED,sEAAsE;AACtE,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,iBAAiB,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAC,CAUzD;AAED,oEAAoE;AACpE,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAAC,CAazD"}