@withloops.ai/contracts 0.0.0-stage → 0.1.0

package/examples/acme-checks.manifest.json

@@ -0,0 +1,24 @@
+{
+  "manifestVersion": 1,
+  "id": "acme-checks",
+  "name": "Acme Checks",
+  "version": "1.0.0",
+  "summary": "Background checks on your contacts, started from the record.",
+  "developer": { "name": "Acme", "email": "dev@acme-checks.com", "website": "https://acme-checks.com" },
+  "visibility": "public",
+  "scopes": ["contacts:read", "notes:write"],
+  "ui": {
+    "apiVersion": 1,
+    "slots": ["recordTab", "linkCard"],
+    "uses": ["contact.firstName", "contact.email"],
+    "does": ["record.note"],
+    "hears": ["contact.updated"],
+    "links": ["*.acme-checks.com/report/*"],
+    "settings": { "apiKey": { "type": "secret", "label": "Your Acme API key" }, "package": { "type": "choice", "label": "Package", "options": ["Basic", "Enhanced"] } },
+    "endpoints": {
+      "checkStatus": { "method": "GET", "url": "https://api.acme-checks.com/v1/checks/{email}", "sends": { "email": "contact.email" }, "returns": { "status": "enum:clear|pending|flagged", "date": "date" } },
+      "startCheck": { "method": "POST", "url": "https://api.acme-checks.com/v1/checks", "sends": { "name": "contact.firstName", "email": "contact.email", "package": "settings.package" }, "returns": { "id": "string", "status": "enum:pending" } },
+      "report": { "method": "GET", "url": "https://api.acme-checks.com/v1/reports/{id}", "sends": { "id": "link.path.id" }, "returns": { "status": "enum:clear|pending|flagged" } }
+    }
+  }
+}

package/examples/acme-crm.manifest.json

@@ -0,0 +1,114 @@
+{
+  "manifestVersion": 1,
+  "id": "acme-crm",
+  "name": "Acme CRM",
+  "version": "0.1.0",
+  "summary": "Use Acme CRM as your CRM of record; Loops writes calls and notes to its timeline.",
+  "developer": {
+    "name": "Acme",
+    "email": "dev@acme-crm.com",
+    "website": "https://acme-crm.com"
+  },
+  "visibility": "public",
+  "scopes": [
+    "contacts:write",
+    "companies:write"
+  ],
+  "sync": {
+    "baseUrl": "https://api.acme-crm.com",
+    "auth": {
+      "type": "oauth2",
+      "authorizeUrl": "https://app.acme-crm.com/oauth/authorize",
+      "tokenUrl": "https://api.acme-crm.com/oauth/token",
+      "scopes": [
+        "contacts",
+        "companies"
+      ]
+    },
+    "objects": [
+      {
+        "theirs": "people",
+        "ours": "CONTACT",
+        "list": {
+          "path": "/v1/people",
+          "itemsPath": "data",
+          "cursorParam": "cursor",
+          "nextCursorPath": "next_cursor",
+          "updatedSinceParam": "updated_since"
+        },
+        "fields": [
+          {
+            "theirs": "first_name",
+            "ours": "firstName",
+            "owner": "theirs"
+          },
+          {
+            "theirs": "email",
+            "ours": "email",
+            "owner": "theirs"
+          }
+        ],
+        "match": [
+          "email"
+        ]
+      },
+      {
+        "theirs": "organizations",
+        "ours": "COMPANY",
+        "list": {
+          "path": "/v1/organizations",
+          "itemsPath": "data",
+          "cursorParam": "cursor",
+          "nextCursorPath": "next_cursor"
+        },
+        "fields": [
+          {
+            "theirs": "name",
+            "ours": "name",
+            "owner": "theirs"
+          },
+          {
+            "theirs": "domain",
+            "ours": "website",
+            "owner": "theirs"
+          }
+        ],
+        "match": [
+          "domain"
+        ]
+      }
+    ],
+    "links": [
+      {
+        "from": "CONTACT",
+        "to": "COMPANY",
+        "theirs": "organization_id"
+      }
+    ],
+    "changeFeed": {
+      "webhook": {
+        "signature": {
+          "scheme": "hmac-sha256",
+          "header": "X-Acme-Signature"
+        }
+      },
+      "polling": {
+        "everyMinutes": 15
+      }
+    },
+    "writeBack": {
+      "call": {
+        "method": "POST",
+        "path": "/v1/activities"
+      },
+      "note": {
+        "method": "POST",
+        "path": "/v1/notes"
+      }
+    },
+    "limits": {
+      "requestsPerSecond": 10,
+      "burst": 100
+    }
+  }
+}

