@softize/opus 22.1.0 → 23.0.0

package/src/core/types.ts

@@ -356,6 +356,15 @@ export interface AuditRecord {
   output?: unknown
   error?: ActionError
 
+  /** Efeito resolvido da action (ADR 0041): `list` e `view` são sempre leitura. */
+  effect?: ActionEffect
+  /**
+   * Presente quando a action declara `personalData: true` e executou com sucesso (ADR 0041):
+   * a requisição expôs dado pessoal a quem a executou. `records` conta os registros devolvidos
+   * (itens da página de uma `list`, 1 para um objeto) e é `null` quando a saída não permite contar.
+   */
+  personalData?: { records: number | null }
+
   severity: 'info' | 'warning' | 'error'
   /** Campo legado preservado para compatibilidade com sinks/consumers existentes. */
   trace?: {
@@ -629,6 +638,9 @@ export interface FilterSpec {
 
   type: 'text' | 'select' | 'lookup' | 'date' | 'number'
   multiple?: boolean
+  /** Controle usado para um `select` de escolha única. `select` é o padrão; `toggle`
+   *  mantém todas as opções curtas visíveis em um grupo conectado. */
+  presentation?: 'select' | 'toggle'
   /** Habilita busca local nas opções de um `select`; `lookup` já é pesquisável por natureza. */
   searchable?: boolean
   /** Quando `false`, a interface omite a opção vazia. Limpar restaura o default do filtro. */
@@ -709,6 +721,12 @@ export interface ExpandSpec {
 
 export type ActionKind = 'simple' | 'form' | 'list' | 'view'
 
+/**
+ * O que a action faz com o estado (ADR 0041). `list` e `view` são leitura pelo protocolo (`GET`);
+ * `simple` e `form` declaram, porque cobrem as duas coisas.
+ */
+export type ActionEffect = 'read' | 'write'
+
 export type AuthorizeFn<In, Loaded = Record<string, unknown>> = (
   ctx: ActionContext,
   input: In,
@@ -784,7 +802,7 @@ export type LoadersSpec<In> = Record<string, LoaderFn<In>>
  *     aqui.
  *   - **`ParsedIn`** — o lado PARSEADO (o output do schema de input, defaults
  *     aplicados). O runtime SEMPRE valida antes de executar, então `handler`,
- *     `mockHandler`, `authorize` e `loads` recebem `ParsedIn`.
+ *     `handler`, `authorize` e `loads` recebem `ParsedIn`.
  *
  * O default `ParsedIn = In` mantém retrocompat com anotações à mão de dois
  * genéricos; `defineAction`/`defineContract` inferem os dois lados do schema.
@@ -810,6 +828,20 @@ export interface ActionBase<In, Out, ParsedIn = In> {
   input: Schema<In, ParsedIn>
   output: Schema<Out>
 
+  // — Natureza (ADR 0041) —
+  /**
+   * `read` não altera estado; `write` altera. `list` e `view` já são leitura pelo protocolo e não
+   * declaram (declarar `write` nelas é recusado no registro). `simple` e `form` declaram: o `kind`
+   * sozinho não diz se a action lê ou escreve. Declarativo — o runtime não impede o handler.
+   */
+  effect?: ActionEffect
+  /**
+   * A resposta contém dados que identificam pessoas: nome, documento, contato, placa ou texto
+   * livre sobre alguém. Com `true`, toda execução bem-sucedida é marcada no `AuditRecord` e no
+   * span, qualquer que seja o consumidor. Nunca inferido; ausente significa "não declarado".
+   */
+  personalData?: boolean
+
   // — Autorização (fail-closed default) —
   public?: boolean
   requires?: string | string[]
@@ -819,16 +851,6 @@ export interface ActionBase<In, Out, ParsedIn = In> {
   // — Execução —
   handler: HandlerFn<ParsedIn, Out>
 
-  /**
-   * Handler alternativo executado quando `process.env.OPUS_MODE === 'design'`.
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); sai na próxima major. No modo design, a action sem
-   * mock já responde com dado gerado a partir do `output`; quando o design precisar de uma resposta
-   * específica, declare um cenário fora do contrato com `defineDesignScenario`, de
-   * `@softize/opus/design`, e aponte a opção `scenarios` do `opusDesign()` para ele.
-   */
-  mockHandler?: HandlerFn<ParsedIn, Out>
-
   // — Comportamento —
   audit?: boolean | AuditConfig
   confirm?: ConfirmSpec
@@ -893,24 +915,13 @@ export interface SearchFilters {
  * envelope — handler é fonte de verdade.
  */
 export interface ListAction<In, Out, ParsedIn = In>
-  extends Omit<ActionBase<In, Out, ParsedIn>, 'handler' | 'mockHandler'> {
+  extends Omit<ActionBase<In, Out, ParsedIn>, 'handler'> {
   kind: 'list'
   handler: (
     ctx: ActionContext,
     input: ParsedIn,
     loaded?: Record<string, unknown>,
   ) => Paginated<Out> | Promise<Paginated<Out>>
-  /**
-   * Mesma semântica de `ActionBase.mockHandler`, mas devolve `Paginated<Out>`
-   * (search retorna lista paginada, não item solto).
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); ver `ActionBase.mockHandler`.
-   */
-  mockHandler?: (
-    ctx: ActionContext,
-    input: ParsedIn,
-    loaded?: Record<string, unknown>,
-  ) => Paginated<Out> | Promise<Paginated<Out>>
   /** Colunas declarativas da listagem (a UI deriva a tabela; ver ListColumnSpec). */
   columns?: ListColumnSpec[]
   filters?: Record<string, FilterSpec>
@@ -1301,12 +1312,23 @@ export interface AiTool {
   title?: string
   description: string
   inputSchema: unknown
+  /** Anotações padrão de ferramenta do MCP, derivadas do contrato (ADR 0041). */
+  annotations?: {
+    /** A ferramenta não altera estado (efeito `read`). */
+    readOnlyHint?: boolean
+    /** A ferramenta pode destruir dados (`ai.destructive`); só faz sentido quando não é leitura. */
+    destructiveHint?: boolean
+  }
   /** Metadados de governança para o host; não fazem parte do prompt nem concedem acesso. */
   metadata?: {
     /** Identificadores técnicos dos Produtos de Dados relacionados. */
     dataProducts?: string[]
     /** Labels humanas por identificador; ausente para runtimes legados. */
     dataProductLabels?: Record<string, string>
+    /** Efeito resolvido; ausente quando `simple`/`form` não declaram. */
+    effect?: ActionEffect
+    /** A action declara devolver dado pessoal; ausente quando não declarou. */
+    personalData?: boolean
   }
 }
 

package/src/design/index.ts

@@ -9,7 +9,7 @@
  * respostas ao runtime de design.
  */
 
-import { z } from 'zod'
+import type { ZodTypeAny } from 'zod'
 import type { ActionContext, InferOutput, Paginated } from '../core/types.ts'
 import { fake, fakeMany } from '../testing/fake.ts'
 
@@ -102,11 +102,14 @@ interface DesignActionShape {
  * - `list` devolve três páginas do tamanho pedido em `limit` ({@link DESIGN_PAGE_SIZE} quando a
  *   entrada não pede) e respeita a paginação declarada; busca e filtros não filtram o dado gerado.
  * - Nas demais, a saída ecoa o `id` da entrada quando o schema da saída aceita esse valor.
- * - Saída que não é schema zod não tem gerador: a resposta é `null`.
+ * - Saída que não é schema Zod não tem gerador: a resposta é `null`.
  */
 export function designResponse(action: DesignActionShape, input: unknown): unknown {
   const output = action.output
-  if (!(output instanceof z.ZodType)) return null
+  // O contrato vem do grafo do consumidor e pode carregar outra instância física do Zod.
+  // `instanceof` confundiria identidade de módulo com contrato; o gerador usa somente a
+  // estrutura pública/estável que já recebe (`safeParse`) e a definição introspectável (`_def`).
+  if (!isZodSchema(output)) return null
   const seed = `${action.name}:${canonicalJson(withoutPagination(input))}`
 
   if (action.kind === 'list') {
@@ -177,3 +180,11 @@ function canonicalJson(value: unknown): string {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
+
+function isZodSchema(value: unknown): value is ZodTypeAny {
+  return (
+    isRecord(value) &&
+    isRecord(value._def) &&
+    typeof value.safeParse === 'function'
+  )
+}

package/src/mcp/index.ts

@@ -48,9 +48,15 @@ export function createOpusMcpServer(runtime: Runtime, opts: OpusMcpOptions = {})
       ...(t.title !== undefined ? { title: t.title } : {}),
       description: t.description,
       inputSchema: toJsonSchema(t.inputSchema) as { type: 'object' },
+      // Anotações padrão do MCP (ADR 0041): o cliente sabe se a ferramenta só lê.
+      ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
       _meta: {
         'com.softize.opus/data-products': t.metadata?.dataProducts ?? [],
         'com.softize.opus/data-product-labels': t.metadata?.dataProductLabels ?? {},
+        ...(t.metadata?.effect !== undefined ? { 'com.softize.opus/effect': t.metadata.effect } : {}),
+        ...(t.metadata?.personalData !== undefined
+          ? { 'com.softize.opus/personal-data': t.metadata.personalData }
+          : {}),
       },
     })),
   }))

package/src/testing/index.ts

@@ -14,8 +14,6 @@
  *     valida output (pulado em `list`, como no runtime). Falha estoura o MESMO
  *     `ActionError` tipado do runtime (`validation.invalid_input`, `auth.unauthenticated`,
  *     `auth.system_forbidden`, `auth.forbidden`…). A opção `schedule` executa como o sistema.
- *     Em `OPUS_MODE=design` roteia pro `mockHandler` como o runtime — contrato puro
- *     (sem handler) é testável em design; fora dele, erro claro (`testing.no_handler`).
  *   • `memStorage()` — StorageAdapter em memória pra testar handler que anexa
  *     arquivo, com a mesma régua de key dos drivers reais.
  *
@@ -30,9 +28,7 @@ import { evalExpression } from '../dsl/eval.ts'
 import { parseExpression } from '../dsl/parser.ts'
 import { normalizeKey } from '../storage/index.ts'
 import { error } from '../core/errors.ts'
-// Import direto do runtime (fora do index público): a régua handler×mockHandler
-// tem UMA fonte — o harness nunca pode divergir do execute().
-import { assertAuthenticated, isOpusDesignMode, markSystemActor } from '../core/runtime.ts'
+import { assertAuthenticated, markSystemActor } from '../core/runtime.ts'
 import type {
   ActionContext,
   ActionKind,
@@ -206,14 +202,8 @@ export interface TestableAction<In, Out, ParsedIn = In> {
   authorize?: AuthorizeSpec<ParsedIn>
   input: Schema<In, ParsedIn>
   output: Schema<Out> | Schema<unknown, Out>
-  /** Opcional: contrato puro (sem handler) só executa pelo `mockHandler` obsoleto. */
+  /** Opcional para produzir um erro útil quando um contrato puro chega ao harness. */
   handler?: HandlerFn<ParsedIn, Out>
-  /**
-   * Em `OPUS_MODE=design` vence o handler real — mesma régua do runtime.
-   *
-   * @deprecated Desde a 22.1.0 (ADR 0037); teste a action ligada ao handler.
-   */
-  mockHandler?: HandlerFn<ParsedIn, Out>
 }
 
 /** Variante list: o schema descreve o ITEM, o handler devolve `Paginated<Item>`. */
@@ -230,11 +220,6 @@ export interface TestableListAction<In, Item, ParsedIn = In> {
     input: ParsedIn,
     loaded?: Record<string, unknown>,
   ) => Paginated<Item> | Promise<Paginated<Item>>
-  mockHandler?: (
-    ctx: ActionContext,
-    input: ParsedIn,
-    loaded?: Record<string, unknown>,
-  ) => Paginated<Item> | Promise<Paginated<Item>>
 }
 
 export interface RunActionOptions extends TestContextOptions {
@@ -278,9 +263,8 @@ async function validate<T>(
  * validado + o contexto observável (`emitted`, `logged`); falha estoura o mesmo
  * `ActionError` do runtime — afirme com `expect(...).rejects`.
  *
- * A escolha do executável segue a régua do `execute()`: em `OPUS_MODE=design`,
- * `mockHandler` presente vence; senão, `handler` real. Contrato puro (sem
- * handler) só roda em design — fora dele, `testing.no_handler`.
+ * Contrato puro sem handler termina em `testing.no_handler`: dados de design
+ * pertencem ao plugin `opusDesign()` e não são comportamento da action.
  */
 export async function runAction<In, Item, ParsedIn = In>(
   action: TestableListAction<In, Item, ParsedIn>,
@@ -325,18 +309,14 @@ export async function runAction<In, Out, ParsedIn = In>(
     if (decision !== true) throw decision
   }
 
-  const handlerToRun =
-    isOpusDesignMode() && action.mockHandler !== undefined
-      ? action.mockHandler
-      : action.handler
-  if (handlerToRun === undefined) {
+  if (action.handler === undefined) {
     throw error({
       code: 'testing.no_handler',
       category: 'internal',
       message: `Action "${action.name}" não tem handler executável: teste o ActionDef produzido pelo bindAction. Os dados do modo design são gerados pelo plugin opusDesign() e não são comportamento da action.`,
     })
   }
-  const raw = await handlerToRun(ctx, parsed, loaded)
+  const raw = await action.handler(ctx, parsed, loaded)
 
   // Mesmo skip do runtime: list devolve Paginated<Item>, o schema descreve Item.
   const output = action.kind === 'list' ? (raw as Out) : await validate<Out>(action.output, raw, 'output')

package/src/ui/components/patterns/content-header.tsx

@@ -19,11 +19,9 @@ import { SurfaceMedia, type SurfaceMediaProps } from "./surface-media.tsx";
 import {
   SurfaceHeader,
   surfaceHeaderClasses,
-  type SurfaceHeaderVariant,
 } from "./surface-header.tsx";
 
 export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
-export type ContentHeaderVariant = SurfaceHeaderVariant;
 export type ContentElement = "section" | "fieldset";
 export type ContentFrameVariant = "default" | "legend";
 
@@ -34,7 +32,7 @@ interface ContentContextValue {
   layout: SurfaceLayout;
   level: ContentHeaderLevel;
   titleId: string;
-  variant: ContentHeaderVariant;
+  variant: "page" | "section";
 }
 
 const ContentContext = createContext<ContentContextValue | null>(null);
@@ -55,8 +53,6 @@ interface ContentSharedProps {
   framed?: boolean;
   /** Anatomia interna: contínua (default) ou com header separado do corpo. */
   layout?: SurfaceLayout;
-  /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
-  variant?: ContentHeaderVariant;
 }
 
 interface ContentSectionBaseProps
@@ -80,7 +76,6 @@ interface ContentFieldsetBaseProps
   /** Tratamento visual da moldura: contínua (default) ou recortada pela legenda. */
   frameVariant?: ContentFrameVariant;
   level?: never;
-  variant?: "section";
 }
 
 interface ContentSectionShorthandProps extends ContentSectionBaseProps {
@@ -128,7 +123,6 @@ export function Content({
   description,
   actions,
   level = 2,
-  variant = "section",
   framed = false,
   layout = "continuous",
   frameVariant = "default",
@@ -138,7 +132,8 @@ export function Content({
 }: ContentProps): ReactElement {
   const titleId = useId();
   const fill = useFillRegion();
-  const context = {
+  const variant = level === 1 && as === "section" ? "page" : "section";
+  const context: ContentContextValue = {
     element: as,
     frameVariant,
     framed,
@@ -245,7 +240,8 @@ export function Content({
           {...fill.attributes}
           aria-labelledby={ariaLabelledBy}
           className={cn(
-            layout === "continuous" && "space-y-3",
+            layout === "continuous" &&
+              (variant === "page" ? "space-y-6" : "space-y-3"),
             framed &&
               layout === "continuous" &&
               frameVariant === "default" &&

package/src/ui/components/patterns/list.tsx

@@ -111,6 +111,7 @@ import {
   InputGroupButton,
   InputGroupInput,
 } from "../primitives/input-group.tsx";
+import { iconPickerIcons } from "../primitives/icon-picker.tsx";
 import { Separator } from "../primitives/separator.tsx";
 import {
   Field,
@@ -479,7 +480,23 @@ function dictOptionsFor(
   if (spec.options?.kind !== "dictionary") return [];
   const dict = dicts[spec.options.ref];
   if (dict === undefined) return [];
-  return dict.options().map((o) => ({ value: o.value, label: o.label }));
+  return dict.options().map((o) => {
+    const Icon = o.icon === undefined ? undefined : iconPickerIcons[o.icon];
+    return {
+      value: o.value,
+      label: o.label,
+      ...(Icon === undefined
+        ? {}
+        : {
+            content: (
+              <>
+                <Icon aria-hidden="true" />
+                <span>{o.label}</span>
+              </>
+            ),
+          }),
+    };
+  });
 }
 
 /** Opções vindas de uma action de lookup (`options.kind: 'lookup'`): o Select chama
@@ -571,6 +588,43 @@ function FilterField({
   const changedFromDefault = singleValue !== defaultValue;
   const acceptsEmptyValue = spec.allowEmpty !== false;
 
+  if (
+    spec.type === "select" &&
+    spec.multiple !== true &&
+    spec.presentation === "toggle"
+  ) {
+    const ALL = "__all__";
+    const toggleValue = singleValue === "" ? ALL : singleValue;
+    return (
+      <ToggleGroup
+        type="single"
+        variant="outline"
+        id={`filter-${name}`}
+        value={toggleValue}
+        onValueChange={(next) => {
+          // O grupo sempre preserva uma escolha ativa. Quando vazio é permitido,
+          // a opção explícita representa esse estado em vez de desmarcar o item atual.
+          if (next === "") return;
+          onChange(next === ALL ? "" : next);
+        }}
+        aria-label={label}
+        disabled={!enabled}
+        className={className ?? "max-w-full"}
+      >
+        {acceptsEmptyValue && (
+          <ToggleGroupItem value={ALL}>
+            {text(spec.placeholder, "Todos")}
+          </ToggleGroupItem>
+        )}
+        {base.map((option) => (
+          <ToggleGroupItem key={option.value} value={option.value}>
+            {option.content ?? option.label}
+          </ToggleGroupItem>
+        ))}
+      </ToggleGroup>
+    );
+  }
+
   if (spec.multiple === true) {
     return (
       <Select

package/src/ui/components/patterns/presentation.tsx

@@ -221,7 +221,7 @@ function PresentationFrame({
   if (surface === "page") {
     if (listBody) {
       const content = (
-        <Content level={1} variant="page">
+        <Content level={1}>
           <ContentHeader>
             <ContentTitle>{title}</ContentTitle>
             {headerActions === undefined ? null : (

package/src/ui/components/primitives/icon-picker.tsx

@@ -25,9 +25,12 @@ import {
   Layers,
   LayoutGrid,
   Lightbulb,
+  Mail,
   MapPin,
+  MessageCircle,
   MessageSquare,
   Package,
+  Phone,
   Rocket,
   Settings,
   ShoppingCart,
@@ -77,9 +80,12 @@ export const iconPickerIcons: Record<string, LucideIcon> = {
   'layers': Layers,
   'layout-grid': LayoutGrid,
   'lightbulb': Lightbulb,
+  'mail': Mail,
   'map-pin': MapPin,
+  'message-circle': MessageCircle,
   'message-square': MessageSquare,
   'package': Package,
+  'phone': Phone,
   'rocket': Rocket,
   'settings': Settings,
   'shopping-cart': ShoppingCart,