@portalshq/contracts 0.0.2 → 0.0.3

package/dist/capabilities.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The capability contract. A way for a unit of platform functionality
+ * (chat, polls, lobby presence, a video player, a VR render target, a
+ * game-rules engine -- built or not-yet-built) to declare itself, and a
+ * way for a channel to compose the capabilities it needs.
+ *
+ * Design principle enforced here: a platform that silently no-ops an
+ * unbuilt or misconfigured capability is more dangerous than one that
+ * refuses to resolve. `CapabilityRegistry.resolve()` fails loud, with a
+ * specific error per problem, never a silent partial result. The same
+ * principle extends to tenancy below: a manifest cannot assert its own
+ * trust level -- that comes from a trusted lookup the caller provides,
+ * never from the (potentially untrusted) manifest itself.
+ */
+import type { TenantContext } from "./tenancy.js";
+export interface ValidationResult {
+    ok: boolean;
+    errors?: string[];
+}
+export interface RegistryCapabilityContext<TConfig = unknown> {
+    channelId: string;
+    tenant: TenantContext;
+    config: TConfig;
+}
+export interface CapabilityModule<TConfig = unknown> {
+    /** Globally unique, namespaced, e.g. "platform.chat", "platform.video.mux". */
+    id: string;
+    /** Semver. Used for compatibility checks once external developers ship modules. */
+    version: string;
+    displayName: string;
+    /** Other capability ids this one requires to function, resolved per-channel. */
+    dependsOn?: string[];
+    /**
+     * Validate a channel's config for this capability. Must not throw for
+     * ordinary invalid input -- return a ValidationResult so the registry can
+     * collect every problem in one pass instead of failing on the first.
+     */
+    validateConfig(config: unknown): ValidationResult;
+    /** Called once when a channel using this capability is first resolved. */
+    onChannelRegistered?(ctx: RegistryCapabilityContext<TConfig>): Promise<void>;
+    /** Called when the channel is torn down or the capability is removed. */
+    onChannelUnregistered?(ctx: RegistryCapabilityContext<TConfig>): Promise<void>;
+}
+export interface CapabilityUsage {
+    capabilityId: string;
+    config: unknown;
+}
+export interface ChannelManifestConfig {
+    channelId: string;
+    /** Declared owner. Verified against the trusted TenantContext passed into
+     *  `resolve()`, not taken on faith -- see the mismatch check below. */
+    tenantId: string;
+    displayName: string;
+    capabilities: CapabilityUsage[];
+}
+export interface ResolvedCapability {
+    module: CapabilityModule;
+    config: unknown;
+}
+export type ResolvedChannel = {
+    ok: true;
+    channelId: string;
+    tenant: TenantContext;
+    capabilities: ResolvedCapability[];
+} | {
+    ok: false;
+    channelId: string;
+    errors: string[];
+};
+export declare class CapabilityRegistry {
+    private modules;
+    register(module: CapabilityModule): void;
+    get(id: string): CapabilityModule | undefined;
+    has(id: string): boolean;
+    list(): CapabilityModule[];
+    /**
+     * Resolves a manifest against currently-registered modules, for a given
+     * (trustworthily-sourced) tenant. Collects EVERY problem in a single pass
+     * rather than stopping at the first, so a developer sees the whole
+     * picture at once. `tenant` must come from your own tenant lookup (e.g.
+     * the control plane's database), never from the manifest itself -- a
+     * manifest declaring its own trust level would let any tenant grant
+     * themselves unlimited quota.
+     */
+    resolve(manifest: ChannelManifestConfig, tenant: TenantContext): ResolvedChannel;
+    /** Runs onChannelRegistered for every resolved capability, in declaration order. */
+    activate(resolved: Extract<ResolvedChannel, {
+        ok: true;
+    }>): Promise<void>;
+    /** Runs onChannelUnregistered for every resolved capability, in reverse order. */
+    deactivate(resolved: Extract<ResolvedChannel, {
+        ok: true;
+    }>): Promise<void>;
+}

package/dist/capabilities.js

