Sense 25 — Identity, Roles, Passes, Capabilities — Concept Paper
Sense 25 · Folded in · Last touched 2026-10-07
Folded into
Sense sense-61-the-reservoir.
- last_verified: 2026-07-27
Synced from
docs/design/sense_25_identity_and_passes.mdin the engine repo — that’s the source; this page is a build-time mirror.
“Who am I right now, where am I right now, and what can I do here?”
A product-agnostic access model for the jazzisnow product family. Designed 2026-04-13. Merges
identity_roles_passes.md(2026-03-23) with the scope/pool/offline/reusability evolutions from 2026-04-12. Revised 2026-05-14 (§4, §8, §11, §15) to retire the “pool” vocabulary in favour of “three categories of access defined by where in the scope tree an identity binds”, and to make the Clerk Users-vs-Orgs binding conditional on customer shape.
The Sense framing — read first if you want the cognitive move and the
vendor-flexibility techniques without every YAML schema:
sense_25_the_pass.md. This concept paper is the
full mechanical specification it references.
0. Design Principle: Reusability to its Fullest
Section titled “0. Design Principle: Reusability to its Fullest”This model is not jinflow-specific. It is a jazzisnow-wide identity and authorization framework designed to be the starting point for every product we build — jinflow, cuebook, hrcentral, and whatever comes next.
The lesson from the three rooms (Salon / Lab / Studio) applies here with the same force: we don’t build for one domain and then generalize; we build the grammar first and let each domain instantiate it. The identity model is the grammar. jinflow is the first instantiation. cuebook is the second. hrcentral is the third.
What is shared vs product-specific:
| Concern | Shared module | Product-specific |
|---|---|---|
| The four-level model | Vocabulary, tree structure, evaluation algorithm | — |
| Capability types | ui_visibility, action, api_gate, dynamic_filter | — |
| Scope tree | system → pack → tenant + named lists | Level names (numetrix, rmc, vai) |
| Clerk integration | Session validation, org mapping, profile sync | Which Clerk org maps to which scope |
| Capability evaluator | Walks role tree, flattens, resolves scope, handles non-boolean | Call sites |
| AFS YAML schema | capabilities.yaml, passes.yaml, roles.yaml, identities.yaml, grants.yaml | Content |
| KLS tables | Compiled schema for identities, role tree, grants | Rows |
| Admin UI | Pages, grant/revoke flows, role tree visualizer | Branding, navigation context |
The shared layer ships as a module — pass evaluator, Clerk middleware, role compiler, admin UI components. Any product imports it. jinflow’s YAML and cuebook’s YAML have different content, same schema, same compiler, same engine.
The test for reusability: when hrcentral’s identity setup begins, the only files written are:
afs/identity/capabilities.yaml— what hrcentral’s features needafs/identity/passes.yaml— how capabilities groupafs/identity/roles.yaml— role definitionsafs/identity/identities.yaml— default personas- A few lines in
config.yml— Clerk org mapping
Zero engine code. Zero evaluator changes. Zero admin UI forks. If engine code needs to change for hrcentral, the design failed.
1. Vocabulary
Section titled “1. Vocabulary”| Term | Definition |
|---|---|
| Person | A human being. Has one authentication account (typically Clerk). Can hold identities in multiple scopes. |
| Identity | The single hat a person wears within a given scope. “the owner is an Analyst in RMC.” A person has exactly one identity per scope. |
| Role | A named bundle of passes that represents a job function. An identity maps to one or more roles. Roles are non-hierarchical — no inheritance. |
| Pass | A named group of capabilities that represents a logical permission bundle. Like a backstage pass — “access to all areas” of a coherent domain. Passes are assigned to roles. |
| Capability | The atomic unit. One UI decision, one API gate, one data filter. Answers a single question. Carries a type (ui_visibility, action, api_gate, dynamic_filter) and can return boolean or valued answers. |
| Scope | Where an identity lives. Scopes form a tree: system → pack → tenant. system is a singleton. At pack and tenant levels, a scope can also be a named list. |
| Grant | The act of assigning an identity (or a temporary extra role) to a person within a scope. Grants can be permanent or time-limited + revocable. |
| Pool | A user population. Two pools coexist: the jinflow pool (platform-wide) and per-tenant pools (scoped to one tenant). A person can exist in both. |
| Provider | The authentication source a person used (Clerk, GitHub, env fallback). Some capabilities require a specific provider. |
2. The Four-Level Model
Section titled “2. The Four-Level Model”Identity → Roles → Passes → Capabilities 1:n 1:n 1:nEvery relationship is many-to-many. This prevents premature coupling between organizational structure and technical features.
2.1 Why four levels
Section titled “2.1 Why four levels”Each level has a different change frequency and a different owner. Collapsing them creates coupling — changing a UI feature shouldn’t require redefining organizational roles.
| Level | Changes when… | Owner | Frequency | Lives in |
|---|---|---|---|---|
| Capability | A feature is added/removed from code | Developer | Per release | Code constants + capabilities.yaml |
| Pass | A permission group is redesigned | Pack author | Per pack version | passes.yaml |
| Role | A job function is redefined | Pack author / tenant admin | Per org change | roles.yaml |
| Identity | The user switches context | User (local) / admin (cloud) | Per session / per assignment | identities.yaml (defaults) + grants (per person) |
2.2 Level 4 — Capability (atomic)
Section titled “2.2 Level 4 — Capability (atomic)”What: The atomic unit. One UI decision, one API gate, one data filter.
Who controls it: Developer (code-level).
Examples: view:findings, notebook:write, export:csv, explainer:use.
A capability answers one question: “Can this user do this specific thing right now, and if so, to what extent?“
2.3 Level 3 — Pass (coherent bundle)
Section titled “2.3 Level 3 — Pass (coherent bundle)”What: A named group of capabilities that make sense together.
Who controls it: Pack author.
Examples: explore, report, investigate, build, discuss, admin.
A pass is a coherent bundle. “Explore” grants visibility to all analytical pages. “Investigate” grants notebook write access plus the explainer. You don’t pick individual capabilities — you grant passes.
2.4 Level 2 — Role (job function)
Section titled “2.4 Level 2 — Role (job function)”What: A named bundle of passes that represents a job function.
Who controls it: Pack author (defaults) or tenant admin (custom roles).
Examples: explorer, investigator, builder, executive, auditor.
An identity maps to one or more roles. Roles are the reusable building blocks — an analyst identity might combine explorer and investigator roles.
Roles are non-hierarchical. An engineer doesn’t “inherit” from analyst. They’re separate role combinations. This avoids the fragile inheritance chains that plague traditional RBAC.
2.5 Level 1 — Identity (persona in a scope)
Section titled “2.5 Level 1 — Identity (persona in a scope)”What: The persona the user operates as within a given scope. “I am an analyst in RMC right now.”
Who controls it: The user (local mode) or the tenant/pack/system admin (cloud mode).
Persistence: localStorage (browser, local mode) or KLS _{tenant}.identity table (cloud mode, per-tenant scope) or the jinflow meta store (system/pack scope).
Examples: analyst, cfo, consultant, engineer, viewer.
A person can have different identities in different scopes:
person: mig tenant:rmc → identity: analyst tenant:inspire → identity: viewer pack:numetrix → identity: pack_maintainer system → (no identity — not a platform admin)3. Capability Types
Section titled “3. Capability Types”Capabilities are not just show/hide. They carry a type that determines how they’re enforced. This is the most powerful feature of the model — one vocabulary, four enforcement strategies.
3.1 ui_visibility
Section titled “3.1 ui_visibility”Show or hide a page, section, or component.
view:findings: type: ui_visibility target: page:findings
view:salon: type: ui_visibility target: page:salon3.2 action
Section titled “3.2 action”Enable or disable a button, form, or interactive element.
export:csv: type: action target: button:dimension_export
notebook:write: type: action target: form:notebook_add_cell3.3 api_gate
Section titled “3.3 api_gate”Allow or deny an API call. Enforced server-side.
notebook:write: type: api_gate target: POST /api/notebook/cells
signal:compile: type: api_gate target: POST /api/signal-builder/compile3.4 dynamic_filter
Section titled “3.4 dynamic_filter”Modify what data is returned. Not show/hide — the query itself changes.
view:findings:high_only: type: dynamic_filter rule: "severity IN ('high', 'medium')" target: query:findings
view:dimensions:no_pii: type: dynamic_filter rule: "column NOT IN ('patient_name', 'date_of_birth')" target: query:dimensionsThe CFO doesn’t see low-severity findings — not because they’re hidden in the UI, but because the query doesn’t return them. Data minimization at the source.
3.5 Non-boolean capabilities
Section titled “3.5 Non-boolean capabilities”Capabilities can return values, not just yes/no:
export:row_limit: type: value returns: integer default: 1000
data:access_level: type: value returns: enum values: [bronze, silver, gold] default: gold
api:rate_limit: type: value returns: integer # requests per minute default: 100When evaluated, the capability returns its value (after walking the role tree). If multiple roles grant the same valued capability, the most permissive value wins — highest number, broadest enum.
3.6 Provider-specific requirements
Section titled “3.6 Provider-specific requirements”Some capabilities require a specific authentication provider:
afs:git: type: api_gate target: POST /api/afs/push requires_provider: github # user must have linked GitHub
calendar:sync: type: api_gate target: POST /api/calendar/sync requires_provider: googleA user with the capability granted but no matching provider sees it as unavailable (not denied — unlinked). They can link the required provider to unlock it.
4. The Scope Tree
Section titled “4. The Scope Tree”Scopes form a five-level tree. Every identity is scoped to exactly one node (or a named list at the pack/tenant levels).
The earlier three-level tree (system → pack → tenant) was correct for the first product but missed the layer above. A customer (the org that buys jazzisnow products) may have multiple applications (jinflow, hrcentral, …), each with multiple packs (numetrix, interlogic, …), each with multiple tenants (RMC, Inspire, …). The full tree has to span that space without engine code changes per product.
jazzisnow the maintainer (singleton) └── customer: acme_health the org that buys jazzisnow products ├── application: jinflow │ ├── pack: numetrix │ │ ├── tenant: rmc │ │ ├── tenant: inspire │ │ └── tenant: pricing_lab │ └── pack: interlogic │ └── tenant: … └── application: hrcentral └── pack: hrcentral └── tenant: vaiThe five levels and what each one means:
| Level | What lives there | Who manages it |
|---|---|---|
jazzisnow | The maintainer (us). One node. | Internal — GitHub identity / equivalent |
customer | The organisation that bought one or more applications | Customer-admin layer (Clerk for B2B; see §11) |
application | A product line: jinflow, hrcentral, … | Per-customer entitlement |
pack | A distribution of analytical content within an application: numetrix, interlogic, … | Per-customer entitlement |
tenant | One deployment instance: rmc, vai, … | The customer’s own admin OR jazzisnow-on-their-behalf |
4.1 Resolution rules
Section titled “4.1 Resolution rules”- A tenant-scoped identity sees only its own tenant.
- A pack-scoped identity sees all tenants of that pack (within one customer + application).
- An application-scoped identity sees all packs of that application (within one customer).
- A customer-scoped identity sees everything the customer bought.
- A jazzisnow-scoped identity sees everything.
jazzisnowis a singleton — there is only one. - At the pack and tenant levels, a scope can also be an explicit named list — a cross-cut that doesn’t fit the tree:
- Named list of tenants: “admin for RMC + Inspire but not Pricing Lab”
- Named list of packs: “pack maintainer for numetrix + hrcentral”
4.2 Inheritance
Section titled “4.2 Inheritance”Capabilities flow downward. A jazzisnow-scoped role’s capabilities apply everywhere. A customer-scoped role’s capabilities apply to every application/pack/tenant that customer owns. A tenant-scoped role’s capabilities apply only there. No upward inheritance — a tenant capability never leaks to the pack or customer level.
4.3 Scope conflict resolution
Section titled “4.3 Scope conflict resolution”When the same valued capability is granted at multiple scope levels (tenant says export:row_limit: 1000, pack says 5000), the most permissive value wins. The rule is: closer scope + more permissive = effective value, unless explicitly overridden by a scope_override: restrict marker.
4.4 Three categories of access defined by where an identity binds
Section titled “4.4 Three categories of access defined by where an identity binds”The earlier draft talked about a “jinflow pool” and a “tenant pool”. That vocabulary is retired — it conflated two distinct populations (jazzisnow team + jazzisnow customers) and didn’t generalise across applications. The cleaner framing: categories of access are defined by where in the scope tree an identity binds, not by a separate “pool” abstraction:
| Category | Binds at | Who fits | Managed where |
|---|---|---|---|
| jazzisnow-team | jazzisnow | Platform maintainers (the owner + future colleagues) | Internal tools, GitHub |
| customer-admin | customer (and below) | The people who pay for the product and administer their org’s access | Clerk (B2B; conditional — see §11) |
| tenant-end-user | tenant (and below) | The day-to-day users of one deployment — the CFO at RMC, the HR officer at VAI | Per-tenant config; NOT Clerk |
This split matters because Clerk is the right tool for the customer-admin category (B2B operations offload, SSO/SAML, billing) and the wrong tool for the tenant-end-user category (where the user pool is the customer’s responsibility, not ours).
5. Capability Resolution
Section titled “5. Capability Resolution”At runtime, the system resolves the full chain:
person: mig ← from Clerk / providerscope: tenant:rmc ← from URL / contextidentity: analyst ← from grants table → roles: [explorer, investigator] → passes: [explore, report, investigate, discuss] → capabilities: view:findings → true view:salon → true export:csv → true export:row_limit → 10000 notebook:write → true explainer:use → true ...The resolved set is a flat map:
type CapabilitySet = Map<string, boolean | number | string | string[]>;Every UI component and API endpoint checks:
if (can('notebook:write')) { // show the add-cell toolbar}
const limit = capValue('export:row_limit'); // returns 10000Server-side enforcement for API gates:
if (!can('notebook:write')) { return json({ error: 'Insufficient permissions' }, { status: 403 });}6. Identity Lifecycle
Section titled “6. Identity Lifecycle”6.1 Creation
Section titled “6.1 Creation”A person is created via an authentication provider (Clerk in production). Clerk holds:
- Authentication credentials (email, password, OAuth providers)
- Profile (name, avatar, email)
- Organization memberships (mapped to jinflow scopes)
jinflow holds:
- Identity-to-scope assignments
- Role assignments per identity
- Temporary grants
- The compiled capability tree (baked into KLS)
6.2 Assignment
Section titled “6.2 Assignment”An admin assigns an identity to a person within a scope:
"the owner is an analyst in numetrix.rmc" → person: mig (Clerk user_id) → scope: tenant:rmc → identity: analyst → effective: permanent6.3 Temporary grants
Section titled “6.3 Temporary grants”An admin can temporarily grant an additional role on top of the existing identity:
"Give the owner the admin role in RMC for 48 hours" → person: mig → scope: tenant:rmc → extra_role: admin → effective: 2026-04-13T10:00 → 2026-04-15T10:00 → revocable: trueEffective capabilities = union of the permanent identity’s capabilities and any active temporary grants. When the grant expires, the extra capabilities disappear automatically — no cleanup needed, the evaluator checks timestamps.
6.4 Revocation
Section titled “6.4 Revocation”- Remove identity: person loses all access to that scope.
- Downgrade identity: swap analyst → viewer. Capabilities narrow immediately.
- Revoke temporary grant: admin explicitly ends a time-limited grant early.
6.5 Invitations
Section titled “6.5 Invitations”Onboarding a new person is two writes — one on each side of the trust boundary:
| Side | What is written | When |
|---|---|---|
| AFS | A principal YAML with email, identity, scope | Always — this is the grant |
| Clerk | An invitation (Clerk Invitations API) | Only when the invitee needs web/proxy access |
A CLI-only operator (CI runner, a builder who only ever runs jin make) doesn’t need the Clerk side — they get an AFS principal plus a service token (see §7.3). A human who wants to use JinDesk needs both.
jin invite command shape:
jin invite mig@example.com \ --tenant numetrix.inspire \ --identity builder \ --principal-id mig # required — slug for the new principal # (omit --no-web to fire the Clerk invitation; # --no-web for CLI-only operators)The slug is mandatory — --principal-id is a required flag. The reasoning is that principal_id is effectively immutable once set: it’s the joining key in many other YAML files (incumbent, invited_by, members[], the person-naming fields on notebook / bookmark / signal / verdict artifacts), it’s baked into the principal_registry KLS table, and it’s carried in Clerk’s invitation publicMetadata. Renaming a principal is a multi-file find-and-replace plus a Clerk metadata patch. Cheap when chosen well; expensive when chosen badly. The CLI forces a deliberate choice at the only cheap moment.
The slug must match ^[a-z][a-z0-9_]*$ (the principal-contract id pattern).
The command:
- Verifies the caller’s session has
identity == 'owner'in the target tenant (simplified Phase C capability gate — full 4-level cascade will replace this later). - Resolves the target against the tenant’s existing principals:
NEW(proceed),EXISTING_BOUND(refuse, point atjin grant),EXISTING_UNBOUND(refuse, point at re-send flow),SLUG_TAKEN(refuse, ask the caller to pick a different slug — common conventions are appending a domain stem likemig_acmeor a role likemig_external). - Writes
afs/principals/user_<slug>.yamlwithemail,identity,display_name. Theuser_prefix on the filename matches the existing in-tree convention forkind: userprincipals; sibling files for roles and groups userole_/group_. - If
--web(default): POSTs to JinDesk’s/api/invitationsendpoint. The server-side handler verifies the CLI’s Bearer JWT (requireCliAuth), re-runs the capability gate against the bakedprincipal_registry, then calls Clerk’screateInvitationwithpublicMetadata.jinflow = { tenant, identity, principal_id, invited_by_clerk_user_id, invited_by_principal_id }. Returns theclerk_invitation_id, which the CLI then stamps onto the AFS principal viaPrincipalWriter.stamp_invitation().
Recording the inviter (corrected 2026-08-02). The AFS principal carries the
same distinction Clerk’s publicMetadata already draws above — as two fields,
exactly one of which is set:
| Field | Holds | Validated |
|---|---|---|
invited_by | the inviter’s principal_id | resolved against the roster; must be kind: user |
invited_by_clerk_user_id | the inviter’s Clerk user id | shape only (user_ prefix) — never resolved |
The second exists because a tenant can be owned through Clerk publicMetadata
alone, with no AFS roster — that is a supported ownership shape, and it is how
the owner gate passes for such a tenant. Its inviter genuinely has no
principal_id, so there is nothing for a roster lookup to find.
This was a live defect, not a hypothetical: jin invite resolved the caller’s
principal_id and fell back to the raw Clerk user id when it found none,
writing it into invited_by — a field the contract types principal_id? and
principalcheck resolves against declared principals. The result was an
invitation that left the tenant unbuildable, failing in a later command with
an error that never mentioned invite (2026-08-02).
The writer now refuses to express it: passing a Clerk-shaped id as invited_by
raises, both fields together raises, neither raises, and jin invite prints
which provenance it recorded. principalcheck names the fix in its error when it
meets the old shape, so a red build carries its own remedy.
Deliberately unchanged: invited_by stays a validated reference rather than
becoming free provenance. A consequence to watch — removing a principal who once
invited others turns those files invalid, so retiring an inviter is a roster
operation with a build-visible tail. That is a separate decision from this fix.
Acceptance flow (web case):
- Invitee clicks the Clerk invitation magic link.
- Clerk creates the user and binds them to the org (where applicable — see §11.1).
- On first sign-in, the resolver looks up the AFS principal by
clerk_invitation_idand stampsclerk_user_idonto the YAML. From this moment on, the binding is byclerk_user_id— email becomes a stale display hint.
Email is the invitation seed, not the durable link. People change email addresses. clerk_user_id is opaque and durable; that is what the AFS principal carries after acceptance.
7. Surfaces and Modes
Section titled “7. Surfaces and Modes”The same identity model has to serve three surfaces — JinDesk (SvelteKit web app), Proxy (P2P2P tunnel, Sense 16), and CLI (jin commands). Each resolves “who is calling” from a different input, but they all share the same downstream: Clerk userId → AFS principal → capability check.
| Surface | Input | Resolver |
|---|---|---|
| JinDesk (SSR) | Clerk session cookie | verifyToken → userId |
| Proxy (P2P2P) | Forwarded Clerk session via tunnel | same verification |
| CLI | ~/.jinflow/session.json (Clerk JWT minted via JinDesk’s /cli-auth bridge) or JINFLOW_API_KEY env var | session.user_id (Clerk userId from the JWT payload) |
7.1 Local mode
Section titled “7.1 Local mode”jinflow desk on localhost — the user is the machine owner.
Two options:
-
Implicit all-access (default): Every capability is granted. No identity selection needed. The engineer who just wants to work.
-
Identity switcher: The user optionally picks an identity from a dropdown in JinDesk header. This restricts capabilities to match the selected persona. Useful for “what will the CFO see?” previewing.
Identity selection in local mode is stored in localStorage. Refreshing preserves it. Switching is instant — no page reload, just a reactive capability-set update.
function resolveCapabilities(mode: 'local' | 'cloud', identity?: string, scope?: string): CapabilitySet { if (mode === 'local' && !identity) { return ALL_CAPABILITIES; // god mode } return resolveChain(identity, scope);}7.2 Cloud mode
Section titled “7.2 Cloud mode”Deployed JinDesk — multiple users, multiple tenants, API-enforced.
- User authenticates via Clerk (email, OAuth, whatever Clerk supports).
- Tenant admin has assigned an identity (or user self-selects from allowed identities).
- Capabilities are resolved server-side and passed to the client.
- API endpoints enforce capabilities via middleware.
7.3 CLI mode
Section titled “7.3 CLI mode”jin commands run on developer laptops, headless servers (SSH’d), CI runners, Docker containers, and cloud workers. The identity story stays unified — every surface authenticates against Clerk when authentication is wanted at all — but the CLI is local-first: it works fully without ever talking to Clerk, and opts in to authenticated mode only when the user runs jin login.
The bridge is JinDesk itself. Clerk doesn’t expose an RFC 8628 device-code endpoint, and the Backend API uses a server-only secret key we can’t ship to laptops. The dominant Clerk-CLI pattern (see Erik Steiger’s Rust tutorial, October 2025) wraps Clerk’s <SignIn/> component in a small server-side endpoint that mints a JWT and redirects to a localhost callback. That endpoint already has a natural home: the existing JinDesk SvelteKit app, which is part of every jinflow deployment by construction (local via jin desk, cloud via Fly). No separate api.jinflow.io service is needed.
Configurable target URL. The CLI talks to whichever JinDesk it’s pointed at:
# ~/.jinflow/config.yml (or env override $JINFLOW_API_URL)api_url: https://app.jinflow.io # cloud defaultapi_url: http://localhost:4000 # local JinDesk (jin desk)This delivers the Independent conviction concretely: a hospital can run jinflow fully on-prem (local JinDesk + local CLI + Clerk as the only third party) without any jinflow-controlled service in the loop. If jinflow.io is down, point at your own JinDesk.
Operating modes by environment:
| Context | What works | Capability check |
|---|---|---|
| Air-gapped / no internet | Everything except --web flags | Skipped (you own the machine — local-mode god-rights) |
| Internet up, never signed in | Same as air-gapped | Skipped |
Internet up, signed in via jin login | Everything | Enforced against AFS principal |
| Internet down, signed in (within grace) | Read-only AFS ops; refuse new Clerk invitations | Enforced against cached resolution |
jinflow.io cloud down but local JinDesk up | Everything (point api_url at localhost) | Enforced normally |
Login modes (when jin login is invoked):
| Mode | When | Flow |
|---|---|---|
| Browser-callback | Laptop with a graphical browser | CLI starts local HTTP server on an ephemeral port. Opens browser to {api_url}/cli-auth?port=<N>. User signs in via Clerk on that page (JinDesk renders Clerk’s <SignIn/>). Page calls /api/cli-token, which uses clerkClient to mint a JWT, then redirects to http://localhost:<N>/callback?token=<jwt>. CLI receives and stores. |
| API key | CI/CD, Docker, cloud workers | JINFLOW_API_KEY=sk_xxx env var. Bypasses sign-in entirely. |
Device-code flow (RFC 8628) was scoped, carried briefly in commit
2362caf6, then parked per the 2026-05-25 cuebook letter exchange. Every CLI user today is on a laptop with a browser; carrying the half-working--deviceflag risked someone hitting a dead endpoint. The browser-callback path covers 100% of current need. Build device-code back when a real headless user materialises — there’s no JinDesk-side bridge for it yet, and the work is ~2 hours against actual constraints.
Session storage: ~/.jinflow/session.json, plaintext, 0600 perms. Cross-environment portability beats OS-keychain integration; keyring is a hard dependency on a desktop environment that CI / headless surfaces don’t have.
Three-layer check on every command (small allowlist excepted — jin login, jin --version, jin --help):
1. Local-mode escape hatch — does the user explicitly want local-mode OR has a session never existed? yes → skip all checks; treat caller as machine owner (god mode).
2. Authentication — load_session() returned a session token. absent + cloud-mode-required → "Not signed in. Run `jin login`."
3. Authorization — does the bound principal hold the required capability in the target tenant? denied → "Signed in as mig, but no `user:manage` capability in `numetrix.inspire`. Ask an owner to grant access."The Phase-3-era plan/billing layer (require_auth("feature")) is parked: no api.jinflow.io service exists to enforce it. It can return cleanly later if billing logic warrants its own service. For now, the model is just authentication + authorization, both threaded through the same JWT.
Local JinDesk god-mode (§7.1) is unchanged. The CLI’s local-first default is the same posture — engineer on their own machine just wants to work. Adding jin login is opt-in escalation to a stricter regime.
7.4 Offline grace period
Section titled “7.4 Offline grace period”The CLI runs offline often enough (planes, hotel wifi, off-site customer engagements) that a hard “must verify online” policy is wrong. The session file caches what api.jinflow.io told us last, and the cache stays valid for a bounded window after the last successful online check.
Cache contents (~/.jinflow/session.json, plaintext):
{ "user_id": "user_3DxK2tZb3HuiCmsJJh48zktya0F", "email": "mig@example.com", "token": "eyJ...", "refreshed_at": "2026-05-24T08:42:11Z", "api_url": "https://app.jinflow.io"}The Phase-3-era session shape carried org_id, org_name, plan fields too; those return only if/when the billing service comes back.
Why we don’t cache the resolved capabilities here. The AFS lives on the same machine as the CLI. Capability resolution reads YAML files locally and is therefore always available — no cache needed for that side. The cache exists for the authentication side, where the source of truth (Clerk via JinDesk bridge) is remote.
Grace period: 30 days by default (OFFLINE_GRACE_DAYS in jinflow/auth.py). Long enough that air travel and multi-week customer engagements don’t break the tool; short enough that genuinely revoked access lands within a month.
Check flow when offline:
- now − refreshed_at < 30 days → proceed with cached plan, emit one-line offline note- now − refreshed_at ≥ 30 days → deny: "Session expired. Run `jin login` when online."Banner cadence — quiet most of the window, escalates as the deadline approaches:
| Phase of grace window | Cadence | Tone |
|---|---|---|
| Days 1–25 (most of the window) | First command of each calendar day | Quiet |
| Days 26–29 (last 5 days) | Once per session | Yellow |
| Day 30 (last 24h) | Every command, escalated wording | Red |
| After expiry | Command denied with reason | — |
Banner format (single line at the top of command output):
⚠ Working offline. Re-verify by 2026-06-23 08:42 (in 27d).Status query (no nag): jin us includes an auth section — signed-in identity, online/offline, last verified, grace remaining when offline. Users who want the picture without scrolling use that surface.
Why 30 days instead of the originally-proposed 3. The original §7.4 draft (2026-05-24) called for 3-day grace to tighten identity-revocation latency. Reality on review: the existing 30-day grace pre-existed (Phase 3 of the jinflow product), serves the dual concern of subscription stays valid + identity stays bound through the same refreshed_at clock, and aligns with what every other modern dev tool offers (gh, gcloud, aws sso all use long grace periods). Headless-mode contexts where you can’t easily re-auth on demand also need the longer window. Tighter revocation latency is a focused upgrade that can land separately if a real incident motivates it.
8. Three Categories of Access
Section titled “8. Three Categories of Access”Earlier drafts called this “Dual Pool Architecture” and named two pools (
tenantandjinflow). The vocabulary was retired on 2026-05-14 because it conflated two distinct populations (jazzisnow team + jazzisnow customers) and didn’t generalise across applications. Same content, less invented terminology. Categories of access are defined by where in the five-level scope tree an identity binds (see §4.4). No new “pool” abstraction is needed.
8.1 The three categories
Section titled “8.1 The three categories”| Category | Binds at | Who fits | Managed where |
|---|---|---|---|
| jazzisnow-team | jazzisnow | Platform maintainers — the people who write the engine | Internal tools / GitHub |
| customer-admin | customer (and below) | The people who pay for the product and administer their org’s access — billing contact, customer success, customer admin | Clerk (conditional — see §11) |
| tenant-end-user | tenant (and below) | The day-to-day users of one deployment instance — the CFO at RMC, the HR officer at VAI | Per-tenant config; not Clerk |
A person can hold identities in more than one category — e.g. a jazzisnow engineer who is also contracted as an RMC analyst. The categories are not mutually exclusive populations; they’re roles in the access tree that happen to be managed by different surfaces.
8.2 What lives where
Section titled “8.2 What lives where”- jazzisnow-team identities sit in the
jazzisnownode of the tree. There’s exactly one such node; membership is internal. - customer-admin identities sit at the
customerlevel (or, in larger orgs, atcustomer → applicationfor “admin of jinflow but not hrcentral”). They are the orgs that BUY jazzisnow products. - tenant-end-user identities sit at the
tenantlevel and below (a department, a role-within-a-department, etc.). The customer’s own admin grants and revokes these — or jazzisnow does it on their behalf.
8.3 Scope binding in practice (multi-customer, multi-application, multi-pack, multi-tenant)
Section titled “8.3 Scope binding in practice (multi-customer, multi-application, multi-pack, multi-tenant)”The five-level tree means the same model spans every product. For one customer:
acme_health (customer) ├── jinflow (application) │ ├── numetrix (pack) │ │ ├── rmc │ │ ├── inspire │ │ └── pricing_lab │ └── interlogic (pack) │ └── … └── hrcentral (application) └── hrcentral (pack) └── vai- Alice is the customer-admin for
acme_health— she binds at thecustomernode. She sees billing, can invite users, can re-deploy packs. - Bob is the CFO at RMC — he binds at
customer → jinflow → numetrix → rmc. He sees RMC’s KLS only. - A jazzisnow engineer binds at
jazzisnowand sees everything (subject to the data sovereignty story from Sense 16 — visibility ≠ access to the bytes).
8.4 Cross-category identities
Section titled “8.4 Cross-category identities”When a person holds identities in more than one category:
- They have one
principal_id(e.g.prn_alice_…) that names them across the system. - They have one or more identity grants, each pinning an identity to a scope node.
- The effective capability set at a given tenant scope is the union of the tenant identity’s capabilities and any pack/application/customer/jazzisnow identity’s capabilities (downward inheritance from §4.2).
Clerk’s active_organization_id (when Clerk is in play) provides the current context — at any moment, the user is acting from one Clerk org, even if they belong to several. The scope resolver maps that to one node in the tree and walks downward.
9. Resolution Chain
Section titled “9. Resolution Chain”When a request arrives at JinDesk with tenant context:
- Authentication: resolve the person’s identifier.
- Clerk session → verified user_id, org memberships
- GitHub OAuth → verified GitHub user (for git-scoped capabilities)
JINFLOW_USERenv var → hardcoded identifier (CI / dev)jinflow-mecookie → graffiti name (display only, treated as anonymous for auth)- Nothing → anonymous
- Scope resolution: what scope is this request in? (from URL:
/numetrix.rmc/...→tenant:rmc) - Identity lookup: for this person_id in this scope, what identity is assigned?
- Capability resolution: walk identity → roles → passes → capabilities, apply scope inheritance, resolve conflicts.
- Provider check: for capabilities with
requires_provider, verify the person authenticated via the required provider. If not, the capability is marked unavailable (distinct from denied). - Temporal grants: merge in any active temporary grants. Drop expired ones.
10. Storage
Section titled “10. Storage”10.1 What Clerk owns vs what jinflow owns
Section titled “10.1 What Clerk owns vs what jinflow owns”| Concern | Owner |
|---|---|
| Authentication (who are you?) | Clerk |
| Profile (name, avatar, email) | Clerk |
| Organization membership | Clerk |
| Identity assignment (which persona?) | jinflow (AFS → KLS) |
| Role / pass / capability definitions | jinflow (AFS → KLS) |
| Capability evaluation | jinflow (JinDesk, from KLS) |
| Session management | Clerk (JWT) |
| Invitation flow | Clerk (email) + jinflow (identity assignment) |
10.2 AFS source files
Section titled “10.2 AFS source files”The identity model lives in the AFS as YAML:
afs/ identity/ capabilities.yaml -- capability definitions (type, target, default value) passes.yaml -- pass-to-capability mappings roles.yaml -- role-to-pass mappings identities.yaml -- identity-to-role mappings (default personas) grants.yaml -- person-to-identity grants (permanent + temporary) defaults.yaml -- anonymous access policy, fallback identity10.3 KLS tables (compiled output)
Section titled “10.3 KLS tables (compiled output)”jinflow make compiles the AFS YAML into KLS tables in the metadata schema _{tenant}:
-- Flattened capability map per identityCREATE TABLE capability_map ( identity VARCHAR, capability VARCHAR, value VARCHAR, -- text-encoded: 'true', '5000', 'gold', etc. cap_type VARCHAR, -- ui_visibility | action | api_gate | dynamic_filter | value target VARCHAR, rule VARCHAR, -- for dynamic_filter requires_provider VARCHAR -- NULL if none);
-- Person-to-identity grants (permanent)CREATE TABLE identity_grant ( user_id VARCHAR, display_name VARCHAR, scope VARCHAR, -- 'tenant:rmc' | 'pack:numetrix' | 'system' | 'tenants:[rmc,inspire]' identity VARCHAR, granted_at TIMESTAMP, granted_by VARCHAR);
-- Temporary role grantsCREATE TABLE role_grant_temporary ( user_id VARCHAR, scope VARCHAR, extra_role VARCHAR, granted_at TIMESTAMP, expires_at TIMESTAMP, granted_by VARCHAR, revoked_at TIMESTAMP -- NULL if still active);
-- Identity → roles flattened for fast lookupCREATE TABLE identity_roles ( identity VARCHAR, role VARCHAR);
-- Role → passes flattenedCREATE TABLE role_passes ( role VARCHAR, pass VARCHAR);
-- Pass → capabilities flattenedCREATE TABLE pass_capabilities ( pass VARCHAR, capability VARCHAR);10.4 Offline / P2P2P
Section titled “10.4 Offline / P2P2P”The entire capability tree is compiled into the KLS. JinDesk evaluates capabilities from the KLS, not from a network service. This means:
- P2P2P works fully offline — the KLS carries its own authorization.
- Clerk is only needed for authentication (session validation). If Clerk is unreachable, JinDesk can fall back to the cookie/env chain with a degraded identity (e.g.
vieweroranonymous, depending ondefaults.yaml). - Updating the capability model requires a rebuild (
jinflow make). Updating a person’s identity grant is a SIS write → AFS commit → rebuild, or a direct admin API write to the KLS meta tables.
11. Coexistence
Section titled “11. Coexistence”11.1 Clerk Users vs Clerk Orgs — conditional by customer shape
Section titled “11.1 Clerk Users vs Clerk Orgs — conditional by customer shape”The earlier draft implied “one customer = one Clerk Org” universally. That’s wrong: forcing a Clerk Org for every registration would be heavy and expensive in the self-register / solo case where the user just wants to try the product. The binding is conditional on the customer shape, and Clerk supports every flavour:
| Customer shape | Clerk binding | Why |
|---|---|---|
| Solo (self-register, free tier or paid-as-individual) | Clerk User only, no Org | Lightest path; one billing contact == the user themselves. |
| B2B (paid org, multiple seats) | Clerk User + Org | Org owns billing, seats, and the customer-admin self-service surface. |
| Enterprise SAML / SSO | Clerk User + Org (required) | SAML enrolment is org-scoped in Clerk; this is the standard pattern. |
| Parent with sub-orgs (chain of hospitals, holding co) | Parent Org + N child Orgs | Parent admin manages child admins; each child owns its tenant pool. |
| Federation (a customer with sub-units sharing one billing relationship) | One Org with named sub-scopes | One billing context, multiple application/pack/tenant scopes underneath. |
The shared lesson: the access model does not force the same Clerk binding on everyone. The five-level scope tree from §4 stays constant; the Clerk binding hugs the customer’s actual organisational shape.
11.2 What Clerk Orgs buy us
Section titled “11.2 What Clerk Orgs buy us”The per-Org cost is justified by the operations offload for the B2B case. Specifically:
- Customer-admin self-service — the customer’s own admin invites users, revokes seats, resets passwords. We don’t sit in the middle of every onboarding request.
- SSO / SAML — enterprise sign-on is org-scoped in Clerk; we get it without writing SAML plumbing ourselves.
- Per-org billing — invoices, seat counts, plan upgrades attach to the Org, not to scattered users.
- Active-org session context — Clerk hands us
active_organization_idon every request, so the scope resolver knows which customer the user is acting as right now (matters when one user belongs to several Orgs). - Per-org analytics — usage metrics group naturally by Org. We can answer “is acme_health getting value?” without re-aggregating across user-level events.
These all apply to the customer-admin category (§8). They do not apply to the tenant-end-user category — that population isn’t in Clerk at all.
11.3 Multi-Org identity (one person, multiple customers)
Section titled “11.3 Multi-Org identity (one person, multiple customers)”Alice is a consultant. She belongs to two Clerk Orgs: acme_health (where she’s a senior analyst) and bayer_pharma (where she’s an auditor). In our model:
- One
principal_idfor Alice (prn_alice_…). - Two identity grants:
analystscoped toacme_health → jinflow → numetrix → rmc, andauditorscoped tobayer_pharma → jinflow → numetrix. - One active context at a time — Clerk’s session carries
active_organization_id. When Alice is signed intoacme_health, the resolver walks from that node. Switching the active org in Clerk switches the scope.
There’s no global “Alice has these N capabilities” answer — capabilities are always capability at a node in the scope tree. This keeps customer-of-customer data air-gapped at the model level.
11.4 GitHub OAuth
Section titled “11.4 GitHub OAuth”Kept as a developer/CI authentication path. A GitHub-authenticated user gets their identity resolved the same way as a Clerk user — just a different provider feeding into the same identity lookup. GitHub identity is specifically required for requires_provider: github capabilities (e.g. afs:git).
11.5 P2P2P tunnels
Section titled “11.5 P2P2P tunnels”Clerk auth layers on top of the tunnel, not instead of it. The tunnel provides network reachability; Clerk provides identity verification. When Clerk is unreachable (air-gapped, offline), JinDesk falls back to the cookie/env chain with a degraded identity.
11.6 Graffiti name
Section titled “11.6 Graffiti name”The me store (localStorage + cookie) remains as the display name for artifact authoring. When Clerk is active, it’s auto-populated from the Clerk profile. When Clerk is absent, the WelcomePrompt fires as before. The graffiti name is for display; the capability model is for authorization. They’re orthogonal.
11.7 Vendor flexibility
Section titled “11.7 Vendor flexibility”The five vendor-flexibility techniques from the Sense 25 proposal (AuthProvider interface, portable principal_id, capability resolution local to the KLS, webhook normalisation, no provider-specific YAML) apply at the customer-admin category only. The other two categories (jazzisnow-team, tenant-end-user) don’t go through Clerk and therefore don’t need a Clerk migration path. The flexibility is precisely there to let the customer-admin layer move from Clerk to another vendor (Auth0, WorkOS, Stytch, …) without rewriting the engine. We’re paying the Clerk Org cost for B2B convenience — and we’ve kept the door open in case that convenience stops being worth the cost.
12. Artifact Ownership and Assignment
Section titled “12. Artifact Ownership and Assignment”This section answers what was previously Open Question 3 (artifact ownership) directly: how do artifact references to people transition from free-text graffiti to structured identifiers under the principal model? It’s a separate concern from authorization (capability resolution) and from authentication (who’s logged in). It’s about the meaning of every field in the AFS that names a person, role, or group.
12.1 The current shape
Section titled “12.1 The current shape”Many artifact YAMLs contain fields that name a person or organisation as free text:
| Artifact | Field | Today’s shape | Examples |
|---|---|---|---|
| Action cell (notebook) | assignee | scalar string | a viewer, ronnie, an SME / a viewer, Hospital Administration, Department Head Endoscopy |
| Subject Matter | provider.name, provider.role, provider.date | nested string | an SME Hess, Senior Analyst, 2026-04-12 |
| Dossier | curator.name, curator.role, curator.date | nested string | same shape |
| Note | author.name, author.role, author.date | nested string | same shape |
| Bookmark | owner | scalar string | the graffiti name (e.g. mig, ronnie) |
| Recents | per-user file recents_<user>.yaml | filename slug | the graffiti slug |
| Reference cells | discussion[].author | scalar string | graffiti |
Two problems with the current shape:
- No referential identity.
a viewerandronnieare two distinct strings; the system can’t recognise them as the same person. Joining “all artifacts by a viewer” requires fuzzy matching. - Mixed semantics.
Hospital Administrationisn’t a person — it’s an organisational unit.Department Head Endoscopyis a role, not a name. The single string-typed field carries three different concepts.
12.2 Principals
Section titled “12.2 Principals”A principal is anything a person-named artifact field can refer to. Three kinds:
user— an individual person. Maps 1:1 with a Clerk user when authentication is active. Carriesdisplay_name,role, optionalemail.role— an organisational position. May or may not be filled by a single user (Department Head Endoscopycould be a viewer this year and someone else next year). The role itself has continuity; its incumbent doesn’t.group— a body of multiple people acting as one.Hospital Administration,Data Team. No single doer.
All three share the same id space — a principal_id, a stable slug. Examples:
principal_id: ronniekind: userdisplay_name: a viewer Hessrole: Senior Analystemail: r.hess@rmc.example # optionalclerk_user_id: user_2abc... # optional, set when Clerk is active
# afs/principals/role_department_head_endoscopy.yamlprincipal_id: department_head_endoscopykind: roledisplay_name: en: Department Head, Endoscopy de: Abteilungsleiter Endoskopie fr: Chef de département, Endoscopieincumbent: ronnie # optional, current holder
# afs/principals/group_hospital_administration.yamlprincipal_id: hospital_administrationkind: groupdisplay_name: en: Hospital Administration de: Spitalleitung fr: Direction hospitalièremembers: [ronnie, raffa] # optional, transparent membership12.3 Field shapes
Section titled “12.3 Field shapes”Artifact fields adopt one of two shapes — scalar reference (single principal) or list reference (multiple principals). Both store principal_id strings. The display layer resolves them at render time.
Scalar reference (single):
# bookmarkowner: ronnie
# subject matterprovider: principal_id: raffa date: 2026-04-12List reference (multiple):
# action cell — multi-assignee version of (2) from the assignee discussionassignees: [ronnie, raffa]
# subject matter with co-providersproviders: - { principal_id: raffa, date: 2026-04-12 } - { principal_id: ronnie, date: 2026-04-12 }12.4 RACI extension for actions
Section titled “12.4 RACI extension for actions”Action cells benefit from a structural split because the single assignee field is doing triple duty today:
# afs/notebook/nb_rmc_*.yaml — action cell schema (extended)- id: action_clarify_prix_moyen type: action status: proposed owner: ronnie # the doer (single) consulted: [raffa] # whose opinion is needed before acting informed: [hospital_administration] # to keep posted on outcome description: en: Clarify what prix_moyen means in OPALEBackwards compatibility: assignee: <id> is interpreted as owner: <id> during the migration. New cells should use the explicit fields.
12.5 Display rendering
Section titled “12.5 Display rendering”JinDesk (and any consumer) renders a principal reference by looking up the principal in the registry and substituting:
display_name(locale-aware if multilingual)rolefor users (subtitle)- A small icon by kind (person / chair / group)
When a principal_id does not resolve to a registered principal, the consumer falls back to rendering the slug itself with a warning glyph — a signal to the AFS author that they referenced an undeclared principal.
12.6 Storage
Section titled “12.6 Storage”Principals live in the AFS as YAML, alongside other declared artifacts:
afs/ principals/ user_ronnie.yaml user_raffa.yaml user_mig.yaml role_department_head_endoscopy.yaml group_hospital_administration.yaml group_data_team.yamlA compiler bakes them into the KLS as _<tenant>.principals (peer of _<tenant>.bookmark_registry, _<tenant>.note_registry). JinDesk reads from there at render time.
12.7 Scope
Section titled “12.7 Scope”Principals are tenant-scoped by default — a viewer is an RMC principal, declared in afs/principals/. When a person works on multiple tenants, the same principal_id is declared in each tenant’s AFS (with potentially different roles). A future enhancement can promote a principal to pack-scope (packs/numetrix/principals/) for genuinely cross-tenant identities; the resolution chain (§9) handles the cascade.
This matches how Identities themselves are scoped: a user’s Identity in tenant RMC might be analyst; in tenant Inspire it might be auditor. The principal_id stays the same; the role (capabilities) varies by scope.
12.8 Relationship to the four-level model
Section titled “12.8 Relationship to the four-level model”Principals sit below Identities in the model. An Identity is “what set of roles is this principal playing in this scope?” — meaningful only for kind: user principals (groups and roles don’t log in or carry capabilities themselves).
principal (who is this?) └── identity (what role-set are they playing here?) └── roles (which bundles of access?) └── passes (which capabilities?) └── capabilities (concrete decisions)For groups and roles, the Identity layer is not applicable. They’re labels for responsibility, not access.
12.9 Migration path
Section titled “12.9 Migration path”Adds a Phase 1.5 to §14 between Phase 1 (local switcher) and Phase 2 (API enforcement):
Phase 1.5 — Principals registry + reference migration
- Define principals YAML schema and validator.
- Bake principals into KLS via a new compiler (
principalcompile.py). - Create the per-tenant principals registry by inferring from existing free-text occurrences:
- All
assignee:strings,author.name,provider.name,curator.name,owneracross the AFS - A heuristic mapping table (case-insensitive collapse, slash-split for
an SME / a viewer, role-vs-person classification by keyword) - The author manually reviews the generated
afs/principals/*.yamland corrects classifications
- All
- Rewrite affected artifact YAMLs:
assignee: a viewer→owner: ronnieassignee: an SME / a viewer→owner: ronnie,consulted: [raffa](heuristic, author reviews)provider: { name: "an SME Hess" }→provider: { principal_id: raffa }
- Validators reject artifacts that name a principal_id not in the registry, with a clear “did you mean…” hint based on edit distance.
The migration tooling lives in scripts/principalmigrate.py. The first run is destructive (rewrites YAMLs) — author reviews via git diff before committing.
12.10 Implications for other concerns
Section titled “12.10 Implications for other concerns”- Watchers/followers (idea (5) from the assignee discussion): a separate
watchers: [principal_id, ...]field on actions. Notification system later fans out via principal lookup → email/Slack. - Reassignment history (idea (3)): an event log
_<tenant>.action_eventscapturing(action_id, kind: status_change | reassignment, from: principal_id, to: principal_id, by: principal_id, at: timestamp, reason?). The cell carries only the current state. - Default-assignee at note level (idea (9)): a
default_owner: principal_idat the note’s top, inherited by action cells without their own. - Acceptance flow (idea (10)): a new status value
accepted, plus anaccepted_atfield. Or a separateacceptance: { by: principal_id, at: timestamp }block. Either way, only meaningful once owners are stable principal_ids.
12.11 Open sub-questions
Section titled “12.11 Open sub-questions”-
Should an unresolved principal_id (referenced but not declared) be a hard validation error or a warning? Hard errors block builds; warnings let you reference an “intended” principal before declaring them. Proposed: warning during incremental builds, hard error in CI / publish. (Same pattern dbt uses for
ref()in some configurations.) -
How do we handle principals who leave the team? Soft-delete with
kind: user, status: archived, replaced_by: <new_id>. References resolve through the redirect for historical artifacts; new artifacts can’t pick the archived id. -
Should
display_nameaccept multilingual values forkind: user? “a viewer Hess” doesn’t translate. But “Hospital Administration” does. Proposed: strings foruser, locale dicts forroleandgroup. -
Where does
emaillive on a Clerk-authenticated user — in the AFS principal record or fetched from Clerk at render time? AFS storage means email survives Clerk being unreachable (P2P2P offline mode). Clerk fetch means it’s always current. Proposed: AFS as cache, Clerk as authority when reachable, refresh on identity grant change.
13. Default Vocabulary (jinflow pack)
Section titled “13. Default Vocabulary (jinflow pack)”These are the jinflow defaults. Each pack ships its own capabilities.yaml, passes.yaml, roles.yaml, and identities.yaml. hrcentral will define its own — the same structure, different content.
12.1 Identities
Section titled “12.1 Identities”identities: analyst: label: { en: "Analyst", de: "Analyst", fr: "Analyste" } icon: "chart" roles: [explorer, investigator]
cfo: label: { en: "Executive", de: "Geschäftsleitung", fr: "Direction" } icon: "briefcase" roles: [executive]
consultant: label: { en: "Consultant", de: "Berater", fr: "Consultant" } icon: "lightbulb" roles: [explorer, investigator, builder]
engineer: label: { en: "Engineer", de: "Ingenieur", fr: "Ingénieur" } icon: "wrench" roles: [explorer, investigator, builder, operator]
viewer: label: { en: "Viewer", de: "Betrachter", fr: "Observateur" } icon: "eye" roles: [reader]12.2 Roles
Section titled “12.2 Roles”roles: reader: passes: [overview, report]
explorer: passes: [explore, report]
investigator: passes: [investigate, discuss]
builder: passes: [build, calibrate, evolve]
operator: passes: [deploy, admin]
executive: passes: [overview, report]12.3 Passes
Section titled “12.3 Passes”passes: overview: capabilities: - view:overview - view:whats_new
explore: capabilities: - view:findings - view:dimensions - view:theses - view:signals - view:taxonomies - view:interpretations - view:smebits - view:bitbundles - view:salon - view:lab - view:studio - view:about - search:jumpbar - export:csv - export:row_limit
report: capabilities: - view:executive_summary - view:reports
investigate: capabilities: - notebook:read - notebook:write - notebook:delete - view:save - explainer:use - explain:ai
discuss: capabilities: - notebook:reply - notebook:action - notebook:toggle_action
build: capabilities: - signal:view_sql - signal:compile - signal:save - signal:playground - view:pipeline - view:calibration
calibrate: capabilities: - calibration:run - calibration:view
evolve: capabilities: - evolve:repl
deploy: capabilities: - make:run - afs:write - afs:git
admin: capabilities: - tenant:admin - tenant:init - user:manage - role:assign12.4 Sample capability definitions
Section titled “12.4 Sample capability definitions”capabilities: view:overview: type: ui_visibility target: page:overview
view:findings: type: ui_visibility target: page:findings
notebook:write: type: api_gate target: POST /api/notebook/cells
export:csv: type: action target: button:dimension_export
export:row_limit: type: value returns: integer default: 1000
afs:git: type: api_gate target: POST /api/afs/push requires_provider: github
view:findings:high_only: type: dynamic_filter rule: "severity IN ('high', 'medium')" target: query:findings14. Admin UI
Section titled “14. Admin UI”The admin experience lives under /{tenant}/admin/ (tenant-scoped) and /admin/ (system-scoped):
| Page | Scope | What it shows |
|---|---|---|
/{tenant}/admin/users | Tenant | All identities in this tenant. Name, identity, roles, granted_at, expires_at. Invite button. |
/{tenant}/admin/users/{user_id} | Tenant | One person. Current identity, effective capabilities (flattened tree), temporary grants. Edit identity, grant/revoke. |
/{tenant}/admin/roles | Tenant | Role tree visualization. Which identities include which roles, which roles include which passes, which passes grant which capabilities. Read-only for non-admins. |
/admin/tenants | System | All tenants across all packs. Create tenant, assign pack admins. |
/admin/packs | System | Pack catalogue. Assign pack maintainers. |
/admin/users | System | Platform-wide user directory. Cross-tenant identity view. |
15. Migration Path
Section titled “15. Migration Path”Phase 0 — Define the Model ✅ (this paper)
Section titled “Phase 0 — Define the Model ✅ (this paper)”- Capability list as YAML
- Pass → capability mapping
- Role → pass mapping
- Identity → role mapping
- Scope tree definition
resolveCapabilities()function spec- No auth, no persistence — just the data model
Phase 1 — Local Mode Identity Switcher ✅ (Phase 1d shipped 2026-05-14)
Section titled “Phase 1 — Local Mode Identity Switcher ✅ (Phase 1d shipped 2026-05-14)”capabilities.yaml,passes.yaml,roles.yaml,identities.yamlinsystem/- Identity compiler (
capabilitycompile.py) bakes into_{tenant}.{capability_map, pass_definition, role_definition, identity_definition}— auto-wired intojin makeas Phase 4c.0 GET /[tenant]/api/identity/treeendpoint hydrates JinDesk’s client-side stores- Identity switcher in the sidebar (
IdentitySwitcher.svelte) localStoragepersistence- Sidebar filtering by capability via
canStore - Local mode: all-access by default, switchable for preview
- No API enforcement yet (trust the client)
Phase 1.5 — Principals Registry + Reference Migration
Section titled “Phase 1.5 — Principals Registry + Reference Migration”See §12.9 for full detail. In short: introduce afs/principals/*.yaml,
the principalcompile.py baker, and a one-shot migration tool that
rewrites every free-text assignee/provider/curator/owner/author
field to a structured principal_id. Adds the RACI split for action
cells (owner/consulted/informed). Builds on Phase 1 (local switcher
exists) and is foundational for Phase 2 (API enforcement needs stable
ids to authorise against).
Phase 2 — API Enforcement
Section titled “Phase 2 — API Enforcement”- Server-side capability middleware (
hooks.server.ts) - API endpoints check
can()and return 403 if denied - Server-side
capabilities.tsswitches from the hardcoded TS to the KLS-baked tree (today it still reads the hardcoded copy; client is already KLS-baked) - Dynamic filter capabilities inject SQL
WHEREclauses server-side - UI and API both consult the same compiled capability set
Phase 3 — Clerk Integration (customer-admin category only)
Section titled “Phase 3 — Clerk Integration (customer-admin category only)”Important rephrasing (2026-05-14): Clerk is for the customer-admin category only (§8). It is not the day-to-day login system for tenant-end-users. That distinction governs Phase 3 vs Phase 4 vs Phase 7.
- Clerk SvelteKit SDK on the customer admin surface (the page where a customer’s billing contact / admin manages their org)
- Conditional binding per customer shape (§11.1): solo → User-only; B2B → User + Org; SAML → User + Org required; parent-with-subs → parent + children; federation → one Org with named sub-scopes
- Session validation →
principal_id active_organization_id→ resolves whichcustomernode in the scope tree the user is acting as- Clerk org membership → customer/application/pack entitlement (which products did this customer buy?)
- WelcomePrompt becomes “Sign in with Clerk” on the customer-admin surface (graffiti fallback for unsigned tenant-end-users in the meantime)
- GitHub OAuth linking for
requires_provider: githubcapabilities (developer-side; not tied to Clerk)
Phase 4 — Tenant-End-User Provisioning
Section titled “Phase 4 — Tenant-End-User Provisioning”The tenant-end-user category (§8) does not live in Clerk. Each tenant has its own user pool, managed either by the customer’s admin (via the customer-admin surface) or by jazzisnow on their behalf.
- Per-tenant user table (or per-tenant Clerk Org if the customer wants Clerk’s user management for their end-users — optional, not required)
- Tenant admin invites users, assigns identities
- Identity grants at the tenant level (and pack/application levels when the customer wants cross-tenant analysts)
- Customer-admin surface includes “manage end-users for tenant X” once they own the customer-admin grant
- No assumption that tenant-end-users have email addresses we can reach — local-mode users may be authenticated by site-local SSO
Phase 5 — Temporal Grants + Admin UI
Section titled “Phase 5 — Temporal Grants + Admin UI”role_grant_temporarytable- Grant/revoke flow in admin UI
- Expiry enforcement in evaluator
- Audit log: who granted what, when
Phase 6 — Dynamic Filters
Section titled “Phase 6 — Dynamic Filters”- Server-side query rewriting based on
dynamic_filtercapabilities - CFO sees only high/medium severity (query-level)
- PII filtering for non-clinical users
- Data minimization at the query level
Phase 7 — jazzisnow-Team Provisioning
Section titled “Phase 7 — jazzisnow-Team Provisioning”The jazzisnow-team category (§8) is the smallest population and the highest-trust. It does not go through Clerk. Likely binding:
- GitHub identity (single source of truth for the team)
- Membership in a specific GitHub org / team grants the
jazzisnowscope identity - Capability set is the most permissive (engine internals, debugging, cross-customer support)
- Visibility ≠ access to the data bytes — see Sense 16 (P2P2P) and Sense 28 (The Direct Line): a jazzisnow-team member can see that a customer exists without being able to read their KLS without explicit authorisation
This phase is last because it’s the smallest and we currently authenticate the team via GitHub already; the work is mostly making the binding explicit in the model.
16. Open Questions
Section titled “16. Open Questions”-
Anonymous access policy: resolved —JINFLOW_ALLOW_ANONYMOUS=1opens anonymous read-only via thereaderrole; unset by default. Shipped 2026-05-19 (1e4068ab). -
Cross-scope conflict semantics: when a person has identities in multiple scopes that cover the same tenant (e.g. system-scoped platform_admin AND tenant-scoped analyst), what’s the effective capability set? Proposal: union (both apply, most permissive value wins per capability). Alternative: the tenant-scoped identity’s values override the system-scoped ones.
-
Identity ownership of artifacts: resolved in §12 — principals registry + per-artifactprincipal_idreferences + Phase 1.5 migration. Open sub-questions about that design are listed in §12.11. -
Clerk pricing: need to verify Clerk’s organization feature supports the dual-pool model without hitting tier limits. Free tier allows 5 orgs — may need a paid plan for production multi-tenant.
-
Pack override of jinflow defaults: a pack may want to define its own identities/roles that differ from the jinflow-level defaults. How does the cascade resolve? Proposal: pack YAML wins over engine defaults, tenant YAML wins over pack. Same as the
display.*andcomponents.*config cascade. -
Dynamic filter composition: if two passes grant overlapping
dynamic_filtercapabilities on the same query, how do they compose? Conjunction (both filters apply, AND) or disjunction (either filter applies, OR)? Proposal: conjunction by default, explicitcompose: ormarker for opt-in. -
Temporary grant notification: should the admin be notified when a temporary grant is about to expire? Should the grantee? (e.g. “Your admin access to RMC expires in 2 hours.”)
Appendix A — Comparison with the March 2026 draft
Section titled “Appendix A — Comparison with the March 2026 draft”The earlier paper (identity_roles_passes.md, 2026-03-23, status: partial) established the four-level model, the capability types, the local-vs-cloud distinction, and the provider-specific requirements. All preserved here.
New in this paper:
- Section 0: Reusability as first design principle
- Section 4: The Scope Tree (
system → pack → tenant+ named lists) - Section 8: Dual Pool Architecture (tenant + jinflow pools)
- Section 6.3: Temporary grants
- Section 3.5: Non-boolean capabilities
- Section 10: KLS compilation for offline P2P2P
- Section 11: Coexistence story (GitHub, P2P2P, graffiti)
- Section 12: Artifact Ownership and Assignment (added 2026-04-26 — closes the artifact-ownership open question with a concrete principals registry + reference shape + RACI extension + migration phase)
- Section 6.5: Invitations (added 2026-05-24 —
jin invitecommand, AFS principal pre-declaration + optional Clerk invitation,clerk_user_idstamping at acceptance) - Section 7 rename + intro: “Local vs Cloud Mode” → “Surfaces and Modes”. Three surfaces explicit (JinDesk / Proxy / CLI), each resolves identity from a different input but shares the same downstream chain.
- Section 7.3: CLI mode (added 2026-05-24, revised 2026-05-25 twice — first to reconcile against existing auth.py, then again after discovering api.jinflow.io was a DNS-only placeholder. Final shape: local-first CLI, JinDesk-hosted bridge routes for opt-in Clerk auth, configurable
api_url. No separate jinflow-controlled middleman.) - Section 7.4: Offline grace period (added 2026-05-24, revised 2026-05-25 — 30-day grace in
~/.jinflow/session.json, escalating banner cadence. Storage stayed file-based for cross-environment portability; the keychain proposal was set aside.) - Clerk explicit (was “Clerk or similar”)
- Role naming and some capabilities updated for Sense 14 vocabulary (signals, not probes)
The earlier paper’s four-level model, non-hierarchical roles, capability types, and local/cloud modes are the bones of this paper. Nothing from March was discarded.
Numerical neighbors: ← Sense 24: The Steward — jinflow Operating On Itself · Sense 25: The Pass — what you can do here, today, in this scope →