Namespaces

What a namespace is

A namespace is a named scope that can hold repos, contain child namespaces, carry grants, and apply policy. Most teams map namespaces onto their organisational chart: acme/ at the root, acme/payments and acme/infra as the team scopes, acme/payments/api as a repo.

Namespaces are not directories on disk and not branches. They're a logical structure that lives in the Heddle control plane and applies to both hosted and self-hosted repos.

The cascade

Grants on a parent namespace flow to every descendant. If acme/payments grants reviewer to alex@acme.com, alex is a reviewer on every repo under acme/payments — today's repos and tomorrow's. No need to update every repo individually.

A grant is bound to three things: the namespace it's set on, the role it confers, and the actor it applies to. The model is "grant role R on namespace N to actor A" — set once at the highest scope you want it to apply, inherit from there. The CLI surface for this is foundation-in-place; the user-facing heddle namespace subcommands land in a follow-on docs pass alongside the commands themselves.

Overrides work in one direction: a more specific grant raises access, never silently strips it. If you need to lock something down at a child scope, you do it at a visible scope — not via an implicit subtraction that's hard to trace later.

Effective role

Every action runs against the effective role for the actor at the exact scope they're acting on. The effective role is computed by walking the namespace tree from the action's scope upward, collecting grants, and applying the most-specific rule.

When access fails, Heddle tells you exactly which layer said no — token scope, namespace policy, or repo grant — and surfaces the direct and inherited edges behind the decision. No opaque 403s, no hunting through logs.

Why this beats group-based ACL

The traditional model is groups + ACLs: define a "payments reviewers" group, add people to it, add the group to every repo's ACL. It works, until your org has 47 groups and nobody can remember which one to add a new hire to. Worse, a group can grant access to repos that didn't exist when the group was created — you only find out by reading every group's membership for every repo.

Heddle's cascade inverts this: the grant lives at the namespace, the repos are leaves, and access resolves on demand. A new repo under acme/payments inherits the reviewers automatically. A new reviewer added to the namespace gets access to every repo at once. The organisational structure IS the access structure.

Multi-team org sprawl

Large orgs have nested teams, contractors with time-bounded access, support staff who need read-only on everything for triage. Namespaces handle all three:

• Nested teams map directly. Grants at any level flow down.
• Time-bounded access via heddle support grant — a grant that expires automatically, audit-trailed throughout.
• Read-only triage via a low-privilege role granted at the org root. Every repo readable, no repo writable.

The commands

• heddle namespace — create, list, grant, revoke. Planned — subcommands and reference page land in the next docs pass.
• heddle support grant — time-bounded admin grants for staff/contractors.

Next: attribution and signing for how namespace grants combine with signature requirements, or the oplog for how grant changes are recorded for audit.