@palettelab/cli 0.3.51 → 0.3.53

package/README.md

@@ -783,10 +783,19 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 Inspect and generate OS-broker service integrations declared through
 `provides` and `consumes` in `palette-plugin.json`.
 
+Use this command family when one Palette app needs governed data, approvals, or
+events from another app. The CLI keeps the app manifest, local mocks, provider
+schema files, and generated clients aligned with the broker contract.
+
 ```bash
+pltt init employee-management --template provider-app
+pltt init leave-management --template consumer-app
+pltt services sync
 pltt services list --env staging
 pltt services add hr/v1#approvalChain.get --reason "Route approvals through HR"
 pltt services add hr/v1#hierarchy.updated --event --optional
+pltt services mock hr/v1#approvalChain.get
+pltt services test --offline
 pltt services pull --env staging
 pltt services scaffold approvalChain.get
 ```
@@ -795,13 +804,48 @@ Subcommands:
 
 - `list`: fetches `/api/v1/os-broker/catalog` from the selected environment and prints services/events available to the current org. Use `--json` for the raw catalog.
 - `add <namespace/version#name>`: appends a consumed service target to `consumes.services`. Use `--event` or `--type event` for `consumes.events`, `--optional` for non-required dependencies, and `--reason <text>` to record why the dependency is needed.
-- `pull`: reads `consumes.services` and `consumes.events`, fetches JSON Schemas from `/api/v1/os-broker/schemas`, and generates `.palette/types/services.ts` plus `.palette/python/services.py`.
+- `sync`: scans backend `@service(...)` decorators and updates `provides.services` so provider contracts do not drift from code.
+- `mock <namespace/version#name>`: adds a local response to `.palette/app-services.local.json` for `pltt dev`.
+- `test`: checks local consumes/provides/mocks and, unless `--offline` is set, verifies consumed targets against `/api/v1/os-broker/schemas`.
+- `pull`: reads `consumes.services` and `consumes.events`, fetches JSON Schemas from `/api/v1/os-broker/schemas`, and generates nested `.palette/types/services.ts` plus Python helpers in `.palette/python/services.py`.
 - `scaffold <method>`: adds a provider method to `provides.services`, creates `schemas/<method>.in.json` and `schemas/<method>.out.json`, and writes a Python handler stub under `broker/`.
 
 Generated TypeScript clients use the SDK's default `palette` client. Generated
 Python clients call `palette_sdk.services(ctx)`, so backend routes still pass
 through Palette's broker permission and install checks.
 
+Recommended workflow:
+
+1. Provider app: implement backend methods with `@service(...)` and declare
+   event topics in `provides.events`.
+2. Provider app: run `pltt services sync` or `pltt services scaffold <method>`
+   to keep manifest methods and schema files current.
+3. Consumer app: run `pltt services add <target>` for each consumed service or
+   event, including a `--reason` for review and install UI.
+4. Consumer app: use `pltt services mock <target>` and `pltt services test
+   --offline` during local development.
+5. Consumer app: use `pltt services pull --env staging` to generate typed
+   clients from the live `/api/v1/os-broker/schemas` endpoint.
+6. Run `pltt test` before publish; contract checks include local
+   `provides`/`consumes`, mocks, schemas, and dependency-policy validation.
+
+Runtime behavior:
+
+- Service calls go through `POST /api/v1/os-broker/dispatch`.
+- Event publishes go through `POST /api/v1/os-broker/events/emit`.
+- Event subscriptions use `GET /api/v1/os-broker/events/stream`.
+- Catalog and generated client metadata come from `/api/v1/os-broker/catalog`
+  and `/api/v1/os-broker/schemas`.
+- Installs use `/api/v1/app-installs/<app_id>/dependency-plan` and can include
+  required provider apps with `?include_dependencies=true`.
+- Org owners/admins can revoke or restore individual cross-app grants from
+  Settings > Apps; the broker checks those grants on every call and stream.
+
+Provider methods can use inline JSON Schema objects or schema file paths in
+`input_schema`, `input`, `output_schema`, and `output`. Event topics can use
+`schema` or `payload_schema`. The CLI scaffolds schema files by default because
+they are easier to review and reuse for generated clients.
+
 ## Global Flags
 
 - `--json` emits machine-readable output for `package`, `publish`, `status`, `logs`, `test`, and `version`.

package/backend-sdk/palette_sdk/__init__.py

