@withloops.ai/contracts 0.1.0 → 0.2.0

package/dist/manifest.js

@@ -0,0 +1,215 @@
+import { z } from 'zod';
+import { AppId, HttpsUrl, SemVer } from "./ids.js";
+import { EventTypeSchema, scopeForEvent } from "./events.js";
+import { ScopeSchema, expandScopes } from "./scopes.js";
+/**
+ * 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']);
+const RECORD_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(),
+    }),
+]);
+/** 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,
+});
+// ── ui: the LoopKit half ────────────────────────────────────────────────────────
+export const SLOTS = [
+    'recordPanel',
+    'recordTab',
+    'recordAction',
+    'bulkAction',
+    'composerButton',
+    'messageAction',
+    'loopCard',
+    'linkCard',
+    'crmPanelItem',
+    'settingsPage',
+    'dashboardTile',
+    'simiTool',
+];
+export const Slot = z.enum(SLOTS);
+/** 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' };
+export const Does = z.enum(Object.keys(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 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'),
+});
+// ── 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 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, path, why) => {
+        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` });
+                }
+            }
+        }
+    }
+});
+/** 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) {
+    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/dist/registry.d.ts

@@ -0,0 +1,368 @@
+import { z } from 'zod';
+/**
+ * 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.
+ */
+export declare const REVIEW_STATES: readonly ["submitted", "checking", "ai_review", "awaiting_human", "approved", "rejected"];
+export declare const ReviewState: z.ZodEnum<{
+    submitted: "submitted";
+    checking: "checking";
+    ai_review: "ai_review";
+    awaiting_human: "awaiting_human";
+    approved: "approved";
+    rejected: "rejected";
+}>;
+export type ReviewState = z.infer<typeof ReviewState>;
+/** Allowed moves. Anything else is refused by the registry. A failure at any step = rejected, instantly. */
+export declare const REVIEW_TRANSITIONS: Record<ReviewState, readonly ReviewState[]>;
+export declare function canMove(from: ReviewState, to: ReviewState): boolean;
+export declare const AppRecord: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    summary: z.ZodString;
+    ownerWorkspaceId: z.ZodString;
+    createdBy: z.ZodString;
+    visibility: z.ZodEnum<{
+        private: "private";
+        public: "public";
+    }>;
+    liveVersionId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AppRecord = z.infer<typeof AppRecord>;
+export declare const AppVersionRecord: z.ZodObject<{
+    id: z.ZodString;
+    appId: z.ZodString;
+    version: z.ZodString;
+    manifest: z.ZodObject<{
+        manifestVersion: z.ZodLiteral<1>;
+        id: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodString;
+        summary: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        developer: z.ZodObject<{
+            name: z.ZodString;
+            email: z.ZodEmail;
+            website: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strip>;
+        visibility: z.ZodDefault<z.ZodEnum<{
+            private: "private";
+            public: "public";
+        }>>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            "contacts:read": "contacts:read";
+            "contacts:write": "contacts:write";
+            "companies:read": "companies:read";
+            "companies:write": "companies:write";
+            "leads:read": "leads:read";
+            "leads:write": "leads:write";
+            "deals:read": "deals:read";
+            "deals:write": "deals:write";
+            "notes:write": "notes:write";
+            "actions:write": "actions:write";
+            "loops:read": "loops:read";
+            "loops:write": "loops:write";
+            "calls:read": "calls:read";
+            "meetings:read": "meetings:read";
+            "webhooks:manage": "webhooks:manage";
+        }>>>;
+        sync: z.ZodOptional<z.ZodObject<{
+            baseUrl: z.ZodURL;
+            auth: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"oauth2">;
+                authorizeUrl: z.ZodURL;
+                tokenUrl: z.ZodURL;
+                scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                refresh: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"apiKey">;
+                header: z.ZodDefault<z.ZodString>;
+                prefix: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "type">;
+            objects: z.ZodArray<z.ZodObject<{
+                theirs: z.ZodString;
+                ours: z.ZodEnum<{
+                    CONTACT: "CONTACT";
+                    COMPANY: "COMPANY";
+                    LEAD: "LEAD";
+                    DEAL: "DEAL";
+                }>;
+                list: z.ZodObject<{
+                    path: z.ZodString;
+                    itemsPath: z.ZodDefault<z.ZodString>;
+                    cursorParam: z.ZodOptional<z.ZodString>;
+                    nextCursorPath: z.ZodOptional<z.ZodString>;
+                    updatedSinceParam: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>;
+                fields: z.ZodArray<z.ZodObject<{
+                    theirs: z.ZodString;
+                    ours: z.ZodString;
+                    owner: z.ZodEnum<{
+                        theirs: "theirs";
+                        ours: "ours";
+                    }>;
+                }, z.core.$strip>>;
+                match: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+            links: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                from: z.ZodEnum<{
+                    CONTACT: "CONTACT";
+                    COMPANY: "COMPANY";
+                    LEAD: "LEAD";
+                    DEAL: "DEAL";
+                }>;
+                to: z.ZodEnum<{
+                    CONTACT: "CONTACT";
+                    COMPANY: "COMPANY";
+                    LEAD: "LEAD";
+                    DEAL: "DEAL";
+                }>;
+                theirs: z.ZodString;
+                role: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            changeFeed: z.ZodObject<{
+                webhook: z.ZodOptional<z.ZodObject<{
+                    signature: z.ZodObject<{
+                        scheme: z.ZodEnum<{
+                            "hmac-sha256": "hmac-sha256";
+                            "hmac-sha1": "hmac-sha1";
+                        }>;
+                        header: z.ZodString;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+                polling: z.ZodOptional<z.ZodObject<{
+                    everyMinutes: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+            writeBack: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+                call: "call";
+                transcript: "transcript";
+                meeting: "meeting";
+                note: "note";
+                action: "action";
+                campaignReply: "campaignReply";
+            }> & z.core.$partial, z.ZodObject<{
+                method: z.ZodEnum<{
+                    POST: "POST";
+                    PUT: "PUT";
+                    PATCH: "PATCH";
+                }>;
+                path: z.ZodString;
+            }, z.core.$strip>>>;
+            limits: z.ZodObject<{
+                requestsPerSecond: z.ZodNumber;
+                burst: z.ZodOptional<z.ZodNumber>;
+                retryAfterHeader: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        ui: z.ZodOptional<z.ZodObject<{
+            apiVersion: z.ZodLiteral<1>;
+            slots: z.ZodArray<z.ZodEnum<{
+                recordPanel: "recordPanel";
+                recordTab: "recordTab";
+                recordAction: "recordAction";
+                bulkAction: "bulkAction";
+                composerButton: "composerButton";
+                messageAction: "messageAction";
+                loopCard: "loopCard";
+                linkCard: "linkCard";
+                crmPanelItem: "crmPanelItem";
+                settingsPage: "settingsPage";
+                dashboardTile: "dashboardTile";
+                simiTool: "simiTool";
+            }>>;
+            uses: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            does: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                "record.note": "record.note";
+                "loop.post": "loop.post";
+                "action.add": "action.add";
+            }>>>;
+            hears: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                "contact.created": "contact.created";
+                "contact.updated": "contact.updated";
+                "contact.deleted": "contact.deleted";
+                "company.created": "company.created";
+                "company.updated": "company.updated";
+                "company.deleted": "company.deleted";
+                "lead.created": "lead.created";
+                "lead.updated": "lead.updated";
+                "lead.deleted": "lead.deleted";
+                "deal.created": "deal.created";
+                "deal.updated": "deal.updated";
+                "deal.deleted": "deal.deleted";
+                "loop.message": "loop.message";
+                "loop.call.ended": "loop.call.ended";
+                "meeting.ended": "meeting.ended";
+                "app.installed": "app.installed";
+                "app.uninstalled": "app.uninstalled";
+            }>>>;
+            links: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            settings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"secret">;
+                label: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"text">;
+                label: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"choice">;
+                label: z.ZodString;
+                options: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>], "type">>>;
+            endpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                method: z.ZodEnum<{
+                    POST: "POST";
+                    PUT: "PUT";
+                    PATCH: "PATCH";
+                    GET: "GET";
+                    DELETE: "DELETE";
+                }>;
+                url: z.ZodURL;
+                sends: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                returns: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, z.core.$strip>>>;
+            entry: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    state: z.ZodEnum<{
+        submitted: "submitted";
+        checking: "checking";
+        ai_review: "ai_review";
+        awaiting_human: "awaiting_human";
+        approved: "approved";
+        rejected: "rejected";
+    }>;
+    reasons: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    sourceCommit: z.ZodNullable<z.ZodString>;
+    submittedBy: z.ZodString;
+    submittedAt: z.ZodISODateTime;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type AppVersionRecord = z.infer<typeof AppVersionRecord>;
+export declare const InstallStatus: z.ZodEnum<{
+    active: "active";
+    paused: "paused";
+    uninstalled: "uninstalled";
+}>;
+export type InstallStatus = z.infer<typeof InstallStatus>;
+export declare const InstallRecord: z.ZodObject<{
+    id: z.ZodString;
+    appId: z.ZodString;
+    versionId: z.ZodString;
+    workspaceId: z.ZodString;
+    installedBy: z.ZodString;
+    grantedScopes: z.ZodArray<z.ZodEnum<{
+        "contacts:read": "contacts:read";
+        "contacts:write": "contacts:write";
+        "companies:read": "companies:read";
+        "companies:write": "companies:write";
+        "leads:read": "leads:read";
+        "leads:write": "leads:write";
+        "deals:read": "deals:read";
+        "deals:write": "deals:write";
+        "notes:write": "notes:write";
+        "actions:write": "actions:write";
+        "loops:read": "loops:read";
+        "loops:write": "loops:write";
+        "calls:read": "calls:read";
+        "meetings:read": "meetings:read";
+        "webhooks:manage": "webhooks:manage";
+    }>>;
+    status: z.ZodEnum<{
+        active: "active";
+        paused: "paused";
+        uninstalled: "uninstalled";
+    }>;
+    dev: z.ZodDefault<z.ZodBoolean>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type InstallRecord = z.infer<typeof InstallRecord>;
+/** A Marketplace card: what the window lists. */
+export declare const Listing: z.ZodObject<{
+    appId: z.ZodString;
+    name: z.ZodString;
+    summary: z.ZodString;
+    developerName: z.ZodString;
+    version: z.ZodString;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "contacts:read": "contacts:read";
+        "contacts:write": "contacts:write";
+        "companies:read": "companies:read";
+        "companies:write": "companies:write";
+        "leads:read": "leads:read";
+        "leads:write": "leads:write";
+        "deals:read": "deals:read";
+        "deals:write": "deals:write";
+        "notes:write": "notes:write";
+        "actions:write": "actions:write";
+        "loops:read": "loops:read";
+        "loops:write": "loops:write";
+        "calls:read": "calls:read";
+        "meetings:read": "meetings:read";
+        "webhooks:manage": "webhooks:manage";
+    }>>;
+    installed: z.ZodBoolean;
+}, z.core.$strip>;
+export type Listing = z.infer<typeof Listing>;
+export declare const Caller: z.ZodObject<{
+    workspaceId: z.ZodString;
+    userId: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        member: "member";
+    }>;
+    developer: z.ZodBoolean;
+    superUser: z.ZodBoolean;
+}, z.core.$strip>;
+export type Caller = z.infer<typeof Caller>;
+/** `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[]>;
+    /** Apps owned by the caller's workspace (`GET /v1/developer/apps`). Added in 0.2.0. */
+    listApps(caller: Caller): Promise<AppRecord[]>;
+    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/dist/registry.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { AppId, InstallId, SemVer, Timestamp, UserId, VersionId, WorkspaceId } from "./ids.js";
+import { ManifestV1, Visibility } from "./manifest.js";
+import { ScopeSchema } from "./scopes.js";
+/**
+ * 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'];
+export const ReviewState = z.enum(REVIEW_STATES);
+/** Allowed moves. Anything else is refused by the registry. A failure at any step = rejected, instantly. */
+export const REVIEW_TRANSITIONS = {
+    submitted: ['checking', 'rejected'],
+    checking: ['ai_review', 'rejected'],
+    ai_review: ['awaiting_human', 'rejected'],
+    awaiting_human: ['approved', 'rejected'],
+    approved: [],
+    rejected: [],
+};
+export function canMove(from, to) {
+    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 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 const InstallStatus = z.enum(['active', 'paused', 'uninstalled']);
+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,
+});
+/** 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(),
+});
+// ── 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(),
+});