IF Commons GitHub

Integrations observe

0005Active

0005-integrations-observe · owner if · domain commons

The observation

FR-001checkpassing

An observation MUST be {at, provider, account, assets, posture, gaps, entities?, records?}, with gaps typed (denied, unavailable, partial, entity-kind-not-declared) and posture values scalar.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: an observation round-trips through its document

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts an observation round-trips through its document, and one of another schema is refused

FR-002checkpassing

A record MUST be {label, ocsf_class_uid, native_id, display_name, props, unmapped?}, and entities MUST be people, accounts, devices and repositories as typed products.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: records and entities decode

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts an observation round-trips through its document, and one of another schema is refused

FR-003checkpassing

A Connector MUST have describe, probe and observe as methods and check for its policies; describe MUST be derived from the governance so that it cannot differ, and MUST hold no credential value.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: describe agrees with governance

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts a connector observes over an in-memory port and a fixed clock, and describe agrees with go

FR-004checkpassing

defineConnector MUST refuse governance with a problem and a policy id twice, and MUST wrap observe so that governance is enforced on what any connector returns.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: defineConnector refuses a connector with problems

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts defineConnector refuses a connector with problems

FR-005checkpassing

Enforcement MUST remove from every record's properties and unmapped data each field the denylist denies, and MUST remove an entity kind the connector did not declare and name it as a gap, whatever the connector returned.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a denied field and an undeclared entity kind do not survive

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts a denied field and an undeclared entity kind do not survive

FR-006checkpassing

A posture policy MUST be data in the vocabulary of GRC (@intellectual-frontiers/grc): an id, a title, the fact, an Expectation and a Severity of GRC, the status a miss has, the control urns it bears on and a fix; evaluatePolicy MUST be total and give a GRC Status: pending where the fact was not observed, else GRC's own evaluation (a pass, the status of a miss, or error).

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: evaluatePolicy over each expectation

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts evaluatePolicy over each expectation, by the evaluation of GRC

FR-007checkpassing

Every connector MUST have the policy observation-fresh, failing where the observation is older than its cadence allows.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a stale observation fails the freshness policy

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts a stale observation fails the freshness policy

FR-008checkpassing

A persisted observation MUST be a document with kind and schema; reading one of another kind or schema, or a field of the wrong type, MUST be an error with its path.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a document of another schema is refused

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/observe.ts

Tests: passed: suite/observe.test.ts an observation round-trips through its document, and one of another schema is refused

The registry

FR-009checkpassing

A source MUST be pinned to https://...@<tag or 40-hex commit> and a branch MUST be refused; a registry entry MUST hold the id, title, pinned source, SHA-256, the contract version and when it was added.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: pinSource refuses a branch

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/registry.ts

Tests: passed: suite/observe.test.ts pinSource refuses a branch

FR-010checkpassing

The lock MUST be a persisted document (kind and schema) whose entries are in the order of their ids, and reading it MUST refuse an id twice, an id or digest that is not one, and a contract version that is not this one.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a lock round-trips in order

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/registry.ts

Tests: passed: suite/observe.test.ts a lock round-trips in order, and a copy with another digest is refused

FR-011checkpassing

verifyCopy MUST accept a copy whose digest is the pin and refuse any other, naming both digests, and an id the registry does not have.

Enforced (check): .github: cd commons/integrations && bun run verify — suite/observe.test.ts: a copy with another digest is refused

Proved by: integrations/suite/observe.test.ts

Written in: integrations/src/logical/registry.ts

Tests: passed: suite/observe.test.ts a lock round-trips in order, and a copy with another digest is refused

Acceptance scenarios

  1. Given a connector that returns a record with a salary property, When it is observed, Then the property is not in the observation, per FR-005.
  2. Given a source https://example.test/c@main, When it is pinned, Then it is refused as a branch, per FR-009.

Out of scope

  • Planned: the stolos connectors (31) as plugin packages; the fixtures of a registry entry run at load.
  • The reference connector integrations-github is its own package.

Edge cases

  • A connector that returns an entity kind it did not declare: removed and named as a gap, per FR-005.

Assumptions

  • A connector reads through a ReadPort; credentials are applied at the edge.

Open questions

  • None.

Key entities

  • Observation - what a connector saw at one moment.
  • Connector - governance and the three methods.
  • Registry entry - a pinned source.

Success criteria

SC-001success criterion

Whatever a connector does, what it returns obeys its governance.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Integrations, logical/observe, logical/registry

Titles, headings, exports, tables, columns and requirements. Esc closes.