Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,12 @@ compatible, or editorial.

## Unreleased

- Propose stable record IDs 0.1.0 in Draft RFC 0009 (new additive family),
built on RFC 9562 UUIDv4 with standard hyphenated lowercase suffixes, pinpoint
standards references, and synthetic syntax/version/variant and inventory/reference
conformance evidence. Prefix and identity lifecycle rules remain application policy. No
existing or released contract semantics change; adoption remains undecided.
- Accept stable record IDs 0.1.0 in RFC 0009 as a new additive application
profile, built on RFC 9562 UUIDv4 with standard hyphenated lowercase suffixes,
pinpoint standards references, and synthetic syntax/version/variant and
inventory/reference conformance evidence. Andrew owns the restricted,
version-controlled inventory and reviewed allocation process. The profile is
unreleased; existing released contract semantics remain unchanged.

- Clarified the unreleased Comic Manifest 1.0.0 candidate's (#95 prerequisite)
detached approval time bounds: decision time is inclusive, expiry is exclusive
Expand Down
148 changes: 84 additions & 64 deletions rfcs/0009-stable-record-ids.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# RFC 0009: Stable record IDs

- Status: Draft — proposal only; merge does not itself accept this contract
- Status: Accepted for application use by owner on 2026-10-26; unreleased
- Authors: @andrewperis
- Created: 2026-10-24
- Contract families: identifiers
- Compatibility: New additive proposed contract, version 0.1.0; no stable predecessor
- Compatibility: New additive accepted application profile, version 0.1.0; no stable predecessor
- Supersedes: None
- Superseded by: None
- Constitution version: 1.0.0
Expand All @@ -16,16 +16,19 @@

## Summary

Propose a reusable application-level naming and identity profile built on
Define an accepted, reusable application-level naming and identity profile built
on
[RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html), using UUIDv4 for
character, location, and relationship records.
An ID names the same logical record across edits, display-name changes, and
repository moves. It does not identify exact content bytes or confer authority.
The requirements below describe the proposed 0.1.0 contract, not an accepted
standard, production allocation, or publication approval. This repository RFC
is a local proposal, not an IETF submission, endorsement or standards-track
document. A broader proposal could be considered later through a separate
review and submission decision; no external submission is part of this work.
The requirements below define accepted application-profile semantics at
version 0.1.0. This RFC records the owner-approved decision; its review and merge
remain required, and neither the RFC change nor this status releases a bundle,
starts a consumer migration, issues IDs, or approves publication. This is a
local application profile, not an IETF submission, endorsement or
standards-track document. A broader proposal would require a separate review
and submission decision; no external submission is part of this work.

## Motivation and existing-contract inventory

Expand All @@ -45,13 +48,13 @@ invent a random-number encoding; it does not alter those URNs or their meanings.
Existing prompt, package, schema, production and artifact identities retain
their own meanings and namespaces.

Reuse that safe ASCII repertoire, exact string comparison, and independent
version/content identity rather than add a resolver protocol. Those existing
schemes do not specify persistent record issuance, collision or rename rules;
therefore a small separate proposal is necessary. No source ID is converted,
reserved, replaced or reinterpreted by this RFC.
This profile reuses that safe ASCII repertoire, exact string comparison, and
independent version/content identity rather than add a resolver protocol. Those
existing schemes do not specify persistent record issuance, collision or
rename rules; therefore a small separate application profile is necessary. No
source ID is converted, reserved, replaced or reinterpreted by this RFC.

## Specification (proposed)
## Specification (accepted application profile 0.1.0)

### Standards basis and application rules

Expand Down Expand Up @@ -86,8 +89,9 @@ required version/variant bits. Merely inserting hyphens into arbitrary random
bytes is insufficient; a name/content hash with overwritten version bits is
not UUIDv4 generation. Schema validation can check syntax, version and variant,
but cannot establish random generation.
The prefix `record` and three kind tokens are proposed only. This RFC neither
reserves nor changes an existing released namespace. IDs are opaque: names,
The prefix `record` and three kind tokens are specific to this accepted
application profile. This RFC neither reserves nor changes an existing released
namespace. IDs are opaque: names,
slugs, file paths, chronology, ownership and classification MUST NOT be encoded.
Consumers MUST reject malformed or noncanonical profile IDs rather than trim,
case-fold, normalize or repair them. Lowercase is the producer's serialization
Expand All @@ -106,20 +110,25 @@ alone cannot establish it.

### Issuance and collisions

