Documentation · The Lagstyr handbook

What this installation connects to

Lagstyr records the mandate, the evidence, the decision and the effect. The facts themselves usually live somewhere else: an accounting system, a payment processor, a calendar, a mailbox, a source repository. An integration is a governed connection to one of those systems. It reads records in, writes effects out, or both, and everything it does carries a source and an event.

Two kinds reach this installation, and the difference matters when something goes wrong.

Built-in adapters ship with the release. They are maintained by the vendor, they are listed below, and they are upgraded when the installation is upgraded. Customer and partner integrations are built against the published contract, signed, and published into this installation by proposal and approval. Their releases are yours: nobody else’s upgrade changes them.

What ships with the installation

An adapter being present in the release is not the same as it running. Most need a credential and a deployed worker before they do anything, and some belong to an optional pack that an installation has to activate before their workers will start at all. Absence is therefore normal: a clean installation connects to nothing until somebody decides it should. Packs shows which of the packs this build ships are on, which were never activated, and which are running contents nobody has consented to since an upgrade; turning one on is a governed decision needing a second approver, not a switch.

Accounting. Reads the chart of accounts, invoices, contacts and payments from Xero, imports a whole book’s journals into the shadow ledger, and records a daily bank position. Both the daily ledger import and posting journals back out belong to the financial-mirror pack — everything that reads that ledger does — so an installation without the pack captures from Xero and imports no book.

Payments. Acts on Stripe — collecting and refunding through a governed effect — and receives Stripe’s webhooks through a verified inbound edge. A delivery probe watches whether Stripe’s own webhooks are arriving.

Email. Sends through a governed outbox, receives inbound mail as evidence, imports an existing mail archive as documents, and watches deliverability.

Calendar. Keeps a provider-neutral mirror of a calendar the installation is entitled to read, and makes governed changes to it.

Source repositories. Projects pull requests and releases from a forge into evidence, and acts on a repository under governance. Both belong to the software-delivery-governance pack, so an installation without that pack neither polls a forge nor holds a forge credential.

Spreadsheets and exports. Imports tabular files as records under the same capture rules as a live provider.

Monitoring. Eleven probes — host, database, object store, TLS, DNS registration, HTTP, an identity provider, a status page, payment delivery, mail deliverability and integrations themselves — belong to the operational-assurance pack.

Outbound delivery. Signed event delivery to endpoints you nominate, which carries metadata and never record content.

The authoritative list is integrations/MANIFEST.tsv in the release. Every place the installation reaches a provider, or is reached by one, has a row there, and a gate holds that file equal to the code in both directions: a connector with no row fails the build, and so does a row whose code has gone. If it is not in that file, this installation does not connect to it.

What your own connectors can do

Anything a built-in adapter can do. A customer or partner integration declares its capture and its effects in a manifest, is signed with a key this installation has registered, and is published as an immutable release through the ordinary proposal and approval path. It reaches the same governed write seam, records the same events, raises the same findings and appears on the same pages as a built-in adapter. It is not a plug-in running inside the kernel: it is a separate worker that may only act through the contract, which is what keeps a connector’s defect a connector’s defect.

Engineering builds these. Building and commissioning integrations has the whole path.

Whether an integration is healthy

Each integration on the register carries a status, its active release, a readiness flag and any conditions. Status is active, paused or retired. Readiness answers one question: may new work start? An integration can be blocked without anything paging — a pause by a person is containment, and containment is not an incident.

Only three things page, and they are the conditions:

A condition stops paging when it is covered. An in-date remediation case covers a blocked release or a refusing capture; putting every break behind an active quarantine also covers a refusing capture, because containment is an acknowledgement. Nothing covers an overdue remediation — being overdue is precisely the acknowledgement having lapsed, so there is no way to quieten it except to resolve or re-date the case.

What the findings mean

A condition is the alarm; a finding is the diagnosis. The vocabulary is closed at twenty-four codes, so a finding you see is one the installation can explain, and a remediation case can only name one of them. They fall into groups:

• The release cannot run — incompatible or stale, its signing key revoked, or its pack not active. All three block new work and raise a release blocked condition.
• The release runs, but nobody signed it — it was installed by owner bypass. Alone among the release findings this one does not block new work and raises no condition, so the integration goes on capturing and nothing reaches your attention queue. The finding on the integration’s own page is the only place it is reported, which is why the page names it in full rather than showing a bare code.
• The executor cannot act — no registration for the connector, no route granted, or no live credential.
• Work is behind — cursors carrying errors, a cursor pinned to a superseded release, tasks that failed terminally, effects not yet settled, or unsettled work belonging to a previous release.
• A person or the system intervened — paused by an operator, or paused by the system.
• Records are being refused — capture refusing, or the provider’s published specification has drifted from the active release.
• The provider connection — never connected, refresh failing, reconnection required, disconnected by an operator, or a revocation the provider never confirmed.
• The case itself — a remediation case is open, or overdue.

Each finding carries a default action, and there are five: rotate credentials, repair a cursor, replay or settle work, replace the release, or investigate. The action is a starting point recorded on the case, not an instruction the installation carries out by itself.

What you can do from the console

Five acts are immediate. They re-authenticate you, record you as the person who did it, and take effect at once, because containment that waits for a second approver is not containment: pause this integration, close this break, disconnect now, withdraw candidate, and begin consent, which spends an approval already granted rather than making a new decision.

Six acts are governed proposals. They need a rationale and a second approver: open a remediation case, resolve one, quarantine a break’s source, lift a quarantine, retire an integration, and propose a provider connection. Resuming a paused integration is not a seventh act — it is a new release, published the ordinary way.

A break’s page shows each refused record as a drift capsule: what was expected, what arrived, the record’s digest and when the evidence will be erased. The record itself is never shown, and no page here will show it to you, because the bytes a connector submitted are the provider’s data and not evidence you need in order to decide.

When a provider changes its API

Providers change. What matters is that the change is visible before it reaches a record, and that nothing changes underneath you.

Upload the provider’s new specification and this installation compiles it into a candidate — a proposed manifest, never an authority. Where the specification does not say enough to be certain, the candidate carries a hole rather than a guess, and a person resolves each hole through the ordinary proposal path. Where the compiler cannot proceed at all it refuses with a code and quotes the part of the specification that stopped it. The provider’s own text is shown as a quotation, labelled as written by the provider and never to be followed as an instruction.

Comparing a candidate against the active release reports drift, which raises a finding but deliberately does not page: a comparison you chose to run should not wake anybody. Your active release keeps running throughout, unchanged, until you publish a new one. If the change does reach a live record, capture refusing pages then — and that is the alarm that means it now matters.

What is not an integration

A source is the name of a system facts came from. Registering one records that the system exists and how reliable it is; it connects nothing. Every integration writes against a source, but a source can exist with no connector behind it — a bank statement someone uploads by hand has a source and no integration. Sources, structure and the operations index covers the source register.