Collaboration policy

The collaboration policy is how a regulated organisation controls what its people share through the Context Platform: lenses, handoffs, pair session invitations, team memory, presence, the work registry and agent instruction files. It does not grant access to content; it only limits sharing.

The policy document

One JSON document per node (organisation, department, team or project), every key optional. An absent key inherits.

Unknown keys are refused. An organisation that sets nothing sees no change from before the policy existed; the opt-in keys (personal file sharing, custom file shares, hash_only, the custom file name allow-list) start in their most restrictive state.

Inheritance: lower levels only tighten

The policy that applies to a person is folded from, in order: the organisation; the departments of the person's teams and of the content's chain; the teams of the person's groups and of the content's chain; the projects of the content's chain. Switches combine with AND, limits take the minimum, allow-lists intersect, deny-lists unite.

• A person in several teams gets the tightest of them. This is deliberate and fails closed, and it can surprise.
• Tighten-only is checked twice. On write, a document that would loosen what the level above allows is refused with 422 context.collab_policy.loosens_parent, naming the fields. At read time the merge can only tighten, so a document that became looser than a parent tightened later is simply overridden.
• The built-in deny list of files (.env, keys, credentials) cannot be changed by any policy: 422 context.collab_policy.builtin_deny_immutable.
• A policy that cannot be resolved refuses the operation: 503 context.collab_policy.unavailable. Nothing reads an error as "no policy".

Manage the policy

Administration routes need context:space:admin on the node's space (the organisation's root space for the organisation), always enforced.

Example: limit the payments team to sharing within the team, at most confidential, with approval for anything above internal, and shares lasting at most 30 days:

PUT /api/v1/context/collaboration/policy
Content-Type: application/json

{
  "nodeKind": "team",
  "nodeId": "<payments team id>",
  "reason": "CHG-2041: payments data handling",
  "policy": {
    "share_scope": "team",
    "classification_ceiling": "confidential",
    "approval_above": "internal",
    "max_share_expiry_seconds": 2592000,
    "default_share_expiry_seconds": 604800
  }
}

The answer includes violatingShares, violatingHandoffRecipients and violatingSessionInvitations: the numbers of existing grants that now break the policy. They are ineffective at once, listed, and never deleted.

Versions and audit

Every change is an immutable version with its author, time and reason. The versions table refuses update, delete and truncate for every role. Clearing a policy is a new, empty version, so the history stays whole. Every change is audited with its input (context.collab_policy.put, .clear).

The as-of lookup uses the current hierarchy: renaming or moving a team after the fact is not replayed.

Where it is enforced

Refusals carry stable codes: context.collab_policy. followed by capability_disabled, classification_ceiling, approval_required, scope_exceeded, too_many_targets, level_not_allowed, expiry_exceeds_max (all 403), or expiry_in_past, invalid_policy, loosens_parent, builtin_deny_immutable, reason_required (422), version_conflict (409), not_found (404), unavailable (503).

Ending and leaving a pair session stay possible when pair sessions are switched off, so nobody is stuck in one. Presence entries already written expire within their 30-second lifetime.

Share oversight

Administrators see and revoke every grant of the organisation, or of one node:

Administrators never see content they cannot read: a lens's name and spaces appear only when the administrator may read every space of the lens; otherwise the row is restricted: true and keeps who, with whom, level, expiry and classification. A revocation needs context:space:admin on every space the content covers and is audited with its reason. A revoked handoff recipient is an append-only record; the recipient row stays.

The policy and share oversight have no console page yet; use the API.