package/examples/hello.manifest.json

@@ -0,0 +1,14 @@
+{
+  "manifestVersion": 1,
+  "id": "hello",
+  "name": "Hello",
+  "version": "0.1.0",
+  "summary": "Says hello on a contact.",
+  "developer": { "name": "Loops", "email": "developers@withloops.ai" },
+  "scopes": ["contacts:read"],
+  "ui": {
+    "apiVersion": 1,
+    "slots": ["recordPanel"],
+    "uses": ["contact.firstName"]
+  }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@withloops.ai/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The Loops developer platform contracts (zod): app manifest v1, scopes, events, the /v1 API envelope and registry records. Everything else builds on these.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^24.0.0"
+  },
+  "homepage": "https://withloops.ai",
+  "keywords": [
+    "loops",
+    "withloops",
+    "sdk",
+    "contracts"
+  ]
+}

package/src/api.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { Timestamp } from './ids.ts';
+
+/**
+ * The public REST API envelope: `api.withloops.ai/v1`. One envelope for every resource, cursor paging, one error shape.
+ * Only ever ADD fields (versioning promise). Hono + @hono/zod-openapi build the OpenAPI spec from these schemas.
+ */
+
+export const API_VERSION = 'v1' as const;
+
+// ── Errors ──────────────────────────────────────────────────────────────────────
+
+/** Every error code the API returns, with its HTTP status. */
+export const ERROR_CODES = {
+  bad_request: 400,
+  validation_failed: 422,
+  unauthorized: 401,
+  forbidden: 403,
+  missing_scope: 403,
+  not_found: 404,
+  conflict: 409,
+  rate_limited: 429,
+  internal: 500,
+  upstream_timeout: 504,
+  unavailable: 503,
+} as const;
+export type ErrorCode = keyof typeof ERROR_CODES;
+export const ErrorCodeSchema = z.enum(Object.keys(ERROR_CODES) as [ErrorCode, ...ErrorCode[]]);
+
+export const ApiError = z.object({
+  code: ErrorCodeSchema,
+  /** Plain words a developer can act on. Never a stack trace, never a secret. */
+  message: z.string(),
+  /** Field-level problems for validation_failed: { "email": "Not an email" }. */
+  fields: z.record(z.string(), z.string()).optional(),
+  /** The scope that was missing, for missing_scope. */
+  scope: z.string().optional(),
+  /** Echoed in the `x-request-id` header; quote it to support. */
+  requestId: z.string(),
+});
+export type ApiError = z.infer<typeof ApiError>;
+
+export const ErrorEnvelope = z.object({ ok: z.literal(false), error: ApiError });
+export type ErrorEnvelope = z.infer<typeof ErrorEnvelope>;
+
+export function errorStatus(code: ErrorCode): number {
+  return ERROR_CODES[code];
+}
+
+// ── Success ─────────────────────────────────────────────────────────────────────
+
+export const Page = z.object({
+  /** Pass as `cursor` to get the next page; null on the last page. */
+  nextCursor: z.string().nullable(),
+  hasMore: z.boolean(),
+});
+export type Page = z.infer<typeof Page>;
+
+/** Single object: `{ ok: true, data }`. */
+export function dataEnvelope<T extends z.ZodType>(data: T) {
+  return z.object({ ok: z.literal(true), data });
+}
+
+/** List: `{ ok: true, data: [...], page: { nextCursor, hasMore } }`. */
+export function listEnvelope<T extends z.ZodType>(item: T) {
+  return z.object({ ok: z.literal(true), data: z.array(item), page: Page });
+}
+
+export type DataEnvelope<T> = { ok: true; data: T };
+export type ListEnvelope<T> = { ok: true; data: T[]; page: Page };
+
+// ── Paging query ────────────────────────────────────────────────────────────────
+
+export const PAGE_LIMIT_DEFAULT = 25;
+export const PAGE_LIMIT_MAX = 100;
+
+export const ListQuery = z.object({
+  cursor: z.string().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(PAGE_LIMIT_MAX).default(PAGE_LIMIT_DEFAULT),
+  /** Only records changed at or after this time (sync and polling). */
+  updatedSince: Timestamp.optional(),
+});
+export type ListQuery = z.infer<typeof ListQuery>;
+
+// ── Resources (L0: contacts) ────────────────────────────────────────────────────
+
+/** A Loops contact as the public API shows it. camelCase, ids as strings, dates ISO. */
+export const Contact = z.object({
+  id: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  email: z.email().nullable(),
+  phone: z.string().nullable(),
+  jobTitle: z.string().nullable(),
+  companyId: z.string().nullable(),
+  ownerId: z.string().nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type Contact = z.infer<typeof Contact>;
+
+export const ContactCreate = z
+  .object({
+    firstName: z.string().max(120).optional(),
+    lastName: z.string().max(120).optional(),
+    email: z.email().optional(),
+    phone: z.string().max(40).optional(),
+    jobTitle: z.string().max(200).optional(),
+    companyId: z.string().optional(),
+    ownerId: z.string().optional(),
+  })
+  .refine((c) => c.firstName || c.lastName || c.email, 'Give a name or an email');
+export type ContactCreate = z.infer<typeof ContactCreate>;
+
+export const ContactUpdate = z.object({
+  firstName: z.string().max(120).nullable().optional(),
+  lastName: z.string().max(120).nullable().optional(),
+  email: z.email().nullable().optional(),
+  phone: z.string().max(40).nullable().optional(),
+  jobTitle: z.string().max(200).nullable().optional(),
+  companyId: z.string().nullable().optional(),
+  ownerId: z.string().nullable().optional(),
+});
+export type ContactUpdate = z.infer<typeof ContactUpdate>;

package/src/events.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { AppId, EventId, InstallId, Timestamp, UserId, WorkspaceId } from './ids.ts';
+import type { Scope } from './scopes.ts';
+
+/**
+ * Every event an app can hear (LoopKit `hears`, webhooks out, the engine's queues). Each names the scope that lets an app
+ * hear it. Only ever ADD here (versioning promise).
+ */
+export const EVENTS = {
+  'contact.created': 'contacts:read',
+  'contact.updated': 'contacts:read',
+  'contact.deleted': 'contacts:read',
+  'company.created': 'companies:read',
+  'company.updated': 'companies:read',
+  'company.deleted': 'companies:read',
+  'lead.created': 'leads:read',
+  'lead.updated': 'leads:read',
+  'lead.deleted': 'leads:read',
+  'deal.created': 'deals:read',
+  'deal.updated': 'deals:read',
+  'deal.deleted': 'deals:read',
+  'loop.message': 'loops:read',
+  'loop.call.ended': 'calls:read',
+  'meeting.ended': 'meetings:read',
+  'app.installed': null,
+  'app.uninstalled': null,
+} as const satisfies Record<string, Scope | null>;
+
+export type EventType = keyof typeof EVENTS;
+export const EVENT_TYPES = Object.keys(EVENTS) as [EventType, ...EventType[]];
+export const EventTypeSchema = z.enum(EVENT_TYPES);
+
+/** The scope needed to hear an event; null = every installed app hears it (about itself only). */
+export function scopeForEvent(type: EventType): Scope | null {
+  return EVENTS[type];
+}
+
+/** Who caused a change. Apps never hear their own echo (`causedBy.kind === 'app'` and same app id). */
+export const CausedBy = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('user'), id: UserId }),
+  z.object({ kind: z.literal('app'), id: AppId }),
+  z.object({ kind: z.literal('system') }),
+]);
+export type CausedBy = z.infer<typeof CausedBy>;
+
+/**
+ * The one event envelope. `data` carries ids plus only the fields the app was granted; the engine trims it per install,
+ * so `data` is open here and each consumer narrows it.
+ */
+export const EventEnvelope = z.object({
+  id: EventId,
+  type: EventTypeSchema,
+  version: z.literal(1),
+  occurredAt: Timestamp,
+  workspaceId: WorkspaceId,
+  installId: InstallId.optional(),
+  causedBy: CausedBy,
+  data: z.record(z.string(), z.unknown()),
+});
+export type EventEnvelope = z.infer<typeof EventEnvelope>;
+
+/** True when an app should not get this event back (it caused it). */
+export function isEcho(event: Pick<EventEnvelope, 'causedBy'>, appId: string): boolean {
+  return event.causedBy.kind === 'app' && event.causedBy.id === appId;
+}

