@venn-lang/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @venn-lang/types
+
+> The language's type vocabulary as plain data: ten shapes, no dependencies, no compiler.
+
+A `TypeSpec` is what a plugin publishes about itself and what the checker reads back. It is data
+only, so it survives `JSON.stringify`: a signature written by hand today and one generated from a
+`.d.ts` tomorrow are the same bytes. The compiler's own `Type`, with the inference variables that
+unification writes into, is a separate and internal thing. Nothing mutable lands here.
+
+This package is the shared vocabulary that lets the compiler, the plugin SDK and the `.d.ts` reader
+talk about types without depending on one another. It has no dependencies at all, and its whole
+runtime is one object literal (`t`) and one function (`showSpec`).
+
+## Usage
+
+Write the type of a verb, and the types it takes and gives back:
+
+```ts
+import { t, type TypeSpec } from "@venn-lang/types";
+
+// http.on server handler
+const signature = t.fn(
+  [t.ref("http.Server"), t.callback([t.ref("http.Request")], t.dynamic, 1)],
+  t.void,
+);
+
+// http.Request, as the handler receives it
+const request: TypeSpec = t.record({
+  method: t.string,
+  url: t.string,
+  headers: t.map(t.string),
+  body: t.string,
+});
+```
+
+That is the whole mechanism behind an editor knowing what `req` is with nothing written down:
+
+```ruby
+use "venn/http"
+
+const api = http.serve { port: 0 }
+http.on(api, route)
+
+# `http.on` says it hands its handler a request, so `req` is `http.Request`.
+fn route(req) {
+  req.url.before("?")
+}
+```
+
+## API
+
+Everything `src/index.ts` exports.
+
+| Export | What it is |
+| --- | --- |
+| `TypeSpec` | The union of the ten shapes. The wire format of a Venn type. |
+| `PrimSpec`, `PrimName` | A scalar. `string`, `number`, `bool`, `null`, `void`, plus the units the language treats as first class: `duration`, `size`, `percent`, `instant`. |
+| `LiteralSpec` | A single value (`"GET"`, `200`, `true`). What makes an enum an enum. |
+| `ListSpec`, `MapSpec` | `list<T>`, and keys not known ahead of time with values all alike. |
+| `RecordSpec` | Known fields, with `optional` naming those that may be absent and `open` saying whether extras are tolerated. |
+| `FnSpec` | Params, result, and an optional `takes`: how many params the caller must actually accept. |
+| `UnionSpec` | Members, any of which will do. |
+| `OpaqueSpec` | A named handle with no visible inside. `members` is what it does publish. |
+| `RefSpec` | A named type resolved through the catalog: `http.Request`. |
+| `DynamicSpec` | Unknown, and deliberately so. Unifies with everything, never errors. |
+| `TypeManifest` | What a plugin publishes as a whole: named `types`, and one `FnSpec` per action under `actions`. |
+| `t` | The authoring surface. See below. |
+| `TypeBuilder`, `RecordOptions` | The type of `t`, and the second argument of `t.record`. |
+| `showSpec(spec)` | A spec as one line of text. |
+
+### `t`
+
+Constants: `t.string`, `t.number`, `t.bool`, `t.null`, `t.void`, `t.duration`, `t.size`,
+`t.percent`, `t.instant`, `t.dynamic`.
+
+| Call | Builds |
+| --- | --- |
+| `t.literal(value)` | `"GET"`, `200`, `true` |
+| `t.list(element)` | `list<element>` |
+| `t.map(value)` | keys unknown, values all `value` |
+| `t.record(fields, { optional, open })` | a shape with known fields |
+| `t.fn(params, result)` | a function, arity as written |
+| `t.callback(params, result, takes)` | the same, but usable by a caller that accepts only `takes` of them |
+| `t.union(...members)` | any of the members |
+| `t.opaque(name, members?)` | a handle, with an optional published surface |
+| `t.ref(name)` | a named type, resolved later |
+
+`t.callback` is what makes `req => ...` a valid handler for a verb that also offers the server: a
+callback handed more than it needs is still a good callback. `t.fn` leaves `takes` off, so plain
+arity means what it says.
+
+### `showSpec`
+
+Reads the wire format directly rather than going through the checker, so nothing has to be resolved
+and a package with no compiler in it can still say what it takes. A `ref` or an `opaque` shows as
+the name the plugin published, not the shape behind it.
+
+```ts
+showSpec(t.fn([t.string], t.number));            // "fn(string) -> number"
+showSpec(t.union(t.literal("GET"), t.literal("POST"))); // '"GET" | "POST"'
+showSpec(t.list(t.number));                      // "list<number>"
+showSpec(t.opaque("http.Server"));               // "http.Server"
+```
+
+Records stop after four fields and finish with `…N more`, because past a few fields a shape stops
+informing and starts filling the line.
+
+## The ten shapes, and why only ten
+
+`prim`, `literal`, `list`, `map`, `record`, `fn`, `union`, `opaque`, `ref`, `dynamic`.
+
+Everything TypeScript can say either projects onto one of these or degrades to `dynamic`. It never
+degrades to a failure. Generics, conditional and mapped types are resolved by the TypeScript
+compiler before anything reaches here, so what arrives is the answer rather than the machinery.
+
+`opaque` is the border. Projecting a JS class as a record would drag its whole object graph, the
+`EventEmitter`, the symbols, the hundred inherited members, into a language that means none of it.
+An opaque type can be held, handed to the verbs of its own namespace, and asked for the members it
+chose to publish. Nothing else.
+
+`dynamic` is a first-class citizen, not a hole to be closed. A plugin that says nothing about its
+types is still a plugin that works, and a Venn program with zero annotations still runs.
+
+## Who reads this
+
+| Package | What it does with a `TypeSpec` |
+| --- | --- |
+| [`@venn-lang/sdk`](../sdk) | `defineAction` derives an action's `FnSpec` from the `args` and `result` an author named; a plugin's named types go in `typeDefs`. |
+| [`@venn-lang/core`](../core) | `specToType` reads a spec into the checker's own type, with `ref` resolved through a callback. The handle kinds in `kind-types.ts` are themselves written as specs. |
+| [`@venn-lang/runtime`](../runtime) | `createTypeCatalog` qualifies what the loaded plugins publish (`Request` becomes `http.Request`) and answers the checker's questions. |
+| [`@venn-lang/dts`](../dts) | Reads a package's TypeScript declarations through the compiler and emits specs. The CLI stores the result under `target/types/`. |
+| [`@venn-lang/lsp`](../lsp) | `showSpec` for hover, completion detail and signature help. |
+
+See [`docs/type-system.md`](../../docs/type-system.md) for how the pieces fit together, what runs
+today and what does not.
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk), where plugin authors reach for `t`
+- [`@venn-lang/core`](../core), the checker that reads what was published
+- [`@venn-lang/dts`](../dts), TypeScript declarations turned into specs

