@miadi/inquiry-weave 0.7.0 → 0.8.0

package/dist/chronicle-terminal.d.ts

@@ -0,0 +1,305 @@
+/**
+ * The terminal surface for miadi-chronicle references.
+ *
+ * Contract: rispecs/miadi-chronicle-dsl/SPEC-TERMINAL.md (v1.2).
+ * Grounded in foundations/resource-addressing-and-terminal-hypermedia/.
+ *
+ * Two jobs the pure module cannot do, because both touch the world:
+ *
+ *  - the OPEN LADDER: turn a resolution into one thing a window manager can
+ *    act on, preferring what is on this disk over what is on a network.
+ *  - OSC 8 EMISSION: hand a terminal a link whose label is not its target.
+ *
+ * Why OSC 8 rather than letting the terminal find URLs in the text: regex
+ * linkification is an UNMARKED-ANCHOR mechanism (Grønbæk & Trigg, CACM 37(2),
+ * 1994) — the anchor carries no marker, its location must be computed by
+ * scanning, and its VALUE IS THE MATCHED TEXT. So under linkification the
+ * displayed label and the target are necessarily the same string, and
+ * `{{ … | label="Mila gathering" }}` cannot be expressed at all. OSC 8 is a
+ * marked anchor: declared, retrievable from the selection, carrying a value
+ * independent of what is shown. That is a property of the two anchoring
+ * models, not of any terminal's version number.
+ */
+import { type ArtifactKind, type ChronicleResolution, type FragmentVerdict, type ParsedChronicleUri, type ResolvableEpisode } from "./chronicle-dsl.js";
+/** VTE and iTerm2 both refuse URIs beyond this. */
+export declare const MAX_OSC8_URI_BYTES = 2083;
+/**
+ * Percent-encode anything outside the OSC command-string repertoire.
+ *
+ * ECMA-48 §5.6 constrains a command string to bit combinations 00/08–00/13 and
+ * 02/00–07/14. In practice for a URI that means bytes 32–126: anything else is
+ * undefined behaviour and must be escaped before it reaches the wire.
+ */
+export declare function encodeForOsc8(uri: string): string;
+export interface Osc8Options {
+    /**
+     * Hover-grouping hint, NOT a data channel. VTE caps ids near 250 bytes and
+     * reserves the right to change that without notice, and the OSC 8 spec
+     * instructs multiplexers and pagers to PREFIX incoming ids with a
+     * pane-unique string — so anything meaningful packed in here gets truncated
+     * and namespaced by layers we do not control.
+     *
+     * The spec's own rule: simple line-oriented utilities SHOULD NOT assign an
+     * id; full-screen applications SHOULD. This defaults to omitting it.
+     */
+    id?: string;
+}
+/**
+ * Wrap a label in an OSC 8 hyperlink.
+ *
+ * Emitted unconditionally, because there is no alternative. The OSC 8 spec
+ * says so in its own words: "Currently there's no way of detecting whether the
+ * terminal emulator supports hyperlinks." Any behaviour that branches on
+ * support is unimplementable, and backward compatibility is guaranteed one
+ * layer down — a terminal that parses OSC per ECMA-48 discards the payload and
+ * shows the label.
+ *
+ * Returns the bare label when the URI exceeds the byte ceiling: a link that
+ * would be truncated mid-URI is worse than no link, because it points
+ * somewhere real and wrong.
+ */
+export declare function osc8(uri: string, label: string, options?: Osc8Options): string;
+/**
+ * A chronicle reference as a terminal writes it: the marked anchor AND the
+ * address in plain sight.
+ *
+ * Not a fallback — two requirements met at once. The OSC 8 spec: hyperlinks
+ * "should not be the only means of figuring out the target." Engelbart's open
+ * hyperdocument requirement: every address stays "understandable and readable
+ * by a user." And the angle brackets are RFC 3986 Appendix C's explicit
+ * recommendation for delimiting a URI in running text, which is what makes the
+ * line survive `script`, CI capture, a pipe to a file, GNU screen, and xterm —
+ * none of which will ever render the escape.
+ */
+export declare function terminalRef(uri: string, label: string, target: string, options?: Osc8Options): string;
+/**
+ * How complete an answer this resolution is.
+ *
+ * This is a discretised HARVEST report in Fox & Brewer's sense (HotOS-VII,
+ * 1999): yield is whether the reference resolved at all, harvest is "the
+ * fraction of the data reflected in the response, i.e. the completeness of the
+ * answer." `resolved` is the yield; this is the harvest.
+ *
+ * Its consumer is named, deliberately: `resolveLines()` below prints it on
+ * every human-readable run. HTTP shipped exactly this field once — RFC 7234
+ * §5.5's `Warning`, including code 112 "Disconnected Operation" — and RFC 9111
+ * §8.3 obsoleted it because it "is not widely generated or surfaced to users."
+ * A modality nobody renders is dead metadata within two releases.
+ */
+export type Modality = "relational" | "standalone" | "none";
+export interface ArtifactTarget {
+    kind: ArtifactKind;
+    /** Absolute path on this host. */
+    path: string;
+    /** Other candidates the same reference matched — never hidden (SPEC §1). */
+    alternates?: string[];
+}
+/**
+ * The default chronicle room. Verified live 2026-08-16: `/chronicle` and
+ * `/chronicle/<folder>` both answer 200 on 127.0.0.1:3335, the same server the
+ * voice layer already talks to. The 2026-08-07 draft assumed the surface was
+ * down because it probed :3000 — the wrong port — and built a ladder around an
+ * outage that was not happening.
+ */
+export declare const DEFAULT_LOCAL_BASE = "http://127.0.0.1:3335";
+/**
+ * The chronicle room has three addresses and one identity.
+ *
+ * Measured 2026-08-16: `/chronicle/<folder>` answers 200 on all three —
+ * `127.0.0.1:3335`, the tailnet front (`$MIADI_URL_BASE_INTERNAL`), and the
+ * ngrok front (`$MIADI_URL_BASE`). Same room, three doors, and which door is
+ * reachable depends entirely on where the reader is standing.
+ *
+ * This is ARK's Name Mapping Authority rule arriving as a real requirement:
+ * the resolver's hostport is **identity-inert** — "ARKs that differ only in
+ * the optional NMA part identify the same object", and the host is
+ * "temporary, disposable, and replaceable". So the base never enters
+ * `canonical`. `miadi-chronicle:311` is the name; a base is chosen at render
+ * time, by audience.
+ *
+ * Which is also why the earlier draft's single `open` was wrong twice over —
+ * it picked a file when it should have picked a room, and it would have
+ * picked one room when there are three and the right one depends on who is
+ * reading.
+ */
+export interface WebBases {
+    /** This host only. Fastest, and useless to anyone else. */
+    local?: string;
+    /** Tailnet — private, reaches other machines on the tailscale network. */
+    internal?: string;
+    /** Public front. The only one that survives being pasted somewhere. */
+    public?: string;
+}
+export type BaseKind = "local" | "internal" | "public";
+/**
+ * Read the bases from the environment. Nothing is probed — reachability is a
+ * claim about the reader's network, not about this process, and a resolver
+ * that silently dropped an unreachable base would hide exactly the fact a
+ * reader elsewhere needs.
+ */
+export declare function readWebBases(env?: NodeJS.ProcessEnv): WebBases;
+/** One door. A reference has several; which one is right depends on the reader. */
+export interface Destination {
+    kind: "room" | "wheel-api" | "wheel-page" | "artifact-file" | "readme" | "vessel";
+    /** Where the base came from, for the room kinds. */
+    base?: BaseKind;
+    /** Short human label — what a terminal prints inside the anchor. */
+    label: string;
+    url: string;
+}
+export interface Destinations {
+    /**
+     * Every door, in offer order. A chronicle reference is not one place: the
+     * same episode is a room on three fronts and a file on this disk, and which
+     * is useful depends on where the reader is standing and what they came for.
+     *
+     * William's doors principle, in the resolver: *"Depending on the Door you
+     * enter Guillaume's world, you don't get the content presented the same
+     * way."*
+     */
+    all: Destination[];
+    /** The default pick — `all[0]`, or null when nothing resolved. */
+    open: string | null;
+    openKind: Destination["kind"] | "none";
+    /**
+     * The door that survives being pasted somewhere else. A localhost URL in a
+     * chronicle, an issue or a voice record is a link that works for exactly one
+     * reader on exactly one machine.
+     */
+    shareable: string | null;
+    /**
+     * Bytes on this host, for whatever consumes bytes — a script, an agent, an
+     * editor, a diff. Always present when the episode resolved, independent of
+     * any web surface. This is the local-first guarantee kept where it belongs:
+     * local-first is about data ownership and availability, never about
+     * presentation.
+     */
+    path: string | null;
+    modality: Modality;
+}
+/**
+ * `file://` URLs carry this host's name, always.
+ *
+ * Browsers ignore the authority in a file URL. OSC 8 explicitly forbids that
+ * laxity BECAUSE IT BREAKS UNDER SSH: a terminal is required to refuse opening
+ * a local file when the hostname does not match, and to treat empty or
+ * "localhost" as local. RFC 8089 formalises `file-auth = "localhost" / host`,
+ * so that "a client on another system [can] know that it cannot access the
+ * file system."
+ *
+ * On this stack ssh is the normal case — the chronicle wheel is reached
+ * through a tunnel — so `file:///srv/miadi/...` would be a link that opens
+ * confidently, on the wrong machine's disk.
+ */
+export declare function fileUrl(absolutePath: string, host?: string): string;
+export declare function resolveArtifactTarget(kind: ArtifactKind, episodeDir: string): Promise<ArtifactTarget | null>;
+/**
+ * The wheel's own doors, and the one endpoint that can be believed.
+ *
+ * Measured 2026-08-16: `/graph`, `/nodes` and `/relations` all begin
+ * `"use client"`. Fetching `/nodes?node=<a real episode id>` and grepping the
+ * HTML for the episode name returns **zero hits** — the shell is byte-identical
+ * for any parameter, and focus happens in the browser after it fetches
+ * `/api/nodes`. `/graph?direction=nowhere` is a 200 too.
+ *
+ * Forgewright behaves the same way: `?episode=9999-99-99-episode-000-nope`
+ * → 200. Two services, two codebases, one trap.
+ *
+ * **So an HTTP 200 from any of these pages is not evidence the episode
+ * exists.** `GET /api/nodes/<id>` is — it returns the node or a real 404
+ * (`{"error":"Node not found: chronicle:nope"}`). A resolver that hands a human
+ * a page URL without checking it first is handing them a silently empty wheel.
+ */
+export declare const WHEEL_PAGE_DOORS: readonly [{
+    readonly path: "/graph";
+    readonly label: "wheel·graph";
+}, {
+    readonly path: "/nodes";
+    readonly label: "wheel·node";
+}, {
+    readonly path: "/relations";
+    readonly label: "wheel·relations";
+}];
+export declare function wheelUrl(env?: NodeJS.ProcessEnv): string;
+/**
+ * Where a wheel-backed artifact actually lives.
+ *
+ * Every one is keyed by `episode_path` — the full folder name. The number is
+ * not a key: `?episode_number=320` returns 0 records for an episode whose
+ * `?episode_path=<folder>` returns 1, because the records carry no
+ * `episode_number` field and the filter compares strictly.
+ */
+export declare function wheelArtifactUrl(kind: ArtifactKind, episodeFolder: string, base: string): string | null;
+export interface WheelVerdict {
+    checked: boolean;
+    exists: boolean;
+    nodeId: string;
+    status?: number;
+    error?: string;
+}
+/**
+ * Ask the wheel whether this episode is actually on it.
+ *
+ * Opt-in (`--verify`) because it is a network call, and because a resolution
+ * that answers from the catalog on disk is already true about the disk. What
+ * this adds is the other half: whether the relational layer knows the episode
+ * too. Both answers are real, and they can disagree — forgewright's UI sees a
+ * 28-episode registry while its own disk routes resolve episodes the registry
+ * has never heard of.
+ */
+export declare function verifyOnWheel(episodeFolder: string, base: string, timeoutMs?: number): Promise<WheelVerdict>;
+/**
+ * Enumerate every door this reference opens.
+ *
+ * Two questions, never collapsed: *"where do I go to read this?"* is a room,
+ * *"where does this live?"* is the vessel. The 2026-08-07 draft answered only
+ * the second and called it `open`, which is how a chronicle link came to open
+ * emacs on raw JSON.
+ */
+export declare function buildDestinations(resolution: ChronicleResolution, parsed: ParsedChronicleUri, chronicleRoot: string, options?: {
+    bases?: WebBases;
+    prefer?: BaseKind | "local-file";
+    wheelUrl?: string;
+}): Promise<{
+    destinations: Destinations;
+    artifact: ArtifactTarget | null;
+}>;
+export interface ChronicleResolveResult {
+    ok: boolean;
+    uri: string;
+    /** Canonical rootless form — what a caller should persist or cite, and what
+     *  a future registered `x-scheme-handler/miadi-chronicle` app would receive. */
+    canonical: string;
+    parsed: {
+        episodePath: string;
+        segments: string[];
+        episodeSegments: string[];
+        artifact: ArtifactKind | null;
+        query: Record<string, string>;
+        options: Record<string, string>;
+        fragment?: string;
+    };
+    resolution: ChronicleResolution;
+    artifact: ArtifactTarget | null;
+    /** Every door, in offer order. */
+    destinations: Destination[];
+    /** The default pick — `destinations[0]`. */
+    open: string | null;
+    openKind: Destinations["openKind"];
+    /** The door that survives being pasted elsewhere. */
+    shareable: string | null;
+    /** Bytes on this host. Independent of `open`. */
+    path: string | null;
+    modality: Modality;
+    /** Present only when the fragment names something positional. */
+    fragmentWarning?: FragmentVerdict;
+    /** Present only with --verify: what the wheel said about this episode. */
+    wheel?: WheelVerdict;
+}
+export declare function resolveForTerminal(uri: string, entries: ResolvableEpisode[], chronicleRoot: string, options?: {
+    bases?: WebBases;
+    prefer?: BaseKind | "local-file";
+    wheelUrl?: string;
+    verify?: boolean;
+}): Promise<ChronicleResolveResult | null>;
+//# sourceMappingURL=chronicle-terminal.d.ts.map

package/dist/chronicle-terminal.d.ts.map

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