@kanzo-tech/graph 0.1.0 → 0.3.0

package/dist/duck-source.d.ts

@@ -1,18 +1,20 @@
+import { OpenOptions } from '@fossil-lang/corpus';
 import { Coordinator, Selection } from '@kanzo-tech/mosaic';
 import { BoundedSource } from './bounded';
 import { VertexId } from './resident';
 /**
- * A `BoundedSource` over two ordinary relations in DuckDB.
+ * The source: a corpus fossil wrote, read through DuckDB.
  *
- * On a subpath because Mosaic is an optional peer and this is the half that needs it: a host drawing
- * arrays it already holds takes `memorySource` and pays for no database. Splitting them is what lets
- * that promise be true rather than merely stated.
+ * On a subpath because Mosaic and fossil's reader are optional peers and this is the half that needs
+ * them. The root barrel ships no source at all, which is the whole of what that split now means: a
+ * host that installs neither gets the rendering surface and draws nothing.
  *
- * **Neutral about storage, and that is the point.** The neutrality let bounded be measured against
- * unbounded before anything committed to a layout on disk — and it is the reason this file survived
- * a decision on the other side of the seam. The verb it was written to sit beside never landed:
- * `viewport` was dropped and GraphAr with it, because the camera is addressed rather than queried.
- * What replaces it is a tile fetched by a computed URL, which is another source.
+ * **There used to be two here and the second was neutral about storage.** `duckBoundedSource` took
+ * two ordinary relations and the column names that made sense of them, and that neutrality earned
+ * its keep once — it let bounded be measured against unbounded before anything committed to a layout
+ * on disk. What it cost afterwards is the reason it is gone: a corpus already declares those names
+ * in its manifest, so the second source was this side writing down what the other side owns, and the
+ * two answered the same question in two dialects of the same SQL.
  *
  * **Every query in this file goes through a `SliceRead`, and there is no other path.** `onceQuery`
  * was the other one — a throwaway client per query, on this subpath, re-exported for the two
@@ -39,62 +41,8 @@ export interface DuckSource extends BoundedSource {
      */
     publish(vertices: readonly VertexId[] | null): void;
 }