package/dist/index.d.ts

@@ -0,0 +1,156 @@
+//#region src/spec/type-spec.types.d.ts
+/**
+ * The wire format of a Venn type.
+ *
+ * Plain data: no functions, no `Map`s, no inference variables, so a `TypeSpec`
+ * survives `JSON.stringify`. That is what lets a plugin hand-write one and a
+ * generator emit the very same bytes from a `.d.ts`. The compiler's own `Type`,
+ * with its unification variables, is a separate internal thing; nothing mutable
+ * ever lands here.
+ *
+ * Deliberately smaller than TypeScript's type system. Everything TS can say
+ * projects onto these ten shapes or degrades to {@link DynamicSpec}, never to a
+ * failure. Generics, conditional and mapped types are resolved by the TypeScript
+ * compiler at generation time, so what arrives here is the answer, not the
+ * machinery.
+ */
+type TypeSpec = PrimSpec | LiteralSpec | ListSpec | MapSpec | RecordSpec | FnSpec | UnionSpec | OpaqueSpec | RefSpec | DynamicSpec;
+/** The scalars, including the units the language treats as first class. */
+type PrimName = "string" | "number" | "bool" | "null" | "void" | "duration" | "size" | "percent" | "instant";
+/** One of the scalars named by {@link PrimName}. */
+interface PrimSpec {
+  readonly kind: "prim";
+  readonly name: PrimName;
+}
+/** A single value: `"GET"`, `200`, `true`. What makes an enum an enum. */
+interface LiteralSpec {
+  readonly kind: "literal";
+  readonly value: string | number | boolean;
+}
+/** Any number of values of one type. The language has no fixed-length list. */
+interface ListSpec {
+  readonly kind: "list";
+  readonly element: TypeSpec;
+}
+/** Keys not known ahead of time, values all alike: TS's `Record<string, T>`. */
+interface MapSpec {
+  readonly kind: "map";
+  readonly value: TypeSpec;
+}
+/** Known fields. `open` tolerates extra ones; `optional` lists what may be absent. */
+interface RecordSpec {
+  readonly kind: "record";
+  readonly fields: Readonly<Record<string, TypeSpec>>;
+  readonly optional?: readonly string[];
+  readonly open?: boolean;
+}
+/** A callable: what it is given, in order, and what it gives back. */
+interface FnSpec {
+  readonly kind: "fn";
+  readonly params: readonly TypeSpec[];
+  readonly result: TypeSpec;
+  /**
+   * How many parameters the caller must actually take. A callback handed more
+   * than it needs is still a good callback, as with `req => …` against a handler
+   * that is also offered the server.
+   */
+  readonly takes?: number;
+}
+/** A value that is any one of the members. */
+interface UnionSpec {
+  readonly kind: "union";
+  readonly members: readonly TypeSpec[];
+}
+/**
+ * A handle with a name and no visible inside: a socket, a browser, an
+ * `express.Application`.
+ *
+ * This is the border. Projecting a JS class as a record would drag its whole
+ * object graph (`EventEmitter`, symbols, a hundred inherited members) into a
+ * language that means none of it. An opaque type can be held and handed to the
+ * verbs of its namespace, and nothing else.
+ */
+interface OpaqueSpec {
+  readonly kind: "opaque";
+  /**
+   * What a program may do with it, such as `{ port, close }` on a server.
+   *
+   * Opaque is about the *inside* being none of the reader's business, not about
+   * having nothing to offer. With none of these the handle is a name and no
+   * more, which is right for something only its own verbs ever touch.
+   */
+  readonly members?: Readonly<Record<string, TypeSpec>>;
+  readonly name: string;
+}
+/** A named type resolved through the catalog: `http.Request`, `User`. */
+interface RefSpec {
+  readonly kind: "ref";
+  readonly name: string;
+}
+/** Unknown, and deliberately so. Unifies with everything, never errors. */
+interface DynamicSpec {
+  readonly kind: "dynamic";
+}
+/** What a plugin publishes: its named types, and one signature per action. */
+interface TypeManifest {
+  /** Fully qualified: `http.Request`. */
+  readonly types?: Readonly<Record<string, TypeSpec>>;
+  /** Keyed by action name within the namespace: `serve`, `on`. */
+  readonly actions?: Readonly<Record<string, FnSpec>>;
+}
+//#endregion
+//#region src/spec/build.d.ts
+/** What a record needs beyond its fields: which are absent, and whether extras pass. */
+interface RecordOptions {
+  optional?: readonly string[];
+  open?: boolean;
+}
+/** The authoring surface for a {@link TypeSpec}. */
+interface TypeBuilder {
+  readonly string: PrimSpec;
+  readonly number: PrimSpec;
+  readonly bool: PrimSpec;
+  readonly null: PrimSpec;
+  readonly void: PrimSpec;
+  readonly duration: PrimSpec;
+  readonly size: PrimSpec;
+  readonly percent: PrimSpec;
+  readonly instant: PrimSpec;
+  readonly dynamic: DynamicSpec;
+  literal(value: string | number | boolean): LiteralSpec;
+  list(element: TypeSpec): ListSpec;
+  map(value: TypeSpec): MapSpec;
+  record(fields: Readonly<Record<string, TypeSpec>>, options?: RecordOptions): RecordSpec;
+  fn(params: readonly TypeSpec[], result: TypeSpec): FnSpec;
+  /** A function passed as an argument, which may take fewer params than it is handed. */
+  callback(params: readonly TypeSpec[], result: TypeSpec, takes: number): FnSpec;
+  union(...members: readonly TypeSpec[]): UnionSpec;
+  /** A named handle. `members` is what it publishes; without them, a bare name. */
+  opaque(name: string, members?: Readonly<Record<string, TypeSpec>>): OpaqueSpec;
+  ref(name: string): RefSpec;
+}
+/**
+ * Write a type by hand, for what has no `.d.ts` worth reading.
+ *
+ * Everything here is data, the same data a generator emits, so an action typed
+ * by hand today and typed from its TypeScript tomorrow are the same to every
+ * reader downstream.
+ */
+declare const t: TypeBuilder;
+//#endregion
+//#region src/spec/show.d.ts
+/**
+ * A published type as one line of text.
+ *
+ * Reads the wire format directly rather than going through the checker. Nothing
+ * has to be resolved, so a `ref` shows as the name a plugin published
+ * (`http.Server`, not the record behind it), and a package with no compiler in
+ * it can still say what it takes.
+ *
+ * @param spec the type to render
+ * @returns one line; a record past four fields is elided rather than wrapped
+ */
+declare function showSpec(spec: TypeSpec): string;
+//#endregion
+export { type DynamicSpec, type FnSpec, type ListSpec, type LiteralSpec, type MapSpec, type OpaqueSpec, type PrimName, type PrimSpec, type RecordOptions, type RecordSpec, type RefSpec, type TypeBuilder, type TypeManifest, type TypeSpec, type UnionSpec, showSpec, t };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/spec/type-spec.types.ts","../src/spec/build.ts","../src/spec/show.ts"],"mappings":";;;;;;;;;;;;;;;;KAeY,WACR,WACA,cACA,WACA,UACA,aACA,SACA,YACA,aACA,UACA;;KAGQ;;UAYK;WACN;WACA,MAAM;;;UAIA;WACN;WACA;;;UAIM;WACN;WACA,SAAS;;;UAIH;WACN;WACA,OAAO;;;UAID;WACN;WACA,QAAQ,SAAS,eAAe;WAChC;WACA;;;UAIM;WACN;WACA,iBAAiB;WACjB,QAAQ;;;;;;WAMR;;;UAIM;WACN;WACA,kBAAkB;;;;;;;;;;;UAYZ;WACN;;;;;;;;WAQA,UAAU,SAAS,eAAe;WAClC;;;UAIM;WACN;WACA;;;UAIM;WACN;;;UAIM;;WAEN,QAAQ,SAAS,eAAe;;WAEhC,UAAU,SAAS,eAAe;;;;;UCjH5B;EACf;EACA;;;UAIe;WACN,QAAQ;WACR,QAAQ;WACR,MAAM;WACN,MAAM;WACN,MAAM;WACN,UAAU;WACV,MAAM;WACN,SAAS;WACT,SAAS;WACT,SAAS;EAClB,QAAQ,mCAAmC;EAC3C,KAAK,SAAS,WAAW;EACzB,IAAI,OAAO,WAAW;EACtB,OAAO,QAAQ,SAAS,eAAe,YAAY,UAAU,gBAAgB;EAC7E,GAAG,iBAAiB,YAAY,QAAQ,WAAW;;EAEnD,SAAS,iBAAiB,YAAY,QAAQ,UAAU,gBAAgB;EACxE,SAAS,kBAAkB,aAAa;;EAExC,OAAO,cAAc,UAAU,SAAS,eAAe,aAAa;EACpE,IAAI,eAAe;;;;;;;;;cAcR,GAAG;;;;;;;;;;;;;;iBC3CA,SAAS,MAAM"}

