Zum Inhalt springen

Sense 25 — Identity, Roles, Passes, Capabilities — Concept Paper

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

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.md in 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:

ConcernShared moduleProduct-specific
The four-level modelVocabulary, tree structure, evaluation algorithm—
Capability typesui_visibility, action, api_gate, dynamic_filter—
Scope treesystem → pack → tenant + named listsLevel names (numetrix, rmc, vai)
Clerk integrationSession validation, org mapping, profile syncWhich Clerk org maps to which scope
Capability evaluatorWalks role tree, flattens, resolves scope, handles non-booleanCall sites
AFS YAML schemacapabilities.yaml, passes.yaml, roles.yaml, identities.yaml, grants.yamlContent
KLS tablesCompiled schema for identities, role tree, grantsRows
Admin UIPages, grant/revoke flows, role tree visualizerBranding, 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:

  1. afs/identity/capabilities.yaml — what hrcentral’s features need
  2. afs/identity/passes.yaml — how capabilities group
  3. afs/identity/roles.yaml — role definitions
  4. afs/identity/identities.yaml — default personas
  5. 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.


TermDefinition
PersonA human being. Has one authentication account (typically Clerk). Can hold identities in multiple scopes.
IdentityThe single hat a person wears within a given scope. “the owner is an Analyst in RMC.” A person has exactly one identity per scope.
RoleA named bundle of passes that represents a job function. An identity maps to one or more roles. Roles are non-hierarchical — no inheritance.
PassA 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.
CapabilityThe 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.
ScopeWhere 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.
GrantThe act of assigning an identity (or a temporary extra role) to a person within a scope. Grants can be permanent or time-limited + revocable.
PoolA user population. Two pools coexist: the jinflow pool (platform-wide) and per-tenant pools (scoped to one tenant). A person can exist in both.
ProviderThe authentication source a person used (Clerk, GitHub, env fallback). Some capabilities require a specific provider.

Identity → Roles → Passes → Capabilities
1:n 1:n 1:n

Every relationship is many-to-many. This prevents premature coupling between organizational structure and technical features.

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.

LevelChanges when…OwnerFrequencyLives in
CapabilityA feature is added/removed from codeDeveloperPer releaseCode constants + capabilities.yaml
PassA permission group is redesignedPack authorPer pack versionpasses.yaml
RoleA job function is redefinedPack author / tenant adminPer org changeroles.yaml
IdentityThe user switches contextUser (local) / admin (cloud)Per session / per assignmentidentities.yaml (defaults) + grants (per person)

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?“

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.

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)

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.

Show or hide a page, section, or component.

view:findings:
type: ui_visibility
target: page:findings
view:salon:
type: ui_visibility
target: page:salon

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_cell

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/compile

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:dimensions

The 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.

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: 100

When 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.

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: google

A 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.


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: vai

The five levels and what each one means:

LevelWhat lives thereWho manages it
jazzisnowThe maintainer (us). One node.Internal — GitHub identity / equivalent
customerThe organisation that bought one or more applicationsCustomer-admin layer (Clerk for B2B; see §11)
applicationA product line: jinflow, hrcentral, …Per-customer entitlement
packA distribution of analytical content within an application: numetrix, interlogic, …Per-customer entitlement
tenantOne deployment instance: rmc, vai, …The customer’s own admin OR jazzisnow-on-their-behalf
  • 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. jazzisnow is 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”

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.

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:

CategoryBinds atWho fitsManaged where
jazzisnow-teamjazzisnowPlatform maintainers (the owner + future colleagues)Internal tools, GitHub
customer-admincustomer (and below)The people who pay for the product and administer their org’s accessClerk (B2B; conditional — see §11)
tenant-end-usertenant (and below)The day-to-day users of one deployment — the CFO at RMC, the HR officer at VAIPer-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).


At runtime, the system resolves the full chain:

person: mig ← from Clerk / provider
scope: tenant:rmc ← from URL / context
identity: 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 10000

Server-side enforcement for API gates:

if (!can('notebook:write')) {
return json({ error: 'Insufficient permissions' }, { status: 403 });
}

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)

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: permanent

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: true

Effective 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.

  • 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.

Onboarding a new person is two writes — one on each side of the trust boundary:

SideWhat is writtenWhen
AFSA principal YAML with email, identity, scopeAlways — this is the grant
ClerkAn 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:

