@baruk/core 0.4.2 → 0.6.0

package/dist/fiscal/applicability.d.ts

@@ -0,0 +1,73 @@
+import { type FiscalProfile } from './conditions.js';
+/**
+ * O motor de aplicabilidade.
+ *
+ * Recebe perfil + regra + competência e devolve uma DECISÃO, não um booleano.
+ * A diferença não é estilística: "não gerar" tem meia dúzia de causas, cada uma
+ * com uma ação diferente do outro lado. Um booleano faz a obrigação sumir da
+ * lista sem que ninguém saiba se faltou dado do cliente, se a regra venceu, ou
+ * se ela simplesmente não se aplica.
+ *
+ * A regra que organiza a ordem das checagens: **primeiro o que é do produto,
+ * depois o que é do cliente.** Uma regra desabilitada não deve produzir
+ * "faltou informar se o cliente tem empregados" — a informação não seria
+ * usada de todo jeito, e o operador iria atrás do dado errado.
+ */
+export type ApplicabilityOutcome = 'APPLICABLE' | 'NOT_APPLICABLE'
+/** Falta atributo do perfil para decidir. **Nunca** vira `NOT_APPLICABLE`. */
+ | 'INSUFFICIENT_DATA'
+/** Não há regra para esta jurisdição e competência. */
+ | 'RULE_NOT_CONFIGURED' | 'RULE_PENDING_VALIDATION' | 'RULE_EXPIRED' | 'RULE_DISABLED';
+export type RuleStatus = 'not_configured' | 'pending_validation' | 'validated' | 'expired' | 'disabled';
+export interface JurisdictionRef {
+    scope: 'federal' | 'state' | 'municipal';
+    uf: string | null;
+    cityIbge: string | null;
+}
+export interface FiscalRuleRef {
+    id: string;
+    tenantId: string | null;
+    itemTypeId: string;
+    version: number;
+    jurisdiction: JurisdictionRef;
+    validFrom: string;
+    validUntil: string | null;
+    status: RuleStatus;
+    conditions: unknown;
+    dueRule: Record<string, unknown> | null;
+    sourceReference: string | null;
+}
+export interface ClientJurisdiction {
+    uf: string | null;
+    cityIbge: string | null;
+}
+export interface ApplicabilityDecision {
+    outcome: ApplicabilityOutcome;
+    /** Frase curta para a tela. Explica a decisão, não o código. */
+    reason: string;
+    /** O que o motor consultou para decidir — a prova, sem PII. */
+    evidence: {
+        ruleId: string | null;
+        ruleVersion: number | null;
+        jurisdiction: JurisdictionRef | null;
+        /** Atributos que a condição cita e o perfil não conhece. */
+        missingAttributes: string[];
+        /** Atributos que a condição de fato usou. Nunca o perfil inteiro. */
+        consideredAttributes: string[];
+    };
+}
+export interface ApplicabilityInput {
+    rule: FiscalRuleRef | null;
+    profile: FiscalProfile;
+    clientJurisdiction: ClientJurisdiction;
+    /**
+     * Data que representa a competência — normalmente o primeiro dia dela.
+     * É contra ela que a vigência é medida, e não contra "hoje": reprocessar
+     * uma competência antiga precisa usar a regra que valia NAQUELE mês.
+     */
+    referenceDate: string;
+}
+export declare function decideApplicability(input: ApplicabilityInput): ApplicabilityDecision;
+/** Só `APPLICABLE` gera. Todo o resto é espera, ausência ou decisão contrária. */
+export declare function generates(decision: ApplicabilityDecision): boolean;
+//# sourceMappingURL=applicability.d.ts.map

package/dist/fiscal/applicability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applicability.d.ts","sourceRoot":"","sources":["../../src/fiscal/applicability.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,gBAAgB;AAClB,8EAA8E;GAC5E,mBAAmB;AACrB,uDAAuD;GACrD,qBAAqB,GACrB,yBAAyB,GACzB,cAAc,GACd,eAAe,CAAC;AAEpB,MAAM,MAAM,UAAU,GACpB,gBAAgB,GAAG,oBAAoB,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAEjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IACzC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,eAAe,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,eAAe,GAAG,IAAI,CAAC;QACrC,4DAA4D;QAC5D,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,qEAAqE;QACrE,oBAAoB,EAAE,MAAM,EAAE,CAAC;KAChC,CAAC;CACH;AA0CD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB,kBAAkB,EAAE,kBAAkB,CAAC;IACvC;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,qBAAqB,CA8HpF;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAElE"}