@@ -38,6 +38,8 @@ from palette_sdk import events as events_module  # also exposed as `palette_sdk.
 from palette_sdk.events import Event, EventPublisher, subscribe_event
 from palette_sdk.services import (
     BrokerCallError,
+    CrossAppGrantError,
+    MissingDependencyError,
     ServicesClient,
     service,
     services,
@@ -89,6 +91,8 @@ __all__ = [
     "services",
     "ServicesClient",
     "BrokerCallError",
+    "CrossAppGrantError",
+    "MissingDependencyError",
     "get_config",
     "require_config",
     "sign_webhook",

package/backend-sdk/palette_sdk/events.py

@@ -98,3 +98,19 @@ class EventPublisher:
     # Alias: `events.emit(...)` reads more naturally for app-owned events.
     async def emit(self, topic: str, payload: dict[str, Any] | None = None) -> None:
         await self.publish(topic, payload)
+
+    async def publish_durable(self, topic: str, payload: dict[str, Any] | None = None) -> None:
+        """Publish a business event through the broker durable-event API.
+
+        Current platform versions route this through the standard broker event
+        publisher. The method is intentionally stable so apps can adopt durable
+        delivery without changing call sites when queue-backed delivery is
+        enabled by the platform.
+        """
+        if hasattr(self._adapter, "publish_durable"):
+            await self._adapter.publish_durable(topic, payload or {})
+            return
+        await self.publish(topic, payload)
+
+    async def emit_durable(self, topic: str, payload: dict[str, Any] | None = None) -> None:
+        await self.publish_durable(topic, payload)

package/backend-sdk/palette_sdk/manifest.py

@@ -113,6 +113,8 @@ class AppServiceMethodSpec(BaseModel):
     output: dict[str, Any] | str | None = None
     route_method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] | None = None
     route_path: str | None = None
+    deprecated: bool = False
+    replacement: str | None = None
 
 
 class ProvidedAppServiceSpec(BaseModel):

package/backend-sdk/palette_sdk/services.py

@@ -35,11 +35,15 @@ ServiceHandler = Callable[[Any, dict[str, Any]], Awaitable[Any]]
 class ServiceDecl:
     name: str
     handler: ServiceHandler
+    namespace: str | None = None
+    version: str | None = None
     scope: str | None = None
     label: str | None = None
     description: str | None = None
     input_schema: dict | None = None
     output_schema: dict | None = None
+    deprecated: bool = False
+    replacement: str | None = None
 
 
 _pending: list[ServiceDecl] = []
@@ -48,11 +52,17 @@ _pending: list[ServiceDecl] = []
 def service(
     name: str,
     *,
+    namespace: str | None = None,
+    version: str | None = None,
     scope: str | None = None,
     label: str | None = None,
     description: str | None = None,
     input_schema: dict | None = None,
+    input: dict | None = None,
     output_schema: dict | None = None,
+    output: dict | None = None,
+    deprecated: bool = False,
+    replacement: str | None = None,
 ) -> Callable[[ServiceHandler], ServiceHandler]:
     """Mark an async function as a broker-callable service method."""
 
@@ -61,11 +71,15 @@ def service(
             ServiceDecl(
                 name=name,
                 handler=fn,
+                namespace=namespace,
+                version=version,
                 scope=scope,
                 label=label,
                 description=description,
-                input_schema=input_schema,
-                output_schema=output_schema,
+                input_schema=input_schema or input,
+                output_schema=output_schema or output,
+                deprecated=deprecated,
+                replacement=replacement,
             )
         )
         return fn
@@ -84,6 +98,14 @@ class BrokerCallError(RuntimeError):
     """Raised when the broker rejects or fails a service call."""
 
 
+class MissingDependencyError(BrokerCallError):
+    """Raised by generated clients when a required provider app is missing."""
+
+
+class CrossAppGrantError(BrokerCallError):
+    """Raised by generated clients when an org admin revoked a cross-app grant."""
+
+
 class ServicesClient:
     """Returned by `services(ctx)`. Use `.call(target, payload)` or sugar `.proxy(...)`."""
 
@@ -139,6 +161,8 @@ def services(ctx_or_adapter: Any) -> ServicesClient:
 
 __all__ = [
     "BrokerCallError",
+    "CrossAppGrantError",
+    "MissingDependencyError",
     "ServiceDecl",
     "ServicesClient",
     "drain_pending_services",

package/docs/python-backend-sdk.md

@@ -693,7 +693,18 @@ token = await ctx.connections.access_token("google_calendar")
 ## 11. App-To-App Services
 
 Apps can expose governed broker services and events, then consume them from
-other installed apps without knowing another app's URL.
+other installed apps without knowing another app's URL. The broker is the only
+supported integration path for cross-app business data. Do not read another
+app's database tables and do not call another app's private backend route
+directly.
+
+Palette enforces the app-to-app contract in four places:
+
+- Manifest review: providers declare `provides`, consumers declare `consumes`.
+- Install: required provider apps are resolved before the consumer is activated.
+- Org grants: owners/admins can allow or revoke each consumed service/event.
+- Runtime: every service call, event emit, and event stream is checked against
+  same-org install state, `consumes`, grants, and JSON Schemas.
 
 Provider apps declare a namespace and callable methods with `provides`:
 
@@ -705,25 +716,40 @@ Provider apps declare a namespace and callable methods with `provides`:
       {
         "id": "hr.directory",
         "methods": [
-          { "name": "approvalChain.get", "input_schema": "schemas/approval-chain.input.json" }
+          {
+            "name": "approvalChain.get",
+            "input_schema": "schemas/approval-chain.input.json",
+            "output_schema": "schemas/approval-chain.output.json"
+          }
         ]
       }
     ],
-    "events": [{ "topic": "hierarchy.updated" }]
+    "events": [
+      {
+        "topic": "hierarchy.updated",
+        "schema": "schemas/hierarchy-updated.json"
+      }
+    ]
   }
 }
 ```
 
-Expose the handler with `@service`:
+Expose the handler with `@service`. The platform registers handlers when the
+plugin loads and injects a full `PluginContext` at dispatch time:
 
 ```python
 from palette_sdk import PluginContext, service
 
