r35157/com_r35157_nenjim-hubd-impl_ref
0
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0.1-dev
com_r35157_nenjim-hubd-impl…/openspec/specs/nenjim-journal-format/spec.md
T

13 KiB
Raw Permalink Blame History

nenjim-journal-format Specification

Purpose

Defines the observable format-version-1 contract and immutable domain meaning of a complete, artifact-scoped Nenjim Journal snapshot.

Requirements

Requirement: Artifact-scoped complete snapshots

The Journal format SHALL describe exactly one artifact identified by the coordinate <GROUP>-<MODULE>-<ARTIFACT>, SHALL contain no JOURNAL_ID or artifact TYPE, and SHALL represent a complete immutable worldview rather than a delta from its predecessor.

Scenario: Valid artifact identity

  • WHEN metadata contains non-empty GROUP=com_r35157_nenjim, MODULE=hubd, and ARTIFACT=api
  • THEN the parsed coordinate is com_r35157_nenjim-hubd-api

Scenario: Obsolete identity fields

  • WHEN a Journal contains JOURNAL_ID or TYPE
  • THEN parsing fails as an unknown or misplaced field without silently ignoring it

Scenario: No-op semantic revision

  • WHEN a later valid snapshot differs from its predecessor only by JOURNAL_VERSION and PREVIOUS_JOURNAL_DIGEST
  • THEN the snapshot remains valid because revisions are complete worldviews and need not change their semantic content

Requirement: Strict top-level structure and comments

The parser SHALL require the logical order FORMAT_VERSION=1, JOURNAL_VERSION, optional PREVIOUS_JOURNAL_DIGEST, [METADATA], optional [POLICY], and one or more [RELEASE <version>] sections. Blank lines and full-line or trailing # comments SHALL be accepted, except that a # inside a quoted value is data.

Scenario: Comments before format entry

  • WHEN blank lines and full-line comments precede FORMAT_VERSION=1
  • THEN the format entry is treated as the first actual configuration entry and parsing proceeds

Scenario: Hash inside quoted text

  • WHEN DESCRIPTION='Project #1' # trailing comment is parsed
  • THEN the decoded description is Project #1 and the trailing comment is discarded

Scenario: Unsupported format

  • WHEN the first actual entry is FORMAT_VERSION=2
  • THEN parsing fails explicitly because the format version is unsupported

Scenario: Misordered or duplicate structure

  • WHEN a required entry or section is missing, duplicated, malformed, unknown, or placed outside its defined order
  • THEN parsing fails and no unknown content is ignored

Requirement: Journal and publication timestamps

JOURNAL_VERSION and PUBLISHED_AT SHALL each use a strict UTC uuuuMMddHHmmssSSS'Z' timestamp with millisecond precision and SHALL retain distinct revision-time and release-time meanings.

Scenario: Valid timestamp

  • WHEN 20260819121530842Z is supplied as a Journal or publication timestamp
  • THEN it is represented as the corresponding immutable UTC instant/value

Scenario: Invalid timestamp

  • WHEN a timestamp has missing milliseconds, a non-UTC suffix, an impossible calendar value, or trailing characters
  • THEN parsing fails

Requirement: Quoted metadata values

[METADATA] SHALL contain exactly one non-empty GROUP, MODULE, ARTIFACT, and single-quoted DESCRIPTION, and MAY contain at most one single-quoted INFORMATION_URI. The parser SHALL decode \' and \\, reject other malformed escaping and empty quoted values, and expose information URI as Optional<URI> only when the decoded value is a syntactically valid non-empty absolute URI, without restricting its scheme.

Scenario: Valid quoted metadata

  • WHEN metadata contains DESCRIPTION='Nenjim\'s reference hub' and INFORMATION_URI='ftp://ftp.domain.com/components/123.txt'
  • THEN the model exposes description Nenjim's reference hub and the exact absolute FTP URI

Scenario: Optional information URI absent

  • WHEN valid metadata omits INFORMATION_URI
  • THEN the model exposes an empty optional URI

Scenario: Scheme-independent URI

  • WHEN a syntactically valid absolute https:, ftp:, or ipfs: URI is supplied
  • THEN parsing accepts it without fetching, opening, or scheme-specific interpretation