@@ -0,0 +1,102 @@
+/**
+ * The capability contract. A way for a unit of platform functionality
+ * (chat, polls, lobby presence, a video player, a VR render target, a
+ * game-rules engine -- built or not-yet-built) to declare itself, and a
+ * way for a channel to compose the capabilities it needs.
+ *
+ * Design principle enforced here: a platform that silently no-ops an
+ * unbuilt or misconfigured capability is more dangerous than one that
+ * refuses to resolve. `CapabilityRegistry.resolve()` fails loud, with a
+ * specific error per problem, never a silent partial result. The same
+ * principle extends to tenancy below: a manifest cannot assert its own
+ * trust level -- that comes from a trusted lookup the caller provides,
+ * never from the (potentially untrusted) manifest itself.
+ */
+// ── Registry ─────────────────────────────────────────────────────────────
+export class CapabilityRegistry {
+    modules = new Map();
+    register(module) {
+        if (this.modules.has(module.id)) {
+            throw new Error(`Capability "${module.id}" is already registered.`);
+        }
+        this.modules.set(module.id, module);
+    }
+    get(id) {
+        return this.modules.get(id);
+    }
+    has(id) {
+        return this.modules.has(id);
+    }
+    list() {
+        return [...this.modules.values()];
+    }
+    /**
+     * Resolves a manifest against currently-registered modules, for a given
+     * (trustworthily-sourced) tenant. Collects EVERY problem in a single pass
+     * rather than stopping at the first, so a developer sees the whole
+     * picture at once. `tenant` must come from your own tenant lookup (e.g.
+     * the control plane's database), never from the manifest itself -- a
+     * manifest declaring its own trust level would let any tenant grant
+     * themselves unlimited quota.
+     */
+    resolve(manifest, tenant) {
+        if (tenant.tenantId !== manifest.tenantId) {
+            return {
+                ok: false,
+                channelId: manifest.channelId,
+                errors: [
+                    `Tenant mismatch: manifest declares tenant "${manifest.tenantId}" but ` +
+                        `resolution was requested for tenant "${tenant.tenantId}".`,
+                ],
+            };
+        }
+        const errors = [];
+        const resolved = [];
+        const declaredIds = new Set(manifest.capabilities.map((u) => u.capabilityId));
+        for (const usage of manifest.capabilities) {
+            const module = this.modules.get(usage.capabilityId);
+            if (!module) {
+                errors.push(`Channel "${manifest.channelId}" declares capability "${usage.capabilityId}", ` +
+                    `which is not registered on this platform instance.`);
+                continue;
+            }
+            for (const dep of module.dependsOn ?? []) {
+                if (!declaredIds.has(dep)) {
+                    errors.push(`Capability "${module.id}" requires "${dep}", which channel ` +
+                        `"${manifest.channelId}" does not declare.`);
+                }
+            }
+            const validation = module.validateConfig(usage.config);
+            if (!validation.ok) {
+                const detail = validation.errors?.join("; ") ?? "invalid config";
+                errors.push(`Invalid config for capability "${module.id}": ${detail}`);
+                continue;
+            }
+            resolved.push({ module, config: usage.config });
+        }
+        if (errors.length > 0) {
+            return { ok: false, channelId: manifest.channelId, errors };
+        }
+        return { ok: true, channelId: manifest.channelId, tenant, capabilities: resolved };
+    }
+    /** Runs onChannelRegistered for every resolved capability, in declaration order. */
+    async activate(resolved) {
+        for (const { module, config } of resolved.capabilities) {
+            await module.onChannelRegistered?.({
+                channelId: resolved.channelId,
+                tenant: resolved.tenant,
+                config,
+            });
+        }
+    }
+    /** Runs onChannelUnregistered for every resolved capability, in reverse order. */
+    async deactivate(resolved) {
+        for (const { module, config } of [...resolved.capabilities].reverse()) {
+            await module.onChannelUnregistered?.({
+                channelId: resolved.channelId,
+                tenant: resolved.tenant,
+                config,
+            });
+        }
+    }
+}