package/dist/index.js

@@ -0,0 +1,117 @@
+//#region src/spec/build.ts
+function prim(name) {
+	return {
+		kind: "prim",
+		name
+	};
+}
+/**
+* Write a type by hand, for what has no `.d.ts` worth reading.
+*
+* Everything here is data, the same data a generator emits, so an action typed
+* by hand today and typed from its TypeScript tomorrow are the same to every
+* reader downstream.
+*/
+const t = {
+	string: prim("string"),
+	number: prim("number"),
+	bool: prim("bool"),
+	null: prim("null"),
+	void: prim("void"),
+	duration: prim("duration"),
+	size: prim("size"),
+	percent: prim("percent"),
+	instant: prim("instant"),
+	dynamic: { kind: "dynamic" },
+	literal: (value) => ({
+		kind: "literal",
+		value
+	}),
+	list: (element) => ({
+		kind: "list",
+		element
+	}),
+	map: (value) => ({
+		kind: "map",
+		value
+	}),
+	record: (fields, options) => ({
+		kind: "record",
+		fields,
+		...options
+	}),
+	fn: (params, result) => ({
+		kind: "fn",
+		params,
+		result
+	}),
+	callback: (params, result, takes) => ({
+		kind: "fn",
+		params,
+		result,
+		takes
+	}),
+	union: (...members) => ({
+		kind: "union",
+		members
+	}),
+	opaque: (name, members) => members ? {
+		kind: "opaque",
+		name,
+		members
+	} : {
+		kind: "opaque",
+		name
+	},
+	ref: (name) => ({
+		kind: "ref",
+		name
+	})
+};
+//#endregion
+//#region src/spec/show.ts
+/**
+* A published type as one line of text.
+*
+* Reads the wire format directly rather than going through the checker. Nothing
+* has to be resolved, so a `ref` shows as the name a plugin published
+* (`http.Server`, not the record behind it), and a package with no compiler in
+* it can still say what it takes.
+*
+* @param spec the type to render
+* @returns one line; a record past four fields is elided rather than wrapped
+*/
+function showSpec(spec) {
+	switch (spec.kind) {
+		case "prim": return spec.name;
+		case "literal": return typeof spec.value === "string" ? `"${spec.value}"` : String(spec.value);
+		case "list": return `list<${showSpec(spec.element)}>`;
+		case "map": return `map<${showSpec(spec.value)}>`;
+		case "record": return showRecord(spec);
+		case "fn": return showFn(spec);
+		case "union": return spec.members.map(showSpec).join(" | ");
+		case "opaque":
+		case "ref": return spec.name;
+		default: return "dynamic";
+	}
+}
+function showFn(spec) {
+	return `fn(${spec.params.map(showSpec).join(", ")}) -> ${showSpec(spec.result)}`;
+}
+/** Past a few fields a shape stops informing and starts filling the line. */
+const SHOWN_FIELDS = 4;
+function showRecord(spec) {
+	const names = Object.keys(spec.fields);
+	if (names.length === 0) return "{}";
+	const shown = names.slice(0, SHOWN_FIELDS).map((name) => field(spec, name));
+	const rest = names.length > shown.length ? `, …${names.length - shown.length} more` : "";
+	return `{ ${shown.join(", ")}${rest} }`;
+}
+function field(spec, name) {
+	const type = spec.fields[name];
+	return `${name}: ${type ? showSpec(type) : "dynamic"}`;
+}
+//#endregion
+export { showSpec, t };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/spec/build.ts","../src/spec/show.ts"],"sourcesContent":["import type {\n  DynamicSpec,\n  FnSpec,\n  ListSpec,\n  LiteralSpec,\n  MapSpec,\n  OpaqueSpec,\n  PrimSpec,\n  RecordSpec,\n  RefSpec,\n  TypeSpec,\n  UnionSpec,\n} from \"./type-spec.types.js\";\n\n/** What a record needs beyond its fields: which are absent, and whether extras pass. */\nexport interface RecordOptions {\n  optional?: readonly string[];\n  open?: boolean;\n}\n\n/** The authoring surface for a {@link TypeSpec}. */\nexport interface TypeBuilder {\n  readonly string: PrimSpec;\n  readonly number: PrimSpec;\n  readonly bool: PrimSpec;\n  readonly null: PrimSpec;\n  readonly void: PrimSpec;\n  readonly duration: PrimSpec;\n  readonly size: PrimSpec;\n  readonly percent: PrimSpec;\n  readonly instant: PrimSpec;\n  readonly dynamic: DynamicSpec;\n  literal(value: string | number | boolean): LiteralSpec;\n  list(element: TypeSpec): ListSpec;\n  map(value: TypeSpec): MapSpec;\n  record(fields: Readonly<Record<string, TypeSpec>>, options?: RecordOptions): RecordSpec;\n  fn(params: readonly TypeSpec[], result: TypeSpec): FnSpec;\n  /** A function passed as an argument, which may take fewer params than it is handed. */\n  callback(params: readonly TypeSpec[], result: TypeSpec, takes: number): FnSpec;\n  union(...members: readonly TypeSpec[]): UnionSpec;\n  /** A named handle. `members` is what it publishes; without them, a bare name. */\n  opaque(name: string, members?: Readonly<Record<string, TypeSpec>>): OpaqueSpec;\n  ref(name: string): RefSpec;\n}\n\nfunction prim(name: PrimSpec[\"name\"]): PrimSpec {\n  return { kind: \"prim\", name };\n}\n\n/**\n * Write a type by hand, for what has no `.d.ts` worth reading.\n *\n * Everything here is data, the same data a generator emits, so an action typed\n * by hand today and typed from its TypeScript tomorrow are the same to every\n * reader downstream.\n */\nexport const t: TypeBuilder = {\n  string: prim(\"string\"),\n  number: prim(\"number\"),\n  bool: prim(\"bool\"),\n  null: prim(\"null\"),\n  void: prim(\"void\"),\n  duration: prim(\"duration\"),\n  size: prim(\"size\"),\n  percent: prim(\"percent\"),\n  instant: prim(\"instant\"),\n  dynamic: { kind: \"dynamic\" },\n  literal: (value) => ({ kind: \"literal\", value }),\n  list: (element) => ({ kind: \"list\", element }),\n  map: (value) => ({ kind: \"map\", value }),\n  record: (fields, options) => ({ kind: \"record\", fields, ...options }),\n  fn: (params, result) => ({ kind: \"fn\", params, result }),\n  callback: (params, result, takes) => ({ kind: \"fn\", params, result, takes }),\n  union: (...members) => ({ kind: \"union\", members }),\n  opaque: (name, members) =>\n    members ? { kind: \"opaque\", name, members } : { kind: \"opaque\", name },\n  ref: (name) => ({ kind: \"ref\", name }),\n};\n","import type { FnSpec, RecordSpec, TypeSpec } from \"./type-spec.types.js\";\n\n/**\n * A published type as one line of text.\n *\n * Reads the wire format directly rather than going through the checker. Nothing\n * has to be resolved, so a `ref` shows as the name a plugin published\n * (`http.Server`, not the record behind it), and a package with no compiler in\n * it can still say what it takes.\n *\n * @param spec the type to render\n * @returns one line; a record past four fields is elided rather than wrapped\n */\nexport function showSpec(spec: TypeSpec): string {\n  switch (spec.kind) {\n    case \"prim\":\n      return spec.name;\n    case \"literal\":\n      return typeof spec.value === \"string\" ? `\"${spec.value}\"` : String(spec.value);\n    case \"list\":\n      return `list<${showSpec(spec.element)}>`;\n    case \"map\":\n      return `map<${showSpec(spec.value)}>`;\n    case \"record\":\n      return showRecord(spec);\n    case \"fn\":\n      return showFn(spec);\n    case \"union\":\n      return spec.members.map(showSpec).join(\" | \");\n    case \"opaque\":\n    case \"ref\":\n      return spec.name;\n    default:\n      return \"dynamic\";\n  }\n}\n\nfunction showFn(spec: FnSpec): string {\n  return `fn(${spec.params.map(showSpec).join(\", \")}) -> ${showSpec(spec.result)}`;\n}\n\n/** Past a few fields a shape stops informing and starts filling the line. */\nconst SHOWN_FIELDS = 4;\n\nfunction showRecord(spec: RecordSpec): string {\n  const names = Object.keys(spec.fields);\n  if (names.length === 0) return \"{}\";\n  const shown = names.slice(0, SHOWN_FIELDS).map((name) => field(spec, name));\n  const rest = names.length > shown.length ? `, …${names.length - shown.length} more` : \"\";\n  return `{ ${shown.join(\", \")}${rest} }`;\n}\n\nfunction field(spec: RecordSpec, name: string): string {\n  const type = spec.fields[name];\n  return `${name}: ${type ? showSpec(type) : \"dynamic\"}`;\n}\n"],"mappings":";AA6CA,SAAS,KAAK,MAAkC;CAC9C,OAAO;EAAE,MAAM;EAAQ;CAAK;AAC9B;;;;;;;;AASA,MAAa,IAAiB;CAC5B,QAAQ,KAAK,QAAQ;CACrB,QAAQ,KAAK,QAAQ;CACrB,MAAM,KAAK,MAAM;CACjB,MAAM,KAAK,MAAM;CACjB,MAAM,KAAK,MAAM;CACjB,UAAU,KAAK,UAAU;CACzB,MAAM,KAAK,MAAM;CACjB,SAAS,KAAK,SAAS;CACvB,SAAS,KAAK,SAAS;CACvB,SAAS,EAAE,MAAM,UAAU;CAC3B,UAAU,WAAW;EAAE,MAAM;EAAW;CAAM;CAC9C,OAAO,aAAa;EAAE,MAAM;EAAQ;CAAQ;CAC5C,MAAM,WAAW;EAAE,MAAM;EAAO;CAAM;CACtC,SAAS,QAAQ,aAAa;EAAE,MAAM;EAAU;EAAQ,GAAG;CAAQ;CACnE,KAAK,QAAQ,YAAY;EAAE,MAAM;EAAM;EAAQ;CAAO;CACtD,WAAW,QAAQ,QAAQ,WAAW;EAAE,MAAM;EAAM;EAAQ;EAAQ;CAAM;CAC1E,QAAQ,GAAG,aAAa;EAAE,MAAM;EAAS;CAAQ;CACjD,SAAS,MAAM,YACb,UAAU;EAAE,MAAM;EAAU;EAAM;CAAQ,IAAI;EAAE,MAAM;EAAU;CAAK;CACvE,MAAM,UAAU;EAAE,MAAM;EAAO;CAAK;AACtC;;;;;;;;;;;;;;AChEA,SAAgB,SAAS,MAAwB;CAC/C,QAAQ,KAAK,MAAb;EACE,KAAK,QACH,OAAO,KAAK;EACd,KAAK,WACH,OAAO,OAAO,KAAK,UAAU,WAAW,IAAI,KAAK,MAAM,KAAK,OAAO,KAAK,KAAK;EAC/E,KAAK,QACH,OAAO,QAAQ,SAAS,KAAK,OAAO,EAAE;EACxC,KAAK,OACH,OAAO,OAAO,SAAS,KAAK,KAAK,EAAE;EACrC,KAAK,UACH,OAAO,WAAW,IAAI;EACxB,KAAK,MACH,OAAO,OAAO,IAAI;EACpB,KAAK,SACH,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,CAAC,KAAK,KAAK;EAC9C,KAAK;EACL,KAAK,OACH,OAAO,KAAK;EACd,SACE,OAAO;CACX;AACF;AAEA,SAAS,OAAO,MAAsB;CACpC,OAAO,MAAM,KAAK,OAAO,IAAI,QAAQ,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,SAAS,KAAK,MAAM;AAC/E;;AAGA,MAAM,eAAe;AAErB,SAAS,WAAW,MAA0B;CAC5C,MAAM,QAAQ,OAAO,KAAK,KAAK,MAAM;CACrC,IAAI,MAAM,WAAW,GAAG,OAAO;CAC/B,MAAM,QAAQ,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,KAAK,SAAS,MAAM,MAAM,IAAI,CAAC;CAC1E,MAAM,OAAO,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,SAAS,MAAM,OAAO,SAAS;CACtF,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,KAAK;AACtC;AAEA,SAAS,MAAM,MAAkB,MAAsB;CACrD,MAAM,OAAO,KAAK,OAAO;CACzB,OAAO,GAAG,KAAK,IAAI,OAAO,SAAS,IAAI,IAAI;AAC7C"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@venn-lang/types",
+  "version": "0.1.0",
+  "description": "The language's type vocabulary as plain data: ten shapes, no dependencies, no compiler.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "types",
+    "type-system"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/types#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/types"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// @venn-lang/types: the language's type vocabulary as plain data.
+//
+// Zero dependencies on purpose. The compiler, the plugin SDK and the generator
+// that reads TypeScript declarations all speak this, and none of them should
+// have to depend on the others to do it.
+export * from "./spec/index.js";