package/src/ids.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+/** An app's id: the slug chosen at `loops create`, unique across Loops, never changes. */
+export const AppId = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{1,38}[a-z0-9]$/, 'App id: 3–40 characters, lowercase letters, digits and dashes, starting with a letter');
+export type AppId = z.infer<typeof AppId>;
+
+/** Semantic version of one app release (`1.0.0`, `1.2.0-beta.1`). */
+export const SemVer = z
+  .string()
+  .regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?$/, 'Version must look like 1.0.0');
+export type SemVer = z.infer<typeof SemVer>;
+
+/** A Loops workspace (the customer side; Vista tenant id underneath). */
+export const WorkspaceId = z.string().min(1).max(64);
+export type WorkspaceId = z.infer<typeof WorkspaceId>;
+
+/** A person in a workspace (Vista user id underneath). */
+export const UserId = z.string().min(1).max(64);
+export type UserId = z.infer<typeof UserId>;
+
+/** Opaque ids minted by the registry. Prefix shows the kind at a glance in logs. */
+export const InstallId = z.string().regex(/^ins_[A-Za-z0-9]{8,40}$/);
+export type InstallId = z.infer<typeof InstallId>;
+
+export const VersionId = z.string().regex(/^ver_[A-Za-z0-9]{8,40}$/);
+export type VersionId = z.infer<typeof VersionId>;
+
+export const EventId = z.string().regex(/^evt_[A-Za-z0-9]{8,40}$/);
+export type EventId = z.infer<typeof EventId>;
+
+/** ISO 8601 timestamp with offset, e.g. 2026-11-11T09:30:00Z. */
+export const Timestamp = z.iso.datetime({ offset: true });
+export type Timestamp = z.infer<typeof Timestamp>;
+
+/** Public https URL. http is refused everywhere in the platform. */
+export const HttpsUrl = z.url({ protocol: /^https$/ });
+export type HttpsUrl = z.infer<typeof HttpsUrl>;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './ids.ts';
+export * from './scopes.ts';
+export * from './events.ts';
+export * from './manifest.ts';
+export * from './api.ts';
+export * from './registry.ts';