package/dist/capability-contract.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * A Capability is the smallest unit of composition in the platform.
+ * Every capability — realtime-fanout, video-delivery, identity, the
+ * narrative-engine-adapter, everything — implements this same contract
+ * shape. The runtime never calls a capability directly; it always goes
+ * through the registry, which validates against this schema first.
+ *
+ * Modeled deliberately on Kubernetes CRD + controller semantics, not on
+ * a bare RPC interface: declare a resource shape, let the runtime
+ * reconcile it. See docs/architecture-decision-records for rationale.
+ */
+export declare const PermissionScopeSchema: z.ZodObject<{
+    resource: z.ZodString;
+    effect: z.ZodEnum<["allow", "deny"]>;
+}, "strip", z.ZodTypeAny, {
+    resource: string;
+    effect: "allow" | "deny";
+}, {
+    resource: string;
+    effect: "allow" | "deny";
+}>;
+export type PermissionScope = z.infer<typeof PermissionScopeSchema>;
+export declare const CapabilityContractSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    permissions: z.ZodArray<z.ZodObject<{
+        resource: z.ZodString;
+        effect: z.ZodEnum<["allow", "deny"]>;
+    }, "strip", z.ZodTypeAny, {
+        resource: string;
+        effect: "allow" | "deny";
+    }, {
+        resource: string;
+        effect: "allow" | "deny";
+    }>, "many">;
+    plane: z.ZodEnum<["control", "data"]>;
+    lazyStart: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    permissions: {
+        resource: string;
+        effect: "allow" | "deny";
+    }[];
+    plane: "control" | "data";
+    lazyStart: boolean;
+}, {
+    id: string;
+    version: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    permissions: {
+        resource: string;
+        effect: "allow" | "deny";
+    }[];
+    plane: "control" | "data";
+    lazyStart?: boolean | undefined;
+}>;
+export type CapabilityContract = z.infer<typeof CapabilityContractSchema>;
+/**
+ * Implemented by every capability package. The registry calls `invoke`
+ * after validating `input` against the contract's inputSchema. Capabilities
+ * never call each other directly — composition happens at the channel
+ * manifest level, mediated by the runtime.
+ */
+export interface Capability<TInput = unknown, TOutput = unknown> {
+    contract: CapabilityContract;
+    invoke(input: TInput, ctx: CapabilityContext): Promise<TOutput>;
+}
+export interface CapabilityContext {
+    sessionId: string;
+    channelId: string;
+    worldId: string;
+    /** Resolves a NAP address to a narrative/world resource. See @portalshq/resolver. */
+    resolve: (napAddress: string) => Promise<unknown>;
+}

package/dist/capability-contract.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * A Capability is the smallest unit of composition in the platform.
+ * Every capability — realtime-fanout, video-delivery, identity, the
+ * narrative-engine-adapter, everything — implements this same contract
+ * shape. The runtime never calls a capability directly; it always goes
+ * through the registry, which validates against this schema first.
+ *
+ * Modeled deliberately on Kubernetes CRD + controller semantics, not on
+ * a bare RPC interface: declare a resource shape, let the runtime
+ * reconcile it. See docs/architecture-decision-records for rationale.
+ */
+export const PermissionScopeSchema = z.object({
+    resource: z.string(), // e.g. "world:write", "audience:read"
+    effect: z.enum(["allow", "deny"]),
+});
+export const CapabilityContractSchema = z.object({
+    id: z.string(), // e.g. "realtime-fanout"
+    version: z.string(), // semver
+    inputSchema: z.record(z.unknown()), // JSON schema for capability input
+    outputSchema: z.record(z.unknown()), // JSON schema for capability output
+    permissions: z.array(PermissionScopeSchema),
+    plane: z.enum(["control", "data"]), // which plane this capability runs in — see ADR 0001
+    lazyStart: z.boolean().default(true), // billed only while an invoking session is active
+});

