agentleFS
gabrielh-silvestregabrielh-silvestre/hexlog/src/AGENTS.md

hexlog / src

AGENTS.md4 starsChanged 19 days agoMITView on GitHub

Parent context: ../AGENTS.md Generated: 2026-09-17 · Updated: 2026-10-07

  • Reads credentials

The file

Files
AGENTS.md

src

Parent context: ../AGENTS.md Generated: 2026-09-17 · Updated: 2026-10-07

Purpose

Código-fonte TypeScript do servidor MCP stdio hexlog: expõe exatamente 12 tools para agentes registrarem seu histórico de trabalho (registros tipados com relações e gates declarativos, anexos) num log JSONL append-only com cadeia de hash por processo, mais o instalador que versiona o artefato e instala o hook de isolamento Bash no Claude Code.

Key Files

FileDescription
directory.tsdataDir(env): resolve $XDG_DATA_HOME/hexlog ou ~/.local/share/hexlog
errors.tsHexlogError (classe de erro de domínio com code/details), ErrorCode (a união dos códigos de erro; a contagem está no ADR 0009, item 7, e em test/skill-coherence.spec.ts), Detail (além de path/code, os campos opcionais current, process, pid, versions (as versões existentes de uma definição) e kind (o kind do nome de relação fixado, no kind-mismatch)), domainError (o construtor de um único Detail: path, code e message posicionais, e o extra opcional sem as chaves undefined), internalError (o INTERNAL sem details), invalidInput (o INVALID_INPUT com um único Detail, usado por commands/, queries/ e adapters/), legacyDataError (a recusa LEGACY_DATA com o comando de arquivamento em details, D-13: o kernel MCP e os scripts de leitura usam a mesma), brokenChain (o PROCESS_CORRUPTED com broken-chain e o processo em details[0].process: queries/read.ts e commands/register/state.ts não se importam, então a mesma função mora aqui), issueDetails (Zod → JSON Pointer), violationsCapped (o Detail violations-capped de um registro cuja lista de violações o teto de custo cortou; code de Detail, não ErrorCode) e capDetails (deduplica por path+code+message e corta details em 50, com too-many-errors por último e os violations-capped dentro dos 50, depois dos erros, cuja contagem soma a de um too-many-errors que já veio na lista; usado por issueDetails, pelo validador, por commands/register/static.ts#prepareBatch e pelo kernel MCP). Toda construção de HexlogError mora aqui: os construtores de lista (fromIssues, fromDetails, invalidArgs, invalidRecord) e os de reembrulho (mapDetails, withPath) mais uma fábrica nomeada por fato do contrato, só com primitivos, Name e Detail (nenhum tipo de porta nem builtin, porque domain/ importa este arquivo): ioError, lockTimeout, as de anexo (attachmentNotFound, attachmentCorrupted, outsideAllowedRoot, tooBigFile), de processo e definição (processNotFound, unreadableManifest, processTooLarge, definitionNotFound, unreadableDefinition, invalidDefinition, noDefinitions, schemaRootNotObject, breakingChange, exclusiveWriteExhausted), de consulta (projectNotFound, typeNotFound, gateNotFound, invalidFilter, typeNotPinned, markerNotFound, markerProcessNotFound, invalidCursor, invalidCursorPayload) e do register (relationNotFound, cycleRejected, keyConflict)
domain/ids.tsÁrvore nova (1.0), domínio puro: Name, Hash, Instant, Target, RecordId, Marker (tipo, D-24), alias, TypeNames (lista de tipos não vazia e sem repetição), processOf, RESERVED_PROCESS_NAMES e isReservedProcessName (o predicado único de nome reservado, usado por commands/process.ts e adapters/fs/process-store.ts)
domain/record.tsHexRecord, Author, Relation/RelationInput/RelationKind, BatchItem, KindOrAs, withCanonicalLimit (o refine de teto em caracteres canônicos, usado por data e por domain/definitions.ts; a message traz o tamanho medido, (got N)) e os tetos DATA_MAX_CHARS, BATCH_MAX e RELATIONS_MAX (todos em docs/tetos-dominio-v1.md)
domain/manifest.tsManifest: o schema estrito do process.json (D-03; project, process, createdAt, fixed com as versões de tipos, relações e gates, e hashes de cada grupo, mais lineageInheritance?: true, gravado só por create_process); a âncora da cadeia é o sha256 do JCS deste objeto (anchor em domain/chain.ts)
domain/chain.tsCadeia de hash da árvore nova: sha256hex, hashOfJcs (sha256 do JCS de um valor: manifesto, definição e lote), fingerprint, hashLink, anchor, isValidLink (confere um elo contra Expected e devolve { link } ou { reasons } com invalid-line, diverging-seq e hash-mismatch), Batch e Link, com os tetos BATCH_KEY_MAX e BATCH_ALIASES_MAX
domain/relations.tsRelações entre registros: checkRelation (regras de relação com RuleCode; o RuleContext dá a vigência por tipo de relação em vigencyFor), resolveKind (exportado: resolve o kind a partir de kind/as e dos nomes do manifesto, e o serviço o roda antes do lock), hasCycle, vigência (buildVigency) e prova vencida (needsReview, que recebe a Inheritance para o supports herdado contar como vivo)
domain/definitions.tsSchemas de RecordType/RelationName/Gate, semver major.minor (gramática única CANONICAL_VERSION, também usada pelo store; parseVersion, bumpVersion, compareVersions), classifyTypeChange/classifyRelationChange, attachmentFields e os tetos RECORD_TYPE_MAX_CHARS, RELATION_GATE_MAX_CHARS (16.000 caracteres canônicos para RelationName e Gate) e GATE_QUESTIONS_MAX
domain/schema-walk.tsPercurso puro dos subschemas de um JSON Schema (walkSubschemas, usado por adapters/validator.ts#ruleDetails), expandedSize e countNodes (o custo estimado que adapters/validator.ts#createValidator compara com COST_CEILING), withoutFreePatterns (o schema sem pattern/patternProperties, que queries/describe-type.ts devolve) e hasKeywordAt
domain/formats.tsCatálogo fechado de formatos que o validador registra além dos do ajv-formats: FORMAT_CATALOG, isGitSha e catalogNames; entrada do catálogo é imutável (ver docs/directives/invariantes.md)
domain/gate.tsGate declarativo: GateQuestion, Selector, matchesSelector/matchesTargetPrefix, QuestionResult (união discriminada por kind), evaluateGate, puro sobre registros já carregados, e summarizeQuestion com EvidenceMode (failing, counts, full), que enxuga a evidence de uma pergunta; as perguntas approved e no_pending aceitam inherit: true e somam as relações herdadas (GateInput.isInheritanceActive decide por processo)
domain/inheritance.tsHerança de relações pela linhagem de supersedes, só na leitura: buildInheritance devolve Inheritance (into, outOf, has) de InheritedEdge com origin; NO_INHERITANCE é a herança vazia, também a resposta sem isActive
ports.tsÁrvore nova: as portas do núcleo — ProcessRef, RawProcess, Decision, ProcessStore (create, write e o lado de leitura ProcessReader: read, readManifest (só o process.json, sem o log), list, listProjects), mais DefinitionStore (leitura em DefinitionReader: names, versions, read) e AttachmentStore (leitura em AttachmentReader: status, read; putText e putPath devolvem AttachmentPut: hash, bytes e deduplicated), Validator (checkSchema e validate) e SearchIndex (search(process, records, text): o ProcessRef é a chave do cache do índice e records pode ser o log inteiro, o prefixo cortado pelo marcador ou a lista mesclada do projeto sob o ProcessRef com process: '*'); queries/ depende só dos *Reader (ISP); uma implementação real por porta e nenhuma em memória; telemetria: Telemetry (enabled, trace, recordLoad, degraded, shutdown), CallProbe e LoadReport, só tipos e a porta que adapters/telemetry/ implementa (mcp/ importa só Telemetry e CallProbe)
adapters/fs/atomic.tsGravação atômica em disco: writeFileAtomic (temporário + fsync + rename, ou link exclusivo; só Linux, teto no ponytail: dela), writeSynced, fsyncPath, errnoCode e isDirectoryTaken
adapters/fs/data-format.tsFormato em disco do dado 1.0, única fonte dos nomes de pasta e arquivo, usada também pelos testes: dataRoot (<D>/.v1), processPaths (dir, manifest, log e lock de um processo), definitionDir/definitionFile (pasta e arquivo <major>.<minor>.json de uma definição), attachmentsDir/blobFile (blobs de anexo), as constantes MANIFEST_FILE, LOG_FILE, LOCK_DIR, ATTACHMENTS_DIR, ARCHIVE_DIR e VERSION_SUFFIX (todas as funções recebem nomes e versão já validados), LEGACY_NAME e detectLegacy (detecção positiva do dado 0.x, D-13)
adapters/fs/lock.tsLock por processo (D-12): createLockManager (acquire, confirm, release), moveAside, isPidAlive (zumbi conta como morto; archive.ts e installation.ts o reusam); dono identificado por pid, bootId e token, órfão roubado, dono vivo nunca
adapters/fs/io.tsHelpers de I/O compartilhados pelos três stores: mapIo/toHexlogError (errno vira IO_ERROR só com o código, D-26, pela fábrica ioError de errors.ts), safeName, readIfPresent, existsStrict (só ENOENT vale ausente) e listDirectories
adapters/fs/process-store.tscreateProcessStore (D-25): ProcessStore sobre <D>/.v1/<projeto>/<processo>/{process.json,records.jsonl}, escrita sob o lock com um fsync por lote; teto de 64 MiB no records.jsonl (MAX_LOG_BYTES, PROCESS_TOO_LARGE), conferido com stat antes de ler e antes de gravar (o lote que cruzaria o teto é recusado); readManifest lê só o process.json; a opção onLoad recebe um LoadReport (ref, papel target ou read, bytes e lines quando o log foi lido) a cada leitura, sem derrubar a leitura se lançar; readLogText devolve { text, bytes } e avisa o tamanho por onOversize antes de recusar o log acima do teto (relato com bytes e sem lines); create (papel target) e readManifest (papel read) relatam sem tamanho; a contagem de linhas só roda quando há onLoad
adapters/fs/definition-store.tscreateDefinitionStore (D-25): DefinitionStore sobre <D>/.v1/<projeto>/{types,relations,gates}/<nome>/<major>.<minor>.json; versão gravada por link exclusivo, nunca sobrescrita, e o <nome>.json legado do 0.x nunca é lido; read ausente distingue nome sem nenhuma versão (pasta inexistente ou vazia: unknown-name) de versão inexistente num nome com versões (unknown-version, com versions em Detail, nunca vazia); write valida a definição contra o schema do domínio antes de gravar (INTERNAL com invalid-definition, sem gravar)
adapters/fs/attachment-store.tscreateAttachmentStore (D-15, D-25): AttachmentStore sobre <D>/.v1/<projeto>/attachments/<sha256>; blob imutável com teto ATTACHMENT_MAX_BYTES (1 MiB), putPath só dentro do cwd injetado e fora do dataDir, memo de verificação por ino/size/mtime/ctime; texto vazio e surrogate solto em putText não são recusados aqui: moram em commands/attachment.ts, que usa String#isWellFormed
adapters/validator.tscreateValidator: Validator com ajv estrito (2020-12) e ajv-formats, mais o formato attachment (D-16); validate compila uma vez por objeto de schema (WeakMap, o lote de um register repete o mesmo schema), sem registrar $id e recusando $id que o ajv já conhece e $async, em quatro instâncias do ajv (meta, checker e as duas do validate, firstPass e fullPass): meta só confere o schema contra o metaschema; checkSchema com allErrors: true devolve no máximo 50 Detail sem repetição, com too-many-errors por último quando corta, e validate roda sempre um primeiro passe com allErrors: false e verbose: true e, só se o dado reprova e expandedSize(schema) * countNodes(dado) cabe em COST_CEILING (25.000), um segundo passe com allErrors: true, compilado sob demanda, que devolve todas as violações do dado; acima do teto, ficam as do primeiro passe, uma por subschema, mais um violations-capped; nos dois, (got N) na message de maxLength, minLength, maximum e minimum (em anyOf/oneOf/propertyNames saem as dos ramos); checker e validate são neutros (createCompiler): pattern e patternProperties não são aplicados e o motor de regex do ajv nunca casa, então nenhum regex vindo do schema é construído nem executado, e patternProperties conta como ausente (additionalProperties: false recusa a propriedade que só ele admitia); checkSchema devolve sempre path relativo ao documento do schema, e o erro de compilação sai com path vazio (o serviço defineType prefixa /schema); recusa todo pattern e todo patternProperties com code pattern-not-allowed e path do campo (a varredura pura ruleDetails roda antes de qualquer ajv; o checker grava o que só um $ref para dado alcança, e o $ref para o metaschema do JSON Schema não é recusado), e o formato do campo vem do catálogo (FORMAT_CATALOG) ou de minLength/maxLength; o mesmo percurso recusa format: "attachment" fora de /properties/<campo> e /properties/<campo>/items, as duas posições que attachmentFields reconhece, com code invalid-schema e path .../format
adapters/search.tscreateSearchIndex: SearchIndex com MiniSearch cacheado por processo (chave = project + process; validade = quantidade de registros + impressão do último; log que só cresceu indexa só os novos; log menor que o indexado é um prefixo (cursor ou changesSince) e monta um motor efêmero sem tirar o índice quente; LRU de SEARCH_INDEX_BUDGET_CHARS = 24.000.000 caracteres de indexableText somados (calibração em docs/directives/adr-0008-servicos.md; contar registros não limita a memória), e processo maior que isso sozinho não é guardado; o alcance projeto, PROJECT_INDEX de ports.ts, nunca é guardado e monta um motor efêmero a cada busca) sobre type, target e as strings de data; AND com prefixo e fuzzy, e fallback para OR, ambos decididos sobre allowed (o conjunto que passa nos filtros, passado como filter do MiniSearch; o IDF segue sobre o log inteiro, o que muda só a ordem de relevância); os termos da consulta são deduplicados (inclusive variante de caixa e acento)
shared/loader.tsLeitura e verificação do log: parseLog, isValidLine, formatLine, verifyProcess, checkExpectedHead (a âncora expectedHead do verify_chain) e loadVerified (o predicado único de leitura e escrita, D-05), com o teto MAX_BREAKS exportado para queries/query-service.ts#verifyChain
shared/logger.tsLogger e LogRecord: o único tipo de logger da árvore nova (D-22)
shared/latest.tslatestVersions: nomes de definição do projeto com a versão vigente e todas as versões, sem a pasta de nome sem versão
shared/pages.tssliceChars: corte de texto por caracteres sem partir par surrogate; isHighSurrogate: a faixa da metade alta do par
compose.tscompose (D-25), a raiz de composição: o único lugar do servidor em runtime (server.ts e o que ele sobe) que conhece os adaptadores de disco (o subgrafo de instalação importa adapters/fs/ direto, ver Dependencies > Internal); liga o validador, os três stores e o createSearchIndex aos serviços definition, attachment, process e query (ComposeOptions: dataDir, cwd, clock, logger e telemetry?) e expõe isLegacy (D-13, um readdirSync por chamada). composeReader devolve só o lado de leitura (query, loadProcess(ref) (o VerifiedProcess inteiro do carregador único, para os scripts que precisam dos elos crus), isLegacy e list/listProjects do ProcessReader, que enumeram sem ler o manifesto), sem serviço de escrita, e é o que os scripts de leitura usam (scripts/cli-error.ts#openReadOnly); só server.ts, scripts e testes o importam: eslint.boundaries.js o proíbe nas camadas (mcp/ incluída) e test/boundaries.spec.ts trava; telemetria: composeTelemetry(env, logger) devolve noopTelemetry sem HEXLOG_OTEL_ENDPOINT e o adaptador de adapters/telemetry/ com ele, composeShutdown({ telemetry, proc, closeTransport }) liga o encerramento só com a telemetria ligada, e a opção telemetry de ComposeOptions (sem ela vale noopTelemetry) faz o wire(options, onLoad) passar onLoad ao store só se enabled; ComposeReaderOptions omite clock e telemetry, então o composeReader não a aceita; compose.ts é o único importador de adapters/telemetry/
commands/attachment.tscreateAttachmentService: attach (D-15), exatamente um de text/path; recusa pura sobre a entrada antes de chamar a porta, na ordem bad-args, NUL e segmento acima de 255 bytes no path, bad-extension (só .md e .txt) e, no text, vazio e surrogate solto
commands/definition.tscreateDefinitionService: defineType, defineRelation e defineGate sobre um só motor de versão imutável (D-11, D-17); Defined traz created (falso no replay), previousVersion e divergentVersions; breaking: true sobe o major (exceto com definição idêntica à vigente, que é replay), e quando outro escritor ocupa a versão alvo a decisão é refeita, até um teto de tentativas; defineType consulta Validator.checkSchema, prefixa /schema nos path dos detalhes (todo path aponta o campo da entrada) e nada que o adaptador recusaria chega a store.write
commands/process.tscreateProcessService: createProcess (D-18, idempotente por nome: fixa a versão vigente de cada tipo, relação e gate, e devolve stale quando o processo já existia e uma definição mudou) e register (D-06, lote numa só linha do log, lock só da origem; emite batch-replayed no logger injetado, nível info, com a key e sem o conteúdo dos registros, depois que o write devolve replayed); reexporta RegisterInput e RegisterResult
commands/register/static.tsRecusas do register que só dependem da entrada e do manifesto, antes do lock: checkBatchShape (D-06 nível 1), relationNames, prepareBatch (nível 3: tipo fixado de todos os registros e, depois, as violações estáticas juntas num só INVALID_RECORD com o teto de capDetails: o schema de todos os registros e, por registro e relação, as para kind por resolveKind e cross-process-currency), isAliasRef, PreparedItem
commands/register/state.tsOs tipos do register (RegisterInput, RegisterResult) e createDecide: o decide do register (D-06 níveis 4 a 6), síncrono sob o lock da origem: cadeia, busca da key (replay ou IDEMPOTENCY_CONFLICT), destinos de outro processo lidos uma vez e sem lock (melhor esforço: a vigência de supports no destino é corrida residual, ADR 0008), anexos, regras de D-10 e ciclo; monta um elo por item (D-04) e não grava nada se algo falha
commands/register/attachments.tscheckAttachments (D-16): cada anexo citado em campo marcado existe e está íntegro, e valor com forma de sha256 em campo sem a marca que é hash de anexo guardado é recusado (unmarked-attachment); cada hash é consultado uma vez por chamada
commands/register/errors.tsA recusa de regra de relação do register: ruleRefusal (D-10/D-26: not-current é FORK_REJECTED, as demais INVALID_RECORD; no kind-mismatch o Detail leva o kind do nome fixado e a message manda enviar só as ou esse kind) e o mapa RULE_MESSAGES de RuleCode para mensagem. Fica aqui, e não em errors.ts, porque tipa por RuleCode e Violation de domain/relations.ts, e o ADR 0007 a cita por este arquivo; monta o erro com fromDetails e invalidRecord, de errors.ts
queries/query-service.tscreateQueryService e QUERY_TEXT_MAX_CHARS (teto de text, 200, que recusa INVALID_FILTER too-long; text sem termo pesquisável, segundo SearchIndex.terms, recusa no-terms): o QueryService de leitura, que nunca grava — queryRecords (D-24: vigentes que passam nos filtros, com relações de entrada e saída, needsReview e attachmentStatus; fields recorta o data só na saída (projectData, fora do hash do cursor); página por limit e maxChars com cursor D-20 que fixa o marcador; changesSince devolve changes.entered/left com o motivo), evaluateGate (calcula o gate fixado no processo e devolve o marcador do que leu; evidence enxuga cada pergunta por summarizeQuestion e targets avalia um lote numa só leitura, com results por target e um só marcador; o serviço assume evidence: full), verifyChain (cadeia e anexos citados, D-16; quebra vira ok: false, não exceção; breaks e totalBreaks são só da cadeia, os anexos vão em attachmentBreaks e totalAttachmentBreaks, cada lista cortada em MAX_BREAKS), list (projetos, processos e definições, ou o que o manifesto fixou), readAttachment (página do texto do anexo, D-20) e describeType (schema de um tipo); as três últimas vivem em módulos irmãos (list.ts, read-attachment.ts, describe-type.ts) e createQueryService as compõe; recebe as portas (store, definitions, attachments, search), nunca importa compose.ts
queries/list.tscreateList: o list do serviço (projetos, ou um projeto com processos e definições, ou o que o manifesto de um processo fixou, com lineageInheritance quando o manifesto o tem), sobre ProcessReader e DefinitionReader; ListResult segue exportado por query-service.ts.
queries/read-attachment.tscreateReadAttachment e PAGE_CHARS_CAP (24.000): página do texto de um anexo por hash, sobre AttachmentReader; offset além do fim é out-of-range e offset entre as duas metades de um par surrogate é mid-surrogate-pair, os dois INVALID_INPUT em /offset; PAGE_CHARS_CAP segue exportado por query-service.ts.
queries/describe-type.tscreateDescribeType: o schema de um tipo, só por portas de leitura: com process, o fixado no manifesto (readManifest); sem process, a versão vigente ou a pedida do projeto (DefinitionReader); nos dois casos o schema sai sem pattern e patternProperties (withoutFreePatterns, cópia que não muta o manifesto lido). Entrada, saída e erros em docs/tools.md e na emenda de 2026-10-06 do ADR 0009 (item 1).
queries/read.tsreadScope(store, target, marker?, markerPath = '/marker'): lê e verifica o alcance pedido (ReadTarget: processo ou projeto) pelo carregador único, com corte opcional num Marker (alcance processo: marcador com exatamente a entrada do processo lido, senão MARKER_NOT_FOUND; só o projeto lê ausente como vazio; markerPath é o path do erro: /marker, /cursor ou /changesSince); quebra de cadeia é PROCESS_CORRUPTED nomeando o processo, nos dois alcances (falha fechado); devolve Reading (processos, marcador e hash da cabeça de cada um)
queries/select.tsSeleção do query, pura exceto no filtro text: inheritanceActivation (por processo, pelo lineageInheritance do manifesto lido), buildView (registros na ordem de saída, vigência, relações de entrada e a Inheritance da leitura), select (filtros type/targetPrefix/where/ids/relatedTo/includeNonCurrent e text por relevância via SearchIndex.search, que muta o cache de índices e recebe os ids de matching como allowed), relationsOf (modos RELATION_MODES: full, counts por nome as ?? kind e none; fora de none, soma inheritedIn/inheritedOut ou as contagens inherited*Counts quando há herança) e leftReason (superseded, revoked ou no-longer-matches)
queries/cursor.tsCursor opaco do query (D-20): encodeCursor/decodeCursor (base64url(JSON(payload)), sem checksum; texto acima de CURSOR_MAX_CHARS (65.536), JSON ou campo inválido é INVALID_CURSOR) e as recusas INVALID_CURSOR (invalidCursor e invalidCursorPayload, de errors.ts, que também usa o serviço); o cursor não autentica, e a barreira contra forja é a releitura do serviço; CursorPayload leva alcance, marcador, hash da cabeça de cada processo e lastId
mcp/kernel.tsFolha do src/mcp/: não importa tool, adapters/, node:fs nem compose.ts. ToolDeps (services, isLegacy, logger, telemetry), execute (toda tool passa por ele: isLegacy() antes de qualquer serviço → LEGACY_DATA com o comando de arquivamento em details, chave própria __proto__ em qualquer nível dos args crus → INVALID_INPUT com reserved-key (o z.record do zod 4 a descartaria em silêncio e o register selaria um registro diferente do enviado; só os args crus a enxergam, por isso a varredura mora aqui e não num refine; a mesma varredura recusa objeto ou array acima de MAX_ARGS_DEPTH (64 níveis, a raiz dos args é o nível 1) com INVALID_INPUT e too-deep, sem descer nele), entrada validada com zod → INVALID_INPUT com details[{path,code,message}], HexlogError → {code,message,details}, outra exceção → INTERNAL sem stack; o erro vai só em content[0].text, sem structuredContent, porque o outputSchema descreve só o sucesso: o validateToolOutput do SDK 2.x (conferido na 2.3.1) já retorna cedo com isError, e a invariante fica travada em test/mcp/environment.ts#errorBodyOf), defineTool (registra a tool no SDK com name e schema declarados uma só vez e repassa ao run o client, de clientOf: o envelope io.modelcontextprotocol/clientInfo ou unknown; unknown fora da era 2026 do protocolo, sem envelope, é esperado, fica no log com hash e não ganha fallback, D-21; só a tool register monta o author, com model só quando informado), advertise (anuncia o JSON Schema do zod e deixa a entrada crua chegar ao execute; bump de zod ou do SDK exige rodar test/mcp/kernel.spec.ts), toHexlogError (converte a exceção em HexlogError, com internalError para o INTERNAL; fica aqui porque loga pelo Logger de shared/) e o que as tools repartem: MarkerRecord, WRITE_ANNOTATIONS e READ_ANNOTATIONS. O logger é chamado sob guarda: se lançar, o resultado da chamada não muda. Além do log tool, um sucesso cujo texto passa do dobro de PAGE_CHARS_CAP (48.000) emite o warn tool-over-cap (name e chars), sem cortar a resposta. A paginação do envelope não mora aqui, mora em mcp/tools/query.ts. Com a telemetria, settle valida e roda a chamada sem lançar, execute a executa uma vez (once) e finish fecha o log, o aviso telemetry-degraded (com o reason probe ou export) e o probe.end, uma etapa por try; a resposta nunca espera o trace.
mcp/server.tscreateServer({ services, isLegacy, logger, telemetry }): McpServer hexlog com as 12 tools das quatro famílias abaixo; ligado por server.ts.
mcp/tools/process.tsregisterProcessTools: create_process e register (só o register leva _meta anthropic/alwaysLoad); a entrada do register usa os zod de domain/ e o Author é montado na própria tool, com o client do envelope.
mcp/tools/definition.tsregisterDefinitionTools: define_type, define_relation e define_gate, cada uma uma operação de DefinitionService; define_relation e define_gate estendem RelationName e Gate do domínio com safeExtend({ project, breaking }), e o teto de 16.000 caracteres canônicos vem de lá.
mcp/tools/attachment.tsregisterAttachmentTools: attach (text ou path, o serviço exige exatamente um) e read_attachment (offset inteiro ≥ 0, maxChars inteiro entre 1 e PAGE_CHARS_CAP; omitido, vale o padrão do serviço, PAGE_CHARS_CAP de queries/query-service.ts). Os schemas de entrada são z.strictObject: chave desconhecida é INVALID_INPUT com unrecognized_keys.
mcp/tools/query.tsregisterQueryTools: query (via queryPage, a única porta de queryRecords: passa maxChars e corta changes em CHANGES_ITEMS_CAP; limit máx. 200, text máx. QUERY_TEXT_MAX_CHARS, ids máx. 200, where máx. 50 chaves, fields máx. FIELDS_MAX (50) nomes não vazios, changesSince/marker máx. 200 chaves; docs/tetos-dominio-v1.md), evaluate_gate (via gatePage, a única porta de evaluateGate: assume evidence: failing sem targets e counts com targets no run, porque o serviço assume full; aceita targets (1 a TARGETS_MAX = 50) e corta cada lista de evidence em EVIDENCE_ITEMS_CAP, por pergunta de cada target, com omitted), verify_chain (schema com attachmentBreaks e totalAttachmentBreaks), list e describe_type (process e version juntos são recusados no serviço, não no zod: refine de raiz não pode virar combinador no inputSchema), todas READ_ANNOTATIONS. Não existe tool timeline: o alcance projeto da query a substitui.
archive.tsArquivamento do dado 0.x (D-14), só usado por scripts/install.ts: inspectLegacy (lista arquivos com sha256 e diretórios de <D>, sem alterar nada), archiveLegacy (recusa servidor ou lock 0.x vivos, gera <D>/archive/hexlog-0x-<data>.tar, relê e confere caminho e sha256, relista e re-hasheia antes de apagar, remove só o que foi listado; procDir opcional em ArchiveOptions existe só para os testes simularem /proc ausente, sem pid ou com cmdline ilegível; devolve ArchiveResult, união discriminada por archived, com dirs (a contagem de diretórios 0.x removidos) quando arquivou) e ArchiveError (todo aborto; erro de fs sem tratamento vira ArchiveError com o caminho). Lock 0.x com holder presente e fora de <pid>-<hex> aborta (não dá para confirmar que está morto); holder ausente ou de 0 byte conta como morto (D-14). fsyncPath, isPidAlive, isDirectoryTaken, orIfMissing e readIfPresent vêm de adapters/fs/
guard.tsRegras de deny + hook PreToolUse em settings.json: libDirOf (~/.local/lib/hexlog), skillFileOf, expectedRules (ExpectedRules, com dataDir, libDir e execPath), denyOf (devolve [] se deny não é array), findHookEntry (devolve também matcher, type e os entryHooks da entrada), mcpRegistered, mcpEnvOf (o env de mcpServers.hexlog, só valores string) e mcpAddArgs (os argumentos do claude mcp add com cada -e K=V antes do --, para o instalador refazer a entrada sem perder o env), hookProbes, applyGuard (recusa com INVALID_INPUT e o caminho na message um permissions.deny ou hooks.PreToolUse que não é array e um ancestral (permissions, hooks, a raiz) que não é objeto; repara no lugar o matcher (HOOK_MATCHER) e o type da entrada do hook, exceto o matcher errado numa entrada que divide hooks com hooks alheios: aí o hook do hexlog sai para uma entrada própria ^Bash$; devolve { text, removed }; também remove o deny de um <D> antigo só pelo predicado fechado de staleDenyRules, exportada: as três regras de deny de <D> para o mesmo X, basename hexlog, X diferente do <D> atual e ausente do disco, via predicado exists injetado que registerGuard passa; comentários dentro de deny não sobrevivem à remoção), verifyGuard (item hook-matcher quando matcher ou type diverge; recebe artifactModified: os bytes instalados divergem do manifesto) e runRealHook. Puro, exceto runRealHook, o único spawn (spawnSync do hook instalado), que o scripts/install.ts injeta; só usado por installation.ts e scripts/install.ts
installation.tsInstalação versionada do artefato em ~/.local/lib/hexlog/<versão>/: TOOLS_COUNT, versionDirOf, readManifest, installArtifact, writeSkillFolder (depois da troca varre os legados skills/<nome>.tmp-<pid> e, ao lado de skills/, os .hexlog-skill-<nome>.tmp-<pid>/.old-<pid> de pid morto), registerGuard (grava settings.json.bak-hexlog só se ele ainda não existe, para guardar o estado de antes da troca que o criou; EPERM/ENOTSUP do link (filesystem sem hard link) viram INTERNAL (por internalError) antes de gravar, e settings.json por adapters/fs/atomic.ts#writeFileAtomic, no destino do symlink quando settings.json é um e devolvendo-lhe o modo que tinha; devolve { changed, removed } com as regras de deny de <D> antigo que tirou; recusa gravar um settings.json que não faz parse, com INTERNAL, por internalError), verifyInstallation. Grava em disco (arquivos instalados e settings.json); spawn, esbuild e claude entram injetados. Só usado por scripts/install.ts
server.tsPonto de entrada: compose (dataDir(process.env), process.cwd(), relógio e logger de stderr) + log start (dataDir e version) + createServer de mcp/server.ts + serveStdio, cujo onerror loga transport-error (name e message, ou issues com a contagem no lugar do message quando o erro é um ZodError de envelope inválido, cujo message cresce com o payload; a linha de stdin acima de 10 MiB encerra o servidor e este é o único rastro); o servidor sobe mesmo com dado 0.x: isLegacy segue para o createServer, e quem devolve LEGACY_DATA é mcp/kernel.ts#execute, a cada chamada (D-13); ordem de subida: composeTelemetry (que já dispara o probe sem esperá-lo), compose, serveStdio e composeShutdown, com o handle de serveStdio guardado para fechar o transporte
version.tsVERSION, a versão do servidor MCP, reportada no handshake e no log start; deve bater com package.json#version (test/package.spec.ts)

Subdirectories

DirectoryPurpose
domain/Domínio puro: ids, registros, manifesto, cadeia de hash, relações, definições e gate (see domain/AGENTS.md)
shared/Carregador único do log, logger, versões vigentes de definição e corte de texto (see shared/AGENTS.md)
adapters/Implementações das portas de ports.ts: validador de schema e índice de busca, mais os stores de disco em adapters/fs/ (see adapters/AGENTS.md)
adapters/telemetry/Telemetria opcional por OTLP/HTTP: configuração, adaptador OpenTelemetry, noopTelemetry e encerramento do processo (see adapters/telemetry/AGENTS.md)
adapters/fs/Stores em disco de processo, definição e anexo, lock por processo e gravação atômica (see adapters/fs/AGENTS.md)
commands/Serviços de escrita: anexo, definições e processo com register (see commands/AGENTS.md)
commands/register/Etapas do register: validação estática, decide sob lock, anexos e erros (see commands/register/AGENTS.md)
queries/Serviço de leitura: query, evaluate_gate, verify_chain, list, read_attachment e describe_type (see queries/AGENTS.md)
mcp/Kernel de execução das tools e criação do servidor MCP (see mcp/AGENTS.md)
mcp/tools/As 12 tools, registradas em quatro famílias (see mcp/tools/AGENTS.md)

Navigation Notes

  • Specs em test/ espelham os módulos: test/domain/, test/adapters/, test/commands/, test/queries/, test/mcp/ e test/shared/ cobrem a árvore de src/; na raiz de test/ ficam directory.spec.ts, compose.spec.ts, guard.spec.ts, installation.spec.ts (cobre installation.ts), bash-guard.spec.ts, archive.spec.ts, stdio.e2e.spec.ts (bundle real de server.ts), os specs dos scripts e package.spec.ts.

Dependencies

Internal

Ponto de entrada: server.ts → directory.ts (resolve dir de dados) + compose.ts (serviços) + mcp/server.ts (createServer). mcp/server.ts registra as tools de mcp/tools/ e fornece a todas o envelope execute() de mcp/kernel.ts. compose.ts é o único módulo do servidor em runtime (server.ts e o que ele sobe), fora de adapters/, que conhece os adaptadores de disco; commands/ e queries/ dependem só das portas de ports.ts. shared/ é importado por commands/ e queries/ (latest.ts, loader.ts, pages.ts, logger.ts), por compose.ts (loader.ts, logger.ts) e por server.ts (logger.ts); mcp/ e adapters/ só importam shared/logger.ts. domain/ não importa camada nenhuma acima: só errors.ts (domain/definitions.ts e domain/chain.ts usam internalError e domain/schema-walk.ts usa pointer; errors.ts importa de volta só os tipos Name e RecordId, sem ciclo em runtime), além de zod, canonicalize e es-toolkit. Dentro de domain/, ids.ts é a base: record.ts depende dele; chain.ts de ids.ts e record.ts; relations.ts de ids.ts e record.ts, mais definitions.ts só por tipo (aresta relations → definitions); gate.ts de ids.ts, record.ts e relations.ts (vigência); definitions.ts de gate.ts, ids.ts e record.ts; manifest.ts de definitions.ts e ids.ts. archive.ts, guard.ts e installation.ts formam um subgrafo isolado (instalação), consumido só por scripts/install.ts fora de src/. archive.ts, installation.ts e scripts/install.ts importam adapters/fs/ direto: fica fora do mapa de camadas e sem trava de lint.

External

PacoteUso em src/
@modelcontextprotocol/serverMcpServer, serveStdio — servidor MCP e registro de tools (mcp/server.ts, mcp/tools/, server.ts)
zodEsquemas de validação de entrada/saída de toda tool e dos registros (domain/, mcp/kernel.ts, mcp/tools/)
canonicalizeSerialização JCS para hash determinístico (domain/chain.ts, domain/record.ts)
ajv (ajv/dist/2020.js) + ajv-formatsValida schema JSON de tipo em define_type e o data de cada registro (adapters/validator.ts)
minisearchÍndice de texto do filtro text de query (adapters/search.ts)
tarGera o .tar do arquivamento do dado 0.x (archive.ts, só pelo instalador; devDependency)
es-toolkitUtilitários (isNil, isEqual, isPlainObject, isString, kebabCase, mapValues, memoize, omit, omitBy, once, orderBy, pick, sumBy, union, uniq, uniqBy e outros) usados em quase todo módulo; es-toolkit/compat não é importado em src/
jsonc-parserParse/edição de settings.json preservando comentários/formatação (guard.ts)
shell-quoteParse/quote do command do hook PreToolUse (guard.ts)
@opentelemetry/apiSpanStatusCode e os tipos Attributes e Span (adapters/telemetry/otel.ts)
@opentelemetry/sdk-traceTracerProvider e BatchSpanProcessor (adapters/telemetry/otel.ts)
@opentelemetry/sdk-metricsMeterProvider e PeriodicExportingMetricReader (adapters/telemetry/otel.ts)
@opentelemetry/resourcesresourceFromAttributes com service.name e service.version (adapters/telemetry/otel.ts)
@opentelemetry/coretipos de exportação e ExportResultCode (adapters/telemetry/otel.ts)
@opentelemetry/exporter-trace-otlp-httpOTLPTraceExporter, em <base>/v1/traces (adapters/telemetry/otel.ts)
@opentelemetry/exporter-metrics-otlp-httpOTLPMetricExporter e AggregationTemporalityPreference, em <base>/v1/metrics (adapters/telemetry/otel.ts)

Manual Notes

Diretrizes

  • fronteiras.md: camadas, direção de dependência e checklist de review
  • invariantes.md: log, cadeia, lock, tools, anexos, definições e erros
  • convencoes.md: idioma, hash, tetos de lista, escrita atômica e import padrão de fs
  • qualidade-e-testes.md: comandos antes de concluir e convenções dos specs

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.