package/src/manifest.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+import { AppId, HttpsUrl, SemVer } from './ids.ts';
+import { EventTypeSchema, scopeForEvent } from './events.ts';
+import { ScopeSchema, expandScopes, type Scope } from './scopes.ts';
+
+/**
+ * App manifest v1 (`loops.manifest.json`). Everything is a Loops App: one manifest, two optional halves —
+ * `sync` (declarative CRM connector, run by the one Loops sync engine) and `ui` (LoopKit). Skill §2 #1–#3, §3.
+ * Only ever ADD optional fields to v1; a breaking change is manifest v2 and v1 keeps working.
+ */
+
+// ── Shared ──────────────────────────────────────────────────────────────────────
+
+/** Loops record kinds a connector maps into. */
+export const RecordKind = z.enum(['CONTACT', 'COMPANY', 'LEAD', 'DEAL']);
+export type RecordKind = z.infer<typeof RecordKind>;
+
+const RECORD_SCOPE: Record<string, { read: Scope; write: Scope }> = {
+  CONTACT: { read: 'contacts:read', write: 'contacts:write' },
+  COMPANY: { read: 'companies:read', write: 'companies:write' },
+  LEAD: { read: 'leads:read', write: 'leads:write' },
+  DEAL: { read: 'deals:read', write: 'deals:write' },
+  contact: { read: 'contacts:read', write: 'contacts:write' },
+  company: { read: 'companies:read', write: 'companies:write' },
+  lead: { read: 'leads:read', write: 'leads:write' },
+  deal: { read: 'deals:read', write: 'deals:write' },
+  loop: { read: 'loops:read', write: 'loops:write' },
+};
+
+const PathTemplate = z.string().regex(/^\/[A-Za-z0-9_\-./{}:]*$/, 'A path starting with /, e.g. /crm/v3/objects/contacts');
+
+// ── sync: the connector half ────────────────────────────────────────────────────
+
+export const SyncAuth = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('oauth2'),
+    authorizeUrl: HttpsUrl,
+    tokenUrl: HttpsUrl,
+    scopes: z.array(z.string().min(1)).default([]),
+    refresh: z.boolean().default(true),
+  }),
+  z.object({
+    type: z.literal('apiKey'),
+    header: z.string().min(1).default('Authorization'),
+    prefix: z.string().optional(),
+  }),
+]);
+export type SyncAuth = z.infer<typeof SyncAuth>;
+
+/** Who owns a field. The customer's CRM owns its fields (locked in Loops); Loops owns its own. Owner wins, never last-write-wins. */
+export const FieldOwner = z.enum(['theirs', 'ours']);
+
+export const SyncField = z.object({
+  theirs: z.string().min(1),
+  ours: z.string().min(1),
+  owner: FieldOwner,
+});
+
+export const SyncObject = z.object({
+  theirs: z.string().min(1),
+  ours: RecordKind,
+  list: z.object({
+    path: PathTemplate,
+    itemsPath: z.string().min(1).default('results'),
+    cursorParam: z.string().optional(),
+    nextCursorPath: z.string().optional(),
+    updatedSinceParam: z.string().optional(),
+  }),
+  fields: z.array(SyncField).min(1),
+  /** Dedupe keys, in order: e.g. ["email"] for contacts, ["domain"] for companies. External id always matches first. */
+  match: z.array(z.string().min(1)).default([]),
+});
+
+export const SyncLink = z.object({
+  from: RecordKind,
+  to: RecordKind,
+  theirs: z.string().min(1),
+  role: z.string().optional(),
+});
+
+export const ChangeFeed = z
+  .object({
+    webhook: z
+      .object({
+        signature: z.object({ scheme: z.enum(['hmac-sha256', 'hmac-sha1']), header: z.string().min(1) }),
+      })
+      .optional(),
+    polling: z.object({ everyMinutes: z.number().int().min(5).max(1440) }).optional(),
+  })
+  .refine((f) => f.webhook || f.polling, 'Declare a webhook, polling, or both');
+
+/** What Loops writes back to the CRM timeline (Loops owns these). */
+export const WriteBackKind = z.enum(['call', 'transcript', 'meeting', 'note', 'action', 'campaignReply']);
+export const WriteBack = z.partialRecord(
+  WriteBackKind,
+  z.object({ method: z.enum(['POST', 'PUT', 'PATCH']), path: PathTemplate }),
+);
+
+export const SyncLimits = z.object({
+  requestsPerSecond: z.number().positive().max(1000),
+  burst: z.number().int().positive().max(10000).optional(),
+  retryAfterHeader: z.string().default('Retry-After'),
+});
+
+export const SyncManifest = z.object({
+  baseUrl: HttpsUrl,
+  auth: SyncAuth,
+  objects: z.array(SyncObject).min(1),
+  links: z.array(SyncLink).default([]),
+  changeFeed: ChangeFeed,
+  writeBack: WriteBack.default({}),
+  limits: SyncLimits,
+});
+export type SyncManifest = z.infer<typeof SyncManifest>;
+
+// ── ui: the LoopKit half ────────────────────────────────────────────────────────
+
+export const SLOTS = [
+  'recordPanel',
+  'recordTab',
+  'recordAction',
+  'bulkAction',
+  'composerButton',
+  'messageAction',
+  'loopCard',
+  'linkCard',
+  'crmPanelItem',
+  'settingsPage',
+  'dashboardTile',
+  'simiTool',
+] as const;
+export const Slot = z.enum(SLOTS);
+export type Slot = z.infer<typeof Slot>;
+
+/** Things an app may do in Loops (`LoopKit.do`), and the scope each needs. */
+export const DOES = { 'record.note': 'notes:write', 'loop.post': 'loops:write', 'action.add': 'actions:write' } as const;
+export const Does = z.enum(Object.keys(DOES) as [keyof typeof DOES, ...(keyof typeof DOES)[]]);
+
+/** A field the app reads: `contact.email`, `deal.value`, `loop.title`. */
+export const FieldPath = z.string().regex(/^(contact|company|lead|deal|loop)\.[a-zA-Z][a-zA-Z0-9_]*$/, 'Like contact.email');
+
+/** Where a sent value comes from: a granted field, the link, or the app's settings. */
+export const ValueSource = z
+  .string()
+  .regex(/^((contact|company|lead|deal|loop)\.[a-zA-Z][a-zA-Z0-9_]*|link\.path\.[a-zA-Z][a-zA-Z0-9_]*|settings\.[a-zA-Z][a-zA-Z0-9_]*)$/);
+
+/** A declared response field type: string, number, boolean, date, or enum:a|b|c. */
+export const ReturnType = z.string().regex(/^(string|number|boolean|date|enum:[A-Za-z0-9_-]+(\|[A-Za-z0-9_-]+)*)$/);
+
+export const Endpoint = z.object({
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+  url: HttpsUrl,
+  sends: z.record(z.string(), ValueSource).default({}),
+  returns: z.record(z.string(), ReturnType),
+});
+export type Endpoint = z.infer<typeof Endpoint>;
+
+export const Setting = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('secret'), label: z.string().min(1).max(80) }),
+  z.object({ type: z.literal('text'), label: z.string().min(1).max(80) }),
+  z.object({ type: z.literal('choice'), label: z.string().min(1).max(80), options: z.array(z.string().min(1)).min(1) }),
+]);
+
+export const UiManifest = z.object({
+  apiVersion: z.literal(1),
+  slots: z.array(Slot).min(1),
+  uses: z.array(FieldPath).default([]),
+  does: z.array(Does).default([]),
+  hears: z.array(EventTypeSchema).default([]),
+  /** Link patterns the app makes cards for, e.g. *.acme.com/report/* (needs the linkCard slot). */
+  links: z.array(z.string().min(3)).default([]),
+  settings: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), Setting).default({}),
+  endpoints: z.record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/), Endpoint).default({}),
+  /** Entry file of the LoopKit source, relative to the app folder. */
+  entry: z.string().default('src/app.tsx'),
+});
+export type UiManifest = z.infer<typeof UiManifest>;
+
+// ── The manifest ────────────────────────────────────────────────────────────────
+
+export const Developer = z.object({
+  name: z.string().min(1).max(80),
+  email: z.email(),
+  website: HttpsUrl.optional(),
+});
+
+export const Visibility = z.enum(['private', 'public']);
+export type Visibility = z.infer<typeof Visibility>;
+
+export const ManifestV1 = z
+  .object({
+    manifestVersion: z.literal(1),
+    id: AppId,
+    name: z.string().min(2).max(40),
+    version: SemVer,
+    summary: z.string().min(1).max(140),
+    description: z.string().max(4000).optional(),
+    developer: Developer,
+    visibility: Visibility.default('private'),
+    scopes: z.array(ScopeSchema).default([]),
+    sync: SyncManifest.optional(),
+    ui: UiManifest.optional(),
+  })
+  .superRefine((m, ctx) => {
+    if (!m.sync && !m.ui) ctx.addIssue({ code: 'custom', message: 'An app needs a sync half, a ui half, or both', path: [] });
+    const granted = new Set(expandScopes(m.scopes));
+    const need = (scope: Scope, path: (string | number)[], why: string) => {
+      if (!granted.has(scope)) ctx.addIssue({ code: 'custom', path, message: `${why} needs the ${scope} scope` });
+    };
+    if (new Set(m.scopes).size !== m.scopes.length) ctx.addIssue({ code: 'custom', path: ['scopes'], message: 'Scopes are listed twice' });
+
+    m.sync?.objects.forEach((o, i) => need(RECORD_SCOPE[o.ours].write, ['sync', 'objects', i, 'ours'], `Syncing ${o.ours}`));
+
+    if (m.ui) {
+      m.ui.uses.forEach((f, i) => need(RECORD_SCOPE[f.split('.')[0]].read, ['ui', 'uses', i], `Reading ${f}`));
+      m.ui.does.forEach((d, i) => need(DOES[d], ['ui', 'does', i], `Doing ${d}`));
+      m.ui.hears.forEach((e, i) => {
+        const s = scopeForEvent(e);
+        if (s) need(s, ['ui', 'hears', i], `Hearing ${e}`);
+      });
+      if (m.ui.links.length && !m.ui.slots.includes('linkCard'))
+        ctx.addIssue({ code: 'custom', path: ['ui', 'links'], message: 'Links need the linkCard slot' });
+      const uses = new Set(m.ui.uses);
+      const settings = m.ui.settings;
+      for (const [name, ep] of Object.entries(m.ui.endpoints)) {
+        for (const [arg, src] of Object.entries(ep.sends)) {
+          const path = ['ui', 'endpoints', name, 'sends', arg];
+          if (src.startsWith('settings.')) {
+            if (!settings[src.slice(9)]) ctx.addIssue({ code: 'custom', path, message: `${src} is not a declared setting` });
+          } else if (src.startsWith('link.')) {
+            if (!m.ui.slots.includes('linkCard')) ctx.addIssue({ code: 'custom', path, message: 'link values need the linkCard slot' });
+          } else if (!uses.has(src)) {
+            ctx.addIssue({ code: 'custom', path, message: `${src} is sent but not declared in ui.uses` });
+          }
+        }
+      }
+    }
+  });
+export type ManifestV1 = z.infer<typeof ManifestV1>;
+export type ManifestV1Input = z.input<typeof ManifestV1>;
+
+/** The manifest file name in an app folder. */
+export const MANIFEST_FILE = 'loops.manifest.json';
+
+/** Parse a manifest; errors come back as plain lines ("ui.uses.0: Reading contact.email needs the contacts:read scope"). */
+export function parseManifest(input: unknown): { ok: true; manifest: ManifestV1 } | { ok: false; errors: string[] } {
+  const r = ManifestV1.safeParse(input);
+  if (r.success) return { ok: true, manifest: r.data };
+  return { ok: false, errors: r.error.issues.map((i) => `${i.path.join('.') || '(manifest)'}: ${i.message}`) };
+}