package/dist/channel-manifest.schema.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+/**
+ * A Channel is a declarative composition of capabilities + a world template.
+ * Developers write one of these instead of writing infrastructure. This is
+ * the file the SDK CLI reads, validates, and deploys.
+ *
+ * Deliberately format-agnostic: a branching-film channel, a live game-show
+ * channel, and a text/image channel are all just different capability
+ * selections against the same manifest shape — there is no separate
+ * "channel type" concept in the runtime.
+ */
+export declare const CapabilityRefSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    capabilityId: string;
+    config?: Record<string, unknown> | undefined;
+    version?: string | undefined;
+}, {
+    capabilityId: string;
+    config?: Record<string, unknown> | undefined;
+    version?: string | undefined;
+}>;
+export declare const ChannelManifestSchema: z.ZodObject<{
+    apiVersion: z.ZodLiteral<"nap/v1">;
+    kind: z.ZodLiteral<"Channel">;
+    metadata: z.ZodObject<{
+        name: z.ZodString;
+        owner: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        owner: string;
+        description?: string | undefined;
+    }, {
+        name: string;
+        owner: string;
+        description?: string | undefined;
+    }>;
+    spec: z.ZodObject<{
+        worldTemplate: z.ZodString;
+        narrativeRef: z.ZodOptional<z.ZodString>;
+        capabilities: z.ZodArray<z.ZodObject<{
+            capabilityId: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }, {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }>, "many">;
+        visibility: z.ZodDefault<z.ZodEnum<["public", "unlisted", "private"]>>;
+    }, "strip", z.ZodTypeAny, {
+        capabilities: {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }[];
+        worldTemplate: string;
+        visibility: "public" | "unlisted" | "private";
+        narrativeRef?: string | undefined;
+    }, {
+        capabilities: {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }[];
+        worldTemplate: string;
+        narrativeRef?: string | undefined;
+        visibility?: "public" | "unlisted" | "private" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    apiVersion: "nap/v1";
+    kind: "Channel";
+    metadata: {
+        name: string;
+        owner: string;
+        description?: string | undefined;
+    };
+    spec: {
+        capabilities: {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }[];
+        worldTemplate: string;
+        visibility: "public" | "unlisted" | "private";
+        narrativeRef?: string | undefined;
+    };
+}, {
+    apiVersion: "nap/v1";
+    kind: "Channel";
+    metadata: {
+        name: string;
+        owner: string;
+        description?: string | undefined;
+    };
+    spec: {
+        capabilities: {
+            capabilityId: string;
+            config?: Record<string, unknown> | undefined;
+            version?: string | undefined;
+        }[];
+        worldTemplate: string;
+        narrativeRef?: string | undefined;
+        visibility?: "public" | "unlisted" | "private" | undefined;
+    };
+}>;
+export type ChannelManifest = z.infer<typeof ChannelManifestSchema>;

package/dist/channel-manifest.schema.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * A Channel is a declarative composition of capabilities + a world template.
+ * Developers write one of these instead of writing infrastructure. This is
+ * the file the SDK CLI reads, validates, and deploys.
+ *
+ * Deliberately format-agnostic: a branching-film channel, a live game-show
+ * channel, and a text/image channel are all just different capability
+ * selections against the same manifest shape — there is no separate
+ * "channel type" concept in the runtime.
+ */
+export const CapabilityRefSchema = z.object({
+    capabilityId: z.string(), // must match a CapabilityContract.id in the registry
+    version: z.string().optional(), // pin a version; defaults to latest compatible
+    config: z.record(z.unknown()).optional(),
+});
+export const ChannelManifestSchema = z.object({
+    apiVersion: z.literal("nap/v1"),
+    kind: z.literal("Channel"),
+    metadata: z.object({
+        name: z.string(),
+        owner: z.string(), // provider/developer id
+        description: z.string().optional(),
+    }),
+    spec: z.object({
+        worldTemplate: z.string(), // NAP address of the world template
+        narrativeRef: z.string().optional(), // NAP address, if this channel uses narrative state
+        capabilities: z.array(CapabilityRefSchema).min(1),
+        visibility: z.enum(["public", "unlisted", "private"]).default("public"),
+    }),
+});

package/{src/content.ts → dist/content.d.ts}

@@ -12,22 +12,18 @@
  * and regulatory requirements (COPPA and equivalents) need real legal
  * review -- this only guarantees a rating can't be silently absent.
  */
-
-import type { CapabilityContext } from "./capabilities.js";
-
+import type { RegistryCapabilityContext } from "./capabilities.js";
 export type AgeRating = "all-ages" | "teen" | "mature" | "unrated";
-
 export interface ContentRating {
-  rating: AgeRating;
-  /** Platform-defined vocabulary, not free text, so parental-control
-   *  filters can match reliably -- e.g. "violence", "language". */
-  descriptors?: string[];
-  /** Self-rated by the creator, or confirmed by platform review. A
-   *  parental-control profile should be able to require "platform-reviewed"
-   *  specifically, not just any declared rating. */
-  source: "creator-declared" | "platform-reviewed";
+    rating: AgeRating;
+    /** Platform-defined vocabulary, not free text, so parental-control
+     *  filters can match reliably -- e.g. "violence", "language". */
+    descriptors?: string[];
+    /** Self-rated by the creator, or confirmed by platform review. A
+     *  parental-control profile should be able to require "platform-reviewed"
+     *  specifically, not just any declared rating. */
+    source: "creator-declared" | "platform-reviewed";
 }
-
 /**
  * The seam between "what a channel produces" and "how a viewer receives
  * it." Text+image, video, and VR are all ContentDeliveryAdapters -- the
@@ -37,13 +33,12 @@ export interface ContentRating {
  * references the client interprets per `contentType`.
  */
 export interface ContentDescriptor {
-  contentType: string;
-  payload: unknown;
-  mediaRefs?: string[];
-  rating: ContentRating;
+    contentType: string;
+    payload: unknown;
+    mediaRefs?: string[];
+    rating: ContentRating;
 }
-
 export interface ContentDeliveryAdapter<TContent = unknown, TConfig = unknown> {
-  contentType: string;
-  describe(ctx: CapabilityContext<TConfig>, content: TContent): Promise<ContentDescriptor>;
+    contentType: string;
+    describe(ctx: RegistryCapabilityContext<TConfig>, content: TContent): Promise<ContentDescriptor>;
 }

package/dist/content.js

@@ -0,0 +1,15 @@
+/**
+ * Content delivery and content rating.
+ *
+ * `rating` is required, not optional, on every ContentDescriptor --
+ * enforced at the type level so a ContentDeliveryAdapter implementation
+ * cannot compile without producing one. This is the engineering side of
+ * "general audience, possibly including minors": the platform should be
+ * structurally incapable of serving unrated content, not just discouraged
+ * from it.
+ *
+ * This is NOT legal guidance. Actual age-verification, parental-consent,
+ * and regulatory requirements (COPPA and equivalents) need real legal
+ * review -- this only guarantees a rating can't be silently absent.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./capability-contract.js";
+export * from "./channel-manifest.schema.js";
+export * from "./capabilities.js";
+export * from "./tenancy.js";
+export * from "./content.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./capability-contract.js";
+export * from "./channel-manifest.schema.js";
+export * from "./capabilities.js";
+export * from "./tenancy.js";
+export * from "./content.js";

package/{src/tenancy.ts → dist/tenancy.d.ts}

@@ -8,58 +8,28 @@
  * privileged is an explicit, optional upgrade; everything less privileged
  * is an automated demotion (a quota/abuse signal), not a ban.
  */
-
 export type TrustLevel = "platform" | "reviewed" | "standard" | "restricted";
-
 export interface ResourceQuota {
-  maxConcurrentExecutions: number;
-  maxExecutionDurationMs: number;
-  maxMemoryMb: number;
-  /** Rolling 30-day compute budget. The metering/enforcement hook lives in
-   *  the execution plane (Lambda/Fargate reservations, billing alarms) --
-   *  this is just the declared ceiling a tenant is told about. */
-  maxMonthlyComputeMs: number;
+    maxConcurrentExecutions: number;
+    maxExecutionDurationMs: number;
+    maxMemoryMb: number;
+    /** Rolling 30-day compute budget. The metering/enforcement hook lives in
+     *  the execution plane (Lambda/Fargate reservations, billing alarms) --
+     *  this is just the declared ceiling a tenant is told about. */
+    maxMonthlyComputeMs: number;
 }
-
 export interface TenantContext {
-  tenantId: string;
-  trustLevel: TrustLevel;
-  quota: ResourceQuota;
+    tenantId: string;
+    trustLevel: TrustLevel;
+    quota: ResourceQuota;
 }
-
 /**
  * Starting points to tune against real usage, not load-bearing numbers.
  * The point being enforced is structural: every tier has an explicit,
  * finite ceiling -- including `platform`, which should get a real quota
  * before this goes to production rather than staying "unlimited."
  */
-export const DEFAULT_QUOTAS: Record<TrustLevel, ResourceQuota> = {
-  platform: {
-    maxConcurrentExecutions: 10_000,
-    maxExecutionDurationMs: 15 * 60_000,
-    maxMemoryMb: 3008,
-    maxMonthlyComputeMs: Number.MAX_SAFE_INTEGER,
-  },
-  reviewed: {
-    maxConcurrentExecutions: 200,
-    maxExecutionDurationMs: 60_000,
-    maxMemoryMb: 1024,
-    maxMonthlyComputeMs: 50 * 60 * 60_000, // 50 compute-hours / month
-  },
-  standard: {
-    maxConcurrentExecutions: 10,
-    maxExecutionDurationMs: 10_000,
-    maxMemoryMb: 256,
-    maxMonthlyComputeMs: 2 * 60 * 60_000, // 2 compute-hours / month
-  },
-  restricted: {
-    maxConcurrentExecutions: 1,
-    maxExecutionDurationMs: 5_000,
-    maxMemoryMb: 128,
-    maxMonthlyComputeMs: 10 * 60_000, // 10 compute-minutes / month
-  },
-};
-
+export declare const DEFAULT_QUOTAS: Record<TrustLevel, ResourceQuota>;
 /**
  * Every new tenant starts here, automatically, with no human in the loop --
  * this is what makes 100,000 tenants onboardable at all. Upgrades to
@@ -68,10 +38,4 @@ export const DEFAULT_QUOTAS: Record<TrustLevel, ResourceQuota> = {
  * `restricted` are an automated response to abuse/quota-violation signals,
  * also built later. This function only governs the Day 0 default.
  */
-export function assignInitialTrust(tenantId: string): TenantContext {
-  return {
-    tenantId,
-    trustLevel: "standard",
-    quota: DEFAULT_QUOTAS.standard,
-  };
-}
+export declare function assignInitialTrust(tenantId: string): TenantContext;

package/dist/tenancy.js

@@ -0,0 +1,57 @@
+/**
+ * Tenant trust and resource quotas.
+ *
+ * At a few dozen developers, manually reviewing each one before granting
+ * access is a reasonable process. At 100,000 tenants, "manual review" isn't
+ * a process -- it's a queue that never empties. `standard` is the only
+ * tier a new signup can reach with no human in the loop. Everything more
+ * privileged is an explicit, optional upgrade; everything less privileged
+ * is an automated demotion (a quota/abuse signal), not a ban.
+ */
+/**
+ * Starting points to tune against real usage, not load-bearing numbers.
+ * The point being enforced is structural: every tier has an explicit,
+ * finite ceiling -- including `platform`, which should get a real quota
+ * before this goes to production rather than staying "unlimited."
+ */
+export const DEFAULT_QUOTAS = {
+    platform: {
+        maxConcurrentExecutions: 10_000,
+        maxExecutionDurationMs: 15 * 60_000,
+        maxMemoryMb: 3008,
+        maxMonthlyComputeMs: Number.MAX_SAFE_INTEGER,
+    },
+    reviewed: {
+        maxConcurrentExecutions: 200,
+        maxExecutionDurationMs: 60_000,
+        maxMemoryMb: 1024,
+        maxMonthlyComputeMs: 50 * 60 * 60_000, // 50 compute-hours / month
+    },
+    standard: {
+        maxConcurrentExecutions: 10,
+        maxExecutionDurationMs: 10_000,
+        maxMemoryMb: 256,
+        maxMonthlyComputeMs: 2 * 60 * 60_000, // 2 compute-hours / month
+    },
+    restricted: {
+        maxConcurrentExecutions: 1,
+        maxExecutionDurationMs: 5_000,
+        maxMemoryMb: 128,
+        maxMonthlyComputeMs: 10 * 60_000, // 10 compute-minutes / month
+    },
+};
+/**
+ * Every new tenant starts here, automatically, with no human in the loop --
+ * this is what makes 100,000 tenants onboardable at all. Upgrades to
+ * `reviewed` or `platform` are explicit, out-of-band actions (an admin
+ * decision, or an automated reputation system built later); downgrades to
+ * `restricted` are an automated response to abuse/quota-violation signals,
+ * also built later. This function only governs the Day 0 default.
+ */
+export function assignInitialTrust(tenantId) {
+    return {
+        tenantId,
+        trustLevel: "standard",
+        quota: DEFAULT_QUOTAS.standard,
+    };
+}

package/package.json

@@ -1,13 +1,26 @@
 {
   "name": "@portalshq/contracts",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/portalshq/portals-cloud"
   },
   "description": "Capability contract types and channel manifest schema. The single source of truth every other package validates against.",
-  "main": "src/index.ts",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
     "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^20.0.0"
   }
 }