Terminal window
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:

  1. 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).
  2. Resolves the target against the tenant’s existing principals: NEW (proceed), EXISTING_BOUND (refuse, point at jin 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 like mig_acme or a role like mig_external).
  3. Writes afs/principals/user_<slug>.yaml with email, identity, display_name. The user_ prefix on the filename matches the existing in-tree convention for kind: user principals; sibling files for roles and groups use role_ / group_.
  4. If --web (default): POSTs to JinDesk’s /api/invitations endpoint. The server-side handler verifies the CLI’s Bearer JWT (requireCliAuth), re-runs the capability gate against the baked principal_registry, then calls Clerk’s createInvitation with publicMetadata.jinflow = { tenant, identity, principal_id, invited_by_clerk_user_id, invited_by_principal_id }. Returns the clerk_invitation_id, which the CLI then stamps onto the AFS principal via PrincipalWriter.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:

FieldHoldsValidated
invited_bythe inviter’s principal_idresolved against the roster; must be kind: user
invited_by_clerk_user_idthe inviter’s Clerk user idshape 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):

  1. Invitee clicks the Clerk invitation magic link.
  2. Clerk creates the user and binds them to the org (where applicable — see §11.1).
  3. On first sign-in, the resolver looks up the AFS principal by clerk_invitation_id and stamps clerk_user_id onto the YAML. From this moment on, the binding is by clerk_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.


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.

SurfaceInputResolver
JinDesk (SSR)Clerk session cookieverifyToken → userId
Proxy (P2P2P)Forwarded Clerk session via tunnelsame verification
CLI~/.jinflow/session.json (Clerk JWT minted via JinDesk’s /cli-auth bridge) or JINFLOW_API_KEY env varsession.user_id (Clerk userId from the JWT payload)

jinflow desk on localhost — the user is the machine owner.

Two options:

  1. Implicit all-access (default): Every capability is granted. No identity selection needed. The engineer who just wants to work.

  2. 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);
}

Deployed JinDesk — multiple users, multiple tenants, API-enforced.

  1. User authenticates via Clerk (email, OAuth, whatever Clerk supports).
  2. Tenant admin has assigned an identity (or user self-selects from allowed identities).
  3. Capabilities are resolved server-side and passed to the client.
  4. API endpoints enforce capabilities via middleware.

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 default
api_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:

ContextWhat worksCapability check
Air-gapped / no internetEverything except --web flagsSkipped (you own the machine — local-mode god-rights)
Internet up, never signed inSame as air-gappedSkipped
Internet up, signed in via jin loginEverythingEnforced against AFS principal
Internet down, signed in (within grace)Read-only AFS ops; refuse new Clerk invitationsEnforced against cached resolution
jinflow.io cloud down but local JinDesk upEverything (point api_url at localhost)Enforced normally

Login modes (when jin login is invoked):

ModeWhenFlow
Browser-callbackLaptop with a graphical browserCLI 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 keyCI/CD, Docker, cloud workersJINFLOW_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 --device flag 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.

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 windowCadenceTone
Days 1–25 (most of the window)First command of each calendar dayQuiet
Days 26–29 (last 5 days)Once per sessionYellow
Day 30 (last 24h)Every command, escalated wordingRed
After expiryCommand 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.


Earlier drafts called this “Dual Pool Architecture” and named two pools (tenant and jinflow). 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.

CategoryBinds atWho fitsManaged where
jazzisnow-teamjazzisnowPlatform maintainers — the people who write the engineInternal tools / GitHub
customer-admincustomer (and below)The people who pay for the product and administer their org’s access — billing contact, customer success, customer adminClerk (conditional — see §11)
tenant-end-usertenant (and below)The day-to-day users of one deployment instance — the CFO at RMC, the HR officer at VAIPer-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.

  • jazzisnow-team identities sit in the jazzisnow node of the tree. There’s exactly one such node; membership is internal.
  • customer-admin identities sit at the customer level (or, in larger orgs, at customer → application for “admin of jinflow but not hrcentral”). They are the orgs that BUY jazzisnow products.
  • tenant-end-user identities sit at the tenant level 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 the customer node. 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 jazzisnow and sees everything (subject to the data sovereignty story from Sense 16 — visibility ≠ access to the bytes).

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.


When a request arrives at JinDesk with tenant context:

  1. Authentication: resolve the person’s identifier.
    • Clerk session → verified user_id, org memberships
    • GitHub OAuth → verified GitHub user (for git-scoped capabilities)
    • JINFLOW_USER env var → hardcoded identifier (CI / dev)
    • jinflow-me cookie → graffiti name (display only, treated as anonymous for auth)
    • Nothing → anonymous
  2. Scope resolution: what scope is this request in? (from URL: /numetrix.rmc/... → tenant:rmc)
  3. Identity lookup: for this person_id in this scope, what identity is assigned?
  4. Capability resolution: walk identity → roles → passes → capabilities, apply scope inheritance, resolve conflicts.
  5. 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).
  6. Temporal grants: merge in any active temporary grants. Drop expired ones.

