Skip to content

Commit 8c98b51

Browse files
committed
wip(metadata-protocol): close the package-less write onto a packaged item
Claude-Session: https://claude.ai/code/session_01FEkQ5ni5yjiTswP6crgAkX Co-Authored-By: Claude <noreply@anthropic.com>
1 parent d08b859 commit 8c98b51

3 files changed

Lines changed: 210 additions & 157 deletions

File tree

‎packages/metadata-protocol/src/protocol-packaged-base-refusal.ts‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ import { expandViewContainer, isAggregatedViewContainer } from '@objectstack/spe
5757
*/
5858
export interface PackagedBaseRefusalHost {
5959
isSealedManagedItem: ObjectStackProtocolImplementation['isSealedManagedItem'];
60+
isOverlayableManagedItem: ObjectStackProtocolImplementation['isOverlayableManagedItem'];
6061
isWritablePackage: ObjectStackProtocolImplementation['isWritablePackage'];
6162
packagedBaseRefusal: ObjectStackProtocolImplementation['packagedBaseRefusal'];
6263
packagedArtifactOwner: ObjectStackProtocolImplementation['packagedArtifactOwner'];
@@ -206,6 +207,71 @@ function sealedDeclareOrRenameClause(type: string, basePackageId: unknown, write
206207
return `Declare an override from '${pair.value}' or rename it to customize it`;
207208
}
208209

210+
// ─────────────────────────────────────────────────────────────────────────
211+
// ADR-0146 D11 — the package-less write onto a packaged item is closed
212+
// ─────────────────────────────────────────────────────────────────────────
213+
214+
/** The write a {@link packagelessOverlayWriteRefusal} judges: the four package-less writes ADR-0146 D11 closes. */
215+
export type PackagelessWriteOperation = 'save' | 'publish' | 'delete' | 'rollback';
216+
217+
/**
218+
* The body of `ObjectStackProtocolImplementation#packagelessOverlayWriteRefusal`;
219+
* the method's docblock there is its contract.
220+
*
221+
* [ADR-0146 D11] The closure of the package-less write onto a packaged item:
222+
* a write naming no package (`packageId` absent, `null` or empty) onto an item
223+
* a code package ships, of a type whose registry entry opens an overlay
224+
* channel ({@link PackagedBaseRefusalHost.isOverlayableManagedItem}: the five
225+
* `allowEnvironmentOverlay` types), is refused `403 NOT_OVERRIDABLE` — the
226+
* code and status the sealed write already answers, so no door gains a code.
227+
* Every other type's packaged item is sealed already
228+
* ({@link refusePackagedBaseOverride}), so after this no package-less write
229+
* reaches a packaged item at all.
230+
*
231+
* The sentence names the fix the writer has: the base's paired `.custom`
232+
* (`?package=<base>.custom`), where the customization is a declared override,
233+
* and `os migrate packageless-overlays`, the ceremony that moves a
234+
* package-less row stored before the close there. A row that ceremony has not
235+
* moved yet is still served (the read path is not this function's); only its
236+
* package-less write is refused, by this same sentence.
237+
*
238+
* `null` when the write names a package, or the item is no packaged item of an
239+
* overlay type: a name no package ships is environment metadata and keeps its
240+
* package-less write (ADR-0146 D11, "is not touched").
241+
*/
242+
export function packagelessOverlayWriteRefusal(
243+
this: Pick<PackagedBaseRefusalHost, 'isOverlayableManagedItem' | 'packagedArtifactOwner'>,
244+
request: { type: string; name: string; packageId?: string | null },
245+
operation: PackagelessWriteOperation,
246+
): Error | null {
247+
if (typeof request.packageId === 'string' && request.packageId.length > 0) return null;
248+
if (!this.isOverlayableManagedItem(request.type, request.name)) return null;
249+
const type = PLURAL_TO_SINGULAR[request.type] ?? request.type;
250+
const item = `'${type}/${request.name}'`;
251+
const owner = this.packagedArtifactOwner(request);
252+
const pairId = typeof owner === 'string' ? customizationPackageId(owner) : undefined;
253+
const pair = pairId?.ok ? `'${pairId.value}'` : 'the paired .custom package of the package that ships it';
254+
const query = pairId?.ok ? ` (?package=${pairId.value})` : '';
255+
const shipped = typeof owner === 'string' ? `ships in '${owner}'` : 'ships in an installed package';
256+
const declared = typeof owner === 'string' ? `overrides: { package: '${owner}', basedOn }` : 'overrides: { package, basedOn }';
257+
const ceremony = `A package-less customization stored before this release is still served: run \`os migrate packageless-overlays\` to move it into ${pair}`;
258+
const fix = operation === 'delete'
259+
? `Remove it from ${pair}${query}. ${ceremony} first.`
260+
: operation === 'rollback'
261+
? `${ceremony}, then roll it back there.`
262+
: operation === 'publish'
263+
? `Publish it into ${pair}${query}, declaring ${declared}. ${ceremony} first.`
264+
: `Save it into ${pair}${query}, declaring ${declared}. ${ceremony} first.`;
265+
const what = operation === 'rollback' ? 'a rollback of its package-less row' : 'a write naming no package';
266+
const err = new Error(
267+
`${item} ${shipped}, and ${what} onto a packaged item is closed: a customization of an installed package `
268+
+ `lives in its paired .custom package (ADR-0146 D11). ${fix}`,
269+
);
270+
(err as any).code = 'NOT_OVERRIDABLE';
271+
(err as any).status = 403;
272+
return err;
273+
}
274+
209275
// ─────────────────────────────────────────────────────────────────────────
210276
// ADR-0146 D2 — the override write gate (ruling A on decision card #28390)
211277
// ─────────────────────────────────────────────────────────────────────────

‎packages/metadata-protocol/src/protocol-packageless-overlay-migration.ts‎

Lines changed: 1 addition & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ import {
8888
} from '@objectstack/spec/kernel';
8989
import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from '@objectstack/spec/shared';
9090
import { storedRowDocument } from './item-lock.js';
91-
import { OVERLAY_MEMBER_COLUMN, overlayMemberValue } from './migrations/overlay-index.js';
91+
import { OVERLAY_MEMBER_COLUMN } from './migrations/overlay-index.js';
9292
import type { ObjectStackProtocolImplementation } from './protocol.js';
9393
import { shippingPackageIds } from './protocol-environment-rows.js';
9494
import { isServedOverrideRowOf } from './served-override.js';
@@ -524,73 +524,3 @@ export async function migratePackagelessOverlays(
524524
.sort((a, b) => a.base.localeCompare(b.base)),
525525
};
526526
}
527-
528-
// ─────────────────────────────────────────────────────────────────────────
529-
// Until #28576 closes the package-less write: a package-less save landing on
530-
// a migrated row keeps that row's declaration (N-16a, Wanted 4)
531-
// ─────────────────────────────────────────────────────────────────────────
532-
533-
/** The class members {@link packagelessPairLanding} reads. */
534-
export interface PackagelessPairLandingHost {
535-
readonly overlayTypes: ReadonlySet<string>;
536-
readonly packagelessAddress: ObjectStackProtocolImplementation['packagelessAddress'];
537-
readonly packagelessDraftAddress: ObjectStackProtocolImplementation['packagelessDraftAddress'];
538-
readonly findEnvironmentRows: ObjectStackProtocolImplementation['findEnvironmentRows'];
539-
}
540-
541-
/**
542-
* The declared override a package-less save of an overlay type lands on: when
543-
* the save's own address — {@link ObjectStackProtocolImplementation.packagelessAddress}
544-
* for a publish-mode save, {@link ObjectStackProtocolImplementation.packagelessDraftAddress}'s
545-
* `into` for a draft — is a base's paired `<base>.custom`, and that pair's row
546-
* of the item (the draft's own row first for a draft save, then the active
547-
* row) is the served override of the base ({@link isServedOverrideRowOf}),
548-
* answers the pair, the base and the row's `overrides` block. Otherwise
549-
* `undefined`: nothing changes for the save.
550-
*
551-
* Why the save asks it. After `os migrate packageless-overlays` moves Setup's
552-
* customization into the pair, Setup still saves and resets it naming no
553-
* package, and the package-less address lands that save on the pair's row
554-
* (sole binding). Setup's form sends the item as it read it — its `overrides`
555-
* key included, or not, depending on the editor — and a pair row saved without
556-
* its declaration is refused by the override write gate as an undeclared same
557-
* name (ADR-0146 D2, N-09). So the save keeps the row's declaration when the
558-
* body carries none, and judges a body that carries one as a write into the
559-
* pair, which is where it lands. #28576 closes the package-less write; this
560-
* goes with it.
561-
*/
562-
export async function packagelessPairLanding(
563-
this: PackagelessPairLandingHost,
564-
request: { type: string; name: string; mode?: string },
565-
member: string | undefined,
566-
): Promise<{ pair: string; base: string; declaration: Record<string, unknown> } | undefined> {
567-
const type = PLURAL_TO_SINGULAR[request.type] ?? request.type;
568-
if (!this.overlayTypes.has(type)) return undefined;
569-
const draft = request.mode === 'draft';
570-
let into: string | null;
571-
if (draft) {
572-
const address = await this.packagelessDraftAddress(type, request.name, member);
573-
if (address.kind === 'ambiguous') return undefined;
574-
into = address.into;
575-
} else {
576-
const address = await this.packagelessAddress(type, request.name, member, 'active');
577-
into = address.candidates.length === 1 ? address.packageId : null;
578-
}
579-
const base = typeof into === 'string' ? customizationBasePackageId(into) : null;
580-
if (base === null || into === null) return undefined;
581-
const rows = await this.findEnvironmentRows('sys_metadata', {
582-
where: { type, name: request.name, package_id: into },
583-
context: SYSTEM,
584-
});
585-
// The member as the row stores it: `null` (absent here) for the canonical one.
586-
const storedMember = overlayMemberValue(type, member) ?? undefined;
587-
const at = (state: 'active' | 'draft') =>
588-
(rows ?? []).find((row) => row?.state === state && memberOf(row) === storedMember);
589-
for (const row of draft ? [at('draft'), at('active')] : [at('active')]) {
590-
if (row === undefined || !isServedOverrideRowOf(row, base)) continue;
591-
const declaration = (bodyOf(row) as { overrides?: unknown } | undefined)?.overrides;
592-
if (declaration === null || typeof declaration !== 'object' || Array.isArray(declaration)) continue;
593-
return { pair: into, base, declaration: { ...(declaration as Record<string, unknown>) } };
594-
}
595-
return undefined;
596-
}

0 commit comments

Comments
 (0)