package/src/capabilities.ts

@@ -1,179 +0,0 @@
-/**
- * The capability contract. A way for a unit of platform functionality
- * (chat, polls, lobby presence, a video player, a VR render target, a
- * game-rules engine -- built or not-yet-built) to declare itself, and a
- * way for a channel to compose the capabilities it needs.
- *
- * Design principle enforced here: a platform that silently no-ops an
- * unbuilt or misconfigured capability is more dangerous than one that
- * refuses to resolve. `CapabilityRegistry.resolve()` fails loud, with a
- * specific error per problem, never a silent partial result. The same
- * principle extends to tenancy below: a manifest cannot assert its own
- * trust level -- that comes from a trusted lookup the caller provides,
- * never from the (potentially untrusted) manifest itself.
- */
-
-import type { TenantContext } from "./tenancy.js";
-
-export interface ValidationResult {
-  ok: boolean;
-  errors?: string[];
-}
-
-export interface CapabilityContext<TConfig = unknown> {
-  channelId: string;
-  tenant: TenantContext;
-  config: TConfig;
-}
-
-export interface CapabilityModule<TConfig = unknown> {
-  /** Globally unique, namespaced, e.g. "platform.chat", "platform.video.mux". */
-  id: string;
-  /** Semver. Used for compatibility checks once external developers ship modules. */
-  version: string;
-  displayName: string;
-  /** Other capability ids this one requires to function, resolved per-channel. */
-  dependsOn?: string[];
-  /**
-   * Validate a channel's config for this capability. Must not throw for
-   * ordinary invalid input -- return a ValidationResult so the registry can
-   * collect every problem in one pass instead of failing on the first.
-   */
-  validateConfig(config: unknown): ValidationResult;
-  /** Called once when a channel using this capability is first resolved. */
-  onChannelRegistered?(ctx: CapabilityContext<TConfig>): Promise<void>;
-  /** Called when the channel is torn down or the capability is removed. */
-  onChannelUnregistered?(ctx: CapabilityContext<TConfig>): Promise<void>;
-}
-
-// ── Channel manifests ────────────────────────────────────────────────────
-
-export interface CapabilityUsage {
-  capabilityId: string;
-  config: unknown;
-}
-
-export interface ChannelManifest {
-  channelId: string;
-  /** Declared owner. Verified against the trusted TenantContext passed into
-   *  `resolve()`, not taken on faith -- see the mismatch check below. */
-  tenantId: string;
-  displayName: string;
-  capabilities: CapabilityUsage[];
-}
-
-export interface ResolvedCapability {
-  module: CapabilityModule;
-  config: unknown;
-}
-
-export type ResolvedChannel =
-  | { ok: true; channelId: string; tenant: TenantContext; capabilities: ResolvedCapability[] }
-  | { ok: false; channelId: string; errors: string[] };
-
-// ── Registry ─────────────────────────────────────────────────────────────
-
-export class CapabilityRegistry {
-  private modules = new Map<string, CapabilityModule>();
-
-  register(module: CapabilityModule): void {
-    if (this.modules.has(module.id)) {
-      throw new Error(`Capability "${module.id}" is already registered.`);
-    }
-    this.modules.set(module.id, module);
-  }
-
-  get(id: string): CapabilityModule | undefined {
-    return this.modules.get(id);
-  }
-
-  has(id: string): boolean {
-    return this.modules.has(id);
-  }
-
-  list(): CapabilityModule[] {
-    return [...this.modules.values()];
-  }
-
-  /**
-   * Resolves a manifest against currently-registered modules, for a given
-   * (trustworthily-sourced) tenant. Collects EVERY problem in a single pass
-   * rather than stopping at the first, so a developer sees the whole
-   * picture at once. `tenant` must come from your own tenant lookup (e.g.
-   * the control plane's database), never from the manifest itself -- a
-   * manifest declaring its own trust level would let any tenant grant
-   * themselves unlimited quota.
-   */
-  resolve(manifest: ChannelManifest, tenant: TenantContext): ResolvedChannel {
-    if (tenant.tenantId !== manifest.tenantId) {
-      return {
-        ok: false,
-        channelId: manifest.channelId,
-        errors: [
-          `Tenant mismatch: manifest declares tenant "${manifest.tenantId}" but ` +
-            `resolution was requested for tenant "${tenant.tenantId}".`,
-        ],
-      };
-    }
-
-    const errors: string[] = [];
-    const resolved: ResolvedCapability[] = [];
-    const declaredIds = new Set(manifest.capabilities.map((u) => u.capabilityId));
-
-    for (const usage of manifest.capabilities) {
-      const module = this.modules.get(usage.capabilityId);
-      if (!module) {
-        errors.push(
-          `Channel "${manifest.channelId}" declares capability "${usage.capabilityId}", ` +
-            `which is not registered on this platform instance.`,
-        );
-        continue;
-      }
-
-      for (const dep of module.dependsOn ?? []) {
-        if (!declaredIds.has(dep)) {
-          errors.push(
-            `Capability "${module.id}" requires "${dep}", which channel ` +
-              `"${manifest.channelId}" does not declare.`,
-          );
-        }
-      }
-
-      const validation = module.validateConfig(usage.config);
-      if (!validation.ok) {
-        const detail = validation.errors?.join("; ") ?? "invalid config";
-        errors.push(`Invalid config for capability "${module.id}": ${detail}`);
-        continue;
-      }
-
-      resolved.push({ module, config: usage.config });
-    }
-
-    if (errors.length > 0) {
-      return { ok: false, channelId: manifest.channelId, errors };
-    }
-    return { ok: true, channelId: manifest.channelId, tenant, capabilities: resolved };
-  }
-
-  /** Runs onChannelRegistered for every resolved capability, in declaration order. */
-  async activate(resolved: Extract<ResolvedChannel, { ok: true }>): Promise<void> {
-    for (const { module, config } of resolved.capabilities) {
-      await module.onChannelRegistered?.({
-        channelId: resolved.channelId,
-        tenant: resolved.tenant,
-        config,
-      });
-    }
-  }
-
-  /** Runs onChannelUnregistered for every resolved capability, in reverse order. */
-  async deactivate(resolved: Extract<ResolvedChannel, { ok: true }>): Promise<void> {
-    for (const { module, config } of [...resolved.capabilities].reverse()) {
-      await module.onChannelUnregistered?.({
-        channelId: resolved.channelId,
-        tenant: resolved.tenant,
-        config,
-      });
-    }
-  }
-}

