model: retain optional typed object facts in canonical ownership

[sighook]

Problem

Canonical owned_entry currently preserves only:

directory
non_directory

This is honest for the historical /var/lib/pkg/db format, but it is also the current ceiling of the lossless canonical generation store. Consequently, a complete canonical snapshot cannot retain richer application-time facts such as the exact object kind or selected metadata of the object whose ownership was published.

The optional libpkgstate-plan adapter therefore projects ownership claims with no recorded filesystem-object metadata. libpkgplan can still operate from explicit target observations, so this does not block current planning or the first libpkgapply implementation. It does, however, remove an additional consistency check and may limit future audit, sharing, reconciliation, and stale-state diagnostics.

This limitation must remain explicit. It must not later appear as a surprise when an application receipt contains richer completed-object evidence than canonical installed state can retain.

Authority boundary

Any richer object fact must come from an authority that actually established it while applying or observing the completed operation.

Allowed sources may include:

• completed libpkgapply evidence;
• an explicit post-application observation bound to the same target context;
• explicit migration input whose provenance and completeness are retained.

Forbidden sources include:

• reconstructing installed facts from the current package archive;
• copying raw package-image metadata into installed state without completed application evidence;
• probing the current filesystem during legacy database reads;
• upgrading legacy_snapshot facts by inference;
• treating unknown legacy non_directory entries as regular files.

Unknown must remain unknown.

Desired model direction

Investigate extending canonical ownership with an optional state-owned recorded object fact, separate from the ownership relation itself.

The exact vocabulary should be chosen with libpkgapply and audit requirements in view, but may need to distinguish at least:

regular file
directory
symbolic link
hard-link relation
FIFO
socket
character device
block device
unknown non-directory

Selected metadata may include only facts whose semantics and durability are clear, for example:

• permissions;
• owner and group identifiers;
• device numbers;
• symbolic-link target;
• regular-file content identity;
• hard-link group or target identity;
• explicit unknown or unavailable fields.

Do not automatically persist every stat field. Timestamps, inode numbers, mount-specific identifiers, security labels, ACLs, and extended attributes each need an explicit authority and stability decision before entering canonical state.

The ownership relation must remain logically distinct:

package owns path
        !=
recorded object fact at path
        !=
current observed object at path

Shared owners must either cite one compatible recorded fact or represent their recorded facts in a way that cannot silently contradict at the same path.

Identity and storage consequences

A future implementation must define:

• whether recorded object facts participate directly in installed_package_identity, ownership_inventory_identity, or both;
• canonical encoding and ordering;
• schema-version and storage-format compatibility;
• how absent, unknown, historically unavailable, and known-empty values differ;
• whether adding the facts requires a new canonical snapshot schema, generation format, or SONAME;
• how old canonical generations decode without invented metadata;
• how the planner adapter maps only semantically equivalent fields into libpkgplan::filesystem_object_metadata.

The existing generation format must not be reinterpreted as though it had stored facts that were never encoded.

Legacy compatibility

The historical database retains only directory versus non-directory. Legacy reads and imports must continue to preserve that limitation explicitly.

A migration may supply richer facts only through a named external authority and must retain migration provenance. Merely observing the filesystem at migration time must not silently convert a historical ownership record into a historical installed-object claim.

Relationship to libpkgapply

This issue is not a prerequisite for creating libpkgapply.

The first application layer should produce sufficiently typed completed-object evidence so that a later state extension can consume it without changing what the actuator actually observed.

The state/application integration design should therefore avoid collapsing completed evidence immediately to directory/non_directory before publication policy has had a chance to decide what is durably retained.

Acceptance criteria

• A concrete recorded-object fact model is proposed with explicit authority and completeness semantics.
• Ownership, recorded installed facts, and live observations remain separate types or clearly separate semantic domains.
• Legacy records remain directory/non-directory and never gain inferred precision.
• Canonical identity and generation-format changes are specified before implementation.
• Shared ownership and contradictory recorded facts have defined behavior.
• The optional planner adapter projects only facts with equivalent semantics.
• Tests cover unknown metadata, legacy import, shared ownership, identity sensitivity, storage round trips, and old-generation compatibility.
• Manuals state exactly which object facts canonical state retains.

Non-goals

• Filesystem probing inside libpkgstate.
• Archive inspection inside libpkgstate.
• Reconstructing historical facts from current mutable authorities.
• Making state publication and filesystem mutation globally atomic.
• Blocking the initial libpkgapply work while the present limitation remains explicit and correctly represented.