v0 state

owner

prefix

sep

sep is the payload separator. A single byte, because the point here is the shape of the boundary and not the encoding: a real one would need escaping, and choosing it is a decision this pattern does not make for you.

Handler

Handler is the whole interface an implementation satisfies. It never changes, because everything that would have changed it is in Schema instead.

verb

Ownable

candidates

// pkgpath -> Handler

live

livePath

liveVerbs

// verb name -> \*verb, for lookup

liveOrder

// the same verbs in DECLARATION order, for listing

Propose

Propose nominates the calling realm, exactly as in pattern F. Its schema is parsed here so a malformed one is rejected at proposal rather than at accept.

Accept

Accept promotes a candidate, and refuses one that would break an existing caller. This is the check a Go interface cannot express.

AcceptBreaking

AcceptBreaking promotes a candidate that Accept refuses. It exists because the diff is SYMMETRIC, which is not obvious until it bites: once v1 has added a verb, rolling back to v0 drops that verb and is a regression by exactly the same rule that protects callers going forward. A pattern that can only move forward is worse than one with no diff at all, so the escape hatch is required, and making it a separate function is the point: the owner has to type a different word, and the audit log shows which one. Use it to roll back, and to retire a verb nobody calls any more. Not to make an upgrade go through.

resolve

resolve is the owner check and the lookup both accepts share.

assertNoRegression

assertNoRegression is the upgrade diff. A new schema may ADD verbs and may not remove one or change its arity, because a caller compiled against the old one is still out there calling it.

Call

Call is the one signature this realm is committed to forever.

Verbs

Verbs lists the accepted API in DECLARATION order, which is the order the handler wrote it in and the order a reader of the schema expects. Iterating the avl tree instead would list them alphabetically, silently: caught by a test, not by a compiler.

Signature

Signature is one verb's shape, as a caller would write it.

SchemaText

SchemaText is the whole accepted API in the declaration format, so a client can read back exactly what the handler declared.

Live

Live is the package path currently serving, or "" before the first Accept.

Candidates

Candidates lists every path that has nominated itself, in order.

assertLive

parseSchema

parseSchema turns the declaration text into verbs, and is the only validation of a name that Render later echoes.

assertIdent

Render