@oatscenter/trellis 0.100.0-rc.1

package/generated_support.js

@@ -0,0 +1,359 @@
+function fail(expected) {
+    throw new TypeError(`Expected ${expected}`);
+}
+function codec(decode, encode = decode) {
+    return Object.freeze({ decode, encode });
+}
+function integer(name, minimum, maximum) {
+    return codec((value) => typeof value === "number" && Number.isInteger(value) && value >= minimum &&
+        value <= maximum && !Object.is(value, -0)
+        ? value
+        : fail(`${name} integer`));
+}
+function bigintCodec(name, minimum, maximum) {
+    const pattern = /^(?:0|-?[1-9][0-9]*)$/;
+    return codec((value) => {
+        if (typeof value !== "string" || !pattern.test(value)) {
+            return fail(`${name} decimal string`);
+        }
+        const decoded = BigInt(value);
+        return decoded >= minimum && decoded <= maximum
+            ? decoded
+            : fail(`${name} decimal string`);
+    }, (value) => typeof value === "bigint" && value >= minimum && value <= maximum
+        ? value.toString()
+        : fail(`${name} bigint`));
+}
+const stringCodec = codec((value) => typeof value === "string" ? value : fail("string"));
+const boolCodec = codec((value) => typeof value === "boolean" ? value : fail("boolean"));
+const numberCodec = codec((value) => typeof value === "number" && Number.isFinite(value)
+    ? value
+    : fail("finite number"));
+function decodeBase64(value) {
+    if (typeof value !== "string" || value.length % 4 !== 0 ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+        return fail("padded standard base64 string");
+    }
+    const binary = atob(value);
+    const decoded = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return encodeBase64(decoded) === value
+        ? decoded
+        : fail("padded standard base64 string");
+}
+function encodeBase64(value) {
+    if (!(value instanceof Uint8Array))
+        return fail("Uint8Array");
+    let binary = "";
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function timestamp(value) {
+    if (typeof value !== "string")
+        return fail("RFC 3339 timestamp");
+    const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/i
+        .exec(value);
+    if (!match)
+        return fail("RFC 3339 timestamp");
+    const [, seconds, fraction, offset] = match;
+    if (seconds.slice(-2) === "60") {
+        return fail("RFC 3339 timestamp without leap second");
+    }
+    const localSeconds = seconds.replace("t", "T");
+    const local = new Date(`${localSeconds}Z`);
+    if (Number.isNaN(local.getTime()) ||
+        local.toISOString().slice(0, 19) !== localSeconds) {
+        return fail("RFC 3339 timestamp");
+    }
+    if (offset.toUpperCase() !== "Z" &&
+        (+offset.slice(1, 3) > 23 || +offset.slice(4) > 59)) {
+        return fail("RFC 3339 timestamp");
+    }
+    const utc = new Date(`${localSeconds}${offset.toUpperCase()}`);
+    if (Number.isNaN(utc.getTime()))
+        return fail("RFC 3339 timestamp");
+    const canonical = utc.toISOString().slice(0, 19);
+    if (canonical[0] === "+" || canonical[0] === "-") {
+        return fail("RFC 3339 timestamp");
+    }
+    const digits = fraction?.replace(/0+$/, "");
+    return `${canonical}${digits ? `.${digits}` : ""}Z`;
+}
+const ulidPattern = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+/** Browser-safe codec vocabulary consumed by generated TypeScript packages. */
+export const codecs = Object.freeze({
+    string: stringCodec,
+    bool: boolCodec,
+    i32: integer("i32", -0x8000_0000, 0x7fff_ffff),
+    u32: integer("u32", 0, 0xffff_ffff),
+    i64: bigintCodec("i64", -(1n << 63n), (1n << 63n) - 1n),
+    u64: bigintCodec("u64", 0n, (1n << 64n) - 1n),
+    f64: numberCodec,
+    bytes: codec(decodeBase64, encodeBase64),
+    timestamp: codec(timestamp),
+    ulid: codec((value) => typeof value === "string" && ulidPattern.test(value)
+        ? value
+        : fail("canonical ULID")),
+    openEnum(values) {
+        if (values.some((value) => typeof value !== "string")) {
+            fail("generated string enum values");
+        }
+        return codec((value) => {
+            if (typeof value !== "string")
+                return fail("string enum value");
+            return value;
+        });
+    },
+    model(fields) {
+        return codec((value) => {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                return fail("object");
+            }
+            const source = value;
+            const decoded = {};
+            for (const [name, field] of Object.entries(fields)) {
+                if (source[name] === undefined && "optional" in field)
+                    continue;
+                decoded[name] = field.decode(source[name]);
+            }
+            return decoded;
+        }, (value) => {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                return fail("object");
+            }
+            const encoded = {};
+            for (const [name, field] of Object.entries(fields)) {
+                const fieldValue = value[name];
+                if (fieldValue === undefined && "optional" in field)
+                    continue;
+                encoded[name] = field.encode(fieldValue);
+            }
+            return encoded;
+        });
+    },
+    named(_name, value) {
+        return codec((input) => value.decode(input), (input) => value.encode(input));
+    },
+    list(item) {
+        return codec((value) => Array.isArray(value) ? value.map(item.decode) : fail("array"), (value) => Array.isArray(value) ? value.map(item.encode) : fail("array"));
+    },
+    map(item) {
+        return codec((value) => {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                return fail("object map");
+            }
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, item.decode(entry)]));
+        }, (value) => Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, item.encode(entry)])));
+    },
+    nullable(value) {
+        return codec((input) => input === null ? null : value.decode(input), (input) => input === null ? null : value.encode(input));
+    },
+    optional(value) {
+        return Object.freeze({
+            optional: true,
+            decode: (input) => input === undefined ? undefined : value.decode(input),
+            encode: (input) => input === undefined ? undefined : value.encode(input),
+        });
+    },
+    ref(get) {
+        return codec((value) => get().decode(value), (value) => get().encode(value));
+    },
+    recursive(build) {
+        let resolved;
+        const get = () => {
+            resolved ??= build(self);
+            return resolved;
+        };
+        const self = codec((value) => get().decode(value), (value) => get().encode(value));
+        return self;
+    },
+});
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isCodec(value) {
+    return isRecord(value) && typeof value.decode === "function" &&
+        typeof value.encode === "function";
+}
+function validateAction(name, action) {
+    if (!["rpc", "operation", "event", "feed"].includes(String(action.kind)) ||
+        action.descriptorName !== name || !name.startsWith(`${action.kind}:`) ||
+        name.length === String(action.kind).length + 1) {
+        fail("generated action descriptor");
+    }
+    switch (action.kind) {
+        case "rpc":
+            if (!isCodec(action.input) || !isCodec(action.output) ||
+                !Array.isArray(action.errors) ||
+                typeof action.download !== "boolean" ||
+                (action.pagination !== undefined && action.pagination !== "cursor"))
+                fail("generated RPC descriptor");
+            break;
+        case "operation":
+            if (!isCodec(action.input) || !isCodec(action.output) ||
+                (action.progress !== undefined && !isCodec(action.progress)) ||
+                !Array.isArray(action.errors) ||
+                !isRecord(action.signals) ||
+                Object.values(action.signals).some((value) => !isCodec(value)) ||
+                typeof action.upload !== "boolean")
+                fail("generated operation descriptor");
+            break;
+        case "event":
+            if (!isCodec(action.payload) || !Array.isArray(action.parameters) ||
+                action.parameters.some((path) => !Array.isArray(path) || path.some((part) => typeof part !== "string")))
+                fail("generated event descriptor");
+            break;
+        case "feed":
+            if (!isCodec(action.input) || !isCodec(action.event)) {
+                fail("generated feed descriptor");
+            }
+            break;
+    }
+}
+function validateApiDescriptor(descriptor) {
+    if (!descriptor || typeof descriptor !== "object" ||
+        typeof descriptor.identity !== "string" ||
+        descriptor.identity.length === 0 || !isRecord(descriptor.actions)) {
+        fail("API descriptor");
+    }
+    for (const [name, action] of Object.entries(descriptor.actions)) {
+        validateAction(name, action);
+    }
+}
+/** Validate and retain generated API evidence without deriving authority from it. */
+export function apiDescriptor(descriptor) {
+    validateApiDescriptor(descriptor);
+    for (const action of Object.values(descriptor.actions))
+        Object.freeze(action);
+    Object.freeze(descriptor.actions);
+    return Object.freeze(descriptor);
+}
+function validateResource(resource) {
+    if (!["state", "kv", "store", "job", "consumer"].includes(String(resource.kind)) ||
+        !["required", "optional"].includes(String(resource.availability)))
+        fail("generated resource descriptor");
+    if (resource.kind === "state" || resource.kind === "kv") {
+        if (!isCodec(resource.codec) || typeof resource.version !== "number" ||
+            !Number.isInteger(resource.version) || resource.version <= 0 ||
+            !isRecord(resource.migrations))
+            fail("generated representation descriptor");
+        const currentVersion = resource.version;
+        if (Object.entries(resource.migrations).some(([version, value]) => !/^[1-9][0-9]*$/.test(version) || Number(version) >= currentVersion ||
+            !isCodec(value)))
+            fail("generated representation descriptor");
+    }
+    else if (resource.kind === "job" &&
+        (!isCodec(resource.payload) ||
+            (resource.result !== undefined && !isCodec(resource.result)) ||
+            (resource.update !== undefined && !isCodec(resource.update)))) {
+        fail("generated job descriptor");
+    }
+    if (resource.kind === "job") {
+        if (resource.deadlineMs !== undefined &&
+            (!Number.isInteger(resource.deadlineMs) ||
+                Number(resource.deadlineMs) <= 0))
+            fail("generated job descriptor");
+        if (resource.retry !== undefined) {
+            if (!isRecord(resource.retry) ||
+                !Number.isInteger(resource.retry.attempts) ||
+                Number(resource.retry.attempts) <= 0 ||
+                !Array.isArray(resource.retry.backoffMs) ||
+                resource.retry.backoffMs.length !==
+                    Number(resource.retry.attempts) - 1 ||
+                resource.retry.backoffMs.some((value) => !Number.isInteger(value) || Number(value) <= 0))
+                fail("generated job descriptor");
+        }
+    }
+}
+function validatePackageEvidence(evidence) {
+    if (!isRecord(evidence) || typeof evidence.rootPackage !== "string" ||
+        evidence.rootPackage.length === 0 ||
+        typeof evidence.rootDigest !== "string" ||
+        evidence.rootDigest.length === 0 || !Array.isArray(evidence.packages))
+        fail("package evidence");
+    let previous = "";
+    let rootFound = false;
+    for (const entry of evidence.packages) {
+        if (!isRecord(entry) || typeof entry.name !== "string" ||
+            entry.name.length === 0 || entry.name <= previous ||
+            typeof entry.version !== "string" || entry.version.length === 0 ||
+            typeof entry.digest !== "string" || entry.digest.length === 0 ||
+            typeof entry.source !== "string" || entry.source.length === 0)
+            fail("sorted package evidence");
+        previous = entry.name;
+        if (entry.name === evidence.rootPackage) {
+            if (entry.digest !== evidence.rootDigest) {
+                fail("matching root package evidence");
+            }
+            rootFound = true;
+        }
+    }
+    if (!rootFound)
+        fail("root package evidence");
+}
+/** Validate and retain generated participant evidence without resolving grants or authority. */
+export function participantDescriptor(descriptor) {
+    if (!descriptor || typeof descriptor !== "object" ||
+        !["service", "device", "app", "agent"].includes(descriptor.kind) ||
+        descriptor.id !== descriptor.identity ||
+        typeof descriptor.identity !== "string" ||
+        descriptor.identity.length === 0 ||
+        typeof descriptor.path !== "string" || descriptor.path.length === 0 ||
+        !isRecord(descriptor.packageEvidence) ||
+        typeof descriptor.packageEvidence.rootPackage !== "string" ||
+        descriptor.identity !==
+            `${descriptor.packageEvidence.rootPackage}.${descriptor.path}` ||
+        !Array.isArray(descriptor.implements) || !Array.isArray(descriptor.uses) ||
+        !isRecord(descriptor.actionNames) ||
+        !isRecord(descriptor.resources)) {
+        fail("participant descriptor");
+    }
+    for (const api of descriptor.implements)
+        validateApiDescriptor(api);
+    for (const selection of descriptor.uses) {
+        if (!isRecord(selection) || !isRecord(selection.api) ||
+            !Array.isArray(selection.actions) ||
+            !Array.isArray(selection.optionalCapabilities))
+            fail("generated action selection");
+        const api = selection.api;
+        validateApiDescriptor(api);
+        for (const selected of selection.actions) {
+            if (!isRecord(selected) || typeof selected.descriptorName !== "string" ||
+                !(selected.descriptorName in api.actions))
+                fail("generated action selection");
+            const kind = api.actions[selected.descriptorName].kind;
+            if ((kind === "rpc" && selected.direction !== "call") ||
+                (kind === "operation" && selected.direction !== "invoke") ||
+                (kind === "event" && selected.direction !== "publish" &&
+                    selected.direction !== "subscribe") ||
+                (kind === "feed" && selected.direction !== "subscribe"))
+                fail("generated action direction");
+        }
+        if (selection.optionalCapabilities.some((value) => typeof value !== "string")) {
+            fail("generated action selection");
+        }
+    }
+    for (const resource of Object.values(descriptor.resources)) {
+        validateResource(resource);
+        Object.freeze(resource);
+    }
+    if (descriptor.companion) {
+        if (descriptor.kind !== "device" ||
+            !isRecord(descriptor.companion.participant) ||
+            !["required", "optional"].includes(descriptor.companion.availability) ||
+            !["app", "agent"].includes(descriptor.companion.participant.kind) ||
+            descriptor.companion.participant.identity.split(".").slice(0, -1).join(".") !== descriptor.identity ||
+            descriptor.companion.participant.companion !== undefined) {
+            fail("companion descriptor");
+        }
+        participantDescriptor(descriptor.companion.participant);
+        Object.freeze(descriptor.companion);
+    }
+    validatePackageEvidence(descriptor.packageEvidence);
+    Object.freeze(descriptor.implements);
+    Object.freeze(descriptor.uses);
+    Object.freeze(descriptor.resources);
+    Object.freeze(descriptor.packageEvidence.packages);
+    Object.freeze(descriptor.packageEvidence);
+    return Object.freeze(descriptor);
+}

