Sense 39: The Governance
Sense 39 · Forming · Last touched 2026-08-20
- last_verified: 2026-07-27
Synced from
docs/design/sense_39_the_governance.mdin the engine repo — that’s the source; this page is a build-time mirror.
A rule is a sentence with a calendar.
An institution is a chain of decisions, each made under the rules in force at the time, by the people authorised at the time, against the data observable at the time. Asking “is this organisation in order?” without naming the time is asking nothing at all.
Status: proposed Date: 2026-05-20 Author: jazzisnow Architect + Claude (vai compliance discussion, 2026-05-20) Depends on: bitemporal data discipline (this doc), Sense 14 (signals), Sense 25 (identities + passes — the authority layer)
What pulled us in
Section titled “What pulled us in”jinflow’s analytical pyramid — Signals → Theses → Verdicts → Observations — is a-temporal in evaluation. Each artifact is compiled once and runs against the current state of the data. A new jin make re-evaluates everything against the latest. The previous evaluation is lost unless a snapshot froze it.
For analytical questions that is the right shape. “What’s wrong today?” is a present-tense question, and the engine answers it well.
For three other classes of question the shape breaks:
-
Retrospective analysis. “With what we now understand, what was the state of the organisation on 2024-Q3?” — Today’s analyst, applying today’s signals and today’s interpretation, against the data as it was a year ago. The data exists (gold tables carry
valid_from / valid_to); the analytical lens is current; only the time axis on the query is historical. -
Reproductive evidence. “What did the institution actually see on 2024-Q3, given the rules and analytical lens that were in force then?” — A different question. Useful for audits, dispute defense, “we reported X back then because under the then-current Arbeitsgesetz threshold of N hours…”. The data is historical; and the analytical lens must be historical.
-
Compliance and governance. “Did the institution adhere to the rules that were in force during this period?” — A rule that changed in 2020 cannot be re-evaluated as “today’s rule against historical data” or the answer is wrong by construction. A regulator asks the reproductive question by default. So does a contested termination claim. So does an internal audit.
These are different questions with different temporal mechanics. Today, jinflow can answer only the first one — and only when a snapshot happens to exist for the target date.
This Sense names the shape that lets jinflow answer all three.
The vocabulary shift
Section titled “The vocabulary shift”From compliance to governance
Section titled “From compliance to governance”The first instinct is to write a compliance system. “Compliance” is a strong word in regulated industries, has clear customer-facing weight, and maps to existing roles (“Compliance Officer”).
But compliance is one feature of a larger system, not the system itself. Compliance asks the binary question — “did the rule hold or not?” — at a moment in time. The larger system has to:
- Know who set the rule (the authority chain: regulator, standards body, internal policy committee, ad-hoc decision).
- Know when the rule took effect, when it was last amended, when it expires or is repealed.
- Know which entities the rule applies to (population scope: all staff, only physicians, only EU residents, only customers above €X turnover).
- Know what counts as compliant evidence (the rule’s executable predicate, plus the data sources it draws on).
- Know what exceptions are pre-authorised (and who authorised them, with what duration).
- Know what the consequence of violation is (regulatory fine, internal escalation, advisory note).
- Provide an audit trail of who changed the rule, when, with what justification, approved by whom.
Compliance is the verb of looking up answers in this system. Governance is the system itself.
Naming the system “Governance” rather than “Compliance” also opens the surface: governance covers internal policy (staff rotation cadence) as cleanly as it covers external regulation (Arbeitsgesetz). The same machinery answers both. Compliance — as a word — leans regulator-shaped; governance covers both regulator-imposed and self-imposed structure.
From the perspective of a rule
Section titled “From the perspective of a rule”A governance rule is a sentence with a calendar, an authority, a population, an executable predicate, and a consequence.
From <effective_from> to <effective_to>, every <subject> in <scope>must <predicate>, authorised by <authority>, evaluated against<data_sources>. Violations produce <consequence>. Exceptionsrecorded against <exception_register>.This is the same shape whether the rule is Swiss Arbeitsgesetz §9 (“max 50 working hours per week, since 2014, repealed 2020 for senior management — exemptions filed with Cantonal labour office”) or an internal HR policy (“clinical residents must rotate sites every 24 months, since 2018, no exemptions”) or a freight regulation (“dangerous-goods consignments above N kg require ADR documentation since 2010-amended-2022, exception for in-house pharmaceutical-grade transport pre-cleared per BAG circular 7/2018”).
The domain differs; the artifact contract does not.
Two temporal questions, two different costs
Section titled “Two temporal questions, two different costs”The most important architectural insight in this Sense is that the two temporal questions have fundamentally different infrastructure costs.
Retrospective: today’s lens × historical data
Section titled “Retrospective: today’s lens × historical data”“With today’s understanding, what happened on 2024-Q3?”
Requires only:
- Bitemporal discipline in the data layer — gold tables carry
valid_from / valid_to(already partially true in numetrix and hrcentral) ANDobserved_at(the timestamp at which the system learned the fact). With both, any query can be parameterised:WHERE valid_from <= T AND (valid_to IS NULL OR valid_to > T)answers “what was true on T”. - An AS-OF query layer in the engine — a parameter that threads through every gold reader and every signal SQL, defaulting to current time but accepting an explicit T. DuckDB supports the SQL primitives natively.
That’s it. The signals, theses, verdicts, perspectives stay current. The lens is today’s; only the data lookup goes back. This is the cheaper mode and the one with the broader use case. Analysts asking “how did our succession-risk picture evolve over the last three years?” want this. Auditors usually do not.
Reproductive: historical lens × historical data
Section titled “Reproductive: historical lens × historical data”“What did the institution actually see on 2024-Q3, under the rules then in force?”
Requires everything above, plus:
- A versioned artifact catalog baked into the KLS — every prior version of every signal, thesis, verdict, perspective, rule, alongside its own
valid_from / valid_to. A query at time T resolves not just data-at-T butsignal_dormant_employee@v1.0.3 (the version live then). - Artifact-version-aware resolution in the engine — when the AS-OF parameter is set to T, the resolver picks the version of each artifact that was live at T, not the current.
This is the harder mode. It earns its cost in two narrow but high-stakes cases:
- Regulatory audit defense. “You filed report X. Under the rules that applied then, the report was correct. Here is the rule version, here is the data version, here is the evidence.”
- Dispute / litigation evidence. “At the time of the alleged event, the policy stated Y, and the data observable then showed Z.”
For most analytical work, reproductive mode is unnecessary. Retrospective is enough. Governance shipping with retrospective only is already a meaningful product step.
Phasing implication
Section titled “Phasing implication”This insight reshapes the project:
- Phase 1 (retrospective): bitemporal data discipline + AS-OF query layer. ~80% of the value, ~30% of the infrastructure cost.
- Phase 2 (reproductive): versioned artifact catalog + version-aware resolution. ~20% of the value, ~70% of the infrastructure cost. Park until audit-grade need is concrete.
The temptation is to design both at once because they look similar from a distance. They aren’t, and conflating them turns a 2-month project into a 6-month project.
The governance_rule artifact
Section titled “The governance_rule artifact”A new top-level artifact kind, alongside signals / theses / verdicts / perspectives. The contract is informed by the existing signal contract but does not collapse into it — the differences below are first-class and won’t fit cleanly as optional signal fields.
YAML shape
Section titled “YAML shape”rule_id: rule_arbeitsgesetz_max_weekly_hoursversion: "2.0.0"contract: governance_rule.v1
# Temporal validity. effective_to=null means "currently in force."# Multiple versions of a rule_id can coexist: their effective intervals# must not overlap.effective_from: "2020-01-01"effective_to: null
# Authority — who set this rule. Determines who can amend it, what the# audit trail looks like, what evidence an external auditor needs.authority: source: regulator # regulator | standards_body | internal_policy | contract body: "Schweizer Eidgenossenschaft" reference: "Arbeitsgesetz Art. 9" external_url: "https://www.fedlex.admin.ch/eli/cc/1966/57_57_57/de" authorised_by: principal_id: "compliance_officer" role: "Compliance Officer" date: "2020-12-15"
# Subject + scope — who the rule applies to.subject: entity_type: Person scope_predicate: | -- SQL predicate identifying the population the rule covers. -- Evaluated against gold tables at the same time T as the -- rule check. Persons NOT matching this predicate are out of -- scope (the rule says nothing about them). SELECT person_id FROM {{ ref('gold_persons') }} p JOIN {{ ref('gold_assignments') }} a ON a.subject_id = p.person_id WHERE a.activity_type IN ('clinical', 'research', 'understudying') AND a.start_date <= '__AS_OF__' AND (a.end_date IS NULL OR a.end_date >= '__AS_OF__')
# The predicate — the executable rule. Evaluates to a row per violation.# Same shape as a signal's SQL but tagged "rule" for the compiler.predicate: description: en: "Weekly working hours must not exceed 50." de: "Die wöchentliche Arbeitszeit darf 50 Stunden nicht überschreiten." query: | -- Returns one row per (subject, period) violation. SELECT subject_id AS entity_id, 'Person' AS entity_type, week_starting AS time_bucket, total_hours AS observed_value, 50 AS threshold, (total_hours - 50) AS overage FROM {{ ref('gold_assignment_hours_weekly') }} WHERE total_hours > 50
# What happens when violated.consequence: severity: high # advisory | medium | high | critical category: regulatory # regulatory | policy | contractual | safety description: en: "Administrative fine + cantonal labour office notification." escalation_path: - role: "Compliance Officer" sla_days: 7 - role: "HR Director" sla_days: 14
# Exception register — pre-authorised exemptions don't fire violations.exceptions: source: "exception_register.yaml" fields_required: [exception_id, entity_id, granted_by, granted_at, valid_from, valid_to, justification]
# Rule lineage — references to prior versions.supersedes: - rule_arbeitsgesetz_max_weekly_hours@v1.0.0 # the 2014-2019 form - rule_arbeitsgesetz_max_weekly_hours@v1.1.0 # 2019 amendment
# Audit trail — what changed since the last version.changelog: - version: "2.0.0" date: "2020-01-01" summary: "Raised threshold from 45 to 50 hours, narrowed scope to active clinical/research/understudying assignments." authorised_by: "compliance_officer"
# Optional human-readable explanation for the registry / UI.registry: display_name: en: "Arbeitsgesetz — max 50 weekly hours" de: "Arbeitsgesetz — max. 50 Wochenstunden" description: en: "Swiss federal labour law limit on weekly working hours for staff in scope."What’s different from a signal
Section titled “What’s different from a signal”The fields not present in a signal that must be first-class on a governance rule:
effective_from,effective_to— temporal validity of the rule itself, distinct from the data validity.authority— provenance chain. Determines who can amend it, what audit evidence proves it.subject.scope_predicate— explicit population scope, separable from the violation predicate. (Signals usually fold scope and predicate into one query; rules separate them because scope IS the question of “who is bound by this rule.”)consequence— categorised severity + escalation path. Signals have severity, but rules’ severity has regulatory grades and escalation chains.exceptions— pointer to an exception register. Signals don’t natively support “this row was pre-authorised to violate.”supersedes— explicit reference to prior versions, so the engine can reconstruct the rule’s history.changelog— required, not optional. Every rule amendment must record what changed and who authorised the change.
Why a new kind, not a signal subtype
Section titled “Why a new kind, not a signal subtype”Two reasons:
- Contract integrity. The signal contract is intentionally light — anyone can author one, the review bar is “does it produce useful findings?” The rule contract is heavier — every rule carries authority + audit trail + consequence + exception register. If
authorityis optional on signals and required on rules, “a signal that happens to be a rule” becomes an ambiguous artifact whose contract depends on context. Clearer to make them separate kinds. - Routing and review. Signals are authored by analysts. Rules are authored under authority — sometimes the analyst writes the YAML but the Compliance Officer (or Head of HR, or the regulator’s circular) authorises it. The review path is different, the storage location is different (perhaps a separate git history with stricter access), the audit-log requirements are different. Two kinds, two governance contracts.
Bitemporal data discipline (Phase 1)
Section titled “Bitemporal data discipline (Phase 1)”Every gold table carries two time axes. Today some tables do, partially; this discipline makes it uniform.
The two axes
Section titled “The two axes”valid_from/valid_to— world time. The interval during which the fact was true in the real world. SCD-2 semantics. A person’s affiliation that started 2020-03-01 and ended 2022-08-15 hasvalid_from='2020-03-01', valid_to='2022-08-15'. A still-active fact hasvalid_to=NULL.observed_at— system time. The timestamp at which the system learned the fact. The current generation of the row was created atobserved_at. A fact that arrived in 2024-Q1 but was retroactive (true from 2020-03-01) hasvalid_from='2020-03-01',observed_at='2024-01-15T...'. A fact that arrived in real-time has them roughly equal.
The two axes answer different questions:
- What was true at T? →
valid_from <= T AND (valid_to IS NULL OR valid_to > T) - What did the system know at T? →
observed_at <= T - What was true at T, as known at T? → both predicates AND’d. The canonical bitemporal query.
Contract change
Section titled “Contract change”The gold contract gets a new required pair on every entity type that carries temporal facts:
{ "Person": { "fields": { "...": "...", "valid_from": "datetime", "valid_to": "datetime?", "observed_at": "datetime" } }}Migration:
- Tables that already carry
valid_from / valid_to(most numetrix gold entities, several hrcentral) need anobserved_atcolumn added. The default for legacy rows is “the time the row was first written into the KLS” — derivable from KLS build metadata. - Tables that carry only an
as_ofcolumn today (a single time axis) need to be widened. Some will be honest SCD-2 once examined; others will need a backfill plan. - New tables ship with both axes from the start.
Source-of-truth nuance
Section titled “Source-of-truth nuance”For data that comes from a source system, observed_at is the extraction timestamp — when jinflow first saw the fact. For data that comes from a SIS note (Sense 11 / Sense 25 / Sense 33), observed_at is the author’s timestamp. The discipline is the moment jinflow learned, not the moment the source system was first updated.
This nuance matters: a person’s leaving date might have been entered in SAP on 2024-08-20 but only extracted into the KLS on 2024-09-03. observed_at = 2024-09-03, not 2024-08-20. The question “what did jinflow know on 2024-08-25?” answers honestly: not yet.
The AS-OF query layer (Phase 1)
Section titled “The AS-OF query layer (Phase 1)”A single parameter, threaded through every read path.
Engine surface
Section titled “Engine surface”A new function in the dbt macro library:
{{ jinflow.as_of('Person', as_of=as_of) }}Expands to:
SELECT * FROM {{ ref('gold_persons') }}WHERE valid_from <= '{{ as_of }}' AND (valid_to IS NULL OR valid_to > '{{ as_of }}') AND observed_at <= '{{ as_of }}'as_of is a dbt variable. When unset (as_of = NULL or current_date), the predicates reduce to “all currently-valid rows” — backwards-compatible with how today’s queries read.
Signal SQL
Section titled “Signal SQL”Signal queries thread the same parameter. The signal compiler emits queries with {{ jinflow.as_of('Person', as_of=var('as_of')) }} instead of raw {{ ref('gold_persons') }}. At build time, the dbt var defaults to current; at retrospective evaluation time, the var is set to the target T and the signal re-emits findings against that historical state.
JinDesk surface
Section titled “JinDesk surface”A new query parameter on findings/perspectives/verdicts pages:
/{tenant}/findings?as_of=2024-09-30/{tenant}/perspectives/perspective_person_health?as_of=2024-09-30The server-side load function reads the param, sets the dbt-equivalent at runtime, and re-evaluates the page. A small “As of: 2024-09-30 (today’s lens)” indicator at the top of the page makes the temporal mode visible.
The AS-OF default
Section titled “The AS-OF default”Default value: current_date. Without a query param, every page works exactly as today — bitemporal discipline is invisible to current-state queries. The new behavior is unlocked only when AS-OF is set explicitly.
The governance runtime
Section titled “The governance runtime”How a rule executes
Section titled “How a rule executes”A governance rule runs the same way a signal does — dbt build --select rules produces a per-rule violations table — with three additional steps:
- Scope check. Before evaluating the predicate, the engine resolves the rule’s
subject.scope_predicateAT the rule’s effective time (or at AS-OF time if set). Persons / entities not in scope at that moment are excluded. - Predicate evaluation. The rule’s query runs against the in-scope population.
- Exception subtraction. The engine joins the candidate violations against the exception register. Rows with a matching active exception are excluded from the final violations table (but logged separately as
pre_authorised_exceptionsfor audit visibility).
The final output is two tables:
rule_violations— what wasn’t excluded.rule_exceptions_applied— what would have been a violation but was pre-authorised. Auditors care about both.
How a rule changes
Section titled “How a rule changes”A rule amendment is not an edit to the YAML. It’s a new YAML file with the same rule_id and a bumped version, with effective_from set to the date of the amendment. The previous version’s effective_to is set to the day before the new effective_from. The two versions coexist in the AFS.
The engine validates: for any rule_id, the union of (effective_from, effective_to] intervals must cover the desired temporal range without gaps or overlaps. Rule overlap is a compile error.
The exception register
Section titled “The exception register”A small YAML file (or set of files) per tenant, listed in governance/exceptions/:
exceptions: - exception_id: ex_2024_pernet_pikett_overload rule_id: rule_arbeitsgesetz_max_weekly_hours entity_id: p_pernet granted_by: principal_id: hr_director authority_reference: "Internal memo 2024-08-12" granted_at: "2024-08-12" valid_from: "2024-08-15" valid_to: "2024-12-31" justification: | Pediatric Pikett rotation gap during August 2024 leave coverage. Cantonal Arbeitsgesetz exemption applied for, BAG ref 2024-CH-15732.Exceptions are themselves audit artifacts. Their YAML is checked into AFS; modifications require Compliance Officer authority; the engine refuses to compile if exception fields are inconsistent.
Cross-pack abstractions
Section titled “Cross-pack abstractions”Why governance is a jinflow primitive, not a pack feature
Section titled “Why governance is a jinflow primitive, not a pack feature”Every pack’s domain has rules. Building governance into one pack and copy-paste-evolving it into the next is the classic anti-pattern. Building it as a jinflow primitive means:
- hrcentral: Arbeitsgesetz, FMH Weiterbildung curriculum, FADP (Swiss GDPR), internal HR policies.
- numetrix: supply-org pricing rules, dangerous-drug storage, controlled-substances chain-of-custody, vendor contract minimums.
- interlogic: freight tariff regulations, ADR documentation, customs declaration cadence, internal SLA contracts.
- lexflow (planned): client confidentiality timelines, file retention regulations, conflict-of-interest checks.
Each pack ships its own governance/rules/ directory with its own rules. The engine treats them uniformly. JinDesk surfaces them uniformly. The audit trail format is uniform.
The pack contract
Section titled “The pack contract”A pack declares which rules it ships in its manifest:
governance: rules_dir: governance/rules exceptions_dir: governance/exceptions required_authorities: [compliance_officer, hr_director]A pack can express, in its manifest, the roles required to authorise rules at this level. This binds governance to the Identity & Passes model (Sense 25): the pack declares which identities have which authorities; rule changes are gated on having that authority.
Cross-tenant variation
Section titled “Cross-tenant variation”Two tenants in the same pack (e.g. rmc and inspire in numetrix) may have different exception registers — the rules are pack-level, the exceptions are tenant-level. rmc’s compliance officer authorises rmc’s exceptions; inspire’s authorises inspire’s. The rule SQL is shared; the exception data is not.
What snapshots are still for
Section titled “What snapshots are still for”This Sense does not deprecate snapshots. It changes what they’re optimised for.
What snapshots stop being good for
Section titled “What snapshots stop being good for”Analytical exploration of “what did the past look like.” That use case is now served by AS-OF queries against live data. Continuous historical exploration (“show me the compliance score every quarter for three years”) was clumsy in snapshots — you needed a snapshot per quarter — and now needs zero snapshots.
What snapshots are still essential for
Section titled “What snapshots are still essential for”- Audit-grade certified frozen evidence. “This is the Q3 2024 report we filed with the regulator.” A snapshot is a bytewise-identical KLS file the auditor can open and verify. A reconstructive AS-OF query produces an answer, not a file. For regulatory dispute defense, the file is the artifact.
- Cheap point-in-time isolation for the few dates that matter. Year-end accounts, regulator filing dates, dispute crystallisation moments. Snapshots remain the right tool for the small set of “important fixed points.” AS-OF remains the right tool for the continuous range between them.
- Diff Loupe. Comparing two snapshots side-by-side is a different interaction than AS-OF queries (which return a single point-in-time answer per request). The Diff Loupe stays a snapshot-based surface.
The clarifying rule
Section titled “The clarifying rule”Snapshots = the few moments that legally matter. AS-OF = every other moment.
Phased implementation
Section titled “Phased implementation”Phase 1 — Retrospective (the ~80% unlock)
Section titled “Phase 1 — Retrospective (the ~80% unlock)”~4-6 weeks of focused engineering.
- Gold contract update: add
observed_atto every entity contract that carries temporal facts. Bake migration into the existing contract validator. - dbt model audit: every gold model that carries SCD-2 semantics gets
observed_atpopulated (real or backfill-default). Document the backfill source per model. jinflow.as_of()macro: a single helper that wrapsref(...)with the bitemporal predicates. Default = current.- Signal-compiler emits AS-OF-aware SQL: signals get the macro automatically; existing signal YAML doesn’t need to change.
- JinDesk AS-OF param: query param threading through page loads, with a small UI indicator showing the active time.
Deliverable: any analyst can ask “what did the picture look like on 2024-09-30, by today’s signals?” and get an answer. No snapshot required.
Phase 1.5 — Governance rules (the structural addition)
Section titled “Phase 1.5 — Governance rules (the structural addition)”~3-4 weeks, parallel-loadable with Phase 1’s tail.
governance_rule.v1contract: JSON schema for the YAML shape above.rulecheck.py+rulecompile.py: validators + compilers, modelled onsignalcheck.py/signalcompile.py.governance/rules/directory convention: per pack, per tenant.- Exception register YAML format + validator.
rule_violations+rule_exceptions_appliedtables: outputs.- JinDesk
/governanceroute: rules list, rule detail, violations browser, exception register browser.
Deliverable: a pack can ship governance rules; an analyst can browse and review violations and exceptions.
Phase 2 — Reproductive (the audit-grade addition)
Section titled “Phase 2 — Reproductive (the audit-grade addition)”~6-8 weeks. Park until concrete audit-grade need is articulated.
- Versioned artifact catalog: every signal/thesis/verdict/perspective/rule version preserved in the KLS, alongside its own
valid_from / valid_to. - Version-aware AS-OF resolver: when AS-OF is set, every artifact lookup resolves to the version live at T.
- Reproductive JinDesk mode: a separate toggle, distinct from retrospective AS-OF, that switches to “what was seen then” lens. Visible UI distinction: retrospective mode says “as of T, today’s lens”; reproductive mode says “as of T, the lens then in force”.
Deliverable: regulatory audit defense and litigation evidence become natural products of the engine, not bespoke reconstruction efforts.
What’s deliberately not in scope
Section titled “What’s deliberately not in scope”- The Identity & Passes integration for rule authorship. Sense 25 is the right home for who is authorised to author a rule, approve a rule change, grant an exception. The Governance Sense assumes that infrastructure exists; it doesn’t re-author it.
- A separate Diff Loupe for rules. Rule comparison (“what changed between v1 and v2 of rule X”) is real and useful, but lives in the existing diff infrastructure with rule-specific column-level diffs. Not a separate surface.
- Notification / alerting. When a violation fires (or an exception expires), some external system should be notified. That’s a hook layer this Sense doesn’t define.
Cross-cutting design notes
Section titled “Cross-cutting design notes”The as_of parameter and the existing engine
Section titled “The as_of parameter and the existing engine”Today’s signal SQL doesn’t take parameters. The signal compiler emits SELECT ... FROM {{ ref('gold_X') }} WHERE ... and dbt builds it once. Phase 1 changes that: the compiler emits ... FROM {{ jinflow.as_of('Person', as_of=var('as_of')) }} ..., and dbt’s var('as_of') is consulted at build time. At ordinary jin make time, var is unset (= current); at “rebuild this signal at AS-OF=2024-09-30” time, var is set and the build emits AS-OF-resolved findings.
This means a signal’s findings table is per-AS-OF — each AS-OF evaluation produces its own snapshot. For most uses (current-only), only the current findings live in the KLS. For JinDesk pages with ?as_of=, the engine compiles+materializes the requested findings on demand and caches the result keyed on AS-OF.
The bitemporal honest signal
Section titled “The bitemporal honest signal”A subtle design property: with observed_at honestly populated, the engine knows what it didn’t know. A query AS OF 2024-06-15 against data extracted in 2024-09 returns only what jinflow had seen by 2024-06-15 — not the full retrospective truth that arrived later. This is the honest mode, and is the right default for reproductive audits (“what did the institution see at the time”).
The other mode — “what is now known to be true about 2024-06-15, even with later-arriving data” — is the more permissive form, useful for analysis but not for audit. The macro can take a second parameter revealed_by to control which mode:
{{ jinflow.as_of('Person', as_of='2024-06-15', revealed_by='2024-06-15') }} -- honest{{ jinflow.as_of('Person', as_of='2024-06-15', revealed_by=NULL) }} -- permissive (all known truth about that date)This is a small contract surface; it matters because the two queries can return materially different rows.
How this manifests in jinflow
Section titled “How this manifests in jinflow”Not yet manifest in the engine. Status: proposed. See the implementation phases / open questions above for the path from this paper to running code.
Open questions
Section titled “Open questions”These are decisions deferred until implementation begins. Each is a real design choice that this doc doesn’t yet fix.
-
Where do rules sit in the AFS layout?
- Option A:
governance/rules/*.yaml(parallel tosignals/,theses/). - Option B: a single
governance/directory containing both rules and exceptions and authority declarations. - Option C: nested by domain (
governance/labour/,governance/data_protection/).
- Option A:
-
Is
rule_idglobally unique or namespaced?- Across packs the answer should be unique (so a multi-pack tenant’s compliance dashboard can list all rules without collision). Within a pack, the prefix convention probably matters less.
-
How is the “authority” identity resolved against Sense 25 identities?
- The YAML carries
authorised_by.principal_id. That should be an Identity in the Sense 25 model. The validator should check it exists; the engine should refuse to compile a rule whose authority isn’t declared in the tenant’s identity registry.
- The YAML carries
-
What’s the right granularity for
observed_at?- Per-row (each row gets its own
observed_attimestamp) is honest but heavyweight. - Per-build (every row in this
jin makeshares the build’s timestamp) is cheaper but lossier for incremental loads. - Best practical compromise: per-row when the source carries an extraction timestamp; per-build as fallback.
- Per-row (each row gets its own
-
Should exception expiry be enforced or only flagged?
- When an exception’s
valid_topasses, the nextjin makewill start producing the violation again. Should the engine also produce a “exception expired” finding to alert the responsible role? Probably yes; one-time alert at expiry, not repeating thereafter.
- When an exception’s
-
Does the
consequencefield execute anything, or is it documentary?- For Phase 1.5 it should be documentary only — the rule emits a violation; what happens next (notification, escalation, ticket creation) is for the host system, not the engine. Hooks come later.
-
Are rule versions semver?
- The artifact YAML carries
version: "2.0.0". Should bumps be semver-meaningful (major = scope or threshold change; minor = predicate refinement; patch = wording)? Probably yes; the validator can enforce it.
- The artifact YAML carries
-
Can a single rule have multiple effective-time windows that aren’t strict supersession?
- E.g. a rule that’s in force every January–June but suspended July–December. Today the contract assumes contiguous supersession; non-contiguous validity might need first-class support or might be modelled as two separate
rule_ids. Lean toward tworule_ids — clarity > flexibility.
- E.g. a rule that’s in force every January–June but suspended July–December. Today the contract assumes contiguous supersession; non-contiguous validity might need first-class support or might be modelled as two separate
-
How does AS-OF interact with the existing snapshot infrastructure?
- Both produce point-in-time views. Should there be a unified
time selectorUI in JinDesk that knows about both — “pick a snapshot OR pick an as-of date”? Probably yes, but the interaction design is non-trivial.
- Both produce point-in-time views. Should there be a unified
-
What’s the user-facing vocabulary?
- “Governance” is the system word. What’s the user-facing word for a rule’s violation? “Breach” sounds legalistic. “Violation” sounds harsh. “Finding” conflicts with signal findings. “Issue” is too soft. Probably: rule findings (paralleling signal findings) for the analytical surface; breach when explicitly framing for regulatory consumption.
Why now, why this shape
Section titled “Why now, why this shape”Why now
Section titled “Why now”hrcentral surfaces this need first and most clearly. Arbeitsgesetz changes; FMH curriculum changes; FADP applies retroactively; clinical compliance is reviewed continuously. The vai walkthrough showed the gap between today’s signals and the historical questions an institution actually faces. Building governance on the back of hrcentral’s natural temporality is the cheapest entry into the design space.
The other packs benefit downstream: numetrix’s supply-org pricing rules, interlogic’s freight regulations, lexflow’s confidentiality timelines. None of these requires governance to ship; all of them are improved by it shipping.
Why this shape and not a smaller one
Section titled “Why this shape and not a smaller one”The smallest possible shape is “compliance signals” — adding effective_from / effective_to / authority as optional fields on the signal contract. We considered it. It collapses on contract integrity (rules really do need first-class authority and audit trails, not optional metadata) and on review path (rules and signals have different authorisation chains and different storage discipline). The cost of designing two parallel artifact kinds is real but bounded; the cost of letting “compliance” be a soft cousin of “signal” is open-ended and grows under audit pressure.
The shape proposed here is minimal beyond signals: the same SQL execution, the same dbt build, the same JinDesk pyramid — plus the temporal validity, plus the authority chain, plus the exception register. Each addition earns its place.
Why the retrospective/reproductive split matters
Section titled “Why the retrospective/reproductive split matters”Conflating them costs 4-6 months of project time, because the reproductive infrastructure (versioned artifact catalog + version-aware resolver) is substantial. Naming the split early lets Phase 1 ship the bigger half of the value at a third of the cost. Reproductive then becomes an opt-in feature for the cases that genuinely need it (audit defense), not a precondition for the cases that don’t.
Summary
Section titled “Summary”- Compliance is a verb. Governance is the system. Name the system, then compliance is one feature.
- Retrospective (today’s lens × historical data) and reproductive (historical lens × historical data) are different temporal questions with different infrastructure costs. Build retrospective first.
- Bitemporal data discipline is the load-bearing infrastructure. Every gold table gets
valid_from / valid_toANDobserved_at. Thejinflow.as_of()macro threads time through every read path. - Governance rules are a new top-level artifact kind, with
effective_from / effective_to,authority,subject.scope_predicate,predicate,consequence,exceptions,supersedes,changelog. First-class fields, not optional signal metadata. - Exceptions are themselves audit artifacts. YAML files with authority traces, validated by the engine.
- Snapshots stay for legal-grade certified evidence and a few audit moments. AS-OF queries take over for continuous historical exploration.
- Cross-pack from day one. hrcentral surfaces the need first; numetrix and interlogic adopt the same primitive.
- Reproductive (Phase 2) is parked until an audit-grade need is concrete. Most of the unlock lives in Phase 1.
Status: proposed. Next step: review, refine the contract sketch, sequence with other in-flight Sense docs (notably Sense 19 prereqs and Sense 25’s pass model), then convert to implementation tickets.
Numerical neighbors: ← Sense 38: The Scribe — Who Carries the Author’s Action Across a Credential Boundary · Sense 40: The Metamodel →