package/dist/fiscal/applicability.js

@@ -0,0 +1,160 @@
+import { evaluate, missingAttributes, parseCondition, referencedAttributes, } from './conditions.js';
+const semRegra = (reason) => ({
+    outcome: 'RULE_NOT_CONFIGURED',
+    reason,
+    evidence: {
+        ruleId: null,
+        ruleVersion: null,
+        jurisdiction: null,
+        missingAttributes: [],
+        consideredAttributes: [],
+    },
+});
+/**
+ * A regra alcança este cliente geograficamente?
+ *
+ * Federal alcança todos. Estadual exige UF igual. Municipal exige UF **e**
+ * código IBGE iguais — nome de município não entra na comparação, porque
+ * "Goiania" e "Goiânia" são o mesmo lugar e strings diferentes.
+ *
+ * Cliente sem a informação não é "fora": é desconhecido, e vira
+ * `INSUFFICIENT_DATA` em vez de sumir da lista.
+ */
+function jurisdictionMatch(rule, client) {
+    if (rule.scope === 'federal')
+        return 'match';
+    if (client.uf === null)
+        return 'unknown';
+    if (client.uf !== rule.uf)
+        return 'no_match';
+    if (rule.scope === 'state')
+        return 'match';
+    if (client.cityIbge === null)
+        return 'unknown';
+    return client.cityIbge === rule.cityIbge ? 'match' : 'no_match';
+}
+/** A competência cai dentro da vigência? Compara datas ISO, sem fuso. */
+function withinValidity(rule, referenceDate) {
+    if (referenceDate < rule.validFrom)
+        return false;
+    return rule.validUntil === null || referenceDate <= rule.validUntil;
+}
+export function decideApplicability(input) {
+    const { rule, profile, clientJurisdiction, referenceDate } = input;
+    if (!rule) {
+        return semRegra('Não há regra cadastrada para esta obrigação nesta jurisdição.');
+    }
+    const jurisdiction = rule.jurisdiction;
+    const base = { ruleId: rule.id, ruleVersion: rule.version, jurisdiction };
+    // ── 1 · Estado da regra, antes de qualquer coisa do cliente ─────────────
+    if (rule.status === 'disabled') {
+        return {
+            outcome: 'RULE_DISABLED',
+            reason: 'A regra está desligada.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    if (rule.status === 'not_configured') {
+        return {
+            outcome: 'RULE_NOT_CONFIGURED',
+            reason: 'A regra existe como marcador, mas ninguém configurou jurisdição ou vencimento — não há data a aplicar.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    // ── 2 · Vigência ────────────────────────────────────────────────────────
+    if (!withinValidity(rule, referenceDate)) {
+        const futura = referenceDate < rule.validFrom;
+        return {
+            outcome: futura ? 'RULE_NOT_CONFIGURED' : 'RULE_EXPIRED',
+            reason: futura
+                ? `A regra só passa a valer em ${rule.validFrom}; para esta competência não há regra vigente.`
+                : `A regra deixou de valer em ${rule.validUntil}.`,
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    if (rule.status === 'expired') {
+        return {
+            outcome: 'RULE_EXPIRED',
+            reason: 'A regra está marcada como vencida.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    // ── 3 · Jurisdição ──────────────────────────────────────────────────────
+    const geo = jurisdictionMatch(jurisdiction, clientJurisdiction);
+    if (geo === 'no_match') {
+        return {
+            outcome: 'NOT_APPLICABLE',
+            reason: jurisdiction.scope === 'state'
+                ? `Regra de ${jurisdiction.uf}; o cliente está em ${clientJurisdiction.uf}.`
+                : 'A regra é de outro município.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    if (geo === 'unknown') {
+        const falta = jurisdiction.scope === 'state' ? 'UF' : 'código IBGE do município';
+        return {
+            outcome: 'INSUFFICIENT_DATA',
+            reason: `Falta ${falta} no cadastro do cliente para saber se esta regra o alcança.`,
+            evidence: {
+                ...base,
+                missingAttributes: [jurisdiction.scope === 'state' ? 'state_uf' : 'municipality_ibge_code'],
+                consideredAttributes: [],
+            },
+        };
+    }
+    // ── 4 · Condições declarativas ──────────────────────────────────────────
+    let condition;
+    try {
+        condition = parseCondition(rule.conditions);
+    }
+    catch (err) {
+        // Regra malformada é defeito do catálogo, não decisão sobre o cliente.
+        // Nunca vira "não se aplica": isso esconderia a obrigação.
+        return {
+            outcome: 'RULE_NOT_CONFIGURED',
+            reason: `A condição desta regra está malformada: ${err instanceof Error ? err.message : 'inválida'}.`,
+            evidence: { ...base, missingAttributes: [], consideredAttributes: [] },
+        };
+    }
+    const considerados = [...referencedAttributes(condition)].sort();
+    const faltando = missingAttributes(condition, profile);
+    const veredito = evaluate(condition, profile);
+    if (veredito === 'unknown') {
+        return {
+            outcome: 'INSUFFICIENT_DATA',
+            reason: faltando.length === 1
+                ? `Falta informar "${faltando[0]}" no perfil do cliente.`
+                : `Faltam informações no perfil do cliente: ${faltando.join(', ')}.`,
+            evidence: { ...base, missingAttributes: faltando, consideredAttributes: considerados },
+        };
+    }
+    if (veredito === false) {
+        return {
+            outcome: 'NOT_APPLICABLE',
+            reason: 'O perfil do cliente não atende às condições desta regra.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: considerados },
+        };
+    }
+    // ── 5 · Conferência humana, por último ──────────────────────────────────
+    //
+    // Fica depois da aplicabilidade de propósito: dizer "pendente de conferência"
+    // sobre uma regra que nem se aplica a este cliente mandaria o escritório
+    // conferir o que não usaria.
+    if (rule.status === 'pending_validation') {
+        return {
+            outcome: 'RULE_PENDING_VALIDATION',
+            reason: 'A regra se aplica, mas ainda não foi conferida por uma pessoa.',
+            evidence: { ...base, missingAttributes: [], consideredAttributes: considerados },
+        };
+    }
+    return {
+        outcome: 'APPLICABLE',
+        reason: 'A regra está vigente, conferida, e o perfil do cliente a atende.',
+        evidence: { ...base, missingAttributes: [], consideredAttributes: considerados },
+    };
+}
+/** Só `APPLICABLE` gera. Todo o resto é espera, ausência ou decisão contrária. */
+export function generates(decision) {
+    return decision.outcome === 'APPLICABLE';
+}
+//# sourceMappingURL=applicability.js.map

package/dist/fiscal/applicability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applicability.js","sourceRoot":"","sources":["../../src/fiscal/applicability.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/collection/authorization.d.ts

@@ -0,0 +1,152 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalCredentialKind, FiscalDocumentType, FiscalEnvironment } from '../eligibility.js';
+import { type FiscalCompetence } from './competence.js';
+/**
+ * O portão que se gasta.
+ *
+ * ## Por que os três desligamentos da Fase 2 não bastavam
+ *
+ * O motor fiscal já tem `FISCAL_SYNC_ENABLED`, elegibilidade por cliente e
+ * política de cadência. Todos são ESTADO: uma vez ligados, ficam ligados, e essa
+ * é a forma certa de autorizar um REGIME — "este escritório opera automação
+ * fiscal para estes clientes".
+ *
+ * A primeira consulta real a um ambiente oficial não é um regime. É um ato: o
+ * titular autorizou UMA leitura, de UM cliente, sobre UM período, e o que ele
+ * autorizou não deve sobreviver à própria execução. Um estado permanente aqui
+ * significaria que a segunda consulta — a que ninguém aprovou — acontece com a
+ * mesma bênção da primeira.
+ *
+ * ## As quatro propriedades, e onde cada uma mora
+ *
+ *   uma execução     `max_runs = 1`, CHECK na 0060. Não é configuração.
+ *   somente leitura  `operation = 'READ_ONLY'`, CHECK na 0060. Mutação é ingravável.
+ *   prazo            `expires_at`. Uma autorização esquecida morre sozinha.
+ *   consumo          `runs_consumed`, com o teto no CHECK e a corrida resolvida
+ *                    pelo `UPDATE ... WHERE consumed_at IS NULL`, no banco.
+ *
+ * O consumo é a parte que não pode viver no TypeScript. Dois workers lendo
+ * "ainda não consumida" e executando os dois é exatamente a segunda consulta não
+ * autorizada; quem decide é a linha, num único `UPDATE` condicional que devolve
+ * zero para o perdedor.
+ */
+export type FiscalRunOperation = 'READ_ONLY';
+export interface FiscalRunAuthorization {
+    id: string;
+    clientId: string;
+    documentType: FiscalDocumentType;
+    environment: FiscalEnvironment;
+    source: string;
+    credentialKind: FiscalCredentialKind;
+    operation: FiscalRunOperation;
+    competence: FiscalCompetence;
+    maxRuns: number;
+    runsConsumed: number;
+    authorizedBy: string;
+    authorizedAt: string;
+    responsibleName: string | null;
+    expiresAt: string;
+    consumedAt: string | null;
+    revokedAt: string | null;
+    revokeReason: string | null;
+    /** Declara que a credencial ainda não fora aceita por nenhum ambiente. */
+    firstContact: boolean;
+    /** Quem disparou. Primeiro contato só aceita `manual`. */
+    triggerKind: 'manual' | 'scheduled';
+    /** O material aprovado. Trocar o certificado invalida esta autorização. */
+    credentialFingerprint: string | null;
+    /** O estado derivado, calculado contra o relógio de quem pergunta. */
+    state: FiscalAuthorizationState;
+}
+/**
+ * `expired` é distinto de `consumed`, e ambos de `revoked`.
+ *
+ * Colapsá-los em "inválida" custaria a única informação útil na tela: uma
+ * autorização vencida pede que se emita outra; uma consumida diz que a execução
+ * já aconteceu e a pergunta certa é sobre o resultado dela; uma revogada diz que
+ * alguém decidiu parar, e o motivo está gravado.
+ */
+export type FiscalAuthorizationState = 'live' | 'consumed' | 'expired' | 'revoked';
+export declare class AuthorizationConflictError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+export interface GrantRunAuthorizationInput {
+    clientId: string;
+    documentType: FiscalDocumentType;
+    environment: FiscalEnvironment;
+    source: string;
+    credentialKind?: FiscalCredentialKind;
+    competenceYear: number;
+    competenceMonth: number;
+    /** Recorte manual dentro da competência. Ausente = a competência inteira. */
+    periodStart?: string;
+    periodEnd?: string;
+    responsibleName?: string | null;
+    authorizedBy: string;
+    /** Validade em horas. Curta de propósito: um portão aberto ontem não vale hoje. */
+    validForHours?: number;
+    /**
+     * PRIMEIRO CONTATO: quem autoriza declara saber que esta credencial ainda não
+     * foi aceita por nenhum ambiente oficial, e aceita que esta execução seja o
+     * ato que descobre. Sem isto, a autorização exige credencial já verificada — e
+     * a primeira nunca aconteceria. Ver `first-contact.ts`.
+     */
+    firstContact?: boolean;
+    /**
+     * Quem disparou. `scheduled` NUNCA pode acompanhar `firstContact` — e é um
+     * CHECK da 0062 que garante, não este comentário.
+     */
+    triggerKind?: 'manual' | 'scheduled';
+    /**
+     * Impressão digital do certificado vigente no momento da autorização.
+     *
+     * Autorizar é aprovar UM material. Trocar o certificado depois invalida a
+     * autorização, porque o que a pessoa aprovou deixou de existir.
+     */
+    credentialFingerprint?: string | null;
+}
+/**
+ * Emite a autorização.
+ *
+ * Recusa por CONFLITO quando já existe uma viva para o mesmo par
+ * (cliente, fonte, ambiente, competência) — não por capricho de unicidade, mas
+ * porque duas autorizações vivas somam duas execuções, e o produto teria
+ * prometido uma.
+ *
+ * A unicidade é do índice parcial da 0060; o `SELECT` prévio existe só para
+ * devolver um erro legível em vez de uma violação de constraint.
+ */
+export declare function grantRunAuthorization(tx: Tx, input: GrantRunAuthorizationInput): Promise<FiscalRunAuthorization>;
+/**
+ * Consome a autorização — e é AQUI que a unicidade da execução acontece.
+ *
+ * Um `SELECT` seguido de `UPDATE` deixaria a janela em que dois processos leem
+ * "viva" e ambos executam. O `WHERE consumed_at IS NULL` dentro do próprio
+ * `UPDATE` fecha essa janela no banco: o segundo afeta zero linhas e recebe
+ * `null`, que é o sinal de "não execute".
+ *
+ * Devolve `null` — e não lança — para todo desfecho de recusa. Quem chama é o
+ * orquestrador no meio de uma carteira, e uma exceção aqui derrubaria o lote por
+ * causa de um portão fechado, que é estado normal.
+ */
+export declare function consumeRunAuthorization(tx: Tx, input: {
+    authorizationId: string;
+    runId: string;
+}): Promise<FiscalRunAuthorization | null>;
+/**
+ * Cancela antes da execução.
+ *
+ * O mecanismo de abortar (C1.34) não precisa de tabela nova: revogar a
+ * autorização é o cancelamento, porque sem ela não há execução real. Revogar uma
+ * já consumida é permitido e não desfaz nada — só registra a decisão, para o
+ * caso em que alguém descobre depois que não deveria ter autorizado.
+ */
+export declare function revokeRunAuthorization(tx: Tx, input: {
+    authorizationId: string;
+    revokedBy: string;
+    reason: string;
+}): Promise<boolean>;
+/** As autorizações de um cliente, mais recentes primeiro. Sem segredo por construção. */
+export declare function listRunAuthorizations(tx: Tx, clientId: string): Promise<FiscalRunAuthorization[]>;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/fiscal/collection/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../../src/fiscal/collection/authorization.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/collection/authorization.js

@@ -0,0 +1,178 @@
+import { uuidv7 } from '@baruk/shared';
+import { competenceOf, validateWindow } from './competence.js';
+export class AuthorizationConflictError extends Error {
+    detail;
+    constructor(detail) {
+        super(`autorização recusada: ${detail}`);
+        this.detail = detail;
+        this.name = 'AuthorizationConflictError';
+    }
+}
+const DEFAULT_VALIDITY_HOURS = 48;
+const MAX_VALIDITY_HOURS = 168; // sete dias
+/**
+ * Emite a autorização.
+ *
+ * Recusa por CONFLITO quando já existe uma viva para o mesmo par
+ * (cliente, fonte, ambiente, competência) — não por capricho de unicidade, mas
+ * porque duas autorizações vivas somam duas execuções, e o produto teria
+ * prometido uma.
+ *
+ * A unicidade é do índice parcial da 0060; o `SELECT` prévio existe só para
+ * devolver um erro legível em vez de uma violação de constraint.
+ */
+export async function grantRunAuthorization(tx, input) {
+    const competence = competenceOf(input.competenceYear, input.competenceMonth);
+    const periodStart = input.periodStart ?? competence.periodStart;
+    const periodEnd = input.periodEnd ?? competence.periodEnd;
+    validateWindow(competence, periodStart, periodEnd);
+    const hours = input.validForHours ?? DEFAULT_VALIDITY_HOURS;
+    if (!Number.isInteger(hours) || hours < 1 || hours > MAX_VALIDITY_HOURS) {
+        throw new AuthorizationConflictError(`validade deve estar entre 1 e ${MAX_VALIDITY_HOURS} horas`);
+    }
+    const live = await tx `
+    SELECT id FROM fiscal_run_authorization
+     WHERE client_id = ${input.clientId}
+       AND source = ${input.source}
+       AND environment = ${input.environment}
+       AND competence_year = ${competence.year}
+       AND competence_month = ${competence.month}
+       AND consumed_at IS NULL AND revoked_at IS NULL
+     LIMIT 1
+  `;
+    if (live[0]) {
+        throw new AuthorizationConflictError('já existe uma autorização viva para este cliente, fonte, ambiente e competência');
+    }
+    const rows = await tx `
+    INSERT INTO fiscal_run_authorization (
+      id, tenant_id, client_id, document_type, environment, source, credential_kind,
+      operation, competence_year, competence_month, period_start, period_end,
+      max_runs, runs_consumed, authorized_by, responsible_name, expires_at,
+      first_contact, trigger_kind, credential_fingerprint
+    ) VALUES (
+      ${uuidv7()}, current_setting('app.current_tenant')::uuid, ${input.clientId},
+      ${input.documentType}, ${input.environment}, ${input.source},
+      ${input.credentialKind ?? 'certificate_a1'},
+      'READ_ONLY', ${competence.year}, ${competence.month}, ${periodStart}, ${periodEnd},
+      1, 0, ${input.authorizedBy}, ${input.responsibleName ?? null},
+      now() + (${hours}::int * interval '1 hour'),
+      ${input.firstContact ?? false}, ${input.triggerKind ?? 'manual'},
+      ${input.credentialFingerprint ?? null}
+    )
+    RETURNING ${tx.unsafe(AUTHORIZATION_COLUMNS)}
+  `;
+    return mapAuthorization(rows[0]);
+}
+/**
+ * Consome a autorização — e é AQUI que a unicidade da execução acontece.
+ *
+ * Um `SELECT` seguido de `UPDATE` deixaria a janela em que dois processos leem
+ * "viva" e ambos executam. O `WHERE consumed_at IS NULL` dentro do próprio
+ * `UPDATE` fecha essa janela no banco: o segundo afeta zero linhas e recebe
+ * `null`, que é o sinal de "não execute".
+ *
+ * Devolve `null` — e não lança — para todo desfecho de recusa. Quem chama é o
+ * orquestrador no meio de uma carteira, e uma exceção aqui derrubaria o lote por
+ * causa de um portão fechado, que é estado normal.
+ */
+export async function consumeRunAuthorization(tx, input) {
+    const rows = await tx `
+    UPDATE fiscal_run_authorization SET
+      runs_consumed = runs_consumed + 1,
+      consumed_at = now(),
+      consumed_by_run_id = ${input.runId},
+      updated_at = now()
+    WHERE id = ${input.authorizationId}
+      AND consumed_at IS NULL
+      AND revoked_at IS NULL
+      AND expires_at > now()
+      AND runs_consumed < max_runs
+    RETURNING ${tx.unsafe(AUTHORIZATION_COLUMNS)}
+  `;
+    return rows[0] ? mapAuthorization(rows[0]) : null;
+}
+/**
+ * Cancela antes da execução.
+ *
+ * O mecanismo de abortar (C1.34) não precisa de tabela nova: revogar a
+ * autorização é o cancelamento, porque sem ela não há execução real. Revogar uma
+ * já consumida é permitido e não desfaz nada — só registra a decisão, para o
+ * caso em que alguém descobre depois que não deveria ter autorizado.
+ */
+export async function revokeRunAuthorization(tx, input) {
+    const rows = await tx `
+    UPDATE fiscal_run_authorization SET
+      revoked_at = now(), revoked_by = ${input.revokedBy},
+      revoke_reason = ${input.reason}, updated_at = now()
+    WHERE id = ${input.authorizationId} AND revoked_at IS NULL
+    RETURNING id
+  `;
+    return rows.count > 0;
+}
+/** As autorizações de um cliente, mais recentes primeiro. Sem segredo por construção. */
+export async function listRunAuthorizations(tx, clientId) {
+    const rows = await tx `
+    SELECT ${tx.unsafe(AUTHORIZATION_COLUMNS)}
+      FROM fiscal_run_authorization
+     WHERE client_id = ${clientId}
+     ORDER BY authorized_at DESC
+     LIMIT 50
+  `;
+    return rows.map(mapAuthorization);
+}
+const AUTHORIZATION_COLUMNS = `
+  id, client_id, document_type, environment, source, credential_kind, operation,
+  competence_year, competence_month, period_start, period_end, max_runs, runs_consumed,
+  authorized_by, authorized_at, responsible_name, expires_at, consumed_at,
+  revoked_at, revoke_reason, first_contact, trigger_kind, credential_fingerprint
+`;
+function mapAuthorization(r) {
+    return {
+        id: r.id,
+        clientId: r.client_id,
+        documentType: r.document_type,
+        environment: r.environment,
+        source: r.source,
+        credentialKind: r.credential_kind,
+        operation: 'READ_ONLY',
+        competence: {
+            year: r.competence_year,
+            month: r.competence_month,
+            label: `${r.competence_year}-${String(r.competence_month).padStart(2, '0')}`,
+            periodStart: isoDate(r.period_start),
+            periodEnd: isoDate(r.period_end),
+        },
+        maxRuns: r.max_runs,
+        runsConsumed: r.runs_consumed,
+        authorizedBy: r.authorized_by,
+        authorizedAt: r.authorized_at.toISOString(),
+        responsibleName: r.responsible_name,
+        firstContact: r.first_contact ?? false,
+        triggerKind: r.trigger_kind ?? 'manual',
+        credentialFingerprint: r.credential_fingerprint ?? null,
+        expiresAt: r.expires_at.toISOString(),
+        consumedAt: r.consumed_at?.toISOString() ?? null,
+        revokedAt: r.revoked_at?.toISOString() ?? null,
+        revokeReason: r.revoke_reason,
+        state: stateOf(r),
+    };
+}
+/**
+ * A ordem das perguntas importa: revogada vence consumida, que vence vencida.
+ *
+ * Uma autorização consumida e depois revogada deve aparecer como revogada — é a
+ * decisão mais recente, e é a que alguém precisa ver ao investigar.
+ */
+function stateOf(r) {
+    if (r.revoked_at)
+        return 'revoked';
+    if (r.consumed_at)
+        return 'consumed';
+    if (r.expires_at.getTime() <= Date.now())
+        return 'expired';
+    return 'live';
+}
+function isoDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+//# sourceMappingURL=authorization.js.map

package/dist/fiscal/collection/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../../src/fiscal/collection/authorization.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/collection/competence.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A janela da coleta — dita por extenso, nunca deduzida.
+ *
+ * ## O relato que originou este módulo
+ *
+ * A equipe do escritório chama de "dar baixa nas notas" o trabalho de, na virada
+ * do mês, entrar nos portais e recolher os documentos do período. Ao descrever
+ * esse trabalho, o relato humano trouxe exemplos de datas que não fechavam entre
+ * si — o que é absolutamente normal em conversa, e absolutamente perigoso como
+ * fonte de regra.
+ *
+ * A tentação é transformar "mês anterior" em constante. O erro que isso produz é
+ * silencioso: uma coleta rodada em 01/11 sobre uma janela que ninguém confirmou
+ * traz documentos de um período que não é o que a pessoa tinha em mente, e a
+ * ausência do que faltava só aparece no fechamento.
+ *
+ * Aqui a competência é um par ano/mês, e o período é um par de DATAS derivado
+ * dele. A sugestão padrão existe — mês calendário anterior —, mas ela é uma
+ * SUGESTÃO exibida, não um valor implícito: a tela mostra "serão consultados
+ * documentos de DD/MM/AAAA a DD/MM/AAAA" antes de qualquer execução, e as duas
+ * datas são gravadas na autorização.
+ */
+export interface FiscalCompetence {
+    year: number;
+    month: number;
+    /** `YYYY-MM`, o mesmo vocabulário de `competence.label` (0026). */
+    label: string;
+    /** Primeiro dia da competência, `YYYY-MM-DD`. */
+    periodStart: string;
+    /** Último dia da competência, `YYYY-MM-DD`. Nunca "hoje", nunca 30 fixo. */
+    periodEnd: string;
+}
+export declare class InvalidCompetenceError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+/** A política padrão desta fase, nomeada para poder ser citada e mudada. */
+export declare const DEFAULT_COMPETENCE_POLICY: "PREVIOUS_CALENDAR_MONTH";
+/**
+ * A competência de um par ano/mês.
+ *
+ * O último dia sai do calendário: `Date.UTC(ano, mês, 0)` — com o mês em base 1
+ * — devolve o último dia daquele mês. Fevereiro bissexto sai de graça, que é o
+ * ponto de não escrever `30`.
+ */
+export declare function competenceOf(year: number, month: number): FiscalCompetence;
+/**
+ * A SUGESTÃO padrão para uma execução feita em `reference`: o mês calendário
+ * anterior.
+ *
+ * Chama-se `suggest` e não `default` de propósito. Uma função chamada
+ * `defaultCompetence()` acaba sendo usada como valor efetivo por quem não leu;
+ * `suggestCompetenceFor()` obriga quem chama a decidir o que fazer com a
+ * sugestão — que é exibi-la ao lado das duas datas.
+ */
+export declare function suggestCompetenceFor(reference: Date): FiscalCompetence;
+/**
+ * Confere uma janela informada à mão contra a competência declarada.
+ *
+ * Permitir janela manual e conferi-la não são opostos: o operador pode querer um
+ * recorte menor dentro do mês — o que é legítimo —, mas uma janela que atravessa
+ * a competência declarada significa que um dos dois campos está errado, e gravar
+ * os dois deixaria a autorização dizendo duas coisas.
+ */
+export declare function validateWindow(competence: FiscalCompetence, periodStart: string, periodEnd: string): void;
+//# sourceMappingURL=competence.d.ts.map