@kubohiroya/turbowarp-structured-data 0.6.2 → 0.6.3

package/README.ja.md

@@ -23,6 +23,8 @@ namespaceとloop contextがTurboWarp BlockUtilityのtarget/thread identityを使
 
 JSON/YAML入力は256 KiB、深さ64、50,000 valueまでです。YAML alias、warning、unknown tag、duplicate key、string以外のmap key、未対応scalarは拒否します。
 
+structured-data providerはnamed-data 0.4.0を介してbindingの任意の`schemaRef`を伝播できます。IDは`^[a-z][a-z0-9.-]{0,127}$`に一致し、versionは完全なSemVerである必要があります。Schema identityの解決は起動時固定で、明示的に有効化するまで既定OFFです。provider読み込み前に`globalThis.__TW_NAMED_DATA_FEATURE_FLAGS__ = {NAMED_DATA_SCHEMA_REF: true}`を設定します。参照はbindingの安定IDと完全なSemVer versionに一致する必要があります。providerはSchema本体を保持せず、別versionへのfallbackもしません。consumerは自身のSchema catalogでidentityを解決し、既存のJSON Schema実装で値を検証します。合意するsubsetは`type`、`properties`、`required`、Boolean形式の`additionalProperties`、`items`、`enum`、`const`、数値範囲、文字列／配列の長さ制約です。未対応keywordは検証動作を追加しません。flagをOFFにすればschema identityなしのmetadataへ即時に戻せます。
+
 ## クイックスタート
 
 ```text

package/README.md

@@ -22,10 +22,22 @@ The `STRUCTURED_DATA_MVP` feature flag is fixed at extension startup and default
 
 JSON and YAML input is limited to 256 KiB, nesting depth 64, and 50,000 values. YAML aliases, warnings, unknown tags, duplicate keys, non-string map keys, and unsupported scalar types are rejected.
 
+The structured-data provider can carry a binding's optional `schemaRef` through named-data 0.4.0.
+The ID must match `^[a-z][a-z0-9.-]{0,127}$` and the version must be a complete SemVer version.
+Schema identity resolution is a startup-fixed opt-in and defaults to `false`; configure
+`globalThis.__TW_NAMED_DATA_FEATURE_FLAGS__ = {NAMED_DATA_SCHEMA_REF: true}` before loading the
+provider. A request must match the binding's stable ID and full SemVer version exactly. The
+provider does not store schema documents or choose a fallback version. Consumers resolve the
+identity in their own schema catalog and validate the returned value with their existing JSON
+Schema implementation. The agreed subset is `type`, `properties`, `required`,
+`additionalProperties` (boolean), `items`, `enum`, `const`, numeric bounds, and string/array
+length bounds; unsupported keywords do not add validation behavior. Turn the flag off to
+immediately return to metadata without schema identities.
+
 ## Installation
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-structured-data@0.6.2
+pnpm add --save-exact @kubohiroya/turbowarp-structured-data@0.6.3
 ```
 
 ## Quick start

package/dist/structured-data.js