package/src/capability-contract.ts

@@ -1,49 +0,0 @@
-import { z } from "zod";
-
-/**
- * A Capability is the smallest unit of composition in the platform.
- * Every capability — realtime-fanout, video-delivery, identity, the
- * narrative-engine-adapter, everything — implements this same contract
- * shape. The runtime never calls a capability directly; it always goes
- * through the registry, which validates against this schema first.
- *
- * Modeled deliberately on Kubernetes CRD + controller semantics, not on
- * a bare RPC interface: declare a resource shape, let the runtime
- * reconcile it. See docs/architecture-decision-records for rationale.
- */
-
-export const PermissionScopeSchema = z.object({
-  resource: z.string(),          // e.g. "world:write", "audience:read"
-  effect: z.enum(["allow", "deny"]),
-});
-export type PermissionScope = z.infer<typeof PermissionScopeSchema>;
-
-export const CapabilityContractSchema = z.object({
-  id: z.string(),                 // e.g. "realtime-fanout"
-  version: z.string(),            // semver
-  inputSchema: z.record(z.unknown()),   // JSON schema for capability input
-  outputSchema: z.record(z.unknown()),  // JSON schema for capability output
-  permissions: z.array(PermissionScopeSchema),
-  plane: z.enum(["control", "data"]),   // which plane this capability runs in — see ADR 0001
-  lazyStart: z.boolean().default(true), // billed only while an invoking session is active
-});
-export type CapabilityContract = z.infer<typeof CapabilityContractSchema>;
-
-/**
- * Implemented by every capability package. The registry calls `invoke`
- * after validating `input` against the contract's inputSchema. Capabilities
- * never call each other directly — composition happens at the channel
- * manifest level, mediated by the runtime.
- */
-export interface Capability<TInput = unknown, TOutput = unknown> {
-  contract: CapabilityContract;
-  invoke(input: TInput, ctx: CapabilityContext): Promise<TOutput>;
-}
-
-export interface CapabilityContext {
-  sessionId: string;
-  channelId: string;
-  worldId: string;
-  /** Resolves a NAP address to a narrative/world resource. See @portalshq/resolver. */
-  resolve: (napAddress: string) => Promise<unknown>;
-}

