Skip to content
Pollenix Docs

Matter-team ACLs

Matter-team ACLs

Ethical walls enforced on every Vault read. When a document’s acl_mode = 'matter_team', only members of the document’s source_matter_id matter team can read it.

How it’s enforced

Per-tenant level enforcement isn’t enough for law firms — within one firm, two matters can have overlapping parties on opposite sides of a deal or dispute. Pollen8 Legal enforces matter-level isolation via:

WHERE (
  d.acl_mode = 'open'
  OR (d.acl_mode = 'matter_team'
      AND d.source_matter_id IS NOT NULL
      AND EXISTS (
        SELECT 1 FROM legal_matter_team mt
        WHERE mt.matter_id = d.source_matter_id
          AND mt.user_id = :user_id
      ))
)

This clause is applied in both:

  • Vector retrieval (legal_qa._vector_search) — pgvector cosine with the ACL filter ANDed in.
  • Keyword retrieval (legal_qa._keyword_search) — raw SQL with the same EXISTS subquery.

Plus an in-Python gate (legal_acl.can_read_doc) for single-doc fetches in workflow loaders + Word transforms.

Setting up a matter team

  1. Open a matter → Team panel (top-right area of the matter detail page).
  2. Add member → pick a user, role (lead / member / observer). Roles are advisory in v1 — Pollen8 doesn’t distinguish them for read gating, but the schema reserves them for future use.

Restricting a document

When uploading or pasting to the Vault, check Restrict to matter team. The Vault row gets acl_mode = 'matter_team' and a required source_matter_id. Uploads without a source_matter_id can’t have matter_team ACL — the API returns matter_team_acl_requires_source_matter_id.

What about the bots?

When a Slack/Teams bot question arrives, we map the asker by email to a Pollen8 user (tenant-scoped). If the email matches, the user_id flows into retrieval and matter-team ACL applies. If it doesn’t, we substitute a synthetic UUID that only matches acl_mode='open' docs — private documents stay private.

Auditing

The Why trace’s retrieval payload includes chunks_returned — diffing that against the absolute chunk count for the same query tells you how many docs were filtered out by the ACL. There’s no dedicated “denied” event today; the trace is implicit.

Limits

  • v1 ACL vocabulary is just two modes: open and matter_team. Per-user / per-role lists are roadmap.
  • Removing someone from a matter team retroactively hides Vault docs from them on the next retrieval — there’s no “stale answers” issue because we don’t cache LLM outputs at the user level.