package/src/spec/build.ts

@@ -0,0 +1,78 @@
+import type {
+  DynamicSpec,
+  FnSpec,
+  ListSpec,
+  LiteralSpec,
+  MapSpec,
+  OpaqueSpec,
+  PrimSpec,
+  RecordSpec,
+  RefSpec,
+  TypeSpec,
+  UnionSpec,
+} from "./type-spec.types.js";
+
+/** What a record needs beyond its fields: which are absent, and whether extras pass. */
+export interface RecordOptions {
+  optional?: readonly string[];
+  open?: boolean;
+}
+
+/** The authoring surface for a {@link TypeSpec}. */
+export interface TypeBuilder {
+  readonly string: PrimSpec;
+  readonly number: PrimSpec;
+  readonly bool: PrimSpec;
+  readonly null: PrimSpec;
+  readonly void: PrimSpec;
+  readonly duration: PrimSpec;
+  readonly size: PrimSpec;
+  readonly percent: PrimSpec;
+  readonly instant: PrimSpec;
+  readonly dynamic: DynamicSpec;
+  literal(value: string | number | boolean): LiteralSpec;
+  list(element: TypeSpec): ListSpec;
+  map(value: TypeSpec): MapSpec;
+  record(fields: Readonly<Record<string, TypeSpec>>, options?: RecordOptions): RecordSpec;
+  fn(params: readonly TypeSpec[], result: TypeSpec): FnSpec;
+  /** A function passed as an argument, which may take fewer params than it is handed. */
+  callback(params: readonly TypeSpec[], result: TypeSpec, takes: number): FnSpec;
+  union(...members: readonly TypeSpec[]): UnionSpec;
+  /** A named handle. `members` is what it publishes; without them, a bare name. */
+  opaque(name: string, members?: Readonly<Record<string, TypeSpec>>): OpaqueSpec;
+  ref(name: string): RefSpec;
+}
+
+function prim(name: PrimSpec["name"]): PrimSpec {
+  return { kind: "prim", name };
+}
+
+/**
+ * Write a type by hand, for what has no `.d.ts` worth reading.
+ *
+ * Everything here is data, the same data a generator emits, so an action typed
+ * by hand today and typed from its TypeScript tomorrow are the same to every
+ * reader downstream.
+ */
+export const t: TypeBuilder = {
+  string: prim("string"),
+  number: prim("number"),
+  bool: prim("bool"),
+  null: prim("null"),
+  void: prim("void"),
+  duration: prim("duration"),
+  size: prim("size"),
+  percent: prim("percent"),
+  instant: prim("instant"),
+  dynamic: { kind: "dynamic" },
+  literal: (value) => ({ kind: "literal", value }),
+  list: (element) => ({ kind: "list", element }),
+  map: (value) => ({ kind: "map", value }),
+  record: (fields, options) => ({ kind: "record", fields, ...options }),
+  fn: (params, result) => ({ kind: "fn", params, result }),
+  callback: (params, result, takes) => ({ kind: "fn", params, result, takes }),
+  union: (...members) => ({ kind: "union", members }),
+  opaque: (name, members) =>
+    members ? { kind: "opaque", name, members } : { kind: "opaque", name },
+  ref: (name) => ({ kind: "ref", name }),
+};

