Skip to content

symfonic.cli.public_api_surface

public_api_surface

The two authorities behind :mod:symfonic.cli.public_api, as data.

PUBLIC_PACKAGES is T1.1.1's declared-public set. SANCTIONED_UNDECLARED and OPEN_GAPS are T1.1.2's triage: the clusters a scaffold may import before they are declared, and the ones that are pinned rather than permitted.

They live apart from the classifier so the tables can grow or shrink -- which is the measure of progress on REQ-S4.3 -- without the rule that reads them moving at all.

OPEN_GAPS module-attribute 

OPEN_GAPS: dict[str, OpenGap] = {}

Empty as of the kernel-native scaffold migration.

All four rows closed the same way, and it is worth recording which way, because none of them closed by declaring the module the gap named.

  • PUB-4 (CorePreference) -- the generated domain no longer fills a DomainTemplate. It declares a DomainPersona and a list of Guardrail, both public on symfonic.capabilities.prompting, so the half-public modelling API is not reached at all.
  • PUB-5 (ConversationMetricsCollector) and PUB-7 (PostgresBudgetStore) -- both are now process resources the host owns and hands over, through symfonic.platform.observability. The scaffold names the bundle, not the internals.
  • PUB-6 (the metrics store's factory and its module globals) -- triaged '(c) internalize store internals', and that verdict stands: the internals stayed internal and the generated app reads the store off the bundle instead of a process global.

A new private dependency must be added back here deliberately; the suite asserts this set is neither exceeded nor stale.

OpenGap dataclass 

OpenGap(finding: str, names: frozenset[str], triage: str, consequence: str)

A symbol the scaffold needs that the framework has not declared public.

Distinct from :class:UndeclaredException in the way that matters: an exception carries a T1.1.2 verdict saying the symbol is public and merely undeclared, so the debt is paperwork. A gap has no such verdict — or has one pointing the other way — so the scaffold depends on a surface nobody promised to keep.

Gaps are pinned rather than fixed because closing one means editing a package this task holds no write authority over (T1.2.7 gives T4.3.1 src/symfonic/cli/** and its evidence directory). Pinning makes the set non-increasing, which is the strongest claim a task can honestly make from inside its own boundary.

consequence instance-attribute 

consequence: str

What breaks for an adopter if the symbol moves or is internalised.

triage instance-attribute 

triage: str

T1.1.2's verdict for the cluster, or untriaged for the long tail.

UndeclaredException dataclass 

UndeclaredException(triage: str, finding: str, names: frozenset[str], reason: str)

One T1.1.2 cluster the scaffold may import before it is declared.

finding instance-attribute 

finding: str

This task's finding id (PUB-n) tracking the declaration work.

names instance-attribute 

names: frozenset[str]

The exact symbols sanctioned. Sanctioning the module would re-admit every future symbol in it without anyone deciding.

triage instance-attribute 

triage: str

a-promote or b-compat-alias — the T1.1.2 verdict, verbatim.