@chipschat/protocol 0.0.0-stage → 1.0.0

package/dist/src/pairing.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The pairing payload (M4.1, ADR 0038): what a QR carries, and what `POST /v1/pairing-codes`
+ * answers beside the code.
+ *
+ * Since Gate 2 a QR has been an address with the code in its fragment —
+ * `http://192.168.1.20:4431/#pair=ABC-234` — which a phone's camera opens and the page reads.
+ * That stays the shape. What joins it, in the same fragment, is everything else a phone needs
+ * to reach the server when it is not on that network: the relay to dial, the server's tunnel
+ * key to ask for there and to authenticate it by, a version, and a list of candidate addresses
+ * for a direct path across the internet that is empty in v0. A QR without a version is one
+ * from before this, and reads as a code alone.
+ *
+ * The fragment rather than the query, as before: a fragment never reaches a server's log.
+ */
+import { z } from "zod";
+/** The payload's version. Bumped when a field's meaning changes, never for a new field. */
+export declare const PAIRING_VERSION = 1;
+/** Six characters from thirty-two, in two groups, as `chips serve` prints them. */
+export declare const pairingCode: z.ZodString;
+/**
+ * A code as somebody typed it, in the form a code is compared in (SEC-6): upper case, the dash
+ * put back after the third character, whatever else was typed between the characters dropped.
+ * Anything that is not six characters of the alphabet comes back as typed, trimmed, which no code
+ * matches.
+ */
+export declare function pairingCodeTyped(typed: string): string;
+/** The server's tunnel key: thirty-two bytes, base64url without padding. */
+export declare const serverKey: z.ZodString;
+export declare const pairingPayload: z.ZodObject<{
+    v: z.ZodInt;
+    code: z.ZodString;
+    lan: z.ZodOptional<z.ZodURL>;
+    relay: z.ZodOptional<z.ZodURL>;
+    key: z.ZodOptional<z.ZodString>;
+    candidates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        address: z.ZodString;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+export type PairingPayload = z.infer<typeof pairingPayload>;
+/** What a server offers beside a code, and what a QR carries beside it. */
+export interface PairingOffer {
+    readonly relay?: string | undefined;
+    readonly key?: string | undefined;
+    /**
+     * The server on its network, when that is not the address the QR opens: a page served from
+     * somewhere else — the desktop app — names the server it is paired with here.
+     */
+    readonly lan?: string | undefined;
+}
+/**
+ * The text a QR carries: the address the phone should try first, with the code and the rest in
+ * the fragment. `base` is that address — the LAN address when the server is bound to the
+ * network, else its own.
+ */
+export declare function pairingUrl(base: string, code: string, offer?: PairingOffer): string;
+/**
+ * The same payload as a link the installed app opens: `chips://pair?pair=ABC-234&v=1&lan=…`.
+ *
+ * A QR's address opens in a browser, and a browser makes a device key only on a secure origin,
+ * which a server's plain-HTTP address on a home network or a tailnet never is. The app has no
+ * such rule. So a page that cannot pair offers this link instead, and `pnpm phone` hands it to
+ * the app directly at launch, with nobody typing anything. The server's address travels in the
+ * query as `lan`, because a `chips://` link has no origin of its own to fall back on.
+ */
+export declare function appPairingUrl(server: string, code: string, offer?: PairingOffer): string;
+/** Where a pairing link opens at a relay (ADR 0210): the page a computer is sent to. */
+export declare const RELAY_PAIR_PATH = "/pair";
+/**
+ * The link a phone sends a computer to pair it, when the server has a relay (ADR 0210): the relay's
+ * own page, with the payload in its fragment and the server beside it as `lan`. The relay is on the
+ * open internet where the server may not be, so the link opens on any network; the page hands the
+ * payload to Chips for Mac as `chips://pair?…`, or to the server's own page for a browser on its
+ * network. The fragment never reaches the relay. `until` is when the code runs out, in seconds, so
+ * the page can say so instead of letting a pairing fail.
+ *
+ *   https://relay.chipschat.ai/pair#pair=ABC-234&v=1&lan=https://host&relay=wss://…&key=…&until=…
+ */
+export declare function pairRelayUrl(relay: string, code: string, offer: {
+    readonly lan: string;
+    readonly key: string;
+    readonly until?: number | undefined;
+}): string;
+/**
+ * The payload in a link somebody pasted (ADR 0210): the relay's page, the server's own page, or
+ * the app's `chips://pair?…`. Nothing when it carries no code, and nothing for a relay page that
+ * names no server, since its own origin is the relay's and no server answers there.
+ */
+export declare function pairingFromLink(text: string): PairingPayload | undefined;
+/**
+ * The payload in an address: the fragment first, and the query for a link somebody rewrote.
+ * Nothing when there is no code. A QR from before M4.1 reads as version 0 with the code and,
+ * when the address has an origin, that origin as the network to try.
+ */
+export declare function pairingFromUrl(url: {
+    readonly origin?: string | undefined;
+    readonly search: string;
+    readonly hash: string;
+}): PairingPayload | undefined;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/src/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/pairing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,2FAA2F;AAC3F,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,mFAAmF;AACnF,eAAO,MAAM,WAAW,aAAkE,CAAC;AAE3F;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAItD;AAED,4EAA4E;AAC5E,eAAO,MAAM,SAAS,aAA0D,CAAC;AAEjF,eAAO,MAAM,cAAc;;;;;;;;;iBAiBzB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,YAAiB,GAAG,MAAM,CAOvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,YAAiB,GAAG,MAAM,CAM5F;AAED,wFAAwF;AACxF,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACzF,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAexE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GAAG,cAAc,GAAG,SAAS,CA0B7B"}

package/dist/src/pairing.js

@@ -0,0 +1,163 @@
+/**
+ * The pairing payload (M4.1, ADR 0038): what a QR carries, and what `POST /v1/pairing-codes`
+ * answers beside the code.
+ *
+ * Since Gate 2 a QR has been an address with the code in its fragment —
+ * `http://192.168.1.20:4431/#pair=ABC-234` — which a phone's camera opens and the page reads.
+ * That stays the shape. What joins it, in the same fragment, is everything else a phone needs
+ * to reach the server when it is not on that network: the relay to dial, the server's tunnel
+ * key to ask for there and to authenticate it by, a version, and a list of candidate addresses
+ * for a direct path across the internet that is empty in v0. A QR without a version is one
+ * from before this, and reads as a code alone.
+ *
+ * The fragment rather than the query, as before: a fragment never reaches a server's log.
+ */
+import { z } from "zod";
+import { candidateAddresses } from "./relay.js";
+/** The payload's version. Bumped when a field's meaning changes, never for a new field. */
+export const PAIRING_VERSION = 1;
+/** Six characters from thirty-two, in two groups, as `chips serve` prints them. */
+export const pairingCode = z.string().regex(/^[A-Z2-9]{3}-[A-Z2-9]{3}$/, "a pairing code");
+/**
+ * A code as somebody typed it, in the form a code is compared in (SEC-6): upper case, the dash
+ * put back after the third character, whatever else was typed between the characters dropped.
+ * Anything that is not six characters of the alphabet comes back as typed, trimmed, which no code
+ * matches.
+ */
+export function pairingCodeTyped(typed) {
+    const characters = typed.toUpperCase().replace(/[^A-Z2-9]/g, "");
+    if (characters.length !== 6)
+        return typed.trim().toUpperCase();
+    return `${characters.slice(0, 3)}-${characters.slice(3)}`;
+}
+/** The server's tunnel key: thirty-two bytes, base64url without padding. */
+export const serverKey = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "a server key");
+export const pairingPayload = z.object({
+    v: z.int().nonnegative().describe("0 for a QR from before M4.1, which carries a code alone."),
+    code: pairingCode,
+    lan: z
+        .url({ protocol: /^https?$/ })
+        .optional()
+        .describe("The server on the network it is on. Tried first, on a short timeout."),
+    relay: z
+        .url({ protocol: /^wss?$/ })
+        .optional()
+        .describe("The relay the server dials out to, when it has one."),
+    key: serverKey
+        .optional()
+        .describe("The server's tunnel key: asked for at the relay, and what the tunnel authenticates."),
+    candidates: candidateAddresses,
+});
+/**
+ * The text a QR carries: the address the phone should try first, with the code and the rest in
+ * the fragment. `base` is that address — the LAN address when the server is bound to the
+ * network, else its own.
+ */
+export function pairingUrl(base, code, offer = {}) {
+    const fields = new URLSearchParams({ pair: code, v: String(PAIRING_VERSION) });
+    if (offer.relay !== undefined && offer.relay !== "")
+        fields.set("relay", offer.relay);
+    if (offer.key !== undefined && offer.key !== "")
+        fields.set("key", offer.key);
+    if (offer.lan !== undefined && offer.lan !== "" && offer.lan !== base)
+        fields.set("lan", offer.lan);
+    return `${base.replace(/\/$/, "")}/#${fields.toString()}`;
+}
+/**
+ * The same payload as a link the installed app opens: `chips://pair?pair=ABC-234&v=1&lan=…`.
+ *
+ * A QR's address opens in a browser, and a browser makes a device key only on a secure origin,
+ * which a server's plain-HTTP address on a home network or a tailnet never is. The app has no
+ * such rule. So a page that cannot pair offers this link instead, and `pnpm phone` hands it to
+ * the app directly at launch, with nobody typing anything. The server's address travels in the
+ * query as `lan`, because a `chips://` link has no origin of its own to fall back on.
+ */
+export function appPairingUrl(server, code, offer = {}) {
+    const fields = new URLSearchParams({ pair: code, v: String(PAIRING_VERSION) });
+    fields.set("lan", (offer.lan ?? server).replace(/\/$/, ""));
+    if (offer.relay !== undefined && offer.relay !== "")
+        fields.set("relay", offer.relay);
+    if (offer.key !== undefined && offer.key !== "")
+        fields.set("key", offer.key);
+    return `chips://pair?${fields.toString()}`;
+}
+/** Where a pairing link opens at a relay (ADR 0210): the page a computer is sent to. */
+export const RELAY_PAIR_PATH = "/pair";
+/**
+ * The link a phone sends a computer to pair it, when the server has a relay (ADR 0210): the relay's
+ * own page, with the payload in its fragment and the server beside it as `lan`. The relay is on the
+ * open internet where the server may not be, so the link opens on any network; the page hands the
+ * payload to Chips for Mac as `chips://pair?…`, or to the server's own page for a browser on its
+ * network. The fragment never reaches the relay. `until` is when the code runs out, in seconds, so
+ * the page can say so instead of letting a pairing fail.
+ *
+ *   https://relay.chipschat.ai/pair#pair=ABC-234&v=1&lan=https://host&relay=wss://…&key=…&until=…
+ */
+export function pairRelayUrl(relay, code, offer) {
+    const page = /^https?:\/\/[^/?#]+/i.exec(relay.replace(/^ws(s?):\/\//i, "http$1://"))?.[0];
+    if (page === undefined)
+        throw new Error(`not a relay's address: ${relay}`);
+    const lan = /^https?:\/\/[^/?#]+/i.exec(offer.lan)?.[0] ?? offer.lan.replace(/\/$/, "");
+    const fields = new URLSearchParams({ pair: code, v: String(PAIRING_VERSION), lan });
+    fields.set("relay", relay);
+    fields.set("key", offer.key);
+    if (offer.until !== undefined)
+        fields.set("until", String(Math.floor(offer.until)));
+    return `${page}${RELAY_PAIR_PATH}#${fields.toString()}`;
+}
+/**
+ * The payload in a link somebody pasted (ADR 0210): the relay's page, the server's own page, or
+ * the app's `chips://pair?…`. Nothing when it carries no code, and nothing for a relay page that
+ * names no server, since its own origin is the relay's and no server answers there.
+ */
+export function pairingFromLink(text) {
+    // A link copied out of a message may come with the message: the word that holds the code.
+    const word = text.split(/\s+/).find((each) => each.includes("pair=")) ?? "";
+    let url;
+    try {
+        url = new URL(word);
+    }
+    catch {
+        return undefined;
+    }
+    const payload = pairingFromUrl({ origin: url.origin, search: url.search, hash: url.hash });
+    if (payload === undefined)
+        return undefined;
+    const named = new URLSearchParams(url.hash.replace(/^#/, "")).has("lan") || url.searchParams.has("lan");
+    if (url.pathname === RELAY_PAIR_PATH && !named)
+        return undefined;
+    return payload;
+}
+/**
+ * The payload in an address: the fragment first, and the query for a link somebody rewrote.
+ * Nothing when there is no code. A QR from before M4.1 reads as version 0 with the code and,
+ * when the address has an origin, that origin as the network to try.
+ */
+export function pairingFromUrl(url) {
+    const fragment = new URLSearchParams(url.hash.replace(/^#/, ""));
+    const query = new URLSearchParams(url.search);
+    const field = (name) => query.get(name) ?? fragment.get(name);
+    const code = field("pair");
+    if (code === null || code === "")
+        return undefined;
+    const version = field("v");
+    const origin = url.origin !== undefined && /^https?:\/\//.test(url.origin) ? url.origin : undefined;
+    // The network address is the QR's own, unless the fragment names one: a page that is not the
+    // server's says where the server is.
+    const lan = field("lan") ?? origin;
+    const parsed = pairingPayload.safeParse({
+        v: version === null ? 0 : Number.parseInt(version, 10),
+        code: code.trim().toUpperCase(),
+        ...(lan === undefined || lan === null ? {} : { lan }),
+        ...(field("relay") === null ? {} : { relay: field("relay") }),
+        ...(field("key") === null ? {} : { key: field("key") }),
+        candidates: [],
+    });
+    // A fragment that names a relay this version cannot read is still a code: the phone pairs on
+    // the network it is on, which is the path that needs nothing from the fragment.
+    if (parsed.success)
+        return parsed.data;
+    const plain = pairingPayload.safeParse({ v: 0, code: code.trim().toUpperCase(), candidates: [] });
+    return plain.success ? plain.data : undefined;
+}
+//# sourceMappingURL=pairing.js.map

package/dist/src/pairing.js.map

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

package/dist/src/primitives.d.ts

@@ -0,0 +1,267 @@
+/**
+ * The sub-schemas events are built from. Each one exists because more than one event needs
+ * it, and each carries a description, because those descriptions become the documentation
+ * reference (technical-plan decision 13).
+ */
+import { z } from "zod";
+import { type IdKind } from "./ids/index.js";
+/** A schema for one kind of prefixed ULID, for example `run_01K4...` (decision 11). */
+export declare function id<K extends IdKind>(kind: K): z.ZodString;
+/**
+ * Who takes part in rooms without being a person: an agent (ADR 0087), or a harness written
+ * before agents, which is a member of rooms until the upgrade gives it one.
+ */
+export declare const agentId: z.ZodString;
+/**
+ * Somebody in a room a message can be for (ADR 0204): an agent (`agentId`), or a person (`usr_`).
+ */
+export declare const memberId: z.ZodString;
+/** The kinds of participant: a person, an agent in rooms, and the harness behind agents. */
+export declare const PARTICIPANT_KINDS: readonly ["person", "harness", "agent"];
+export type ParticipantKind = (typeof PARTICIPANT_KINDS)[number];
+export declare const isoTimestamp: z.ZodISODateTime;
+/** Who caused an event. Every envelope says so; the audit log is a read of this field. */
+export declare const actor: z.ZodObject<{
+    kind: z.ZodEnum<{
+        person: "person";
+        harness: "harness";
+        agent: "agent";
+        system: "system";
+    }>;
+    id: z.ZodString;
+    harness_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Actor = z.infer<typeof actor>;
+/** A person, harness or agent as another party sees them, with the role Chips assigns. */
+export declare const participantRef: z.ZodObject<{
+    participant_id: z.ZodString;
+    kind: z.ZodEnum<{
+        person: "person";
+        harness: "harness";
+        agent: "agent";
+    }>;
+    display_name: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        member: "member";
+        guest: "guest";
+    }>;
+    workspace_role: z.ZodOptional<z.ZodEnum<{
+        owner: "owner";
+        member: "member";
+        guest: "guest";
+        admin: "admin";
+    }>>;
+}, z.core.$strip>;
+export type ParticipantRef = z.infer<typeof participantRef>;
+/** The longest transcript an attachment carries: far more than five minutes of anyone talking. */
+export declare const MAX_TRANSCRIPT_LENGTH = 50000;
+/**
+ * An attachment. Anything you can send a person you can send a harness, so this shape carries
+ * files, images, video and voice notes alike (decision 10).
+ */
+export declare const attachment: z.ZodObject<{
+    attachment_id: z.ZodString;
+    filename: z.ZodString;
+    mime_type: z.ZodString;
+    byte_size: z.ZodInt;
+    sha256: z.ZodString;
+    width: z.ZodOptional<z.ZodInt>;
+    height: z.ZodOptional<z.ZodInt>;
+    duration_ms: z.ZodOptional<z.ZodInt>;
+    transcript: z.ZodOptional<z.ZodString>;
+    replaces: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Attachment = z.infer<typeof attachment>;
+/** An attachment as it reaches a harness: with a URL it can actually fetch. */
+export declare const signedAttachment: z.ZodObject<{
+    attachment_id: z.ZodString;
+    filename: z.ZodString;
+    mime_type: z.ZodString;
+    byte_size: z.ZodInt;
+    sha256: z.ZodString;
+    width: z.ZodOptional<z.ZodInt>;
+    height: z.ZodOptional<z.ZodInt>;
+    duration_ms: z.ZodOptional<z.ZodInt>;
+    transcript: z.ZodOptional<z.ZodString>;
+    replaces: z.ZodOptional<z.ZodString>;
+    url: z.ZodURL;
+    url_expires_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type SignedAttachment = z.infer<typeof signedAttachment>;
+/** Where a claim came from. External sources are what make an action risky. */
+export declare const source: z.ZodObject<{
+    kind: z.ZodEnum<{
+        external: "external";
+        internal: "internal";
+    }>;
+    label: z.ZodString;
+    url: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type Source = z.infer<typeof source>;
+/**
+ * Risk classes. These are the flags the policy engine matches on (decision 8), so the list is
+ * closed: a new class is a protocol change, not a free-text string a harness invents.
+ */
+export declare const riskClass: z.ZodEnum<{
+    external: "external";
+    external_communication: "external_communication";
+    irreversible: "irreversible";
+    destructive: "destructive";
+    financial: "financial";
+    credential: "credential";
+    privacy: "privacy";
+    legal: "legal";
+}>;
+export type RiskClass = z.infer<typeof riskClass>;
+/**
+ * What kind of call a step is (ADR 0162), so a tool whose name Chips has never read still draws
+ * as what it does. Closed for the same reason as the risk classes: each is a glyph and a few
+ * words in the apps, and a kind nobody draws would be a dot again.
+ */
+export declare const stepKind: z.ZodEnum<{
+    edit: "edit";
+    search: "search";
+    web: "web";
+    shell: "shell";
+    image: "image";
+    memory: "memory";
+    file: "file";
+    mail: "mail";
+    handoff: "handoff";
+    other: "other";
+}>;
+export type StepKind = z.infer<typeof stepKind>;
+/** The action a harness wants to take. `kind` is what policy rules glob against. */
+export declare const action: z.ZodObject<{
+    kind: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+    external: z.ZodOptional<z.ZodBoolean>;
+    irreversible: z.ZodOptional<z.ZodBoolean>;
+    money_usd: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Action = z.infer<typeof action>;
+/** What a person is shown before they decide. A diff for a change, prose for a message. */
+export declare const preview: z.ZodObject<{
+    format: z.ZodEnum<{
+        markdown: "markdown";
+        plain: "plain";
+        diff: "diff";
+        json: "json";
+        table: "table";
+    }>;
+    body: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Preview = z.infer<typeof preview>;
+/**
+ * Who may answer an approval. `owner`, `role:<name>` and `lead` are resolved by Chips, so a
+ * harness never needs to know who is on shift; once resolved the list holds ids — a person's,
+ * or the lead harness's (M5.5).
+ */
+export declare const approverRef: z.ZodString;
+/** Autonomy levels L0 to L3 (blueprint: trust is a dial, not a switch). */
+export declare const autonomyLevel: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+export type AutonomyLevel = z.infer<typeof autonomyLevel>;
+/** One policy rule. Rules read like sentences: `email.send to an external domain -> ask the owner`. */
+export declare const policyRule: z.ZodObject<{
+    match: z.ZodString;
+    when: z.ZodOptional<z.ZodObject<{
+        external: z.ZodOptional<z.ZodBoolean>;
+        irreversible: z.ZodOptional<z.ZodBoolean>;
+        money_usd_over: z.ZodOptional<z.ZodNumber>;
+        risk: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            external: "external";
+            external_communication: "external_communication";
+            irreversible: "irreversible";
+            destructive: "destructive";
+            financial: "financial";
+            credential: "credential";
+            privacy: "privacy";
+            legal: "legal";
+        }>>>;
+        starts_with: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    decision: z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        deny: "deny";
+    }>;
+    approvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    reason: z.ZodOptional<z.ZodString>;
+    off: z.ZodOptional<z.ZodBoolean>;
+    made_by: z.ZodOptional<z.ZodString>;
+    made_at: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type PolicyRule = z.infer<typeof policyRule>;
+export declare const policy: z.ZodObject<{
+    autonomy: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    rules: z.ZodArray<z.ZodObject<{
+        match: z.ZodString;
+        when: z.ZodOptional<z.ZodObject<{
+            external: z.ZodOptional<z.ZodBoolean>;
+            irreversible: z.ZodOptional<z.ZodBoolean>;
+            money_usd_over: z.ZodOptional<z.ZodNumber>;
+            risk: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                external: "external";
+                external_communication: "external_communication";
+                irreversible: "irreversible";
+                destructive: "destructive";
+                financial: "financial";
+                credential: "credential";
+                privacy: "privacy";
+                legal: "legal";
+            }>>>;
+            starts_with: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        decision: z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            deny: "deny";
+        }>;
+        approvers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        reason: z.ZodOptional<z.ZodString>;
+        off: z.ZodOptional<z.ZodBoolean>;
+        made_by: z.ZodOptional<z.ZodString>;
+        made_at: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Policy = z.infer<typeof policy>;
+/** Money is always an estimate and always labelled as one (blueprint: cost rolls up the trail). */
+export declare const cost: z.ZodObject<{
+    usd: z.ZodNumber;
+    estimated: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type Cost = z.infer<typeof cost>;
+export declare const budget: z.ZodObject<{
+    limit_usd: z.ZodNumber;
+    spent_usd: z.ZodNumber;
+}, z.core.$strip>;
+export type Budget = z.infer<typeof budget>;
+/** How work travelled to get here, so a lane can be traced back to the message that caused it. */
+export declare const trailEntry: z.ZodObject<{
+    participant_id: z.ZodString;
+    run_id: z.ZodOptional<z.ZodString>;
+    goal: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TrailEntry = z.infer<typeof trailEntry>;
+/**
+ * A pointer to one visit a harness made to a space: `scout:<session_id>`, and whatever
+ * the harness calls it elsewhere. A space outlives its sessions (ADR 0024), so this is what
+ * tells one visit's runs from another's, and what lets a person open the harness's own
+ * transcript of it.
+ */
+export declare const sessionRef: z.ZodString;
+/**
+ * A person's standing in the workspace, as distinct from their standing in a room (ADR 0034).
+ * An owner does everything; an admin everything but touch an owner or make one; a member the
+ * ordinary things; a guest is in one space only and changes nothing about the workspace.
+ */
+export declare const workspaceRole: z.ZodEnum<{
+    owner: "owner";
+    member: "member";
+    guest: "guest";
+    admin: "admin";
+}>;
+export type WorkspaceRole = z.infer<typeof workspaceRole>;
+//# sourceMappingURL=primitives.d.ts.map

package/dist/src/primitives.d.ts.map

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