Skip to content

Governance

Governed Company Brain

Query the factory's governed portfolio with citations, grants and append-only history.

An exact projection of the portfolio

The Company Brain is the exact, governed projection of what a software factory knows about its own portfolio: products (prod), projects (proj) and initiatives (init). It is not OrkMind's semantic memory of collections, tags and search: it lives in its own PostgreSQL tables and only answers what an authorized producer recorded, citing where each item came from.

The context mode, the history operation and this documentation are on the repository's main branch, in the Unreleased section of the CHANGELOG. They are not yet part of a version published on PyPI.

Separate contract and API

The orkmind.company-brain/v1 contract is the same file in OrkMind and Orkastery, byte for byte. Its sha256 is reported by capabilities as contract_hash, and Orkastery refuses a Brain with a different hash. Calls use the orkmind.company-brain-api/v1 envelope: new operations are added to it without changing contract_hash. The context package and history belong to this API.

Validation is strict: unknown fields are rejected, the id starts with the kind, proj only has a prod parent and init only has a proj parent. Failures come out as a brain.* code, without echoing the content.

Identity from the login, explicit grants

Identity comes only from the authenticated PostgreSQL login, which the database administrator maps to a human or service principal. No request field, environment variable or tool argument names a principal. Grants apply per tenant, principal and ACL, with actions, resources, source instances, visible fields and validity; revocation takes effect on the next call.

  • get, query and history are for human principals only.
  • ingest, migrate and rollback are for service principals only.
  • Without a grant for the action, a read answers as if the entity did not exist.

Operations from the CLI and MCP

orkmind brain request reads a JSON envelope on stdin and writes the response to stdout; the orkmind_brain MCP tool takes the same envelope. The DSN comes from ORKMIND_DATABASE_URL and the tenant from ORKMIND_BRAIN_TENANT; no argument selects the database or the identity. The operations are capabilities, get, query, history, receipts, head and ingest. Response states are ok, empty, unknown, withheld, forbidden, unavailable and conflict.

echo '{"schema":"orkmind.company-brain-api/v1","operation":"capabilities"}' | orkmind brain request

context mode: a citable package

A selection with mode context builds the orkmind.company-brain-context/v1 package on the server: the entities requested by id and the parents the grant lets you see, each with the complete source citation (authority, instance, reference, hash, version and location). Everything runs in one REPEATABLE READ, READ ONLY snapshot. Anything without a complete citation becomes a typed gap, with no content.

The digest is the sha256 of the package's canonical JSON, with no timestamp: the same state yields the same digest, and the receiver recomputes it. OrkMind cites; freshness against the source is computed by whoever holds the source. An OrkMind older than this mode answers brain.selection.context-unsupported.

  • entity.unknown: missing, deleted or without the get grant.
  • entity.withheld: withheld by the ACL; only the id appears.
  • citation.incomplete: the visible citation is not complete, so the item is left out.
  • owner.unresolved, observed.unknown and recorded.unknown: a cited item without a resolved owner or a timestamp.

Append-only history

The history operation returns an entity's versions in sequence order, each with its origin: event, producer, cited source, factory cycle, recording time and the rolled_back flag. Nothing deletes or rewrites these versions; for a deleted entity, the tombstone is the last one.

It requires the history action, for humans only; without it, the answer is unknown. A grant that does not show the source field gets forbidden, because a version without an origin is not citable. Body fields follow the grant's fields.

echo '{"schema":"orkmind.company-brain-api/v1","operation":"history","payload":{"tenant_id":"exemplo","id":"proj-exemplo","limit":50}}' | orkmind brain request

Writes, migration and use by Orkastery

Only the service producer writes: ingest checks sequence, authorship, version and references and records projection, history and receipts in the same transaction; repeating the same event returns the same receipt. Administrative migration uses orkmind brain migration, with a hash-checked plan and rollback by compensation, never by restoring the whole database. The schema is created only by an explicit administrative operation; a query never migrates.

In Orkastery, ork brain context requests the context mode, checks the whole package and adds freshness against the local portfolio. Against an OrkMind without this mode, it builds the package the earlier way, with query and get, and says so in the package.