ConcernOwner
Authentication (who are you?)Clerk
Profile (name, avatar, email)Clerk
Organization membershipClerk
Identity assignment (which persona?)jinflow (AFS → KLS)
Role / pass / capability definitionsjinflow (AFS → KLS)
Capability evaluationjinflow (JinDesk, from KLS)
Session managementClerk (JWT)
Invitation flowClerk (email) + jinflow (identity assignment)

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 identity

jinflow make compiles the AFS YAML into KLS tables in the metadata schema _{tenant}:

-- Flattened capability map per identity
CREATE 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 grants
CREATE 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 lookup
CREATE TABLE identity_roles (
identity VARCHAR,
role VARCHAR
);
-- Role → passes flattened
CREATE TABLE role_passes (
role VARCHAR,
pass VARCHAR
);
-- Pass → capabilities flattened
CREATE TABLE pass_capabilities (
pass VARCHAR,
capability VARCHAR
);

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. viewer or anonymous, depending on defaults.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.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 shapeClerk bindingWhy
Solo (self-register, free tier or paid-as-individual)Clerk User only, no OrgLightest path; one billing contact == the user themselves.
B2B (paid org, multiple seats)Clerk User + OrgOrg owns billing, seats, and the customer-admin self-service surface.
Enterprise SAML / SSOClerk 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 OrgsParent 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-scopesOne 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.

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_id on 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_id for Alice (prn_alice_…).
  • Two identity grants: analyst scoped to acme_health → jinflow → numetrix → rmc, and auditor scoped to bayer_pharma → jinflow → numetrix.
  • One active context at a time — Clerk’s session carries active_organization_id. When Alice is signed into acme_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.

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).

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.

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.

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.


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.

Many artifact YAMLs contain fields that name a person or organisation as free text:

ArtifactFieldToday’s shapeExamples
Action cell (notebook)assigneescalar stringa viewer, ronnie, an SME / a viewer, Hospital Administration, Department Head Endoscopy
Subject Matterprovider.name, provider.role, provider.datenested stringan SME Hess, Senior Analyst, 2026-04-12
Dossiercurator.name, curator.role, curator.datenested stringsame shape
Noteauthor.name, author.role, author.datenested stringsame shape
Bookmarkownerscalar stringthe graffiti name (e.g. mig, ronnie)
Recentsper-user file recents_<user>.yamlfilename slugthe graffiti slug
Reference cellsdiscussion[].authorscalar stringgraffiti

Two problems with the current shape:

  1. No referential identity. a viewer and ronnie are two distinct strings; the system can’t recognise them as the same person. Joining “all artifacts by a viewer” requires fuzzy matching.
  2. Mixed semantics. Hospital Administration isn’t a person — it’s an organisational unit. Department Head Endoscopy is a role, not a name. The single string-typed field carries three different concepts.

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. Carries display_name, role, optional email.
  • role — an organisational position. May or may not be filled by a single user (Department Head Endoscopy could 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:

afs/principals/user_ronnie.yaml
principal_id: ronnie
kind: user
display_name: a viewer Hess
role: Senior Analyst
email: r.hess@rmc.example # optional
clerk_user_id: user_2abc... # optional, set when Clerk is active
# afs/principals/role_department_head_endoscopy.yaml
principal_id: department_head_endoscopy
kind: role
display_name:
en: Department Head, Endoscopy
de: Abteilungsleiter Endoskopie
fr: Chef de département, Endoscopie
incumbent: ronnie # optional, current holder
# afs/principals/group_hospital_administration.yaml
principal_id: hospital_administration
kind: group
display_name:
en: Hospital Administration
de: Spitalleitung
fr: Direction hospitalière
members: [ronnie, raffa] # optional, transparent membership

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):

# bookmark
owner: ronnie
# subject matter
provider:
principal_id: raffa
date: 2026-04-12

List reference (multiple):

# action cell — multi-assignee version of (2) from the assignee discussion
assignees: [ronnie, raffa]
# subject matter with co-providers
providers:
- { principal_id: raffa, date: 2026-04-12 }
- { principal_id: ronnie, date: 2026-04-12 }

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 OPALE

Backwards compatibility: assignee: <id> is interpreted as owner: <id> during the migration. New cells should use the explicit fields.