package/src/registry.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { AppId, InstallId, SemVer, Timestamp, UserId, VersionId, WorkspaceId } from './ids.ts';
+import { ManifestV1, Visibility } from './manifest.ts';
+import { ScopeSchema } from './scopes.ts';
+
+/**
+ * Records the control plane (`backend-apps-registry`, D1) keeps, and the RPC surfaces Workers call each other through
+ * (Workers RPC: `WorkerEntrypoint` + service binding; POC passed 11 Nov 2026). Skill §3, §8a.
+ */
+
+// ── Review states (skill §8a) ───────────────────────────────────────────────────
+
+export const REVIEW_STATES = ['submitted', 'checking', 'ai_review', 'awaiting_human', 'approved', 'rejected'] as const;
+export const ReviewState = z.enum(REVIEW_STATES);
+export type ReviewState = z.infer<typeof ReviewState>;
+
+/** Allowed moves. Anything else is refused by the registry. A failure at any step = rejected, instantly. */
+export const REVIEW_TRANSITIONS: Record<ReviewState, readonly ReviewState[]> = {
+  submitted: ['checking', 'rejected'],
+  checking: ['ai_review', 'rejected'],
+  ai_review: ['awaiting_human', 'rejected'],
+  awaiting_human: ['approved', 'rejected'],
+  approved: [],
+  rejected: [],
+};
+
+export function canMove(from: ReviewState, to: ReviewState): boolean {
+  return REVIEW_TRANSITIONS[from].includes(to);
+}
+
+// ── Records ─────────────────────────────────────────────────────────────────────
+
+export const AppRecord = z.object({
+  id: AppId,
+  name: z.string(),
+  summary: z.string(),
+  /** The workspace that owns the app (the developer's workspace). */
+  ownerWorkspaceId: WorkspaceId,
+  createdBy: UserId,
+  visibility: Visibility,
+  /** Latest approved version, shown in the Marketplace; null until one is approved. */
+  liveVersionId: VersionId.nullable(),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type AppRecord = z.infer<typeof AppRecord>;
+
+export const AppVersionRecord = z.object({
+  id: VersionId,
+  appId: AppId,
+  version: SemVer,
+  manifest: ManifestV1,
+  state: ReviewState,
+  /** Plain-words reasons for a rejection, one per line item. */
+  reasons: z.array(z.string()).default([]),
+  /** Artifacts repo commit this version was built from (null in L0 until submit pushes source). */
+  sourceCommit: z.string().nullable(),
+  submittedBy: UserId,
+  submittedAt: Timestamp,
+  decidedBy: UserId.nullable(),
+  decidedAt: Timestamp.nullable(),
+});
+export type AppVersionRecord = z.infer<typeof AppVersionRecord>;
+
+export const InstallStatus = z.enum(['active', 'paused', 'uninstalled']);
+export type InstallStatus = z.infer<typeof InstallStatus>;
+
+export const InstallRecord = z.object({
+  id: InstallId,
+  appId: AppId,
+  versionId: VersionId,
+  workspaceId: WorkspaceId,
+  installedBy: UserId,
+  /** Scopes the admin approved on the consent sheet. A new scope in a later version needs approval again. */
+  grantedScopes: z.array(ScopeSchema),
+  status: InstallStatus,
+  /** True for a `loops dev` install: visible only to that developer, never reviewed. */
+  dev: z.boolean().default(false),
+  createdAt: Timestamp,
+  updatedAt: Timestamp,
+});
+export type InstallRecord = z.infer<typeof InstallRecord>;
+
+/** A Marketplace card: what the window lists. */
+export const Listing = z.object({
+  appId: AppId,
+  name: z.string(),
+  summary: z.string(),
+  developerName: z.string(),
+  version: SemVer,
+  scopes: z.array(ScopeSchema),
+  installed: z.boolean(),
+});
+export type Listing = z.infer<typeof Listing>;
+
+// ── Who is calling (resolved from Better Auth + /api/me at the edge) ────────────
+
+export const Caller = z.object({
+  workspaceId: WorkspaceId,
+  userId: UserId,
+  role: z.enum(['owner', 'admin', 'member']),
+  developer: z.boolean(),
+  /** Recruitly SUPER user; the platform is behind a flag, SUPER only, in L0. */
+  superUser: z.boolean(),
+});
+export type Caller = z.infer<typeof Caller>;
+
+// ── RPC surfaces (typed contracts for service bindings) ─────────────────────────
+
+/** `backend-apps-registry` default WorkerEntrypoint. */
+export interface RegistryRpc {
+  submit(caller: Caller, manifest: unknown): Promise<{ ok: true; version: AppVersionRecord } | { ok: false; errors: string[] }>;
+  listMarketplace(caller: Caller): Promise<Listing[]>;
+  getApp(caller: Caller, appId: string): Promise<{ app: AppRecord; versions: AppVersionRecord[] } | null>;
+  install(caller: Caller, appId: string, grantedScopes: string[]): Promise<{ ok: true; install: InstallRecord } | { ok: false; error: string }>;
+  uninstall(caller: Caller, installId: string): Promise<{ ok: boolean }>;
+  listInstalls(caller: Caller): Promise<InstallRecord[]>;
+  /** Human review (System Admin, SUPER only). */
+  decide(caller: Caller, versionId: string, decision: 'approved' | 'rejected', reason?: string): Promise<{ ok: boolean; error?: string }>;
+}
+
+/** `backend-apps-engine` default WorkerEntrypoint. */
+export interface EngineRpc {
+  /** Wake the install's Agent after the registry wrote the install row. */
+  installed(install: InstallRecord): Promise<{ ok: true }>;
+  uninstalled(installId: string): Promise<{ ok: true }>;
+  health(): Promise<{ ok: true; version: string }>;
+}

package/src/scopes.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * Every permission an app can ask for. One list for REST, MCP, events and LoopKit (skill §8 "one scope list").
+ * Only ever ADD to this list (versioning promise). `consent` is the plain-words line on the install sheet
+ * ("<App> can …"), sentence case.
+ */
+export const SCOPES = {
+  'contacts:read': 'See contacts: names, emails, phone numbers and their company',
+  'contacts:write': 'Add and change contacts',
+  'companies:read': 'See companies',
+  'companies:write': 'Add and change companies',
+  'leads:read': 'See leads',
+  'leads:write': 'Add and change leads',
+  'deals:read': 'See deals and the people on them',
+  'deals:write': 'Add and change deals',
+  'notes:write': 'Write notes on records, marked with the app’s name',
+  'actions:write': 'Add Actions for people in your workspace',
+  'loops:read': 'Read messages in loops the app is added to',
+  'loops:write': 'Post in loops the app is added to, marked with the app’s name',
+  'calls:read': 'See calls and their transcripts',
+  'meetings:read': 'See meetings and their notes',
+  'webhooks:manage': 'Send events from your workspace to the app',
+} as const;
+
+export type Scope = keyof typeof SCOPES;
+export const SCOPE_NAMES = Object.keys(SCOPES) as [Scope, ...Scope[]];
+export const ScopeSchema = z.enum(SCOPE_NAMES);
+
+/** The consent line for a scope, e.g. on the install sheet. */
+export function consentLine(scope: Scope): string {
+  return SCOPES[scope];
+}
+
+/** A `write` scope implies its `read` (asking for contacts:write shows both lines). */
+export function expandScopes(scopes: readonly Scope[]): Scope[] {
+  const out = new Set<Scope>(scopes);
+  for (const s of scopes) {
+    const [res, op] = s.split(':');
+    const read = `${res}:read`;
+    if (op === 'write' && read in SCOPES) out.add(read as Scope);
+  }
+  return SCOPE_NAMES.filter((s) => out.has(s));
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.