Only an authorized record owner MAY issue an ID. The issuer MUST use a
UUIDv4 generator backed by a CSPRNG as required by this profile, check the
complete candidate against the authoritative inventory of issued and retired IDs, and atomically reserve
it with its kind before committing a new record. A reservation collision MUST
cause fresh generation and another reservation attempt. If the inventory or
atomic reservation is unavailable, issuance MUST fail without publishing a
record. Offline candidates are unissued until reservation succeeds. Consumers
MUST NOT mint IDs merely because they encounter a missing reference.

The inventory may be maintained by an existing transactional store or serialized
owner-reviewed allocation process; no new service or framework is prescribed.
The accountable inventory owner and cross-repository reservation workflow must
be selected before adoption. Randomness reduces collision probability; it does
not replace a uniqueness check. Retired IDs remain reserved forever.
Only an authorized record owner MAY issue an ID. Andrew (@andrewperis) is the
accountable owner of the private, version-controlled record-ID inventory and
the serialized allocation process. Each candidate MUST be generated by a
UUIDv4 generator backed by a CSPRNG, checked against the complete issued,
reserved and retired inventory, and included in a reviewed pull request. Before
any candidate allocation, the change MUST document legacy-ID compatibility and
a duplicate check. A candidate remains unissued while its pull request is open.
An approved merge records it as a private reservation; it does not authorize
production issuance or use. Production use requires an immutable contract
release and separately reviewed consumer adoption under the
[change-control policy](../docs/change-control.md). A collision MUST stop the
affected allocation and be escalated to the accountable owner. Do not silently
overwrite, merge or renumber an already-issued ID. Consumers MUST NOT mint IDs
merely because they encounter a missing reference.

The inventory is maintained in the restricted Lore repository through
serialized, owner-reviewed pull requests; no new service or framework is
prescribed. Randomness reduces collision probability; it does not replace a
uniqueness check. Retired IDs remain reserved forever.

A conflict discovered after issuance MUST stop import/update and be escalated
to the accountable owner. Do not silently overwrite, merge or renumber an
Expand All @@ -140,7 +149,7 @@ reviewed and do not make historical references name a different entity.
A record reference carries the full ID. Relationships have their own persistent
ID and explicit endpoint IDs; they MUST NOT derive identity from endpoint order,
names or a hash of the current relationship text. Endpoints in the minimal
examples are characters or locations. This proposal does not define predicates,
examples are characters or locations. This profile does not define predicates,
cardinality, directionality or a relationship payload schema.

An authorized validator MUST check references against its complete permitted
Expand All @@ -160,7 +169,7 @@ conversion. Do not add record fields to existing closed context schemas.
## Conformance examples

All values in the [cases](0009-stable-record-ids/cases.json) are fabricated.
The [proposal-local schema](0009-stable-record-ids/id.schema.json) validates only
The [RFC-local schema](0009-stable-record-ids/id.schema.json) validates only
ID strings; it intentionally has no canonical `$id` and is not a released schema.
The UUIDv4 fixtures were generated solely for synthetic tests with Python
`uuid.uuid4()`; they are not issued or reserved record IDs. The cases exercise
Expand All @@ -171,31 +180,34 @@ Run `node --test tests/stable-record-ids.test.cjs` or `npm test`.

## Compatibility and migration

This introduces proposed 0.1.0 semantics only. Released schemas, bundles, tags,
source IDs and artifact namespaces remain unchanged. No consumer adopts it by
merging this proposal. Candidate consumers are record storage/validation and
reference-producing tools; Context Builder/Prompt SDK would require a separately
reviewed integration only if they consume persistent record references.
@andrewperis owns the decision; affected consumer maintainers must confirm the
inventory and reservation process before acceptance.

Before adoption: inventory existing schemes and references without disclosing
protected records; prefer preserving compatible issued identities over blanket
renumbering; document explicit mappings for incompatible legacy IDs; validate
references and collisions; obtain owner/consumer review; then publish the
accepted specification, canonical versioned schema and immutable release under
[versioning policy](../docs/versioning.md). No existing consumer migration or
dated support window is activated by this proposal. Adoption must set a dated
rollout/rollback window and preserve old references during that window. A rollback
must retain reservations and mappings so issued IDs are never recycled.
This adds accepted 0.1.0 semantics as an unreleased additive family. Released
schemas, bundles, tags, source IDs and artifact namespaces remain unchanged.
Merging this RFC does not publish a release or activate consumer migration.
Production consumers MUST wait for an immutable release and separately reviewed
adoption; a private reservation does not satisfy the release gate.
Candidate consumers are record storage/validation and reference-producing tools;
Context Builder/Prompt SDK would require a separately reviewed integration
only if they consume persistent record references.
@andrewperis owns the decision; affected consumer maintainers must review any
integration before using the profile.