JinDesk (and any consumer) renders a principal reference by looking up the principal in the registry and substituting:

  • display_name (locale-aware if multilingual)
  • role for 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.

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.yaml

A compiler bakes them into the KLS as _<tenant>.principals (peer of _<tenant>.bookmark_registry, _<tenant>.note_registry). JinDesk reads from there at render time.

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.

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.

Adds a Phase 1.5 to §14 between Phase 1 (local switcher) and Phase 2 (API enforcement):

Phase 1.5 — Principals registry + reference migration

  1. Define principals YAML schema and validator.
  2. Bake principals into KLS via a new compiler (principalcompile.py).
  3. Create the per-tenant principals registry by inferring from existing free-text occurrences:
    • All assignee: strings, author.name, provider.name, curator.name, owner across 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/*.yaml and corrects classifications
  4. Rewrite affected artifact YAMLs:
    • assignee: a viewer → owner: ronnie
    • assignee: an SME / a viewer → owner: ronnie, consulted: [raffa] (heuristic, author reviews)
    • provider: { name: "an SME Hess" } → provider: { principal_id: raffa }
  5. 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.

  • 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_events capturing (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_id at the note’s top, inherited by action cells without their own.
  • Acceptance flow (idea (10)): a new status value accepted, plus an accepted_at field. Or a separate acceptance: { by: principal_id, at: timestamp } block. Either way, only meaningful once owners are stable principal_ids.
  1. 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.)

  2. 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.

  3. Should display_name accept multilingual values for kind: user? “a viewer Hess” doesn’t translate. But “Hospital Administration” does. Proposed: strings for user, locale dicts for role and group.

  4. Where does email live 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.


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.

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]
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]
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:assign
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:findings

The admin experience lives under /{tenant}/admin/ (tenant-scoped) and /admin/ (system-scoped):

PageScopeWhat it shows
/{tenant}/admin/usersTenantAll identities in this tenant. Name, identity, roles, granted_at, expires_at. Invite button.
/{tenant}/admin/users/{user_id}TenantOne person. Current identity, effective capabilities (flattened tree), temporary grants. Edit identity, grant/revoke.
/{tenant}/admin/rolesTenantRole tree visualization. Which identities include which roles, which roles include which passes, which passes grant which capabilities. Read-only for non-admins.
/admin/tenantsSystemAll tenants across all packs. Create tenant, assign pack admins.
/admin/packsSystemPack catalogue. Assign pack maintainers.
/admin/usersSystemPlatform-wide user directory. Cross-tenant identity view.

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.yaml in system/
  • Identity compiler (capabilitycompile.py) bakes into _{tenant}.{capability_map, pass_definition, role_definition, identity_definition} — auto-wired into jin make as Phase 4c.0
  • GET /[tenant]/api/identity/tree endpoint hydrates JinDesk’s client-side stores
  • Identity switcher in the sidebar (IdentitySwitcher.svelte)
  • localStorage persistence
  • 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).

  • Server-side capability middleware (hooks.server.ts)
  • API endpoints check can() and return 403 if denied
  • Server-side capabilities.ts switches 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 WHERE clauses 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 which customer node 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: github capabilities (developer-side; not tied to Clerk)

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
  • role_grant_temporary table
  • Grant/revoke flow in admin UI
  • Expiry enforcement in evaluator
  • Audit log: who granted what, when
  • Server-side query rewriting based on dynamic_filter capabilities
  • CFO sees only high/medium severity (query-level)
  • PII filtering for non-clinical users
  • Data minimization at the query level

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 jazzisnow scope 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.


  1. Anonymous access policy: resolved — JINFLOW_ALLOW_ANONYMOUS=1 opens anonymous read-only via the reader role; unset by default. Shipped 2026-05-19 (1e4068ab).

  2. 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.

  3. Identity ownership of artifacts: resolved in §12 — principals registry + per-artifact principal_id references + Phase 1.5 migration. Open sub-questions about that design are listed in §12.11.

  4. 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.

  5. 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.* and components.* config cascade.

  6. Dynamic filter composition: if two passes grant overlapping dynamic_filter capabilities on the same query, how do they compose? Conjunction (both filters apply, AND) or disjunction (either filter applies, OR)? Proposal: conjunction by default, explicit compose: or marker for opt-in.

  7. 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 invite command, AFS principal pre-declaration + optional Clerk invitation, clerk_user_id stamping 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 →

jazzisnow jinflow is a jazzisnow product
v0.65.0 · built 2026-11-13 10:20 UTC