A local-first multi-agent app development platform, built on PenguinHarness
/**
* Interfaces as data, at SIGNATURE level.
*
* Go's rule is the whole contract: a value satisfies an interface when every method the
* interface names exists on it with the same signature. Across a hot-push boundary the
* two sides are separate compilations, so a signature has to be something that can be
* serialized and compared — this module is that form, and {@link satisfies} is the
* comparison. The TS `interface` a module author writes is the source; a build step
* projects it into this shape (see scripts/gen-ifaces.mjs), so the two cannot drift.
*
* Data types are arktype definitions, compared with TS assignability rules (./data.ts);
* the non-data shapes (functions, promises,
* streams, live objects satisfying another interface, host objects compared by name)
* are the six other cases below.
*/
import type { Json } from "./json.js";
import type { TypeTable } from "./data.js";
import { acceptsUndefined, dataExtends } from "./data.js";
/** A type, as data. */
export type TypeExpr =
/** An arktype DEFINITION (string expression or object form): primitives, literals, unions, arrays, tuples, plain objects. */
| { data: Json }
/** A live object satisfying another interface — a key into the {@link IfaceTable}. */
| { iface: string }
/** A callback. */
| { fn: Sig }
| { promise: TypeExpr }
/** AsyncIterable<T>; an AsyncGenerator's return value rides in `returns`. */
| { stream: TypeExpr; returns?: TypeExpr }
| { void: true }
/** An array whose element is not data (promises, callbacks, live objects). */
| { array: TypeExpr }
/** A plain object shape with at least one non-data member, compared member by member. */
| { object: Record<string, TypeExpr>; optional?: readonly string[] }
/** `T | null | undefined` around a non-data T. */
| { maybe: TypeExpr }
/** A union with more than one non-data member (a provider, or a promise of one). */
| { oneOf: readonly TypeExpr[] }
/**
* A host object compared by NAME only (AbortSignal, Request…): platform types the
* generator meets in a .d.ts, or a package's own class written as `Opaque<"Name">`.
*/
| { opaque: string };
/** A method signature: positional parameters and a return type. */
export interface Sig {
params: readonly TypeExpr[];
returns: TypeExpr;
}
/**
* A contribution slot: the data shape one contribution carries (an arktype expression,
* `id` excluded — the framework adds it) and, when the slot needs an implementation
* bound by id, the shape of that implementation.
*/
export interface SlotDecl {
data: Json;
code?: TypeExpr;
}
/**
* One interface. `name` is for messages and lookup; identity is the member set. `fields`
* are the non-method members (Go has none; TS interfaces do, and a published config
* object is nothing but fields) — compared by presence and type, never by value.
*/
export interface IfaceDecl {
name: string;
methods: Record<string, Sig>;
fields?: Record<string, TypeExpr>;
slots: Record<string, SlotDecl>;
}
/**
* Every interface a bundle knows, keyed `<module>#<Export>`, plus the named data types its
* signatures reference by `$ref` (keyed the same way). Self-contained: a reference into it
* never leaves the bundle. A bare interface map is accepted everywhere a table is.
*/
export interface IfaceTable {
ifaces: Record<string, IfaceDecl>;
types: TypeTable;
}
/** The table as functions take it: the full form, or just the interface map. */
export type TableLike = IfaceTable | Record<string, IfaceDecl>;
export function tableOf(t: TableLike | undefined): IfaceTable {
if (t === undefined) return { ifaces: {}, types: {} };
if ("ifaces" in t && "types" in t && typeof t.ifaces === "object" && !("methods" in t.ifaces)) {
return t as IfaceTable;
}
return { ifaces: t as Record<string, IfaceDecl>, types: {} };
}
export interface Mismatch {
/** The method or field. */
method: string;
kind: "missing" | "signature" | "field";
why: string;
}
/** offered satisfies required ⇔ every required method exists on offered with an assignable signature. */
export function satisfies(
offered: IfaceDecl,
required: IfaceDecl,
table: TableLike = {},
seen: Set<string> = new Set(),
): Mismatch[] {
const out: Mismatch[] = [];
for (const [method, want] of Object.entries(required.methods)) {
const have = offered.methods[method];
if (have === undefined) {
out.push({ method, kind: "missing", why: `'${offered.name}' has no method '${method}'` });
continue;
}
for (const why of assignable(have, want, table, seen)) {
out.push({ method, kind: "signature", why });
}
}
for (const [field, want] of Object.entries(required.fields ?? {})) {
const have = offered.fields?.[field];
if (have === undefined) {
if ("maybe" in want) continue; // an optional field the offer does not declare at all
out.push({
method: field,
kind: "missing",
why: `'${offered.name}' has no field '${field}'`,
});
continue;
}
if (!extendsExpr(have, want, table, seen)) {
out.push({
method: field,
kind: "field",
why: `field is ${show(have)}, caller expects ${show(want)}`,
});
}
}
return out;
}
/**
* Function subtyping: `have` can stand in for `want` when it takes no more parameters
* than a caller of `want` passes, each of its parameters accepts what the caller passes
* (contravariant), and what it returns is what the caller expects (covariant).
*/
export function assignable(
have: Sig,
want: Sig,
table: TableLike = {},
seen: Set<string> = new Set(),
): string[] {
const why: string[] = [];
if (have.params.length > want.params.length) {
// Extra parameters are fine only when optional — encoded as `T | undefined`.
for (let i = want.params.length; i < have.params.length; i += 1) {
const p = have.params[i]!;
if (!("maybe" in p) && (!("data" in p) || !acceptsUndefined(p.data, tableOf(table).types))) {
why.push(`takes ${have.params.length} params, caller passes ${want.params.length}`);
break;
}
}
}
have.params.forEach((p, i) => {
const passed = want.params[i];
if (passed === undefined) return;
if (!extendsExpr(passed, p, table, seen)) {
why.push(`param ${i}: caller passes ${show(passed)}, impl wants ${show(p)}`);
}
});
if (!extendsExpr(have.returns, want.returns, table, seen)) {
why.push(`returns ${show(have.returns)}, caller expects ${show(want.returns)}`);
}
return why;
}
/** a ⊆ b over the seven shapes; data goes to arktype, interfaces recurse through the table. */
export function extendsExpr(
a: TypeExpr,
b: TypeExpr,
table: TableLike = {},
seen: Set<string> = new Set(),
): boolean {
if ("void" in b) return true;
if ("data" in a && "data" in b) return dataExtends(a.data, b.data, tableOf(table).types);
if ("opaque" in a && "opaque" in b) return a.opaque === b.opaque;
if ("iface" in a && "iface" in b) {
if (a.iface === b.iface) return true;
const key = `${a.iface}<:${b.iface}`;
if (seen.has(key)) return true; // Coinductive: assume the pair while checking it.
const offered = tableOf(table).ifaces[a.iface];
const required = tableOf(table).ifaces[b.iface];
if (offered === undefined || required === undefined) return false;
// The assumption lives only inside this comparison (a copy, as data.ts does): a pair
// that turns out not to hold must not be taken as holding by a later branch — another
// union member, another parameter — that meets it again.
return satisfies(offered, required, table, new Set(seen).add(key)).length === 0;
}
if ("maybe" in b) return extendsExpr("maybe" in a ? a.maybe : a, b.maybe, table, seen);
if ("maybe" in a) return false;
if ("oneOf" in a) return a.oneOf.every((m) => extendsExpr(m, b, table, seen));
if ("oneOf" in b) return b.oneOf.some((m) => extendsExpr(a, m, table, seen));
if ("array" in a && "array" in b) return extendsExpr(a.array, b.array, table, seen);
if ("object" in a && "object" in b) {
for (const [key, want] of Object.entries(b.object)) {
const have = a.object[key];
const optionalInB = b.optional?.includes(key) ?? false;
if (have === undefined) {
if (optionalInB) continue;
return false;
}
if ((a.optional?.includes(key) ?? false) && !optionalInB) return false;
if (!extendsExpr(have, want, table, seen)) return false;
}
return true;
}
if ("fn" in a && "fn" in b) return assignable(a.fn, b.fn, table, seen).length === 0;
if ("promise" in a && "promise" in b) return extendsExpr(a.promise, b.promise, table, seen);
if ("stream" in a && "stream" in b) {
if (!extendsExpr(a.stream, b.stream, table, seen)) return false;
if (b.returns === undefined) return true;
return a.returns !== undefined && extendsExpr(a.returns, b.returns, table, seen);
}
return false;
}
/** A short rendering for messages. */
export function show(expr: TypeExpr): string {
if ("data" in expr) return typeof expr.data === "string" ? expr.data : JSON.stringify(expr.data);
if ("iface" in expr) return expr.iface;
if ("opaque" in expr) return `opaque<${expr.opaque}>`;
if ("void" in expr) return "void";
if ("promise" in expr) return `Promise<${show(expr.promise)}>`;
if ("array" in expr) return `${show(expr.array)}[]`;
if ("object" in expr)
return `{ ${Object.entries(expr.object)
.map(([k, v]) => `${k}${expr.optional?.includes(k) ? "?" : ""}: ${show(v)}`)
.join(", ")} }`;
if ("maybe" in expr) return `${show(expr.maybe)} | null`;
if ("oneOf" in expr) return expr.oneOf.map(show).join(" | ");
if ("stream" in expr) return `AsyncIterable<${show(expr.stream)}>`;
return `(${expr.fn.params.map(show).join(", ")}) => ${show(expr.fn.returns)}`;
}