package/src/spec/index.ts

@@ -0,0 +1,17 @@
+export { type RecordOptions, type TypeBuilder, t } from "./build.js";
+export { showSpec } from "./show.js";
+export type {
+  DynamicSpec,
+  FnSpec,
+  ListSpec,
+  LiteralSpec,
+  MapSpec,
+  OpaqueSpec,
+  PrimName,
+  PrimSpec,
+  RecordSpec,
+  RefSpec,
+  TypeManifest,
+  TypeSpec,
+  UnionSpec,
+} from "./type-spec.types.js";

package/src/spec/show.ts

@@ -0,0 +1,56 @@
+import type { FnSpec, RecordSpec, TypeSpec } from "./type-spec.types.js";
+
+/**
+ * A published type as one line of text.
+ *
+ * Reads the wire format directly rather than going through the checker. Nothing
+ * has to be resolved, so a `ref` shows as the name a plugin published
+ * (`http.Server`, not the record behind it), and a package with no compiler in
+ * it can still say what it takes.
+ *
+ * @param spec the type to render
+ * @returns one line; a record past four fields is elided rather than wrapped
+ */
+export function showSpec(spec: TypeSpec): string {
+  switch (spec.kind) {
+    case "prim":
+      return spec.name;
+    case "literal":
+      return typeof spec.value === "string" ? `"${spec.value}"` : String(spec.value);
+    case "list":
+      return `list<${showSpec(spec.element)}>`;
+    case "map":
+      return `map<${showSpec(spec.value)}>`;
+    case "record":
+      return showRecord(spec);
+    case "fn":
+      return showFn(spec);
+    case "union":
+      return spec.members.map(showSpec).join(" | ");
+    case "opaque":
+    case "ref":
+      return spec.name;
+    default:
+      return "dynamic";
+  }
+}
+
+function showFn(spec: FnSpec): string {
+  return `fn(${spec.params.map(showSpec).join(", ")}) -> ${showSpec(spec.result)}`;
+}
+
+/** Past a few fields a shape stops informing and starts filling the line. */
+const SHOWN_FIELDS = 4;
+
+function showRecord(spec: RecordSpec): string {
+  const names = Object.keys(spec.fields);
+  if (names.length === 0) return "{}";
+  const shown = names.slice(0, SHOWN_FIELDS).map((name) => field(spec, name));
+  const rest = names.length > shown.length ? `, …${names.length - shown.length} more` : "";
+  return `{ ${shown.join(", ")}${rest} }`;
+}
+
+function field(spec: RecordSpec, name: string): string {
+  const type = spec.fields[name];
+  return `${name}: ${type ? showSpec(type) : "dynamic"}`;
+}

