@portalshq/contracts 0.0.2

package/README.md

@@ -0,0 +1,9 @@
+# @portalshq/contracts
+
+The schema layer every other package depends on. Nothing here has runtime
+behavior — it's types and zod schemas only, so it can be imported by the
+registry, the runtime, every capability package, and the SDK without any
+of them depending on each other.
+
+If you're adding a new capability type, start here: define what its input/
+output/permissions look like before writing the implementation package.

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@portalshq/contracts",
+  "version": "0.0.2",
+  "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",
+  "dependencies": {
+    "zod": "^3.23.0"
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,179 @@
+/**
+ * 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

@@ -0,0 +1,49 @@
+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

@@ -0,0 +1,34 @@
+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/content.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+import type { CapabilityContext } 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";
+}
+
+/**
+ * The seam between "what a channel produces" and "how a viewer receives
+ * it." Text+image, video, and VR are all ContentDeliveryAdapters -- the
+ * platform core never special-cases any one medium. `describe` returns a
+ * generic envelope; it's deliberately NOT "render" -- this layer doesn't
+ * assume a server-side rendering model, just a typed payload + media
+ * references the client interprets per `contentType`.
+ */
+export interface ContentDescriptor {
+  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>;
+}

package/src/index.ts

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

package/src/tenancy.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+
+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;
+}
+
+export interface TenantContext {
+  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
+  },
+};
+
+/**
+ * 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: string): TenantContext {
+  return {
+    tenantId,
+    trustLevel: "standard",
+    quota: DEFAULT_QUOTAS.standard,
+  };
+}