Before a production consumer adopts this profile, inventory its existing
schemes and references without disclosing protected records; preserve compatible
issued identities; document mappings for any incompatible legacy IDs; validate
references and collisions; and obtain owner/consumer review. Any later release
must follow the [versioning policy](../docs/versioning.md). This RFC does not
activate a consumer migration or dated support window. If a consumer later needs
a migration, its separately reviewed plan must define rollout and rollback
dates and retain reservations and mappings so issued IDs are never recycled.

## Security and privacy

Even random IDs can correlate private activity. Public material MUST use wholly
synthetic IDs and examples; do not copy private IDs, names, paths, links, excerpts
or mappings into public fixtures or logs. Inventory access and error detail must
respect classification. An ID's shape proves neither ownership nor permission.
No private record allocation or private validator work is part of this proposal.
synthetic IDs and examples; do not copy private IDs, names, paths, links,
excerpts or mappings into public fixtures or logs. Inventory access and error
detail must respect classification. An ID's shape proves neither ownership nor
permission. The private inventory and validation evidence remain in restricted
systems; Codex fixtures contain synthetic examples only.

## Rights, provenance, accessibility, and portability

Expand All @@ -214,18 +226,26 @@ This RFC does not assess private content or complete a broader conformance item.
identity on ordinary edits or moves.
- Sequential IDs: require coordinated enumeration and reveal allocation order;
UUIDv4 suffixes keep the same explicit uniqueness check without that leakage.
- A custom 32-hex random suffix: superseded in this proposal by standard
- A custom 32-hex random suffix: superseded in this profile by standard
hyphenated UUIDv4 with explicit version and variant, for interoperability.
- Introduce a resolver/registry service or full record taxonomy: unnecessary for
this narrow contract; implementation and payload semantics remain separate.

## Implementation plan and decisions needed

Review the application profile, uniqueness scope, retirement/reference rules
and inventory owner. UUIDv4 is the proposed standard building block; application
adoption and any future broader RFC remain separate decisions.
Confirm whether any existing issued scheme must be retained before accepting.
Only after explicit acceptance should maintainers promote the proposal, choose
its stable version, implement issuance in the owning consumer, and plan release.
The PR should be ready for review while the RFC remains Draft. Do not merge,
release, tag, allocate real IDs or change public canon as part of this task.
## Accepted operational status

The application profile is accepted at 0.1.0 but remains unreleased. Andrew
(@andrewperis) is accountable for the restricted, version-controlled inventory.
Allocations are serialized through reviewed pull requests, and candidates
remain unissued while under review. An approved merge records the candidate as
a private reservation; production issuance and use still require an immutable
release and separately reviewed consumer adoption. Each allocation must first
document compatibility with legacy IDs and a full duplicate check. An
already-issued conflict stops the affected allocation and is escalated; no
silent conversion or renumbering is allowed.

This status does not create a canonical released schema, immutable bundle or
tag, migration window, production integration, or public creative publication.
The RFC-local schema and synthetic fixtures remain bounded to this RFC;
any release or consumer migration requires its normal separate review and
versioning steps. No private record names, IDs or allocation evidence belong in
this repository.
7 changes: 4 additions & 3 deletions rfcs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ RFC filenames use four-digit numbers and a concise kebab-case title:
a proposal. Allocate the next number when the pull request opens; numbers are
never reused.

Accepted candidates include Prompt Definition v1 (RFC 0001), Provider Execution
v1 (RFC 0002), Context Package v1 (RFC 0003), and Structured Output v1 (RFC
0004).
Accepted decisions include Prompt Definition v1 (RFC 0001), Provider Execution
v1 (RFC 0002), Context Package v1 (RFC 0003), Structured Output v1 (RFC 0004),
and the unreleased UUIDv4 application profile 0.1.0 (RFC 0009). RFC 0009 has no
released schema, consumer migration, or production integration yet.
10 changes: 7 additions & 3 deletions specs/ids/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@
Stable identifier formats, namespaces, uniqueness rules, normalization, and
human-readable naming conventions belong here.

[RFC 0009](../../rfcs/0009-stable-record-ids.md) proposes a UUIDv4 application profile for
stable record IDs for characters, locations and relationships. It is Draft, not an accepted
contract or authority to allocate production IDs.
[RFC 0009](../../rfcs/0009-stable-record-ids.md) defines the accepted 0.1.0
UUIDv4 application profile for stable character, location and relationship
record IDs. It is unreleased: the proposal-local schema is not a canonical
released schema, and production allocations still require the private
owner-reviewed inventory process. Production use also requires an immutable
contract release and separately reviewed consumer adoption under the
[change-control policy](../../docs/change-control.md).
Loading