Escrevendo um contrato

apiVersion: oren.sh/v1
kind: Task
metadata:
  name: contar-linhas
  namespace: acme          # obrigatório para publicar
  version: 1.0.0
  summary: Conta linhas de código de um projeto
spec:
  effects: none
  inputs:
    type: object
    properties:
      extensao:
        type: string
        default: js
  outputs:
    type: object
    required: [total]
    properties:
      total: { type: integer }
  dependencies:
    source:
      type: directory
      mutable: false

Inputs e outputs são JSON Schema, com uma keyword extra: secret.

Campos desconhecidos são recusados

Um campo que não está no contrato falha o step, com sugestão:

campo desconhecido: "incremenMajorVersion" — você quis dizer "incrementMajorVersion"?

Isso não é rigor gratuito. No pipeline que originou este projeto, o worker lia incremenMajorVersion e o pipeline enviava incrementMajorVersion — sem o “t”. Major e patch nunca foram incrementados, por dezesseis releases, sem um único erro.

effects

Determina se o resultado pode vir do cache.

Valor	Cacheável	Repetir é seguro	Exemplo
none	sim	—	analisar commits, calcular versão
reads-external	não	sim	terraform plan
external	não	não	publicar imagem, criar tag remota, deploy

O critério: se eu rodar de novo com as mesmas entradas e nada acontecer, o pipeline ainda está correto? Se não, é external.

Os erros não são simétricos. Marcar external a mais custa cache. A menos produz um deploy silenciosamente ausente, com o pipeline reportando sucesso. Na dúvida, external.

reads-external é o caso intermediário: não altera nada, mas lê estado externo mutável. Cachear devolveria uma leitura obsoleta, mas repetir é seguro.

Campos secretos

token:
  type: string
  secret: true

Vale em inputs e outputs. O valor é redigido em log, fica fora do lockfile e do estado em disco, e contamina qualquer campo que o interpole.