Metadata Protection Model — Phase 1 (ADR-0010)

Phase 1 introduces the item-level lock (_lock) and the

provenance / package tags that drive it. Later phases extend this

file with the path-level (_frozenPaths) and package-level

(metadataDefaults) layers; the wire shapes here are forward-

compatible with those additions.

Wire / runtime contract:

• _lock — 4-state enum, controls overlay / delete actions.

• _lockReason — short, user-visible explanation surfaced in

403 item_locked errors and on Studio tooltips.

• _lockSource — which layer set the lock (Phase 1 only emits

'artifact'; 'package' and 'env-forced'

are reserved for Phase 3/2 respectively).

• _provenance — 'package' for loader-introduced items,

'org' for tenant-authored, 'env-forced'

reserved for emergency overrides.

• _packageId / _packageVersion — denormalised from the

registry tag so consumers don't need a second

round-trip to inspect provenance.

See docs/adr/0010-metadata-protection-model.md for the full

design (industry references, 4-layer model, audit trail).

TypeScript Usage

import { MetadataLock, MetadataLockSource, MetadataProvenance } from '@objectstack/spec/kernel';
import type { MetadataLock, MetadataLockSource, MetadataProvenance } from '@objectstack/spec/kernel';

// Validate data
const result = MetadataLock.parse(data);

MetadataLock

Allowed Values

• none
• no-overlay
• no-delete
• full

MetadataLockSource

Allowed Values

• artifact
• package
• env-forced

MetadataProvenance

Allowed Values

• package
• org
• env-forced