-@service("approvalChain.get")
+@service("approvalChain.get", scope="members:read")
 async def approval_chain(ctx: PluginContext, payload: dict) -> dict:
     return {"approvers": [{"user_id": ctx.user_id, "step": 1}]}
 ```
 
+If a method also declares `route_method` and `route_path`, Palette can fall back
+to signed internal HTTP transport when no in-process handler is registered. New
+provider apps should prefer `@service(...)` because it avoids URL coupling and
+keeps dispatch inside the broker lifecycle.
+
 Consumers declare qualified targets with `consumes`:
 
 ```json
@@ -746,8 +772,11 @@ Consumers declare qualified targets with `consumes`:
 The CLI can update the manifest and generate typed clients for those targets:
 
 ```bash
+pltt services sync
 pltt services add hr/v1#approvalChain.get --reason "Route leave approvals through HR"
 pltt services add hr/v1#hierarchy.updated --event --optional
+pltt services mock hr/v1#approvalChain.get
+pltt services test --offline
 pltt services pull --env staging
 ```
 
@@ -764,12 +793,42 @@ from palette_sdk import services
 
 chain = await services(ctx).call("hr/v1#approvalChain.get", {"user_id": ctx.user_id})
 await ctx.events.emit("leave/v1#leave.requested", {"approval_chain": chain})
+await ctx.events.emit_durable("leave/v1#leave.requested", {"approval_chain": chain})
 ```
 
 At install time, Palette checks required `consumes` targets and can show the
 provider apps that must also be installed. The org-level grant is saved on the
 install and the broker checks it on every call, emit, or event stream.
 
+Useful platform endpoints when building or debugging integrations:
+
+```text
+GET  /api/v1/app-installs/{app_id}/dependency-plan
+POST /api/v1/app-installs/{app_id}?include_dependencies=true
+GET  /api/v1/app-installs/{app_id}/cross-app-grants
+PATCH /api/v1/app-installs/{app_id}/cross-app-grants
+GET  /api/v1/os-broker/catalog
+GET  /api/v1/os-broker/schemas?targets=hr/v1#approvalChain.get
+GET  /api/v1/os-broker/audit?app_id=leave-management
+```
+
+Local simulator workflows can use `.palette/app-services.local.json` mocks.
+The mock command writes the file for you:
+
+```bash
+pltt services mock hr/v1#approvalChain.get
+```
+
+Example mock:
+
+```json
+{
+  "hr/v1#approvalChain.get": {
+    "approvers": [{ "user_id": "manager-1", "step": 1 }]
+  }
+}
+```
+
 App storage is separate from Data Rooms. Use `ctx.storage` and `palette.storage` for app-owned files that go directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` or `palette.dataRooms` only when the file should be visible and governed as a Data Room document.
 
 Palette scopes storage the same way. Files written through `ctx.storage` or the

package/lib/commands/init.js

@@ -10,7 +10,7 @@ const DEFAULT_TEMPLATE_REPO = "palette-lab/plugin-template"
 const TEMPLATE_REPO = process.env.PALETTE_TEMPLATE_REPO || DEFAULT_TEMPLATE_REPO
 const TEMPLATE_REF = process.env.PALETTE_TEMPLATE_REF || "main"
 
