coulomb/identity-canon
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Seeded repo with initial and secondary research

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 13:12:48 +02:00
parent 9067e75693
commit 6dc1f8311c
14 changed files with 1418 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
AGENTS.md Normal file
View File

@@ -0,0 +1,226 @@
# identity-canon — Agent Instructions
## Repo Identity
**Purpose:** Orthogonal vocabulary and canonical model for identity-related concepts.
**Domain:** canon
**Repo slug:** identity-canon
**Topic ID:** `fe2aaa78-9c20-4feb-b3d2-4fe0529572a3`
**Workplan prefix:** `IDENTITY-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workstreams for this domain
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=fe2aaa78-9c20-4feb-b3d2-4fe0529572a3&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=identity-canon&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workstream_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=identity-canon&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
make fix-consistency REPO=identity-canon
```
This syncs task status from files into the hub DB.
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/IDENTITY-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-IDENTITY-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: IDENTITY-WP-NNNN
type: workplan
title: "..."
domain: canon
repo: identity-canon
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: IDENTITY-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
To create a new workplan:
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=identity-canon`
(or send a message to the hub agent via `POST /messages/`)
---
## Local Developer Workflow
This repository is currently documentation-only. There is no package manifest,
runtime application, build system, executable test suite, or formatter/linter
configuration checked in.
### Install
No install step is required for normal repository work.
### Build
No build step exists. Treat Markdown and workplan edits as source artifacts.
### Test / lint
There is no project test runner or markdown linter configured yet. Use these
checks before closing a change:
```bash
# Confirm the repository file inventory still looks intentional
rg --files
# Catch whitespace errors in tracked and staged diffs
git diff --check
```
When workplan files change, sync ADR-001 file state into State Hub:
```bash
curl -s -X POST "http://127.0.0.1:8000/repos/identity-canon/sync?fix=true" \
| python3 -m json.tool
```
If the HTTP sync endpoint is unavailable, run the consistency script from the
State Hub checkout:
```bash
cd ~/state-hub
.venv/bin/python scripts/consistency_check.py --repo identity-canon --fix
.venv/bin/python scripts/consistency_check.py --repo identity-canon
```
The generated instruction in older workplans says `make fix-consistency
REPO=identity-canon`; that is still valid when `uv` is installed and on PATH.
On this workstation, the `.venv/bin/python` fallback has been verified.
### Run
There is no local service to run from this repository.
### Documentation Review Checklist
- Keep `INTENT.md`, `SCOPE.md`, and `ResearchProposal.md` aligned on the
repository's research-only boundary.
- Keep source-backed observations in `research/` and canonical candidate terms
in `terminology/`, `canon/`, `model/`, and `scenarios/`.
- Mark draft concepts as candidate or draft until source notes contain real
references and extracted terminology.
- Record implementation ideas in `DownstreamRecommendations.md`, not as code in
this repository.

34
DownstreamRecommendations.md Normal file
View File

@@ -0,0 +1,34 @@
# Downstream Recommendations
Status: draft. This file captures implementation ideas derived from the canon
without moving implementation work into this repository.
## Recommended Consumption Pattern
Downstream repositories should consume identity-canon as a conceptual reference.
They should map their schemas, APIs, CLI commands, UI labels, and authorization
policies to canonical terms, but they should not depend on this repository as a
runtime package unless a later explicit package is extracted.
## Near-Term Recommendations
- When designing user-management schemas, separate Natural Person, Account,
Profile, Credential, and Principal fields.
- When designing tenant-aware systems, model Tenant as a scope and relate it to
Organization, Customer, Vendor, and Realm explicitly.
- When designing organization features, do not reuse Group or Role as a generic
replacement for Organization.
- When designing authorization adapters, treat Principal and relationship
tuples as projections from canonical actors, accounts, and relationships.
- When designing account-linking features, store Synonymity Assertions with
source, evidence, confidence, scope, lifecycle state, and privacy controls.
- When designing UI copy, use product-friendly labels but maintain internal
mappings to canonical concepts.
## Avoid For Now
- Do not implement identity provider integrations in this repository.
- Do not add database migrations or production APIs here.
- Do not treat this glossary as a finalized schema.
- Do not use `user` as a canonical table, API, or class name without a mapping
note that explains which canonical concept it represents.

35
OpenQuestions.md Normal file
View File

@@ -0,0 +1,35 @@
# Open Questions
Status: draft. These questions are intentionally non-secret and
implementation-neutral.
## Canon Questions
- Should Realm stay a Scope specialization, or does it need its own canonical
concept because of issuer and federation semantics?
- Should Customer Account become a canonical concept, or should customer
account records remain downstream commercial modeling?
- Should Team be modeled as a Group, Organization Unit, Community, or a
separate specialization?
- Should Legal Entity be a specialization of Organization or a relationship
between an Organization and a legal system?
- What fields are mandatory for every Relationship versus only for sensitive
relationships such as delegation, representation, and synonymity?
## Synonymity Questions
- Which confidence vocabulary should be used for weak matches?
- What is the minimum evidence model for strong account links?
- How should revocation or expiry of a synonymity assertion affect downstream
caches?
- How should privacy-limited links be represented so accidental broadening is
visible during review?
## Corpus Questions
- Which source notes should be backfilled first: SCIM and LDAP for record
semantics, OIDC and SAML for subject semantics, or OpenFGA and Cedar for
authorization projections?
- How much product-specific detail belongs in source notes versus downstream
recommendations?
- What citation format should the repo use once source notes are populated?

13
README.md
View File

@@ -1 +1,12 @@
Othogonal vocabulary and canonical model for identity related concepts.
# identity-canon
Orthogonal vocabulary and canonical model for identity-related concepts.
Start with:
- `INTENT.md` for purpose and project boundaries;
- `ResearchProposal.md` for the research method and expected deliverables;
- `research/CorpusIndex.md` for the source-note corpus;
- `canon/CanonicalGlossary.md` and `model/ConceptualModel.md` for the current
draft canon;
- `workplans/` for State Hub-tracked work.

54
SCOPE.md Normal file
View File

@@ -0,0 +1,54 @@
# SCOPE
## One-liner
Orthogonal vocabulary and canonical model for identity-related concepts.
## Core Idea
`identity-canon` is a research and terminology repository. It defines an
implementation-neutral vocabulary and conceptual model for identity, accounts,
actors, organizations, tenants, communities, families, agents, relationships,
and synonymity across IAM, directory, federation, social graph, authorization,
decentralized identity, and entity-resolution domains.
## In Scope
- Maintain research notes, source summaries, terminology inventories,
conflict maps, canonical glossary entries, conceptual model notes, scenario
tests, open questions, downstream recommendations, and State Hub workplans.
- Compare overlapping terms across standards, product documentation, social
graph models, authorization systems, and privacy/entity-resolution research.
- Keep canonical definitions separate from external product mappings.
- Record decisions, progress, and workplan status through State Hub.
- Verify changes with markdown review, `git diff --check`, and ADR-001
consistency checks.
## Out of Scope
- Implement identity providers, account-management services, provisioning
adapters, authorization engines, UI components, CLI commands, databases, or
production APIs.
- Own unrelated adjacent systems or operational identity lifecycle tooling.
- Make irreversible operational decisions without human approval.
- Treat draft canon artifacts as finalized schemas before source-note backfill
and scenario review.
## Current State
- Status: active research scaffold.
- The repository is currently documentation-only. It has no package manifest,
build system, runtime app, or executable test suite.
- `IDENTITY-WP-0002` seeded the first terminology, canon, model, scenario,
open-question, and downstream recommendation artifacts. The next research
pass should backfill individual source notes and revise the draft canon from
evidence.
## Getting Oriented
- Start with: INTENT.md
- Research proposal: ResearchProposal.md
- Corpus index: research/CorpusIndex.md
- Draft canon: canon/CanonicalGlossary.md and model/ConceptualModel.md
- Agent instructions: AGENTS.md
- Workplans: workplans/

251
canon/CanonicalGlossary.md Normal file
View File

@@ -0,0 +1,251 @@
# Canonical Glossary
Status: draft. These definitions are initial candidate canon terms. They are
intended to be challenged by source-note backfill and scenario testing.
## Actor
An entity that can participate in relationships, hold or control accounts, be
represented by another actor, or be projected into downstream systems.
Includes: natural persons, organizations, communities, families, service
accounts, bots, and AI agents.
Excludes: raw identifiers, credentials, claims, and profiles unless they are
being represented as records about an actor.
## Natural Person
A human being. A natural person may have many accounts, profiles, identifiers,
credentials, personas, and relationships.
Excludes: account records, social profiles, legal entities, and artificial
agents.
## Artificial Agent
A non-human actor that performs actions under software, automation, or delegated
control.
Includes: bots, service agents, workloads, and AI agents.
## Collective Actor
An actor composed of or associated with multiple actors.
Includes: organizations, communities, families, households, groups, and teams
when they can participate in relationships or be represented.
## Account
An operational record in a scope that enables access, login, administration, or
system participation.
Includes: human login accounts and service accounts.
Excludes: natural persons, billing accounts, profiles, credentials, and
authorization principals unless a source uses account in that narrower context.
## Service Account
An account intended for software, workload, bot, or automation access rather
than ordinary human interactive use.
## Identity Record
A record that describes, binds, or organizes information about an actor within
a source or scope.
Identity Record is deliberately narrower than bare `identity`; it is a record,
not selfhood, not proof material, and not necessarily a login account.
## Identifier
A value or reference used to distinguish or refer to something within a scope.
Examples: username, email address, LDAP DN, OIDC subject, SAML NameID, DID,
employee number, external source ID.
## Scoped Identifier
An identifier whose meaning is intentionally limited to a relying party,
sector, tenant, realm, application, namespace, or other scope.
## Credential
Evidence or secret material used to prove control, entitlement, or a claim.
Examples: password, passkey, certificate, hardware token, verifiable
credential, recovery code, signed assertion.
## Claim
A statement made by an issuer or source about an actor, account, identifier,
relationship, or attribute.
## Authenticated Subject
The protocol-level representation of an entity after an issuer or identity
provider identifies it for a relying party.
Examples: OIDC subject, SAML subject.
## Authorization Principal
The entity considered by an authorization system when evaluating whether an
action is allowed.
## Profile
A presentation or attribute surface for an actor or account in a scope.
Examples: public social profile, local application profile, directory profile.
## Persona
A deliberate contextual presentation of an actor, often used to separate roles,
audiences, privacy boundaries, or pseudonymous participation.
## Scope
A boundary within which identifiers, meanings, relationships, accounts,
policies, or lifecycle states are valid.
Examples: tenant, realm, relying party, namespace, application, community,
authorization domain.
## Tenant
An administrative or isolation scope for a system, service, platform, or
application.
A tenant may be associated with an organization, customer, vendor, or community,
but it is not automatically identical to any of them.
## Realm
An issuer, security, or administrative namespace used by an identity system.
Candidate status: treat Realm as a Scope specialization unless source analysis
shows it needs a separate canonical role.
## Organization
A collective actor with operational, social, administrative, or structural
continuity.
Excludes: tenant, customer, and legal entity unless those meanings are modeled
as separate relationships or specializations.
## Legal Entity
An organization or other actor recognized by a legal system.
## Customer
An actor in a commercial or service-consumption relationship.
Customer is a relationship role, not automatically a tenant or organization.
## Vendor
An actor in a service-provider relationship.
Vendor is a relationship role, not automatically a tenant or organization.
## Community
A collective actor formed around participation, affiliation, identity, interest,
moderation, or social interaction.
## Family Or Household
A collective actor or relationship network involving family, guardian,
dependent, household, or care relationships.
This concept is privacy-sensitive and may have legal implications outside the
canon's scope.
## Group
A named collection of actors or accounts in a scope.
Group membership may have authorization implications, but a group is not the
same concept as a role, community, team, or organization.
## Role
A named capability bundle, responsibility, or relationship label within a
scope.
Roles may be assigned through memberships or relationships, but role is not
identical to group.
## Relationship
A typed, scoped assertion connecting one actor, account, identifier, group, or
other model element to another.
Recommended fields: source, target, type, scope, evidence, issuer or source,
confidence when relevant, lifecycle state, and authorization implications.
## Membership Relationship
A relationship indicating that an actor or account belongs to, participates in,
or is accepted by a collective actor or scope.
## Affiliation Relationship
A relationship indicating association without necessarily implying membership,
control, employment, or authorization.
## Following Relationship
A directed social relationship where one actor subscribes to, follows, or
observes another actor or profile.
## Representation Relationship
A relationship where one actor acts or speaks on behalf of another actor within
a scope.
## Delegation Relationship
A relationship where one actor grants bounded authority to another actor.
## Administration Relationship
A relationship where one actor has management authority over accounts,
relationships, policies, or configuration in a scope.
## Trust Relationship
A relationship where one actor, issuer, verifier, system, or scope relies on
another for claims, identifiers, credentials, or decisions.
## Synonymity Assertion
A scoped, evidenced assertion that two or more identifiers, records, accounts,
profiles, or actors refer to the same target for a stated purpose.
Synonymity assertions may be weak, strong, verified, inferred, revoked,
privacy-limited, or source-specific.
## Evidence Source
A source, document, event, issuer, import, observation, or verification process
supporting a claim, relationship, or synonymity assertion.
## Lifecycle State
The current state of a record, account, relationship, credential, claim, or
assertion.
Examples: proposed, active, suspended, revoked, expired, archived, deleted,
superseded.
## Non-Canonical Convenience Term: User
`User` may be used in prose when quoting or mapping external systems, but it
should not be a canonical root concept. Resolve it to a specific canonical
concept before using it in model definitions.

75
canon/DesignPrinciples.md Normal file
View File

@@ -0,0 +1,75 @@
# Design Principles
Status: draft. These principles make the proposal's modeling stance explicit.
They are constraints for canonical vocabulary and conceptual model work, not
implementation requirements for downstream systems.
## P1. Use Actor As The Participation Root
Do not start the model with `user`. An Actor is anything that can participate
in relationships, hold accounts, be represented, or be evaluated by downstream
systems. Natural persons, organizations, communities, families, and artificial
agents can all be actors.
## P2. Keep Person, Account, Identity, Profile, And Principal Separate
A natural person is not an account. An account is not a profile. A profile is
not a credential. A principal is an authorization projection. A subject is an
issuer-bound protocol view. These distinctions prevent the most common identity
model collapse.
## P3. Treat Scope As First Class
Identifiers, accounts, relationships, roles, policies, and meanings are only
stable within a scope. A scope may be a tenant, realm, relying party, sector,
community, application, namespace, or authorization domain.
## P4. Model Collective Actors Without Collapsing Them
Organizations, legal entities, customers, vendors, communities, families,
households, groups, and teams are not interchangeable. They may relate to each
other, but each should keep its social, legal, operational, or commercial
meaning visible.
## P5. Model Relationships Explicitly
Membership, affiliation, following, ownership, representation, delegation,
administration, employment, guardianship, and trust are separate relationship
types. Do not hide them inside groups, roles, or ad hoc attributes.
## P6. Keep Authorization Projections Separate
Authorization engines need principals, resources, actions, roles, policies, and
relationship tuples. These are projections from the conceptual identity model,
not the whole identity model.
## P7. Treat Synonymity As An Assertion
Weak matches, verified links, same-as claims, and merges are different. The
canon should represent synonymity as a scoped, evidenced, revocable assertion
with confidence and method, never as an automatic destructive merge.
## P8. Preserve Source And Evidence
Source systems, issuers, import jobs, operators, documents, and verification
events matter. Claims and relationships should be traceable to evidence or
source references when the model depends on them.
## P9. Prefer Orthogonal Concepts Over Product Terms
External systems are mapping targets, not the source of canonical truth. If a
product calls something a user, organization, group, project, tenant, or realm,
the canon should identify the underlying concept before adopting the label.
## P10. Test Concepts Against Scenarios
Every canonical concept should survive concrete scenarios: enterprise
directories, vendor/customer tenancy, families, communities, social graphs,
service accounts, delegated agents, weak matches, strong links, and
pseudonymous profiles.
## P11. Keep Implementation Recommendations Downstream
The repository may recommend downstream schemas, APIs, UI flows, or adapters,
but it should not implement them directly. Implementation ideas belong in
`DownstreamRecommendations.md` or a dedicated downstream workplan.

144
model/ConceptualModel.md Normal file
View File

@@ -0,0 +1,144 @@
# Conceptual Model
Status: draft. This is the first narrative model extracted from the research
proposal. It is intentionally implementation-neutral and should be refined by
source-note backfill and scenario testing.
## Core Claim
Identity-canon should model identity-related systems as scoped actors,
records, identifiers, claims, credentials, relationships, and projections. The
model should keep social, legal, operational, authentication, and authorization
meanings visible instead of collapsing them into `user`, `group`, or `tenant`.
## Entity Families
### Actor Layer
- Actor: participation root.
- Natural Person: human actor.
- Artificial Agent: non-human automated actor.
- Collective Actor: actor composed of, representing, or organizing multiple
actors.
- Organization, Community, Family or Household, Group, and Team: candidate
collective actor specializations.
### Record Layer
- Account: operational access record in a scope.
- Service Account: software-oriented account.
- Identity Record: source-specific record about an actor or account.
- Profile: presentation or attribute surface.
- Persona: contextual presentation of an actor.
### Reference Layer
- Identifier: value or reference within a scope.
- Scoped Identifier: identifier designed for limited correlation.
- Credential: proof or control material.
- Claim: statement made by a source or issuer.
- Evidence Source: support for claims, relationships, and synonymity.
### Scope Layer
- Scope: boundary for meaning.
- Tenant: administrative or isolation scope.
- Realm: issuer or security namespace.
- Namespace: naming scope.
- Authorization Domain: scope in which principals, resources, actions, and
policies are evaluated.
### Projection Layer
- Authenticated Subject: protocol projection of an identified entity.
- Authorization Principal: decision-engine projection of an actor, account, or
subject.
- Authorization Resource, Action, Policy, and Relationship Tuple: downstream
authorization projections, not canonical identity roots.
## Relationship Classes
Relationships should be explicit model elements when they affect meaning,
authorization, privacy, or lifecycle.
Core relationship classes:
- Membership: actor participates in a collective actor or scope.
- Affiliation: actor is associated with another actor or collective.
- Following: actor subscribes to or follows another actor or profile.
- Ownership: actor controls or is responsible for a record, resource, tenant,
or organization.
- Representation: actor acts on behalf of another actor.
- Delegation: actor grants bounded authority to another actor.
- Administration: actor manages records, relationships, or configuration in a
scope.
- Trust: actor, issuer, verifier, or system relies on another for a purpose.
- Synonymity: records or identifiers are asserted to refer to the same target
under stated evidence and scope.
Recommended relationship fields:
- relationship type;
- source and target;
- scope;
- source system or issuer;
- evidence reference;
- confidence or assurance when relevant;
- lifecycle state;
- privacy constraints;
- authorization implication, if any.
## Identity Linking Model
Identity linking should not merge records by default. It should create
Synonymity Assertions.
Weak synonymity examples:
- imported records match on name and email hash;
- two profiles share a phone number but lack explicit verification;
- an entity-resolution job proposes a duplicate.
Strong synonymity examples:
- account holder completes explicit account-linking flow;
- issuer signs a claim binding an identifier to a subject;
- operator verifies a link against authoritative evidence.
Privacy-limited synonymity examples:
- pairwise subject identifier bound only for one relying party;
- pseudonymous community profile linked only inside a restricted scope;
- legal identity reference stored separately from a public persona.
## Invariants
- A Natural Person can control zero, one, or many Accounts.
- An Account belongs to exactly one primary operational Scope, but can have
relationships to other scopes.
- A Profile presents an Actor, Account, or Persona within a Scope.
- A Principal is a projection for authorization and should not replace Actor or
Account in the canon.
- A Tenant can be related to an Organization or Customer, but should not be
treated as identical to either.
- A Group can carry Membership relationships, but Role assignment and
relationship semantics must stay explicit.
- A Synonymity Assertion can link records without destroying source identity or
evidence.
- Lifecycle state applies to relationships and assertions, not only accounts.
## External Mapping Rule
When mapping an external system, first identify which canonical layer the
source term belongs to:
1. Actor layer: who or what participates?
2. Record layer: what operational record exists?
3. Reference layer: what values, claims, or credentials refer or prove?
4. Scope layer: where is the meaning valid?
5. Relationship layer: what typed connection is asserted?
6. Projection layer: what downstream protocol or authorization view is needed?
Only after that mapping should source-specific labels such as `user`, `group`,
`organization`, `realm`, `tenant`, `subject`, or `principal` be adopted in a
downstream artifact.

17
research/CorpusIndex.md
View File

@@ -64,3 +64,20 @@ Each source note should capture:
- usefulness for identity-canon;
- candidate canonical mappings;
- open questions.
## Derived Canon Artifacts
The first proposal follow-up pass created these draft artifacts from the
proposal and seeded corpus topics:
- `terminology/TerminologyInventory.md`
- `terminology/TerminologyConflictMap.md`
- `canon/DesignPrinciples.md`
- `canon/CanonicalGlossary.md`
- `model/ConceptualModel.md`
- `scenarios/ScenarioTests.md`
- `OpenQuestions.md`
- `DownstreamRecommendations.md`
These files are candidate canon surfaces. Treat them as hypotheses to test
while backfilling the individual source notes.

189
scenarios/ScenarioTests.md Normal file
View File

@@ -0,0 +1,189 @@
# Scenario Tests
Status: draft. These are narrative tests for the conceptual model. They are
not executable tests yet; they define expected representation checks for future
model revisions.
## Test Format
- Scenario: concrete identity situation.
- Expected representation: the canonical concepts that should be used.
- Checks: conditions the model must satisfy without collapsing terms.
## S01. Single Person With One Local Account
Expected representation: one Natural Person, one Account in an application
Scope, one local Identifier, one Profile, and one Membership or access
relationship if the account belongs to a group.
Checks:
- The person is not identical to the account.
- The profile is not the credential.
- Authorization can project the account or subject into a Principal.
## S02. Person With Multiple Accounts Across Scopes
Expected representation: one Natural Person, multiple Accounts, one Account
per Scope, and optional Synonymity Assertions linking account records.
Checks:
- Each account keeps its source and lifecycle state.
- Linking accounts does not merge them destructively.
- Different scopes can use different identifiers.
## S03. Enterprise With Sub-Organizations
Expected representation: Organization actors linked by structural
relationships, plus Accounts and Membership relationships scoped to relevant
systems.
Checks:
- Sub-organization is not automatically a tenant.
- Legal entity status is modeled separately.
- Membership and administration relationships are explicit.
## S04. Vendor Tenant Serving Customer Tenants
Expected representation: Vendor and Customer relationship roles between
Organization actors; Tenant scopes for platform isolation; optional
Administration relationships for delegated support.
Checks:
- Customer is not collapsed into Tenant.
- Vendor is not collapsed into Realm.
- Cross-tenant administration is scoped and evidenced.
## S05. Customer Organization With Delegated Administrators
Expected representation: Organization actor, Tenant scope, administrator
Accounts, Delegation and Administration relationships.
Checks:
- Admin rights are relationships, not just group names.
- Delegation has source, target, scope, and lifecycle state.
- Authorization projection can consume the relationship separately.
## S06. Family With Guardian And Dependent Accounts
Expected representation: Family or Household collective actor, Natural Person
actors, guardian/dependent relationships, child Accounts, and privacy
constraints.
Checks:
- Guardian relationship is not generic membership.
- Household and legal family can differ.
- Privacy-sensitive links can be scoped.
## S07. Spontaneous Interest Group
Expected representation: Community or Group collective actor, Membership
relationships, optional moderator Administration relationships.
Checks:
- Informal group does not need legal entity or tenant semantics.
- Moderation is not the same as membership.
- Group identity can exist without strong real-world identity proofing.
## S08. Community With Members, Moderators, And Followers
Expected representation: Community actor; Membership relationships for
members; Administration or moderation relationships for moderators; Following
relationships for followers.
Checks:
- Follower is not a member unless the source says so.
- Moderator authority is explicit and scoped.
- Public profile can differ from account.
## S09. Social Media Follower Graph
Expected representation: Actor or Persona profiles connected by Following
relationships in a social Scope.
Checks:
- Following is directed.
- Following does not imply affiliation, membership, trust, or authorization.
- Pseudonymous profiles can remain scoped.
## S10. Bot Or Service Account Acting For An Organization
Expected representation: Artificial Agent actor, Service Account, Organization
actor, Representation or Delegation relationship, and Credential records.
Checks:
- Bot is not a natural person.
- Service account has an owner or responsible actor.
- Delegated authority has bounded scope and lifecycle.
## S11. AI Agent Acting Under Delegated Authority
Expected representation: Artificial Agent actor, Account or Service Account,
Delegation relationship from a Natural Person or Organization, and audit or
evidence references for actions.
Checks:
- Delegation identifies who granted authority.
- Agent actions can be attributed without treating the agent as the person.
- Authorization projection can include delegated context.
## S12. Weak Identity Match From Imported Data
Expected representation: source Identity Records linked by a weak Synonymity
Assertion with method, evidence, confidence, scope, and lifecycle state.
Checks:
- Weak match does not merge accounts.
- Consumers can reject or quarantine weak links.
- Evidence source remains visible.
## S13. Strong Account Link After Explicit Verification
Expected representation: Accounts linked by a strong Synonymity Assertion or
Account Link relationship, with verification evidence and revocation path.
Checks:
- Strong link is still scoped.
- Verification method is recorded.
- Revocation or unlinking is possible.
## S14. Pseudonymous Profile Linked Only Within A Restricted Scope
Expected representation: Persona or Profile with Scoped Identifier and
privacy-limited Synonymity Assertion visible only inside an allowed Scope.
Checks:
- Public consumers cannot infer the hidden link.
- The pseudonym can have relationships independent of legal identity.
- Scope boundaries are explicit.
## S15. Organization Represented By A Legal Entity And Operational Tenants
Expected representation: Organization actor, Legal Entity specialization or
relationship, one or more Tenant scopes, and Representation relationships for
authorized persons or agents.
Checks:
- Legal entity and tenant are separate model elements.
- Multiple tenants can relate to one organization.
- Representation authority is scoped and evidenced.
## Current Result
The initial model can represent all fifteen scenarios at a narrative level.
The next research pass should backfill concrete mappings from source notes and
then revise the glossary where scenario checks reveal ambiguity.

152
terminology/TerminologyConflictMap.md Normal file
View File

@@ -0,0 +1,152 @@
# Terminology Conflict Map
Status: draft. This map records high-risk terms whose meanings differ across
source families. It should be revised after each source-note backfill.
## Conflict: User
Problem: `user` can mean a person, account, login credential holder,
application profile, authorization subject, or product-facing actor.
Canonical stance: do not use `user` as a root concept. Require the writer to
choose among Natural Person, Account, Actor, Authenticated Subject, Principal,
Profile, or Persona.
Current mapping rule:
- If the system stores login state, map to Account.
- If the system renders a public or local display surface, map to Profile.
- If the system evaluates access, map to Principal or Authenticated Subject.
- If the text means a human being, map to Natural Person.
## Conflict: Identity
Problem: `identity` can mean selfhood, a directory record, an issuer-bound
subject, a set of claims, a DID, a credential, a profile, or an account.
Canonical stance: avoid bare `identity`. Prefer Identity Record, Identifier,
Claim, Credential, Profile, Persona, or Synonymity Assertion.
Current mapping rule:
- A persistent record about an actor maps to Identity Record.
- A value used to refer maps to Identifier.
- A statement made by an issuer maps to Claim.
- Proof material maps to Credential.
## Conflict: Account
Problem: account can mean login account, customer billing account, social
account, service account, or account profile.
Canonical stance: Account is an operational access record in a scope. Billing
or customer accounts need explicit relationship and commercial-role modeling.
Current mapping rule:
- Login-capable operational record maps to Account.
- Non-human login-capable record maps to Service Account.
- Commercial customer record maps to Customer relationship or Customer Account
only if a later source analysis justifies the separate concept.
## Conflict: Subject, Principal, Actor
Problem: protocols, authorization engines, and application models use these
terms differently. OIDC and SAML focus on subject identifiers; Cedar and IAM
often decide over principals; social and conceptual models talk about actors.
Canonical stance:
- Actor is the conceptual participant.
- Authenticated Subject is the issuer/protocol view after identification.
- Authorization Principal is the decision-engine projection.
The same natural person or account may appear as all three in different
contexts, but the concepts should not be merged.
## Conflict: Tenant, Realm, Organization, Customer
Problem: multi-tenant products often use tenant, organization, realm, customer,
workspace, project, and account as partial synonyms. Some are isolation
boundaries, some are legal or commercial actors, and some are administrative
containers.
Canonical stance:
- Tenant is an administrative or isolation scope.
- Realm is an issuer or administrative namespace unless source analysis proves
stronger tenant semantics.
- Organization is a collective actor or organizational structure.
- Customer is a commercial relationship role.
Model the relationships among these concepts instead of choosing one term to
stand for all of them.
## Conflict: Group, Role, Team, Community
Problem: IAM systems often use groups for role assignment, collaboration tools
use teams for work coordination, and social platforms use groups or communities
for participation.
Canonical stance:
- Group is a named collection or collective actor with membership.
- Role is a capability bundle or relationship label.
- Team is a domain-specific group or organization unit.
- Community is a participation-oriented collective actor.
Avoid modeling all four as generic `group`.
## Conflict: Member, Follower, Affiliate
Problem: membership, following, affiliation, employment, subscription, and
moderation relationships are often hidden behind `member`.
Canonical stance: relationship type matters. Represent each relationship with
source, target, scope, role or relation kind, evidence, lifecycle state, and
authorization implications if any.
## Conflict: Profile And Persona
Problem: profiles are sometimes account records, public pages, social
identities, or collections of claims. Personas are sometimes aliases,
pseudonyms, or UX-specific presentations.
Canonical stance:
- Profile is a presentation or attribute surface in a scope.
- Persona is a deliberate contextual presentation of an actor, often separate
from other presentations for privacy or role clarity.
## Conflict: Identifier, Credential, Claim
Problem: identifiers, credentials, and claims are often conflated because all
can appear in tokens, profiles, or identity documents.
Canonical stance:
- Identifier refers.
- Credential proves or supports.
- Claim states.
A token may contain all three, but the conceptual model should keep them apart.
## Conflict: Synonymity, Linking, Matching, Merge
Problem: identity systems often collapse weak matches, verified account links,
same-as claims, and destructive record merges into a single identity-linking
feature.
Canonical stance: synonymity is an assertion. It has source, target, scope,
confidence, evidence, method, lifecycle state, and privacy constraints. It does
not require destructive merging.
## Review Queue
- Validate each conflict against populated source notes.
- Add concrete examples and counterexamples once source summaries include
citations.
- Decide whether Customer Account deserves a canonical concept or stays a
downstream commercial model.
- Decide whether Realm should remain a Scope specialization or become a
separate canonical concept.

72
terminology/TerminologyInventory.md Normal file
View File

@@ -0,0 +1,72 @@
# Terminology Inventory
Status: draft. This inventory is seeded from `ResearchProposal.md`,
`INTENT.md`, and the current research corpus index. Mappings are candidate
canonical mappings until the individual source notes have been backfilled with
real source summaries.
## Use
Use this file to collect source terms and their current candidate canonical
home. Use `terminology/TerminologyConflictMap.md` when a term is overloaded or
has incompatible meanings across source families.
## Inventory
| Term | Candidate canonical concept | Source families | Notes |
| --- | --- | --- | --- |
| actor | Actor | authorization, social graphs, proposal | Participation root for anything that can act or be acted for. |
| natural person | Natural Person | identity assurance, social graphs | Human being; never identical to an account or profile. |
| user | Convenience label only | SCIM, products, applications | Overloaded; map to Account, Actor, Subject, or Profile by context. |
| account | Account | SCIM, LDAP, IAM products | Operational record that enables access in a scope. |
| identity | Identity Record or Identity Claim | IAM, federation, DID, VC | Avoid as root noun; clarify whether record, claim, identifier, or social identity is meant. |
| identifier | Identifier | OIDC, SAML, DID, directories | A value or reference used to distinguish something in a scope. |
| credential | Credential | authentication, VC, DID | Evidence or secret material used to prove control, entitlement, or claim. |
| subject | Authenticated Subject | OIDC, SAML, authorization | Security-protocol view of an actor/account after identification by an issuer. |
| principal | Authorization Principal | Cedar, IAM, authorization | Entity considered by an authorization decision. |
| profile | Profile | social graphs, IAM, applications | Presentation or attribute surface for an actor/account in a scope. |
| persona | Persona | social/community systems | Deliberate contextual presentation of an actor, often with limited linkage. |
| agent | Artificial Agent | IAM, agentic systems | Non-human actor, including bot, service account, or AI agent. |
| bot | Artificial Agent | applications, social graphs | Automated actor; may act through an account and under delegation. |
| service account | Service Account | IAM, operations | Account intended for software or workload access rather than human login. |
| organization | Organization | SCIM, LDAP, Keycloak, ZITADEL | Collective actor or structure; do not collapse with tenant, legal entity, or customer. |
| legal entity | Legal Entity | business, compliance | Organization recognized under a legal system. |
| customer | Customer | SaaS, vendor/customer models | Commercial relationship role, not automatically a tenant or organization. |
| vendor | Vendor | SaaS, multi-vendor systems | Provider role in a commercial or operational relationship. |
| tenant | Tenant | SaaS, IAM products | Administrative or isolation scope; may be owned by or assigned to an organization. |
| realm | Realm | Keycloak, federation | Issuer or administrative namespace; candidate mapping is Scope or Tenant depending on use. |
| scope | Scope | OIDC, authorization, proposal | Boundary in which identifiers, policies, relationships, or meanings hold. |
| namespace | Scope | directories, DID, products | Naming boundary; treat as a kind of scope unless stronger semantics exist. |
| community | Community | social graphs, platforms | Collective actor defined by social participation rather than legal or customer status. |
| family | Family or Household | family account models | Relationship network with guardian/dependent semantics and privacy sensitivity. |
| household | Family or Household | family account models | Co-residence or account-management unit; may not equal legal family. |
| group | Group | LDAP, SCIM, social graphs, authz | Container or collective label; must not absorb relationship semantics. |
| team | Group or Organization Unit | SaaS, collaboration systems | Usually a collaboration group; sometimes an org sub-unit. |
| role | Role | RBAC, IAM products | Named capability set or relationship label; keep separate from group membership. |
| member | Membership Relationship | SCIM, groups, communities | Relationship from actor to collective actor or scope. |
| affiliation | Affiliation Relationship | enterprise, social | Looser association than membership; may be external or evidenced. |
| follower | Following Relationship | ActivityPub, social graphs | Directed social relationship, not a membership or authorization grant by default. |
| owner | Ownership Relationship | SaaS, authz | Control or responsibility relationship; needs scope and target. |
| administrator | Administration Relationship | IAM, SaaS | Delegated management authority in a scope. |
| delegation | Delegation Relationship | IAM, authz, agentic systems | Actor grants another actor authority to act in a bounded way. |
| representation | Representation Relationship | legal, org, agent systems | Actor acts on behalf of another actor or organization. |
| trust | Trust Relationship | federation, DID, authz | Reliance relationship; must record source, scope, and purpose. |
| claim | Claim | VC, OIDC, DID | Statement made by an issuer about a subject, actor, or relationship. |
| evidence | Evidence Source | entity resolution, assurance | Material supporting a claim or synonymity assertion. |
| assurance | Assurance Level | NIST, federation | Confidence about identity proofing, authentication, or binding. |
| identifier binding | Identifier Binding | federation, entity resolution | Assertion that an identifier refers to a target within a scope. |
| synonymity | Synonymity Assertion | entity resolution, proposal | Assertion that two records or identifiers refer to the same target under stated conditions. |
| weak match | Weak Synonymity Assertion | entity resolution | Probabilistic or low-confidence link; never a destructive merge. |
| strong link | Strong Synonymity Assertion | account linking, identity proofing | Verified or authoritative link; still scoped and evidenced. |
| pseudonym | Pseudonymous Identifier | privacy, OIDC, DID | Identifier designed to limit cross-scope correlation. |
| pairwise subject | Scoped Identifier | OIDC | Subject identifier scoped to relying party or sector; map to Identifier plus Scope. |
| relationship tuple | Relationship Assertion | Zanzibar, OpenFGA | Authorization-oriented representation of actor-object-relation facts. |
| policy | Authorization Projection | Cedar, IAM, authz | Rule artifact; not part of the canonical identity object model except as mapping. |
| lifecycle state | Lifecycle State | SCIM, IAM, directories | Activation, suspension, deletion, revocation, or archival state of a record or relationship. |
## Backfill Needs
- Add source-specific definitions from each file in `research/*/*.md`.
- Split terms that hide multiple meanings after source review.
- Add citation pointers once source notes contain stable references.
- Move mature canonical definitions to `canon/CanonicalGlossary.md`.

71
workplans/IDENTITY-WP-0001-statehub-bootstrap.md Normal file
View File

@@ -0,0 +1,71 @@
---
id: IDENTITY-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: canon
repo: identity-canon
status: finished
owner: codex
topic_slug: canon
created: "2026-06-05"
updated: "2026-06-05"
state_hub_workstream_id: "b7346171-35f6-45bf-b82f-c3703b79b426"
---
# Bootstrap State Hub integration
Orthogonal vocabulary and canonical model for identity-related concepts.
## Review Generated Integration Files
```task
id: IDENTITY-WP-0001-T01
status: done
priority: high
state_hub_task_id: "3d373474-4258-40f0-9d44-7e26f7ccfc69"
```
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
Completed by reviewing the generated integration files, preserving
`.custodian-brief.md` as generated output, refining `SCOPE.md` to the actual
research-only repository boundary, and correcting `AGENTS.md` repo identity.
## Verify Local Developer Workflow
```task
id: IDENTITY-WP-0001-T02
status: done
priority: high
state_hub_task_id: "c465b751-5799-47a2-b1e0-93017b39b9a7"
```
Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
Completed by adding the local developer workflow to `AGENTS.md`. The repository
is documentation-only: no install, build, runtime service, package manifest, or
configured test runner exists. Current verification is `rg --files`, `git diff
--check`, and State Hub ADR-001 consistency sync after workplan changes.
## Seed First Real Workplan
```task
id: IDENTITY-WP-0001-T03
status: done
priority: medium
state_hub_task_id: "2baf0a58-ad4e-4888-a02a-0935bd329c43"
```
Create the first implementation workplan for the repository's most important
next change. After workplan file updates, run from `~/state-hub`:
```bash
make fix-consistency REPO=identity-canon
```
Completed by `IDENTITY-WP-0002`, which follows up on `ResearchProposal.md` by
seeding the first terminology, canon, model, scenario, open-question, and
downstream recommendation artifacts.

86
workplans/IDENTITY-WP-0002-research-proposal-follow-up.md Normal file
View File

@@ -0,0 +1,86 @@
---
id: IDENTITY-WP-0002
type: workplan
title: "Research proposal follow-up: initial canon scaffold"
domain: canon
repo: identity-canon
status: finished
owner: codex
topic_slug: canon
created: "2026-06-05"
updated: "2026-06-05"
state_hub_workstream_id: "ddb6ca2b-2b35-4dd7-a1fb-f31a51de44f5"
---
# Research proposal follow-up: initial canon scaffold
This workplan follows up on `ResearchProposal.md`, especially Immediate Next
Steps 5 through 9. The goal is to turn the seeded proposal and corpus outline
into the first repository-native terminology, canon, model, and scenario
artifacts without pretending that the source-note research pass is complete.
## Seed Terminology Inventory
```task
id: IDENTITY-WP-0002-T01
status: done
priority: high
state_hub_task_id: "2c66f05d-a19f-4f29-a24d-8cb43c0e7da1"
```
Create the first `terminology/TerminologyInventory.md` from the proposal,
intent, and seeded corpus topics. The inventory must mark mappings as
candidate mappings until the individual source notes are backfilled.
## Seed Terminology Conflict Map
```task
id: IDENTITY-WP-0002-T02
status: done
priority: high
state_hub_task_id: "eeca8178-76ec-485c-bace-70ed13d4a418"
```
Create the first `terminology/TerminologyConflictMap.md` for overloaded terms
that are central to the proposal: `user`, `identity`, `account`, `subject`,
`principal`, `tenant`, `organization`, `group`, `role`, `member`, `profile`,
`persona`, `identifier`, `credential`, and synonymity terms.
## Draft Canonical Principles And Glossary
```task
id: IDENTITY-WP-0002-T03
status: done
priority: high
state_hub_task_id: "44fb593e-1118-412f-a3d8-3976958ad175"
```
Create `canon/DesignPrinciples.md` and `canon/CanonicalGlossary.md` as the
first explicit canonical layer. These files should stay implementation-neutral
and keep external product mappings separate from canonical definitions.
## Add Model And Scenario Tests
```task
id: IDENTITY-WP-0002-T04
status: done
priority: medium
state_hub_task_id: "9a922e09-0609-4dcb-9828-00d12009c9eb"
```
Create `model/ConceptualModel.md` and `scenarios/ScenarioTests.md` so the
initial canon can be tested against the representative scenarios listed in the
research proposal.
## Record Follow-Up Boundaries
```task
id: IDENTITY-WP-0002-T05
status: done
priority: medium
state_hub_task_id: "3231c998-2e1a-4d35-a9c2-c7ff6888394f"
```
Create lightweight follow-up surfaces for open questions and downstream
recommendations. These notes should keep implementation ideas visible without
moving implementation work into this repository.