Scenario: Invalid metadata text or URI

  • WHEN a required quoted value is unquoted, empty, unterminated, badly escaped, or the information URI is relative or syntactically invalid
  • THEN parsing fails at that field

Requirement: Exact artifact releases and content

Every release section SHALL identify a unique exact major.minor.patch stable semantic version and SHALL contain exactly one non-empty quoted LICENSE, exactly one valid PUBLISHED_AT, one or more supported unique CONTENT_DIGEST values, and exactly one non-negative long CONTENT_SIZE.

Scenario: Valid release content

  • WHEN release 1.0.3 contains decoded license text, a valid publication timestamp, a SHA-256 digest, an optional CIDv1 digest, and a non-negative content size
  • THEN the immutable release model exposes all values without normalizing or interpreting the license

Scenario: Invalid release version

  • WHEN a release heading uses 1, 1.0, 1.0.0-beta, or 1.0.0+build.42
  • THEN parsing fails rather than normalizing it to another exact release

Scenario: Duplicate release

  • WHEN two release sections identify the same exact version
  • THEN parsing fails

Scenario: Invalid license

  • WHEN a release omits LICENSE, repeats it, or supplies an unquoted, malformed, or empty value
  • THEN parsing fails

Scenario: Digest validation

  • WHEN content digests use valid sha256:<64 lowercase hexadecimal characters> and/or cid1:<CIDv1 base32 text> values whose payload is the exact canonical unpadded lowercase Base32 encoding of a valid CIDv1 envelope, with at most one digest of each scheme
  • THEN all supplied content identities remain inspectable in the release model

Scenario: Canonical CIDv1 envelope

  • WHEN a CIDv1 content digest is supplied
  • THEN its version, multicodec, multihash code, and digest-length fields use their shortest unsigned varint encoding within the supported long range, and the declared digest length matches the payload

Scenario: Non-canonical CIDv1

  • WHEN a CIDv1 spelling has non-zero unused Base32 padding bits, a non-minimal varint, or a varint that overflows the supported long range in any envelope field
  • THEN parsing fails even if a permissive decoder could produce the same CID bytes or a truncated numeric value

Scenario: Invalid content identity

  • WHEN no content digest exists, a digest scheme is unknown, a digest syntax is invalid, a scheme repeats, or content size is negative or outside the long range
  • THEN parsing fails

Requirement: Normalized version expressions

The model SHALL distinguish exact artifact versions from partial version boundaries, normalize semantically equivalent selector syntax, support membership and set containment, and reject unsupported or empty expressions.

Scenario: Equivalent exact forms

  • WHEN 1.0.3 and [1.0.3] are parsed
  • THEN both produce the same exact version-expression representation

Scenario: Minor series

  • WHEN [1.0] is parsed
  • THEN it contains every stable 1.0.x release from 1.0.0 through the release immediately before 1.1.0 and is not normalized to exact 1.0.0

Scenario: Inclusive and exclusive ranges

  • WHEN [1.0.3-->1.0.7] and [1.0.3-->1.0.7) are parsed
  • THEN the first contains both endpoints and the second excludes 1.0.7

Scenario: Partial range boundaries

  • WHEN [1.0-->1.2] or [1.0-->1.2) is parsed
  • THEN the inclusive form contains the entire 1.2.x series and the exclusive form excludes the entire 1.2.x series

Scenario: Explicit cross-major range

  • WHEN [1.0-->3.0) is parsed
  • THEN it contains stable versions in major lines 1 and 2 but none in major line 3