package/src/channel-manifest.schema.ts

@@ -1,34 +0,0 @@
-import { z } from "zod";
-
-/**
- * A Channel is a declarative composition of capabilities + a world template.
- * Developers write one of these instead of writing infrastructure. This is
- * the file the SDK CLI reads, validates, and deploys.
- *
- * Deliberately format-agnostic: a branching-film channel, a live game-show
- * channel, and a text/image channel are all just different capability
- * selections against the same manifest shape — there is no separate
- * "channel type" concept in the runtime.
- */
-export const CapabilityRefSchema = z.object({
-  capabilityId: z.string(),       // must match a CapabilityContract.id in the registry
-  version: z.string().optional(), // pin a version; defaults to latest compatible
-  config: z.record(z.unknown()).optional(),
-});
-
-export const ChannelManifestSchema = z.object({
-  apiVersion: z.literal("nap/v1"),
-  kind: z.literal("Channel"),
-  metadata: z.object({
-    name: z.string(),
-    owner: z.string(),           // provider/developer id
-    description: z.string().optional(),
-  }),
-  spec: z.object({
-    worldTemplate: z.string(),               // NAP address of the world template
-    narrativeRef: z.string().optional(),     // NAP address, if this channel uses narrative state
-    capabilities: z.array(CapabilityRefSchema).min(1),
-    visibility: z.enum(["public", "unlisted", "private"]).default("public"),
-  }),
-});
-export type ChannelManifest = z.infer<typeof ChannelManifestSchema>;

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from "./capability-contract";
-export * from "./channel-manifest.schema";
-export * from "./capabilities";
-export * from "./tenancy";
-export * from "./content";