-export interface DuckSourceOptions {
-    coordinator: Coordinator;
-    /**
-     * The crossfilter this graph draws inside.
-     *
-     * Given, the page's predicate rides in the slice query and the canvas draws **what survives**.
-     * Omitted, the source is a reader of a relation and nothing else — which is what a graph with no
-     * charts beside it is.
-     */
-    filterBy?: Selection;
-    /** The node relation. */
-    nodes: string;
-    /** The edge relation, as pairs of node ids. */
-    edges: string;
-    /**
-     * Which vertex type this relation is.
-     *
-     * Required, and with no default, because the source is the only thing that knows: a `dense_id`
-     * numbers within one type, so the identity a slice carries is only completed here. A corpus of one
-     * type is type `0` and has to say so — a defaulted `0` would let a second relation ship the same
-     * identities as the first with nothing raised.
-     */
-    typeIndex: number;
-    /**
-     * A **dense** integer id — `0..n-1`, no gaps.
-     *
-     * Dense because `links` refers to positions rather than to ids, so a consumer never pays for an
-     * id→index map. GraphAr's `dense_id` is this column by another name.
-     */
-    idField?: string;
-    /**
-     * The identity column — the subject IRI. **Omitted, a slice carries addresses only.**
-     *
-     * A `dense_id` says where a vertex is; the IRI says which vertex it is, and only the second
-     * survives the layout being redone. The corpus writes it as `subject`, non-null and unique within
-     * a type, which is why that is the name here — but it stays opt-in rather than defaulted, because
-     * reading it costs 1.87× the drawing tile and most points are painted rather than named.
-     *
-     * Set it when something outlives a session: a bookmark, a link out, a selection that has to mean
-     * the same thing after the next `fossil run`.
-     */
-    subjectField?: string;
-    xField?: string;
-    yField?: string;
-    /**
-     * **What colours and what sizes are not here**, and their absence is the shape rather than an
-     * omission: they are `fill` and `r` on the request, because a channel is what the caller wants
-     * drawn now and this object is where the bytes are. Given here too, recolouring meant building a
-     * second source — and two places deciding one colour is the state that move ended.
-     */
-    sourceField?: string;
-    targetField?: string;
-}
-export declare function duckBoundedSource(options: DuckSourceOptions): DuckSource;
 /**
- * A corpus that fossil wrote, read by address.
+ * A corpus that fossil wrote, read by address — **and the addressing is fossil's.**
  *
  * **The five things a call site used to know, and now does not.** Drawing a corpus meant deriving
  * the chunk URLs from a `chunk_size` copied by hand, knowing how a tile is named, knowing what the
@@ -107,18 +55,28 @@ export declare function duckBoundedSource(options: DuckSourceOptions): DuckSourc
  * The consumer knows one thing: **where the corpus is.**
  *
  * ```ts
- * const { source } = await openCorpus({ coordinator, dest: "/bench/1000000" });
+ * const { source } = await openCorpus({ coordinator, dest: "/bench/1000000", wasmUrl });
  * ```
  *
- * **Addressed, not queried.** The manifest and the per-tile boxes are read once and kept; after that
- * a camera move is arithmetic over boxes and a list of URLs. There is deliberately no request on the
- * path between the camera moving and a URL being computable — the moment there is one, this has
- * become the `viewport` verb fossil deleted.
+ * **And this side no longer knows the conventions either, which is the change.** It used to remove
+ * that defect for its callers by committing it one level down — a YAML line-scanner, a
+ * `chunk{k}.parquet` spelling, a `by_source/tile{k}.parquet` spelling and a `HEAD`-probing search
+ * for a tile count — and by the time those were deleted all four were **wrong**: fossil writes
+ * `container: rowgroups`, one `tiles.parquet` whose row groups are the tiles, and `vertex_count`
+ * had been in the manifest the whole time the search was probing for it. Fossil's `open` is
+ * `fossil_graph::plan` compiled to wasm32: the arithmetic the native reader runs, not a second
+ * implementation of it that agrees until it does not.
+ *
+ * **Addressed, not queried.** The manifests and the per-tile boxes are read once and kept; after
+ * that a camera move is arithmetic over boxes and a list of URLs. There is deliberately no request
+ * on the path between the camera moving and a URL being computable — the moment there is one, this
+ * has become the `viewport` verb fossil deleted.
  *
  * **What it is not.** It takes no column names and no type index. Those come from the manifest or
- * they do not come: a corpus reader that also accepts `idField` is `duckBoundedSource` with extra
- * steps, and there is already one of those for the case this is not — an arbitrary relation with
- * `x`/`y` that nobody wrote as a corpus.
+ * they do not come. There used to be a second source here for the case this is not — an arbitrary
+ * relation with `x`/`y` that nobody wrote as a corpus — and taking `idField` here would have been
+ * that one with extra steps. It is gone, so the rule is simpler than the guard against it: a column
+ * name reaching this door is a name the manifest should have carried.
  */
 export interface OpenCorpusOptions {
     coordinator: Coordinator;
@@ -130,6 +88,17 @@ export interface OpenCorpusOptions {
     filterBy?: Selection;
     /** Where the corpus lives, without a trailing slash — the directory holding `graph.graph.yml`. */
     dest: string;
+    /**
+     * Where `fossil_graph_wasm_bg.wasm` is.
+     *
+     * **The one thing about fossil's reader a caller still has to say, and not ours to default.** The
+     * addressing runs in WASM, so the module has to be up before a URL can be composed, and only the
+     * caller knows how its bundler resolves an asset — `?url` under Vite, an asset import under Next,
+     * a `Response` over the bytes in Node. Passed straight through, spelled as fossil spells it.
+     * Omitted, the boot is left to whoever already did it: it is memoised for the session, so a host
+     * on its second corpus need not say it again.
+     */
+    wasmUrl?: OpenOptions["wasmUrl"];
     /**
      * Which vertex type to draw, when a corpus carries more than one.
      *
@@ -143,6 +112,25 @@ export interface OpenCorpusOptions {
      * asks for names when something has to be *named* rather than painted.
      */
     subjects?: boolean;
+    /**
+     * How a manifest is read, when a plain `fetch` of its URL is not how this host reads one.
+     *
+     * **The default is `manifest` below, and it is the whole of what this file knows about reading a
+     * corpus** — right for a corpus served off an origin the page can already read, and wrong for a
+     * host whose blobs sit behind a signature. There the URL fossil composes is correct and
+     * unreadable, and nothing else on these options carries a credential.
+     *
+     * Passed straight through to fossil's `open`, which is where the capability belongs: `open`
+     * composes every address and lends the reader to each one, so a host that signs a URL signs the
+     * index and the per-type manifests the index names **without knowing which files those are**.
+     * That is the point of lending a reader rather than handing over bytes — and it is what keeps a
+     * signing host on this door, because the alternative it otherwise reaches for is composing the
+     * addresses itself, which is the convention-copying `openCorpus` exists to end.
+     *
+     * It reads manifests and nothing else. The payload is read by the coordinator's own connector,
+     * which is the host's already.
+     */
+    readText?: OpenOptions["readText"];
 }
 /**
  * An opened corpus: the half that **draws** and the half that **answers**.

package/dist/duck-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duck-source.d.ts","sourceRoot":"","sources":["../src/duck-source.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAc,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAgC,KAAK,aAAa,EAAgD,MAAM,WAAW,CAAC;AAE3H,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuFD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAmExE;AAmdD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAyCD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,uGAAuG;IACvG,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CA+WlF"}
+{"version":3,"file":"duck-source.d.ts","sourceRoot":"","sources":["../src/duck-source.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAc,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,WAAW,CAAC;AAE9E,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;CACrD;AAojBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,kGAAkG;IAClG,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACpC;AAgCD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,uGAAuG;IACvG,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuYlF"}