package/globals.d.ts

@@ -0,0 +1,9 @@
+export type LoggerLike = {
+    child(bindings: Record<string, unknown>): LoggerLike;
+    trace(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};
+export declare const logger: LoggerLike;

package/globals.js

@@ -0,0 +1,16 @@
+function createNoopLogger() {
+    const noop = () => { };
+    const logger = {
+        child: () => logger,
+        trace: noop,
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: noop,
+    };
+    return logger;
+}
+// Keep the root package browser-safe: importing `@oatscenter/trellis` must not
+// pull in `pino` or Node-only side effects. Server-only entrypoints can inject
+// a real logger, while the shared runtime defaults to a no-op logger here.
+export const logger = createNoopLogger();

package/health_transport.d.ts

@@ -0,0 +1,18 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { type HealthHeartbeatSample } from "./internal_sdk/generated/types/_internal/p0.js";
+export type HealthHeartbeatSubjectIdentity = {
+    sessionKey: string;
+    participantKind: "service" | "device";
+    contractId: string;
+    contractDigest: string;
+    deploymentId: string;
+    instanceId: string;
+};
+/** Builds the exact runtime subject authorized for one heartbeat publisher. */
+export declare function healthHeartbeatSubject(identity: HealthHeartbeatSubjectIdentity): string;
+/** Publishes one validated-size heartbeat sample to its dedicated stream. */
+export declare function publishHealthHeartbeatSample(args: {
+    nc: NatsConnection;
+    identity: HealthHeartbeatSubjectIdentity;
+    sample: HealthHeartbeatSample;
+}): Promise<void>;

package/health_transport.js

@@ -0,0 +1,32 @@
+import { jetstream } from "@nats-io/jetstream";
+import { base64urlEncode } from "./auth/utils.js";
+import { HealthHeartbeatSampleCodec, } from "./internal_sdk/generated/types/_internal/p0.js";
+const HEALTH_HEARTBEAT_SUBJECT_PREFIX = "health.v1.heartbeat";
+function subjectToken(value) {
+    if (value.length === 0)
+        throw new Error("health subject identity is empty");
+    return base64urlEncode(new TextEncoder().encode(value));
+}
+/** Builds the exact runtime subject authorized for one heartbeat publisher. */
+export function healthHeartbeatSubject(identity) {
+    if (!/^[A-Za-z0-9_-]+$/.test(identity.sessionKey)) {
+        throw new Error("health session key is not canonical base64url");
+    }
+    return [
+        HEALTH_HEARTBEAT_SUBJECT_PREFIX,
+        identity.participantKind,
+        subjectToken(identity.contractId),
+        subjectToken(identity.contractDigest),
+        subjectToken(identity.deploymentId),
+        subjectToken(identity.instanceId),
+        identity.sessionKey,
+    ].join(".");
+}
+/** Publishes one validated-size heartbeat sample to its dedicated stream. */
+export async function publishHealthHeartbeatSample(args) {
+    const payload = new TextEncoder().encode(JSON.stringify(HealthHeartbeatSampleCodec.encode(args.sample)));
+    if (payload.byteLength > 65_536) {
+        throw new Error("health heartbeat sample exceeds 64 KiB");
+    }
+    await jetstream(args.nc).publish(healthHeartbeatSubject(args.identity), payload, { msgID: args.sample.sample.id });
+}

package/helpers.d.ts

@@ -0,0 +1,11 @@
+/** Encodes one canonical event parameter value as a NATS subject token. */
+export declare function encodeEventSubjectParameterToken(value: string): string;
+/**
+ * Compute the subject template from the message itself
+ */
+export declare function template(template: string, data: Record<string, string | number>, opts?: {
+    allowWildcards: boolean;
+}): string;
+export declare function escapeNats(token: string): string;
+export declare function escapeKvKey(key: string): string;
+export declare function decodeSubject(token: string): string;

package/helpers.js

@@ -0,0 +1,53 @@
+import { Pointer } from "typebox/value";
+import { base64urlEncode, utf8 } from "./auth/utils.js";
+/** Encodes one canonical event parameter value as a NATS subject token. */
+export function encodeEventSubjectParameterToken(value) {
+    return base64urlEncode(utf8(value));
+}
+/**
+ * Compute the subject template from the message itself
+ */
+export function template(template, data, opts = { allowWildcards: false }) {
+    return template.replace(/\{([^}]+)\}/g, (_, key) => {
+        const token = Pointer.Get(data, key);
+        if (token === undefined || token === null) {
+            if (!opts.allowWildcards) {
+                throw new Error("All option templates must have values at runtime.");
+            }
+            return "*";
+        }
+        if (typeof token !== "string" && typeof token !== "number") {
+            throw new Error("Subject template values must be strings or numbers.");
+        }
+        if (typeof token === "number" &&
+            (!Number.isFinite(token) ||
+                (Number.isInteger(token) && !Number.isSafeInteger(token)))) {
+            throw new Error("Subject template numbers must be finite and safe integers.");
+        }
+        return encodeEventSubjectParameterToken(`${Object.is(token, -0) ? 0 : token}`);
+    });
+}
+const NATS_SUBJECT_TOKEN_FORBIDDEN = /[\u0000\s.*>~]/gu;
+export function escapeNats(token) {
+    const out = token.replace(NATS_SUBJECT_TOKEN_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    // Protect start with $ due to NATS internal use of it
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}
+const NATS_KV_KEY_FORBIDDEN = /[\u0000\s*>~]/gu;
+export function escapeKvKey(key) {
+    const out = key.replace(NATS_KV_KEY_FORBIDDEN, (ch) => `~${ch.codePointAt(0).toString(16).toUpperCase()}~`);
+    if (out.length === 0 || out.startsWith("$")) {
+        return `_${out}`;
+    }
+    return out;
+}
+export function decodeSubject(token) {
+    const out = token.replace(/~([0-9A-F]{1,6})~/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)));
+    if (out.startsWith("_$")) {
+        return out.slice(1);
+    }
+    return out;
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+/** Portable Trellis application API. */
+export * from "./portable.ts";

package/index.js

@@ -0,0 +1,2 @@
+/** Portable Trellis application API. */
+export * from "./portable.js";