-const KNOWN_TEMPLATES = ["frontend-only", "palette-app", "next", "dashboard", "agent-tool", "external-service", "database"]
+const KNOWN_TEMPLATES = ["frontend-only", "palette-app", "next", "dashboard", "agent-tool", "external-service", "database", "provider-app", "consumer-app"]
 
 function toSlug(name) {
   return name

package/lib/commands/services.js

@@ -180,6 +180,54 @@ function safeIdent(s) {
   return s.replace(/[^A-Za-z0-9_]/g, "_")
 }
 
+function safePythonIdent(s) {
+  return safeIdent(s).replace(/^(?=\d)/, "_")
+}
+
+function pythonMethodName(s) {
+  return safePythonIdent(
+    s
+      .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+      .replace(/[.-]+/g, "_")
+      .toLowerCase(),
+  )
+}
+
+function nestedAssign(root, dotted, value) {
+  const parts = dotted.split(".").filter(Boolean)
+  let cursor = root
+  while (parts.length > 1) {
+    const part = parts.shift()
+    cursor[part] = cursor[part] || {}
+    cursor = cursor[part]
+  }
+  cursor[parts[0] || dotted] = value
+}
+
+function renderTsObject(node, indent = "  ") {
+  const lines = ["{"]
+  for (const [key, value] of Object.entries(node)) {
+    const prop = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
+    if (value && value.__service) {
+      if (value.scope) lines.push(`${indent}/** scope: ${value.scope} */`)
+      lines.push(`${indent}async ${prop}(input: ${value.inT}): Promise<${value.outT}> {`)
+      lines.push(`${indent}  return (await palette.broker.call(${JSON.stringify(value.target)}, input)) as ${value.outT}`)
+      lines.push(`${indent}},`)
+    } else if (value && value.__event) {
+      lines.push(`${indent}${prop}(handler: (payload: ${value.payT}) => void) {`)
+      lines.push(`${indent}  return palette.events.on(${JSON.stringify(value.target)}, (payload) => handler(payload as ${value.payT}))`)
+      lines.push(`${indent}},`)
+    } else {
+      const rendered = renderTsObject(value, indent + "  ").split("\n")
+      lines.push(`${indent}${prop}: ${rendered[0]}`)
+      for (const line of rendered.slice(1)) lines.push(line)
+      lines[lines.length - 1] += ","
+    }
+  }
+  lines.push(`${indent.slice(0, -2)}}`)
+  return lines.join("\n")
+}
+
 function tsHeader() {
   return (
     "// AUTOGENERATED by `pltt services pull` — do not edit by hand.\n" +
@@ -194,7 +242,7 @@ function pyHeader() {
     "from __future__ import annotations\n\n" +
     "from typing import Any\n\n" +
     "from pydantic import BaseModel\n" +
-    "from palette_sdk import services as _services\n\n"
+    "from palette_sdk import services as _palette_services\n\n"
   )
 }
 
@@ -240,24 +288,28 @@ async function runPull(argv, { cwd }) {
     const services = items.filter((i) => i.kind === "service")
     const events = items.filter((i) => i.kind === "event")
     if (services.length) {
-      tsLines.push(`export const ${safe} = {`)
+      const tree = {}
       for (const svc of services) {
-        const comment = svc.scope ? `  /** scope: ${svc.scope} */` : ""
-        if (comment) tsLines.push(comment)
-        tsLines.push(`  async ${JSON.stringify(svc.method)}(input: ${svc.inT}): Promise<${svc.outT}> {`)
-        tsLines.push(`    return (await palette.broker.call(${JSON.stringify(ns + "#" + svc.method)}, input)) as ${svc.outT}`)
-        tsLines.push(`  },`)
+        nestedAssign(tree, svc.method, {
+          __service: true,
+          target: `${ns}#${svc.method}`,
+          inT: svc.inT,
+          outT: svc.outT,
+          scope: svc.scope,
+        })
       }
-      tsLines.push(`}\n`)
+      tsLines.push(`export const ${safe} = ${renderTsObject(tree)}\n`)
     }
     if (events.length) {
-      tsLines.push(`export const ${safe}Events = {`)
+      const tree = {}
       for (const evt of events) {
-        tsLines.push(`  on${safeIdent(evt.topic).replace(/^(.)/, (m) => m.toUpperCase())}(handler: (payload: ${evt.payT}) => void) {`)
-        tsLines.push(`    return palette.events.on(${JSON.stringify(ns + "#" + evt.topic)}, (payload) => handler(payload as ${evt.payT}))`)
-        tsLines.push(`  },`)
+        nestedAssign(tree, evt.topic, {
+          __event: true,
+          target: `${ns}#${evt.topic}`,
+          payT: evt.payT,
+        })
       }
-      tsLines.push(`}\n`)
+      tsLines.push(`export const ${safe}Events = ${renderTsObject(tree)}\n`)
     }
   }
   const tsDir = path.join(cwd, ".palette", "types")
@@ -270,7 +322,7 @@ async function runPull(argv, { cwd }) {
     const entry = byTarget.get(target)
     if (!entry) continue
     const safeNs = safeIdent(`${entry.namespace}_${entry.version}`)
-    const safeMethod = safeIdent(entry.method || entry.topic)
+    const safeMethod = pythonMethodName(entry.method || entry.topic)
     if (entry.kind === "service") {
       const { code: inCode, ref: inRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Input`, entry.input_schema)
       const { code: outCode, ref: outRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Output`, entry.output_schema)
@@ -280,7 +332,7 @@ async function runPull(argv, { cwd }) {
         `async def ${safeNs}_${safeMethod}(ctx, payload: ${inRef}) -> ${outRef}:\n` +
           `    """Call ${entry.namespace}/${entry.version}#${entry.method}.\n\n` +
           (entry.scope ? `    Scope: ${entry.scope}\n    """\n` : `    """\n`) +
-          `    return await _services.services(ctx).call(${JSON.stringify(target)}, payload if isinstance(payload, dict) else payload.model_dump())\n`,
+          `    return await _palette_services(ctx).call(${JSON.stringify(target)}, payload if isinstance(payload, dict) else payload.model_dump())\n`,
       )
     } else if (entry.kind === "event") {
       const { code: payCode, ref: payRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Payload`, entry.payload_schema)
@@ -303,6 +355,185 @@ async function runPull(argv, { cwd }) {
   if (missing.length) process.exit(2)
 }
 
+// ---- sync provider contracts from Python decorators -------------------------
+
+function listPythonFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out
+  for (const name of fs.readdirSync(dir)) {
+    const p = path.join(dir, name)
+    const stat = fs.statSync(p)
+    if (stat.isDirectory()) {
+      if (![".venv", "__pycache__", ".palette", "node_modules"].includes(name)) listPythonFiles(p, out)
+    } else if (name.endsWith(".py")) {
+      out.push(p)
+    }
+  }
+  return out
+}
+
+function argValue(source, name) {
+  const match = source.match(new RegExp(`${name}\\s*=\\s*["']([^"']+)["']`))
+  return match ? match[1] : null
+}
+
+function boolArg(source, name) {
+  return new RegExp(`${name}\\s*=\\s*True`).test(source)
+}
+
+function discoverServiceDecorators(cwd) {
+  const files = listPythonFiles(path.join(cwd, "backend"))
+  const found = []
+  for (const file of files) {
+    const text = fs.readFileSync(file, "utf8")
+    const re = /@service\s*\(([\s\S]*?)\)\s*(?:async\s+)?def\s+([A-Za-z_][A-Za-z0-9_]*)/g
+    let match
+    while ((match = re.exec(text))) {
+      const args = match[1]
+      const name = (args.match(/["']([^"']+)["']/) || [])[1]
+      if (!name) continue
+      found.push({
+        name,
+        fn: match[2],
+        scope: argValue(args, "scope"),
+        label: argValue(args, "label"),
+        description: argValue(args, "description"),
+        namespace: argValue(args, "namespace"),
+        version: argValue(args, "version") || "v1",
+        input_schema: argValue(args, "input_schema") || argValue(args, "input"),
+        output_schema: argValue(args, "output_schema") || argValue(args, "output"),
+        deprecated: boolArg(args, "deprecated"),
+        replacement: argValue(args, "replacement"),
+        file: path.relative(cwd, file),
+      })
+    }
+  }
+  return found
+}
+
+async function runSync(argv, { cwd }) {
+  const manifest = readManifest(cwd)
+  const decorators = discoverServiceDecorators(cwd)
+  if (!decorators.length) {
+    console.log("[pltt] no @service(...) decorators found under backend/.")
+    return
+  }
+  manifest.provides = manifest.provides || {}
+  manifest.provides.namespace = valueAfter(argv, "--namespace") || decorators.find(d => d.namespace)?.namespace || manifest.provides.namespace || manifest.id
+  manifest.provides.services = manifest.provides.services || []
+  for (const decl of decorators) {
+    const serviceId = safeIdent(decl.name.split(".")[0] || decl.name).toLowerCase().replace(/_/g, ".")
+    let svc = manifest.provides.services.find(s => s && s.id === serviceId)
+    if (!svc) {
+      svc = { id: serviceId, version: decl.version || "v1", methods: [] }
+      manifest.provides.services.push(svc)
+    }
+    svc.version = svc.version || decl.version || "v1"
+    svc.methods = svc.methods || []
+    let method = svc.methods.find(m => m && m.name === decl.name)
+    if (!method) {
+      method = { name: decl.name }
+      svc.methods.push(method)
+    }
+    if (decl.scope) method.scope = decl.scope
+    if (decl.label) method.label = decl.label
+    if (decl.description) method.description = decl.description
+    if (decl.input_schema) method.input_schema = decl.input_schema
+    else method.input_schema = method.input_schema || `schemas/${decl.name}.in.json`
+    if (decl.output_schema) method.output_schema = decl.output_schema
+    else method.output_schema = method.output_schema || `schemas/${decl.name}.out.json`
+    if (decl.deprecated) method.deprecated = true
+    if (decl.replacement) method.replacement = decl.replacement
+  }
+  writeManifest(cwd, manifest)
+  console.log(`[pltt] synced ${decorators.length} service method(s) into palette-plugin.json`)
+}
+
+// ---- mock -------------------------------------------------------------------
+
+function sampleFromSchema(schema) {
+  if (!schema || typeof schema !== "object") return {}
+  if (schema.example !== undefined) return schema.example
+  if (schema.type === "string") return "string"
+  if (schema.type === "integer" || schema.type === "number") return 1
+  if (schema.type === "boolean") return true
+  if (schema.type === "array") return [sampleFromSchema(schema.items)]
+  const props = schema.properties || {}
+  const out = {}
+  for (const [key, prop] of Object.entries(props)) out[key] = sampleFromSchema(prop)
+  return out
+}
+
+async function runMock(argv, { cwd }) {
+  const target = argv.find((arg) => !arg.startsWith("-"))
+  if (!target || !brokerTargetLooksValid(target)) {
+    console.error("[pltt] usage: pltt services mock <namespace/version#name>")
+    process.exit(1)
+  }
+  const mockPath = path.join(cwd, ".palette", "app-services.local.json")
+  ensureDir(path.dirname(mockPath))
+  const current = fs.existsSync(mockPath) ? JSON.parse(fs.readFileSync(mockPath, "utf8")) : {}
+  current[target] = current[target] || {
+    ok: true,
+    target,
+    items: [],
+  }
+  fs.writeFileSync(mockPath, JSON.stringify(current, null, 2) + "\n")
+  console.log(`[pltt] wrote local mock for ${target} -> ${path.relative(cwd, mockPath)}`)
+}
+
+// ---- test -------------------------------------------------------------------
+
+function validateLocalMocks(cwd, targets) {
+  const mockPath = path.join(cwd, ".palette", "app-services.local.json")
+  if (!fs.existsSync(mockPath)) return []
+  const mocks = JSON.parse(fs.readFileSync(mockPath, "utf8"))
+  const errors = []
+  for (const key of Object.keys(mocks)) {
+    const target = key.split(" ")[0]
+    if (!brokerTargetLooksValid(target)) errors.push(`mock key is not a broker target: ${key}`)
+    if (!targets.has(target)) errors.push(`mock target is not declared in consumes: ${target}`)
+  }
+  return errors
+}
+
+async function runTest(argv, { cwd }) {
+  const manifest = readManifest(cwd)
+  const { services, events } = consumeTargets(manifest)
+  const targets = new Set([...services, ...events])
+  const errors = []
+  for (const target of targets) {
+    if (!brokerTargetLooksValid(target)) errors.push(`invalid broker target: ${target}`)
+  }
+  errors.push(...validateLocalMocks(cwd, targets))
+  const decorators = discoverServiceDecorators(cwd)
+  const provided = new Set()
+  const provides = manifest.provides || {}
+  const ns = provides.namespace || manifest.id
+  for (const svc of provides.services || []) {
+    for (const method of svc.methods || []) {
+      if (method.name) provided.add(`${ns}/${svc.version || "v1"}#${method.name}`)
+    }
+  }
+  for (const decl of decorators) {
+    const target = `${decl.namespace || ns}/${decl.version || "v1"}#${decl.name}`
+    if (!provided.has(target)) errors.push(`@service ${target} is not declared in provides; run pltt services sync`)
+  }
+  if (!argv.includes("--offline") && targets.size) {
+    const { flags } = parseFlags(argv)
+    const env = resolveEnvironment({ cwd, flags })
+    const schemas = await authFetch(env, `/api/v1/os-broker/schemas?targets=${encodeURIComponent(Array.from(targets).join(","))}`)
+    const returned = new Set(schemas.map(s => s.target))
+    for (const target of targets) {
+      if (!returned.has(target)) errors.push(`target not found in ${env.name || env.url}: ${target}`)
+    }
+  }
+  if (errors.length) {
+    for (const error of errors) console.error(`[pltt] ${error}`)
+    process.exit(1)
+  }
+  console.log(`[pltt] services contract check passed (${targets.size} consumed, ${decorators.length} provider decorator(s)).`)
+}
+
 // ---- scaffold provider stub --------------------------------------------------
 
 async function runScaffold(argv, { cwd }) {
@@ -318,9 +549,10 @@ async function runScaffold(argv, { cwd }) {
   provides.namespace = namespace
   provides.services = provides.services || []
   // Ensure a default service slot.
-  let svc = provides.services.find((s) => (s.id || "") === method) || null
+  const serviceId = safeIdent(method.split(".")[0] || method).toLowerCase().replace(/_/g, ".")
+  let svc = provides.services.find((s) => (s.id || "") === serviceId) || null
   if (!svc) {
-    svc = { id: method, version: "v1", methods: [] }
+    svc = { id: serviceId, version: "v1", methods: [] }
     provides.services.push(svc)
   }
   svc.methods = svc.methods || []
@@ -410,11 +642,17 @@ async function run(argv, ctx) {
   const rest = argv.slice(1)
   if (sub === "list") return runList(rest, ctx)
   if (sub === "pull") return runPull(rest, ctx)
+  if (sub === "sync") return runSync(rest, ctx)
+  if (sub === "mock") return runMock(rest, ctx)
+  if (sub === "test") return runTest(rest, ctx)
   if (sub === "scaffold") return runScaffold(rest, ctx)
   if (sub === "add") return runAdd(rest, ctx)
   console.log("pltt services <command>\n")
   console.log("  list      Show services/events available to the current org.")
   console.log("  pull      Generate typed TS+Python clients from consumes block.")
+  console.log("  sync      Update provides from backend @service decorators.")
+  console.log("  mock      Add a local .palette/app-services.local.json response.")
+  console.log("  test      Validate consumed targets, local mocks, and provider declarations.")
   console.log("  scaffold  Add a new provider method + schemas + handler stub.")
   console.log("  add       Add a consumed service/event target to palette-plugin.json.")
   if (sub && !["help", "--help", "-h"].includes(sub)) {

package/lib/dev-simulator.js

@@ -272,6 +272,18 @@ class LocalAppInteropService:
             return DEV_APP_MOCKS[key]
         raise RuntimeError("No local app service mock configured for " + key)
 
+    async def broker_call(self, target: str, payload=None):
+        payload = payload or {}
+        payload_key = target + " " + json.dumps(payload, sort_keys=True, separators=(",", ":"))
+        if payload_key in DEV_APP_MOCKS:
+            return DEV_APP_MOCKS[payload_key]
+        if target in DEV_APP_MOCKS:
+            return DEV_APP_MOCKS[target]
+        raise RuntimeError("No local broker mock configured for " + target)
+
+    async def broker_emit(self, target: str, payload=None):
+        print("[palette-broker-event]", target, json.dumps(payload or {}, sort_keys=True))
+
 class LocalAppServiceClient:
     def __init__(self, service_id: str):
         self.service_id = service_id

package/lib/manifest.js

@@ -108,6 +108,12 @@ function requireString(obj, key, label, errors) {
   }
 }
 
+function requireSchema(obj, key, label, errors) {
+  if (obj[key] !== undefined && typeof obj[key] !== "string" && !isObject(obj[key])) {
+    errors.push(`${label}.${key} must be a JSON schema object or schema file path`)
+  }
+}
+
 function validateArray(value, label, errors) {
   if (value !== undefined && !Array.isArray(value)) errors.push(`${label} must be an array`)
 }
@@ -294,6 +300,8 @@ function validateServiceMethods(value, label, errors) {
         "output",
         "route_method",
         "route_path",
+        "deprecated",
+        "replacement",
       ]),
       methodLabel,
       errors,
@@ -304,9 +312,14 @@ function validateServiceMethods(value, label, errors) {
       errors.push(`duplicate provided method name: ${method.name}`)
     }
     seen.add(method.name)
-    for (const key of ["scope", "label", "description", "input_schema", "input", "output_schema", "output", "route_path"]) {
+    for (const key of ["scope", "label", "description", "route_path"]) {
       requireString(method, key, methodLabel, errors)
     }
+    requireBoolean(method, "deprecated", methodLabel, errors)
+    requireString(method, "replacement", methodLabel, errors)
+    for (const key of ["input_schema", "input", "output_schema", "output"]) {
+      requireSchema(method, key, methodLabel, errors)
+    }
     if (method.route_method !== undefined && !methods.has(String(method.route_method).toUpperCase())) {
       errors.push(`${methodLabel}.route_method must be one of ${Array.from(methods).join(", ")}`)
     }
@@ -374,9 +387,12 @@ function validateProvides(value, errors) {
         } else if (isObject(event)) {
           unknownKeys(event, new Set(["topic", "name", "version", "payload_schema", "schema", "description"]), label, errors)
           topic = event.topic || event.name
-          for (const key of ["version", "payload_schema", "schema", "description"]) {
+          for (const key of ["version", "description"]) {
             requireString(event, key, label, errors)
           }
+          for (const key of ["payload_schema", "schema"]) {
+            requireSchema(event, key, label, errors)
+          }
         } else {
           errors.push(`${label} must be a topic string or object`)
           return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.51",
+  "version": "0.3.53",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.21"
+    "@palettelab/sdk": "^0.1.23"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/templates/consumer-app/README.md

@@ -0,0 +1,10 @@
+# Consumer App Template
+
+This template consumes `hr/v1#approvalChain.get`.
+
+For local development without a provider app:
+
+```bash
+pltt services mock hr/v1#approvalChain.get
+pltt dev
+```

package/template-fallback/templates/consumer-app/backend/api/main.py

@@ -0,0 +1,15 @@
+from fastapi import Depends
+from palette_sdk import PluginContext, PluginRouter, get_plugin_context, services
+
+router = PluginRouter()
+
+
+@router.post("/leave-requests")
+async def create_leave_request(payload: dict, ctx: PluginContext = Depends(get_plugin_context)):
+    chain = await services(ctx).call("hr/v1#approvalChain.get", {
+        "user_id": payload.get("user_id", ctx.user_id),
+    })
+    return {
+        "status": "submitted",
+        "approval_chain": chain,
+    }

package/template-fallback/templates/consumer-app/frontend/src/index.tsx

@@ -0,0 +1,26 @@
+import React, { useState } from "react"
+import { createRoot } from "react-dom/client"
+import { createPaletteClient, usePlatform } from "@palettelab/sdk"
+
+function App() {
+  const platform = usePlatform()
+  const palette = createPaletteClient(platform)
+  const [result, setResult] = useState<string>("")
+
+  async function previewApprover() {
+    const chain = await palette.services("hr/v1").approvalChain.get({
+      user_id: platform.user.id,
+    })
+    setResult(JSON.stringify(chain, null, 2))
+  }
+
+  return (
+    <main style={{ padding: 24, fontFamily: "system-ui, sans-serif" }}>
+      <h1>Consumer App</h1>
+      <button onClick={previewApprover}>Preview approver</button>
+      {result && <pre>{result}</pre>}
+    </main>
+  )
+}
+
+createRoot(document.getElementById("root")!).render(<App />)

package/template-fallback/templates/consumer-app/package.json

@@ -0,0 +1,9 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@palettelab/sdk": "^0.1.23",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/template-fallback/templates/consumer-app/palette-plugin.json

@@ -0,0 +1,45 @@
+{
+  "manifest_version": "1",
+  "id": "consumer-app",
+  "name": "Consumer App",
+  "version": "1.0.0",
+  "developer": "Palette",
+  "category": "Productivity",
+  "tagline": "Consume governed services from other apps",
+  "description": "Example consumer app that asks an HR provider for approval routing.",
+  "icon": "ClipboardText",
+  "gradient": {
+    "bg": "linear-gradient(135deg, #7C3AED, #DB2777)",
+    "text": "#ffffff"
+  },
+  "capabilities": {
+    "frontend": true,
+    "backend": true
+  },
+  "frontend": {
+    "entry": "./frontend/src/index.tsx"
+  },
+  "backend": {
+    "entry": "./backend/api/main.py"
+  },
+  "permissions": [
+    "resources:read",
+    "resources:write"
+  ],
+  "consumes": {
+    "services": [
+      {
+        "target": "hr/v1#approvalChain.get",
+        "required": true,
+        "reason": "Leave approvals follow the employee reporting hierarchy."
+      }
+    ],
+    "events": [
+      {
+        "target": "hr/v1#hierarchy.updated",
+        "required": false,
+        "reason": "Refresh approval routing when hierarchy changes."
+      }
+    ]
+  }
+}

package/template-fallback/templates/consumer-app/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "consumer-app"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = [
+  "palette-sdk"
+]
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.21",
+    "@palettelab/sdk": "^0.1.23",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.21", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.23", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.21", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.23", "react": "^19.0.0" }
 }

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.21",
+    "@palettelab/sdk": "^0.1.23",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/next/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.21",
+    "@palettelab/sdk": "^0.1.23",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/palette-app/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.21",
+    "@palettelab/sdk": "^0.1.23",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/provider-app/README.md

@@ -0,0 +1,10 @@
+# Provider App Template
+
+This template exposes `hr/v1#approvalChain.get` through Palette's OS broker.
+
+Run:
+
+```bash
+pltt services sync
+pltt dev
+```

package/template-fallback/templates/provider-app/backend/api/main.py

@@ -0,0 +1,25 @@
+from fastapi import Depends
+from palette_sdk import PluginContext, PluginRouter, get_plugin_context, service
+
+router = PluginRouter()
+
+
+@service(
+    "approvalChain.get",
+    namespace="hr",
+    version="v1",
+    input_schema="schemas/approvalChain.get.in.json",
+    output_schema="schemas/approvalChain.get.out.json",
+)
+async def approval_chain(ctx: PluginContext, payload: dict) -> dict:
+    user_id = payload["user_id"]
+    return {
+        "user_id": user_id,
+        "next_approver_id": "manager-dev",
+        "levels": ["manager-dev", "hr-dev"],
+    }
+
+
+@router.get("/health")
+async def health(ctx: PluginContext = Depends(get_plugin_context)):
+    return {"ok": True, "plugin_id": ctx.plugin_id}

package/template-fallback/templates/provider-app/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@palettelab/sdk": "^0.1.23",
+    "react": "^19.0.0"
+  }
+}

package/template-fallback/templates/provider-app/palette-plugin.json

@@ -0,0 +1,49 @@
+{
+  "manifest_version": "1",
+  "id": "provider-app",
+  "name": "Provider App",
+  "version": "1.0.0",
+  "developer": "Palette",
+  "category": "Productivity",
+  "tagline": "Expose governed services to other apps",
+  "description": "Example provider app exposing employee hierarchy through the OS broker.",
+  "icon": "UsersThree",
+  "gradient": {
+    "bg": "linear-gradient(135deg, #0F766E, #2563EB)",
+    "text": "#ffffff"
+  },
+  "capabilities": {
+    "backend": true
+  },
+  "backend": {
+    "entry": "./backend/api/main.py"
+  },
+  "permissions": [
+    "resources:read"
+  ],
+  "provides": {
+    "namespace": "hr",
+    "services": [
+      {
+        "id": "approval",
+        "version": "v1",
+        "label": "Approval hierarchy",
+        "description": "Resolve the next approver for an employee.",
+        "methods": [
+          {
+            "name": "approvalChain.get",
+            "input_schema": "schemas/approvalChain.get.in.json",
+            "output_schema": "schemas/approvalChain.get.out.json"
+          }
+        ]
+      }
+    ],
+    "events": [
+      {
+        "topic": "hierarchy.updated",
+        "version": "v1",
+        "schema": "schemas/hierarchy.updated.json"
+      }
+    ]
+  }
+}

package/template-fallback/templates/provider-app/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "provider-app"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = [
+  "palette-sdk"
+]
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"

package/template-fallback/templates/provider-app/schemas/approvalChain.get.in.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "user_id": { "type": "string" }
+  },
+  "required": ["user_id"]
+}

package/template-fallback/templates/provider-app/schemas/approvalChain.get.out.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "user_id": { "type": "string" },
+    "next_approver_id": { "type": "string" },
+    "levels": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "required": ["user_id", "next_approver_id", "levels"]
+}

package/template-fallback/templates/provider-app/schemas/hierarchy.updated.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "changed_user_id": { "type": "string" }
+  },
+  "required": ["changed_user_id"]
+}