Scenario: Open upper range

  • WHEN [1.0-->, (1.0-->, or [1.0.3--> is parsed
  • THEN its implicit exclusive upper boundary is 2.0.0, while its lower boundary respectively starts at 1.0.0, 1.1.0, or 1.0.3

Scenario: Expression union

  • WHEN [1.0.0-->1.0.3], [1.0.7], 1.1.1 is parsed for a repeatable/list-valued rule
  • THEN the model represents the normalized union and accepts whitespace around commas and -->

Scenario: Invalid expression

  • WHEN an expression uses a major-only boundary, a bare incomplete exact version, prerelease/build syntax, mathematical comparison syntax, whitespace inside a numeric version, an empty list element, reversed boundaries, or an empty range
  • THEN parsing fails

Requirement: Nenjim dependencies

Each artifact release SHALL model each nenjim:<artifact-coordinate> dependency target with exactly one DEPENDS_ON base expression set, zero or more described EXCLUDES entries, and zero or more described PREFERRED entries. Unknown schemes SHALL fail explicitly, exclusions and preferences SHALL require a corresponding base dependency, and the complete preferred set SHALL be contained by DEPENDS_ON - EXCLUDES.

Scenario: Valid dependency relationship

  • WHEN a release depends on nenjim:com_r35157_nenjim-hubd-api=[1.0-->, excludes 1.0.4 with a description, and prefers 1.0.3
  • THEN the model preserves the target, base constraint, and individual described exclusion/preference rules

Scenario: Repeated exclusion and preference rules

  • WHEN multiple EXCLUDES or PREFERRED lines refer to one declared target
  • THEN their expression sets form unions while every line and optional description remains individually inspectable

Scenario: Duplicate base dependency

  • WHEN the same dependency target has two DEPENDS_ON entries
  • THEN parsing fails

Scenario: Orphan relationship rule

  • WHEN an EXCLUDES or PREFERRED target has no corresponding DEPENDS_ON
  • THEN parsing fails

Scenario: Invalid preferred subset

  • WHEN any preferred version lies outside the base dependency set or inside an exclusion
  • THEN parsing fails because preference cannot make an invalid version valid

Scenario: Unsupported dependency scheme

  • WHEN a dependency uses maven: or another unsupported scheme in format version 1
  • THEN parsing fails clearly rather than ignoring or resolving it

Requirement: Artifact policy

An optional [POLICY] section SHALL preserve individual BLACKLIST, DISCOURAGED, and RECOMMENDED rules and descriptions. Blacklist SHALL be a hard constraint, discouraged and recommended SHALL be hints, overlaps SHALL be valid, and each recommended rule SHALL identify exactly one exact release present in the same snapshot. These recommendation invariants SHALL be enforced both while parsing and when the public model types are constructed directly without the parser.

Scenario: Valid overlapping policy

  • WHEN a broad discouraged range overlaps a blacklisted exact release and an existing exact release is recommended
  • THEN all individual rules and descriptions remain inspectable and the blacklist has the documented stronger meaning without flattening the rules

Scenario: Repeated policy entries

  • WHEN policy contains several blacklist, discouraged, or recommended lines
  • THEN all lines are retained as immutable individual rules

Scenario: Invalid recommendation

  • WHEN RECOMMENDED contains a non-exact range or identifies a release absent from the snapshot
  • THEN parsing fails

Scenario: Direct policy construction rejects a non-exact recommendation

  • WHEN a caller constructs JournalPolicy directly with a recommended rule containing a range, a minor series, multiple versions, or any other non-exact VersionExpressionSet
  • THEN construction fails because one recommended rule must identify exactly one exact major.minor.patch version

Scenario: Direct Journal construction rejects an absent recommendation

  • WHEN a caller constructs Journal directly with an exact recommended version that is absent from that Journal's release map
  • THEN construction fails because recommendations refer only to releases in the same snapshot

Scenario: Direct construction preserves valid policy overlaps

  • WHEN a caller constructs a Journal with an existing exact release recommended while that version also belongs to discouraged or blacklist rules
  • THEN construction succeeds and all individual rules remain inspectable because overlaps are valid

Scenario: Optional description decoding

  • WHEN a repeatable policy or dependency rule ends with :'Known \'issue\' on C:\\tmp'
  • THEN its decoded non-empty description is Known 'issue' on C:\tmp

Scenario: Invalid optional description

  • WHEN an explicitly supplied description is empty, unquoted, unterminated, or has malformed escaping
  • THEN parsing fails

Requirement: Complete diagnostics and immutable results

Parsing SHALL validate the entire document before it is accepted, SHALL report the known logical source, one-based line number, and reason for every parse failure, and SHALL return immutable defensively copied objects and collections without using null for optional values.

Scenario: Source-aware failure

  • WHEN line 12 of logical source example.journal contains an invalid field
  • THEN the parse exception identifies example.journal, line 12, and the validation reason

Scenario: Immutable model

  • WHEN callers obtain metadata, releases, policies, dependencies, digests, or expression collections
  • THEN callers cannot mutate the Journal snapshot through those returned values
Reference in New Issue View Git Blame Copy Permalink