package/src/spec/type-spec.types.ts

@@ -0,0 +1,130 @@
+/**
+ * The wire format of a Venn type.
+ *
+ * Plain data: no functions, no `Map`s, no inference variables, so a `TypeSpec`
+ * survives `JSON.stringify`. That is what lets a plugin hand-write one and a
+ * generator emit the very same bytes from a `.d.ts`. The compiler's own `Type`,
+ * with its unification variables, is a separate internal thing; nothing mutable
+ * ever lands here.
+ *
+ * Deliberately smaller than TypeScript's type system. Everything TS can say
+ * projects onto these ten shapes or degrades to {@link DynamicSpec}, never to a
+ * failure. Generics, conditional and mapped types are resolved by the TypeScript
+ * compiler at generation time, so what arrives here is the answer, not the
+ * machinery.
+ */
+export type TypeSpec =
+  | PrimSpec
+  | LiteralSpec
+  | ListSpec
+  | MapSpec
+  | RecordSpec
+  | FnSpec
+  | UnionSpec
+  | OpaqueSpec
+  | RefSpec
+  | DynamicSpec;
+
+/** The scalars, including the units the language treats as first class. */
+export type PrimName =
+  | "string"
+  | "number"
+  | "bool"
+  | "null"
+  | "void"
+  | "duration"
+  | "size"
+  | "percent"
+  | "instant";
+
+/** One of the scalars named by {@link PrimName}. */
+export interface PrimSpec {
+  readonly kind: "prim";
+  readonly name: PrimName;
+}
+
+/** A single value: `"GET"`, `200`, `true`. What makes an enum an enum. */
+export interface LiteralSpec {
+  readonly kind: "literal";
+  readonly value: string | number | boolean;
+}
+
+/** Any number of values of one type. The language has no fixed-length list. */
+export interface ListSpec {
+  readonly kind: "list";
+  readonly element: TypeSpec;
+}
+
+/** Keys not known ahead of time, values all alike: TS's `Record<string, T>`. */
+export interface MapSpec {
+  readonly kind: "map";
+  readonly value: TypeSpec;
+}
+
+/** Known fields. `open` tolerates extra ones; `optional` lists what may be absent. */
+export interface RecordSpec {
+  readonly kind: "record";
+  readonly fields: Readonly<Record<string, TypeSpec>>;
+  readonly optional?: readonly string[];
+  readonly open?: boolean;
+}
+
+/** A callable: what it is given, in order, and what it gives back. */
+export interface FnSpec {
+  readonly kind: "fn";
+  readonly params: readonly TypeSpec[];
+  readonly result: TypeSpec;
+  /**
+   * How many parameters the caller must actually take. A callback handed more
+   * than it needs is still a good callback, as with `req => …` against a handler
+   * that is also offered the server.
+   */
+  readonly takes?: number;
+}
+
+/** A value that is any one of the members. */
+export interface UnionSpec {
+  readonly kind: "union";
+  readonly members: readonly TypeSpec[];
+}
+
+/**
+ * A handle with a name and no visible inside: a socket, a browser, an
+ * `express.Application`.
+ *
+ * This is the border. Projecting a JS class as a record would drag its whole
+ * object graph (`EventEmitter`, symbols, a hundred inherited members) into a
+ * language that means none of it. An opaque type can be held and handed to the
+ * verbs of its namespace, and nothing else.
+ */
+export interface OpaqueSpec {
+  readonly kind: "opaque";
+  /**
+   * What a program may do with it, such as `{ port, close }` on a server.
+   *
+   * Opaque is about the *inside* being none of the reader's business, not about
+   * having nothing to offer. With none of these the handle is a name and no
+   * more, which is right for something only its own verbs ever touch.
+   */
+  readonly members?: Readonly<Record<string, TypeSpec>>;
+  readonly name: string;
+}
+
+/** A named type resolved through the catalog: `http.Request`, `User`. */
+export interface RefSpec {
+  readonly kind: "ref";
+  readonly name: string;
+}
+
+/** Unknown, and deliberately so. Unifies with everything, never errors. */
+export interface DynamicSpec {
+  readonly kind: "dynamic";
+}
+
+/** What a plugin publishes: its named types, and one signature per action. */
+export interface TypeManifest {
+  /** Fully qualified: `http.Request`. */
+  readonly types?: Readonly<Record<string, TypeSpec>>;
+  /** Keyed by action name within the namespace: `serve`, `on`. */
+  readonly actions?: Readonly<Record<string, FnSpec>>;
+}