@@ -7,6 +7,10 @@
 (function (Scratch) {
   'use strict';
 
+  function isNamedDataSchemaRefEnabled(source = globalThis) {
+  	const value = source.__TW_NAMED_DATA_FEATURE_FLAGS__?.NAMED_DATA_SCHEMA_REF;
+  	return value === void 0 ? false : value === true || value === "true";
+  }
   function isStructuredDataMvpEnabled(source = globalThis) {
   	const value = source.STRUCTURED_DATA_MVP;
   	return value === void 0 ? false : value === true || value === "true";
@@ -6799,6 +6803,7 @@
   			...opened.digest === void 0 ? {} : { digest: opened.digest },
   			revision: opened.revision,
   			replayable: opened.replayable,
+  			...opened.schemaRef === void 0 ? {} : { schemaRef: opened.schemaRef },
   			body: opened.body,
   			release: tracked.release
   		});
@@ -6964,9 +6969,10 @@
   var STRUCTURED_DATA_NAMESPACE = "structured";
   var STRUCTURED_BODY_MAX_BYTES = 262144;
   var StructuredDataNamedDataProvider = class {
-  	constructor(store, maxBodyBytes = STRUCTURED_BODY_MAX_BYTES) {
+  	constructor(store, maxBodyBytes = STRUCTURED_BODY_MAX_BYTES, schemaRefEnabled = isNamedDataSchemaRefEnabled()) {
   		this.store = store;
   		this.maxBodyBytes = maxBodyBytes;
+  		this.schemaRefEnabled = schemaRefEnabled;
   		this.namespace = STRUCTURED_DATA_NAMESPACE;
   		this.kind = "structured";
   		this.openBodies = /* @__PURE__ */ new Set();
@@ -6977,7 +6983,7 @@
   	}
   	stat(reference, representation, context) {
   		const resolved = this.resolve(reference, representation, context);
-  		return this.metadata(reference, resolved.nativeRepresentation, representation, resolved.bytes.byteLength, resolved.revision);
+  		return this.metadata(reference, resolved.nativeRepresentation, representation, resolved.bytes.byteLength, resolved.revision, resolved.schemaRef);
   	}
   	openBody(reference, representation, context) {
   		const resolved = this.resolve(reference, representation, context);
@@ -6985,7 +6991,7 @@
   		this.openBodies.add(handle);
   		let released = false;
   		return {
-  			...this.metadata(reference, resolved.nativeRepresentation, representation, resolved.bytes.byteLength, resolved.revision),
+  			...this.metadata(reference, resolved.nativeRepresentation, representation, resolved.bytes.byteLength, resolved.revision, resolved.schemaRef),
   			body: resolved.bytes,
   			release: () => {
   				if (released) return;
@@ -7007,6 +7013,9 @@
   		this.throwIfAborted(context.signal);
   		const binding = this.store.get(context.target, reference.name);
   		if (!binding) throw new NamedDataError("NAMED_DATA_NOT_FOUND", `Structured data does not exist: ${reference.name}`);
+  		const requestedSchemaRef = reference.schemaRef;
+  		if (requestedSchemaRef !== void 0 && !this.schemaRefEnabled) throw new NamedDataError("NAMED_DATA_SCHEMA_UNRESOLVED", "Schema reference resolution is disabled.");
+  		if (requestedSchemaRef !== void 0 && (binding.schemaRef?.id !== requestedSchemaRef.id || binding.schemaRef?.version !== requestedSchemaRef.version)) throw new NamedDataError("NAMED_DATA_SCHEMA_VERSION_MISMATCH", "Binding schemaRef does not match the requested reference.");
   		const text = this.render(binding.value, representation);
   		const bytes = new TextEncoder().encode(text);
   		if (bytes.byteLength > this.maxBodyBytes) throw new NamedDataError("NAMED_DATA_BODY_TOO_LARGE", `Encoded body is ${bytes.byteLength} bytes; maximum is ${this.maxBodyBytes}.`);
@@ -7014,7 +7023,8 @@
   		return {
   			bytes,
   			revision: binding.revision,
-  			nativeRepresentation: binding.nativeRepresentation
+  			nativeRepresentation: binding.nativeRepresentation,
+  			...requestedSchemaRef === void 0 ? {} : { schemaRef: binding.schemaRef }
   		};
   	}
   	validateReference(reference, context) {
@@ -7027,7 +7037,7 @@
   		if (representation === "yaml") return renderYamlDocument(value);
   		throw new NamedDataError("NAMED_DATA_REPRESENTATION_UNSUPPORTED", `Structured data cannot be rendered as ${representation}.`);
   	}
-  	metadata(reference, nativeRepresentation, representation, byteLength, revision) {
+  	metadata(reference, nativeRepresentation, representation, byteLength, revision, schemaRef) {
   		return {
   			reference: { ...reference },
   			nativeRepresentation,
@@ -7035,7 +7045,8 @@
   			mediaType: representation === "json" ? "application/json; charset=utf-8" : "application/yaml; charset=utf-8",
   			byteLength,
   			revision: String(revision),
-  			replayable: true
+  			replayable: true,
+  			...schemaRef === void 0 ? {} : { schemaRef }
   		};
   	}
   	throwIfAborted(signal) {

package/lib-editor/src/config.d.ts

@@ -1,5 +1,11 @@
 export declare const STRUCTURED_DATA_MVP_DEFAULT = false;
 export declare const NAMED_DATA_REGISTRY_MVP_DEFAULT = false;
+export declare const NAMED_DATA_SCHEMA_REF_DEFAULT = false;
+export declare function isNamedDataSchemaRefEnabled(source?: {
+    __TW_NAMED_DATA_FEATURE_FLAGS__?: {
+        NAMED_DATA_SCHEMA_REF?: unknown;
+    };
+}): boolean;
 export declare function isStructuredDataMvpEnabled(source?: {
     STRUCTURED_DATA_MVP?: unknown;
 }): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-structured-data",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Named structured data with JSON/YAML codecs and deterministic path operations for TurboWarp.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "license": "MPL-2.0",
@@ -61,7 +61,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@kubohiroya/turbowarp-extension-manifest": "0.3.2",
-    "@kubohiroya/turbowarp-named-data": "0.3.1",
+    "@kubohiroya/turbowarp-named-data": "0.4.0",
     "@kubohiroya/vite-plugin-turbowarp-extension": "0.6.1",
     "@types/node": "^24.13.3",
     "eslint": "^9.39.5",
@@ -71,17 +71,18 @@
     "vite": "^8.2.2",
     "vitest": "^5.0.0",
     "react-dom": "18.3.1",
-    "@kubohiroya/turbowarp-extension-data-editor": "0.2.1"
+    "@kubohiroya/turbowarp-extension-data-editor": "0.2.1",
+    "@kubohiroya/turbowarp-named-functions": "0.1.1"
   },
   "dependencies": {
     "yaml": "^2.9.1"
   },
   "peerDependencies": {
-    "@kubohiroya/turbowarp-named-data": "0.3.1"
+    "@kubohiroya/turbowarp-named-data": ">=0.4.0 <1"
   },
-  "gitHead": "385a31c2a7957b51003686fab0b2d76199db705a",
+  "gitHead": "870ebcaa4071e0eacb4d36a6d9e98734e51f2361",
   "x-turbowarp-source": {
-    "revision": "385a31c2a7957b51003686fab0b2d76199db705a",
+    "revision": "870ebcaa4071e0eacb4d36a6d9e98734e51f2361",
     "revisionRole": "base-commit",
     "sourceState": "local-release-overlay"
   },

package/src/config.ts

@@ -1,5 +1,16 @@
 export const STRUCTURED_DATA_MVP_DEFAULT = false;
 export const NAMED_DATA_REGISTRY_MVP_DEFAULT = false;
+export const NAMED_DATA_SCHEMA_REF_DEFAULT = false;
+
+export function isNamedDataSchemaRefEnabled(
+  source: {__TW_NAMED_DATA_FEATURE_FLAGS__?: {NAMED_DATA_SCHEMA_REF?: unknown}} =
+    globalThis as {__TW_NAMED_DATA_FEATURE_FLAGS__?: {NAMED_DATA_SCHEMA_REF?: unknown}}
+): boolean {
+  const value = source.__TW_NAMED_DATA_FEATURE_FLAGS__?.NAMED_DATA_SCHEMA_REF;
+  return value === undefined
+    ? NAMED_DATA_SCHEMA_REF_DEFAULT
+    : value === true || value === 'true';
+}
 
 export function isStructuredDataMvpEnabled(
   source: {STRUCTURED_DATA_MVP?: unknown} = globalThis as {STRUCTURED_DATA_MVP?: unknown}

package/src/structured-provider.ts

@@ -1,4 +1,5 @@
 import {renderJsonDocument, renderYamlDocument} from './codecs.js';
+import {isNamedDataSchemaRefEnabled} from './config.js';
 import type {JsonValue} from './core.js';
 import {
   NamedDataError,
@@ -6,6 +7,7 @@ import {
   type NamedDataMetadata,
   type NamedDataProvider,
   type NamedDataReference,
+  type NamedDataSchemaRef,
   type NamedDataRepresentation,
   type NamedDataResolveContext
 } from '@kubohiroya/turbowarp-named-data/composition';
@@ -17,6 +19,7 @@ export interface StructuredDataBinding {
   value: JsonValue;
   revision: number;
   nativeRepresentation: 'json' | 'yaml';
+  schemaRef?: NamedDataSchemaRef;
 }
 
 export interface StructuredDataBindingStore {
@@ -31,7 +34,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
 
   public constructor(
     private readonly store: StructuredDataBindingStore,
-    private readonly maxBodyBytes = STRUCTURED_BODY_MAX_BYTES
+    private readonly maxBodyBytes = STRUCTURED_BODY_MAX_BYTES,
+    private readonly schemaRefEnabled = isNamedDataSchemaRefEnabled()
   ) {}
 
   public canResolve(
@@ -57,7 +61,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
       resolved.nativeRepresentation,
       representation,
       resolved.bytes.byteLength,
-      resolved.revision
+      resolved.revision,
+      resolved.schemaRef
     );
   }
 
@@ -76,7 +81,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
         resolved.nativeRepresentation,
         representation,
         resolved.bytes.byteLength,
-        resolved.revision
+        resolved.revision,
+        resolved.schemaRef
       ),
       body: resolved.bytes,
       release: () => {
@@ -100,7 +106,12 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     reference: NamedDataReference,
     representation: NamedDataRepresentation,
     context: NamedDataResolveContext
-  ): {bytes: Uint8Array; revision: number; nativeRepresentation: 'json' | 'yaml'} {
+  ): {
+    bytes: Uint8Array;
+    revision: number;
+    nativeRepresentation: 'json' | 'yaml';
+    schemaRef?: NamedDataSchemaRef;
+  } {
     if (this.released) {
       throw new NamedDataError('NAMED_DATA_PROVIDER_RELEASED', 'The structured provider was released.');
     }
@@ -113,6 +124,23 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
         `Structured data does not exist: ${reference.name}`
       );
     }
+    const requestedSchemaRef = reference.schemaRef;
+    if (requestedSchemaRef !== undefined && !this.schemaRefEnabled) {
+      throw new NamedDataError(
+        'NAMED_DATA_SCHEMA_UNRESOLVED',
+        'Schema reference resolution is disabled.'
+      );
+    }
+    if (
+      requestedSchemaRef !== undefined &&
+      (binding.schemaRef?.id !== requestedSchemaRef.id ||
+        binding.schemaRef?.version !== requestedSchemaRef.version)
+    ) {
+      throw new NamedDataError(
+        'NAMED_DATA_SCHEMA_VERSION_MISMATCH',
+        'Binding schemaRef does not match the requested reference.'
+      );
+    }
     const text = this.render(binding.value, representation);
     const bytes = new TextEncoder().encode(text);
     if (bytes.byteLength > this.maxBodyBytes) {
@@ -125,7 +153,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     return {
       bytes,
       revision: binding.revision,
-      nativeRepresentation: binding.nativeRepresentation
+      nativeRepresentation: binding.nativeRepresentation,
+      ...(requestedSchemaRef === undefined ? {} : {schemaRef: binding.schemaRef})
     };
   }
 
@@ -164,7 +193,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
     nativeRepresentation: 'json' | 'yaml',
     representation: NamedDataRepresentation,
     byteLength: number,
-    revision: number
+    revision: number,
+    schemaRef?: NamedDataSchemaRef
   ): NamedDataMetadata {
     return {
       reference: {...reference},
@@ -176,7 +206,8 @@ export class StructuredDataNamedDataProvider implements NamedDataProvider {
           : 'application/yaml; charset=utf-8',
       byteLength,
       revision: String(revision),
-      replayable: true
+      replayable: true,
+      ...(schemaRef === undefined ? {} : {schemaRef})
     };
   }