@wovin/core 0.2.2 → 0.3.2

package/dist/viewmodel/types.d.ts

@@ -0,0 +1,97 @@
+import type { ApplogValue, EntityID } from '../applog/datom-types.ts';
+import type { Thread } from '../thread/basic.ts';
+import type { ObjectBuilder } from './builder.ts';
+export interface VMAttributeDef {
+    /** Attribute name (short: e.g. 'name', 'content') */
+    name: string;
+    /** The wovin at-path used in applogs (e.g. 'block/content', 'speaker/name') */
+    atPath: string;
+    /** Whether the attribute is optional */
+    optional: boolean;
+    /** Default value if not present in applogs */
+    defaultValue?: ApplogValue;
+}
+/**
+ * A schema adapter converts a type-system schema (TypeBox, Zod, ArkType, Typia)
+ * into a uniform representation that the VM factory can consume.
+ */
+export interface ISchemaAdapter<T extends Record<string, ApplogValue> = Record<string, ApplogValue>> {
+    /** Get the attribute definitions for this schema */
+    getAttributeDefs(): VMAttributeDef[];
+    /** Get default values for all attributes */
+    getDefaults(): Partial<T>;
+    /** Optional: runtime validator */
+    createValidator?(): (value: unknown) => value is T;
+    /** The entity prefix used for wovin at-paths (e.g. 'block', 'speaker') */
+    getEntityPrefix(): string;
+}
+export interface ViewModelFactoryOptions<T extends Record<string, ApplogValue>> {
+    /** The schema adapter for this entity type */
+    adapter: ISchemaAdapter<T>;
+    /** How to get the default thread context */
+    getDefaultThread?: () => Thread;
+    /** EntityID generation length (default: 7) */
+    entityIdLength?: number;
+    /** Function to generate entity IDs */
+    generateEntityId?: (data: Partial<T> & {
+        ts?: string;
+    }) => EntityID;
+    /** Override the entity prefix for at-paths */
+    entityPrefix?: string;
+    /** Optional function to make thread current-state (lastWriteWins) */
+    makeCurrentThread?: (thread: Thread) => Thread;
+    /** Name for the VM type (used in logging and debugging) */
+    vmName?: string;
+    /**
+     * Signal adapter for framework-specific reactivity.
+     * Default: non-reactive (direct Subscribable reads).
+     * For SolidJS, pass createSolidSignalAdapter() from @wovin/ui-solid/viewmodel.
+     */
+    signalAdapter?: ISignalAdapter;
+}
+export interface IVMInstance<T extends Record<string, ApplogValue> = Record<string, ApplogValue>> {
+    readonly en: EntityID;
+    readonly thread: Thread;
+    /** Get a builder for updating this entity */
+    buildUpdate(init?: Partial<T>): ObjectBuilder<T>;
+    /** Soft-delete this entity */
+    setDeleted(thread?: Thread): void;
+    /** Whether this entity is deleted */
+    readonly isDeleted: boolean;
+    /** The entity thread filtered to this entity */
+    readonly entityThread: Thread;
+}
+export interface IVMClass<T extends Record<string, ApplogValue> = Record<string, ApplogValue>> {
+    new (en: EntityID, thread: Thread, ...args: any[]): IVMInstance<T>;
+    /** Get or create a VM instance for the given entity ID and thread */
+    get(en: EntityID, thread: Thread): IVMInstance<T>;
+    /** Create a new entity builder */
+    buildNew(init?: Partial<T>, en?: EntityID): ObjectBuilder<T>;
+}
+/**
+ * A signal adapter abstracts how the VM creates reactive signals for each attribute.
+ * The core factory uses a default (non-reactive) implementation.
+ * Framework-specific extensions (Solid, Vue, etc.) override this.
+ */
+export interface ISignalAdapter {
+    /**
+     * Create a reactive getter for a subscribable value.
+     * Returns a function that returns the current value.
+     * In the default implementation, this is just () => subscribable.value.
+     */
+    createGetter<T>(subscribable: {
+        value: T;
+        subscribe(cb: () => void): () => void;
+    }): () => T;
+    /**
+     * Create a writable signal for an attribute.
+     * Returns [get, set] pair.
+     * Default implementation stores and returns value directly.
+     */
+    createWritable<T>(initial: T): [() => T, (v: T) => void];
+}
+export type VMInstanceMap<T> = Map<EntityID, T>;
+/** WeakMap from Thread → Map<VMName, Map<EntityID, VMInstance>> */
+export declare const GlobalVMInstances: WeakMap<Thread, Map<string, Map<string, unknown>>>;
+export declare function getInstancesForThread(thread: Thread): Map<string, Map<EntityID, unknown>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/viewmodel/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/viewmodel/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wovin/core",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -57,6 +57,31 @@
       "import": "./dist/utils.js",
       "types": "./dist/utils.d.ts"
     },
+    "./viewmodel": {
+      "source": "./src/viewmodel/index.ts",
+      "import": "./dist/viewmodel/index.js",
+      "types": "./dist/viewmodel/index.d.ts"
+    },
+    "./viewmodel/adapters/typebox": {
+      "source": "./src/viewmodel/adapters/typebox.ts",
+      "import": "./dist/viewmodel/adapters/typebox.js",
+      "types": "./dist/viewmodel/adapters/typebox.d.ts"
+    },
+    "./viewmodel/adapters/zod": {
+      "source": "./src/viewmodel/adapters/zod.ts",
+      "import": "./dist/viewmodel/adapters/zod.js",
+      "types": "./dist/viewmodel/adapters/zod.d.ts"
+    },
+    "./viewmodel/adapters/arktype": {
+      "source": "./src/viewmodel/adapters/arktype.ts",
+      "import": "./dist/viewmodel/adapters/arktype.js",
+      "types": "./dist/viewmodel/adapters/arktype.d.ts"
+    },
+    "./viewmodel/adapters/typia": {
+      "source": "./src/viewmodel/adapters/typia.ts",
+      "import": "./dist/viewmodel/adapters/typia.js",
+      "types": "./dist/viewmodel/adapters/typia.d.ts"
+    },
     "./ipns": {
       "source": "./src/ipns.ts",
       "import": "./dist/ipns.js",
@@ -67,7 +92,6 @@
     "./dist/",
     "./src/"
   ],
-  "packageManager": "pnpm",
   "esm.sh": {
     "bundle": false
   },
@@ -88,8 +112,10 @@
     "lodash-es": "^4.17.21",
     "@libp2p/crypto": "^5.0.0",
     "ipns": "^10.1.2",
-    "multiformats": "^13.4.1",
+    "multiformats": "^14.0.0",
+    "partysocket": "^1.0.2",
     "safe-stable-stringify": "^2.5.0",
+    "w3name": "^1.1.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/applog/applog-utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import type { Applog } from './datom-types.ts'
-import { compareApplogsByTs, isLaterByTsAndPv, sortApplogsByTs } from './applog-utils.ts'
+import { compareApplogsByTs, deriveDeterministicEntityID, isLaterByTsAndPv, mintNewEntity, sortApplogsByTs } from './applog-utils.ts'
 
 const mkLog = (overrides: Partial<Applog>): Applog => ({
 	cid: 'cid-default' as any,
@@ -106,3 +106,45 @@ describe('isLaterByTsAndPv', () => {
 		expect(isLaterByTsAndPv(b, a)).toBe('other'.localeCompare('shared') > 0)
 	})
 })
+
+describe('deriveDeterministicEntityID — natural-key identity', () => {
+	it('is deterministic: same key ⇒ same id (write & read converge on one soul)', () => {
+		const a = deriveDeterministicEntityID({ type: 'segment', mediaId: 'm1', startMs: 0, endMs: 100 })
+		const b = deriveDeterministicEntityID({ type: 'segment', mediaId: 'm1', startMs: 0, endMs: 100 })
+		expect(a).toBe(b)
+	})
+
+	it('is stable across key property order (safe-stable-stringify)', () => {
+		const a = deriveDeterministicEntityID({ mediaId: 'm1', type: 'segment' })
+		const b = deriveDeterministicEntityID({ type: 'segment', mediaId: 'm1' })
+		expect(a).toBe(b)
+	})
+
+	it('different keys ⇒ different ids', () => {
+		expect(deriveDeterministicEntityID('#rust')).not.toBe(deriveDeterministicEntityID('#typescript'))
+	})
+
+	it('honors the requested length', () => {
+		expect(deriveDeterministicEntityID('#rust', 7)).toHaveLength(7)
+		expect(deriveDeterministicEntityID('#rust', 10)).toHaveLength(10)
+	})
+})
+
+describe('mintNewEntity — occurrence identity', () => {
+	it('re-minting the same logical seed with a fresh ts yields a DIFFERENT id (the re-mint trap)', () => {
+		// Documents why an existing entity must be resolved & its `en` reused rather than
+		// re-minted: a timestamp in the seed forks a new soul on every call.
+		const first = mintNewEntity({ msgId: 42, ts: '2026-06-16T00:00:00.000Z' })
+		const editedLater = mintNewEntity({ msgId: 42, ts: '2026-06-16T00:00:01.000Z' })
+		expect(first).not.toBe(editedLater)
+	})
+
+	it('is deterministic for an identical seed (same ts ⇒ same id)', () => {
+		const seed = { msgId: 42, ts: '2026-06-16T00:00:00.000Z' }
+		expect(mintNewEntity(seed)).toBe(mintNewEntity({ ...seed }))
+	})
+
+	it('honors the requested length', () => {
+		expect(mintNewEntity({ a: 1 }, 6)).toHaveLength(6)
+	})
+})

package/src/applog/applog-utils.ts

@@ -255,7 +255,35 @@ export const removeDuplicateAppLogs = (appLogArray: Applog[], mode?: RemoveDupli
 // 	return Array.from(logMap.values())
 // }
 
-export const getHashID = (stringifiable: any, lngth = 8) => cyrb53hash(stringify(stringifiable), 31, lngth) as string
+/** Low-level: stable-stringify + cyrb53 → hex entity id of `lngth` chars. Prefer the named wrappers below. */
+const hashToEntityId = (stringifiable: any, lngth = 8) => cyrb53hash(stringify(stringifiable), 31, lngth) as string
+
+/**
+ * Mint a brand-new entity id — coin a fresh "soul" for a genuinely new occurrence.
+ *
+ * The hashed `seed` MUST include something that makes this occurrence unique (a timestamp
+ * and/or random nonce), otherwise two distinct creations collide on one id.
+ *
+ * ⚠️ NEVER call this to re-reference an entity that already exists: doing so mints a *new*
+ * soul and forks a duplicate (breaking pv / lastWriteWins chains). To reference an existing
+ * entity, look it up and reuse its `en`. For identity that is *defined by* a stable key, use
+ * {@link deriveDeterministicEntityID}. See docs/architecture.md#entity-identity-soul.
+ */
+export const mintNewEntity = (seed: any, lngth = 8) => hashToEntityId(seed, lngth)
+
+/**
+ * Derive a deterministic entity id from a stable, identity-defining key.
+ *
+ * Same key ⇒ same `en`, so all references converge on one soul — used for both writing and
+ * reading the same entity (singleton / natural-key entities, e.g. a tag, a per-agent setting,
+ * a media segment).
+ *
+ * ⚠️ Use with care: two users/agents using the same name/key for something does NOT necessarily
+ * mean they mean the same thing/entity/soul. Only use when the key TRULY defines identity. The
+ * key must be canonicalized — diverging formats fork the soul and silently break lookups.
+ * See docs/architecture.md#entity-identity-soul.
+ */
+export const deriveDeterministicEntityID = (stableKey: any, lngth = 8) => hashToEntityId(stableKey, lngth)
 
 export function isVariable(x: any): x is string {
 	return typeof x === 'string' && x.startsWith('?')
@@ -324,21 +352,16 @@ export function matchPartStatic(field: keyof Applog, patternPart: ValueOrMatcher
 			result = patternPart === atomPart // shortcut for most common use-case
 		} else if (typ === 'function') {
 			result = (patternPart as Function)(atomPart)
-		} else if (Array.isArray(patternPart)) {
-			// A bare array is ambiguous now that `vl` may itself be an array value: it could
-			// mean set-membership or a literal-array match. Fail loudly rather than match wrong.
-			throw ERROR(
-				`[matchPartStatic] a bare array is not a valid matcher for field '${field}'.`
-					+ ` Use anyOf(...) for set-membership, or a predicate (v) => isEqual(v, [...]) to match a literal array value.`,
-				patternPart,
-			)
-		} else if (typeof (patternPart as any).has === 'function') {
-			result = (patternPart as Set<any>).has(atomPart)
+		} else if (patternPart instanceof Set) {
+			// A Set means set-membership (use anyOf(...) to build one). Bare arrays/objects are
+			// NOT membership — they are literal values compared by deep equality (see else).
+			result = patternPart.has(atomPart)
 		} // if (field === 'at' && typ === 'string' && patternPart.endsWith('*')) {
 		// 	return typeof atomPart === 'string' && atomPart.startsWith(patternPart.slice(0, -1))
 		// }
 		else {
-			// object/array values compare by deep equality; primitives via isEqual's === fast-path
+			// object/array values (and primitives) compare by deep equality;
+			// isEqual short-circuits on === so primitives stay on the cheap path
 			result = valueEq(patternPart as ApplogValue, atomPart)
 		}
 	} else {
@@ -368,15 +391,9 @@ export function matchPart(patternPart: ValueOrMatcher<ApplogValue>, atomPart: Ap
 	if (typeof patternPart === 'function') {
 		return patternPart(atomPart) ? context : null
 	}
-	if (Array.isArray(patternPart)) {
-		throw ERROR(
-			`[matchPart] a bare array is not a valid matcher.`
-				+ ` Use anyOf(...) for set-membership, or a predicate to match a literal array value.`,
-			patternPart,
-		)
-	}
-	if (patternPart && typeof (patternPart as any).has === 'function') {
-		return (patternPart as Set<any>).has(atomPart) ? context : null
+	if (patternPart instanceof Set) {
+		// set-membership (use anyOf(...)); bare arrays/objects are literal deep-equality matches below
+		return patternPart.has(atomPart) ? context : null
 	}
 	return valueEq(patternPart as ApplogValue, atomPart) ? context : null
 }

package/src/applog/datom-types.ts

@@ -118,12 +118,12 @@ type MapKeysStripPrefix<SELECT extends string, TPrefix extends string> = {
 }
 
 FormatRegistry.Set('CID', (value) => !!value.match(isCID))
-export const CIDTB = Type.String({ format: 'CID' })
+export const CIDTB = Type.String({ pattern: isCID.source })
 export type CIDTB = Static<typeof EntityID>
 
 const isURL = /^http([s]?):\/\/.*\..*/
 FormatRegistry.Set('URL', (value) => !!value.match(isURL))
-export const URL = Type.String({ format: 'URL' })
+export const URL = Type.String({ pattern: isURL.source })
 export type URL = Static<typeof URL>
 
 // Recursive JSON value: primitives plus nested arrays/objects (mirrors ApplogValue / JsonValue).

package/src/applog/object-values.test.ts

@@ -74,15 +74,12 @@ describe('object/array applog values', () => {
 		expect(index.get(valueKey({ a: 9 }))).toHaveLength(1)
 	})
 
-	it('matchPartStatic matches a literal object value by deep equality', () => {
+	it('matchPartStatic matches a literal object/array value by deep equality', () => {
 		expect(matchPartStatic('vl', { a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
 		expect(matchPartStatic('vl', { a: 1 }, { a: 2 })).toBe(false)
-	})
-
-	it('matching a literal array value requires a predicate (a bare array throws)', () => {
-		// bare arrays are reserved/rejected, so an array value is matched via a predicate
-		expect(matchPartStatic('vl', (v: any) => valueEq(v, [1, 2, 3]), [1, 2, 3])).toBe(true)
-		expect(() => matchPartStatic('vl', [1, 2, 3] as any, [1, 2, 3])).toThrow(/anyOf/)
+		// a bare array is a literal value, matched deeply (NOT set-membership)
+		expect(matchPartStatic('vl', [1, 2, 3], [1, 2, 3])).toBe(true)
+		expect(matchPartStatic('vl', [1, 2], [1, 2, 3])).toBe(false)
 	})
 
 	it('anyOf(...) provides set-membership and matches via matchPartStatic', () => {
@@ -96,8 +93,11 @@ describe('object/array applog values', () => {
 		expect(matchPartStatic('vl', isDark, { theme: 'light' })).toBe(false)
 	})
 
-	it('a bare array pattern fails loudly rather than matching ambiguously', () => {
-		expect(() => matchPartStatic('at', ['a', 'b'] as any, 'a')).toThrow(/anyOf/)
+	it('a bare array is a literal value, not set-membership (use anyOf for membership)', () => {
+		// ['a','b'] is the literal value to match, so it does NOT match the string 'a'
+		expect(matchPartStatic('at', ['a', 'b'], 'a')).toBe(false)
+		// membership is explicit via anyOf
+		expect(matchPartStatic('at', anyOf('a', 'b'), 'a')).toBe(true)
 	})
 
 	it('anyOf rejects object/array members (would silently never match)', () => {

package/src/ipfs/car.ts

@@ -69,11 +69,23 @@ export async function decodePubFromBlocks(
 			// New(er) format
 			if (!applogsCID) applogsCID = root.applogs  // Save from first snapshot
 			const applogsBlock = (await getDecodedBlock(blockStore, root.applogs)) as SnapBlockLogsOrChunks
+			if (!applogsBlock) {
+				throw ERROR('[decodePubFromBlocks] applogs block missing from blockStore', {
+					cid: root.applogs.toString(),
+					rootCID: cidStr,
+				})
+			}
 			pubLogsArray = await unchunkApplogsBlock(applogsBlock, blockStore)
 			// Info only from first (most recent) snapshot
 			if (!firstInfo) {
-				firstInfo = (await getDecodedBlock(blockStore, root.info)) as SnapBlockLogs
-				DEBUG(`new format - infoLogs`, firstInfo.logs.map(l => ({ [l.toString()]: l })))
+				const decoded = (await getDecodedBlock(blockStore, root.info)) as SnapBlockLogs
+				if (decoded) {
+					firstInfo = decoded
+					DEBUG(`new format - infoLogs`, firstInfo.logs.map(l => ({ [l.toString()]: l })))
+				} else {
+					WARN(`[decodePubFromBlocks] info block not found for ${root.info}, using empty info`)
+					firstInfo = { logs: [] }
+				}
 			}
 			// TODO: verify signatures
 		} else {

package/src/ipns/gateway-resolver.ts

@@ -0,0 +1,63 @@
+import { CID } from 'multiformats/cid'
+import { Logger } from 'besonders-logger'
+
+const { WARN, LOG, DEBUG } = Logger.setup(Logger.INFO) // eslint-disable-line unused-imports/no-unused-vars
+
+/**
+ * Resolve an IPNS name to a CID using a public IPFS gateway's HTTP HEAD response.
+ *
+ * Mechanism: per the IPFS HTTP Gateway spec, `HEAD <gateway>/ipns/<name>/` returns the
+ * IPNS-resolved root CID in the `X-Ipfs-Roots` response header (space-separated, ordered
+ * from root to leaf). The first entry is the IPNS-resolved CID.
+ *
+ * This works against any gateway that follows the spec and exposes CORS for HEAD
+ * (most public gateways do, e.g. ipfs.zt.ax, ipfs.io, dweb.link).
+ *
+ * The legacy w3name HTTP endpoint (`GET <base>/name/<ipns>` returning `{value: "/ipfs/<cid>"}`)
+ * is also supported here for back-compat with self-hosted w3name-like services — but the
+ * X-Ipfs-Roots path is preferred since it's the standardised gateway mechanism.
+ *
+ * @param ipns - The IPNS name (k51... string)
+ * @param gateways - List of gateway base URLs (e.g. `["https://ipfs.zt.ax"]`)
+ * @returns The resolved CID, or null if no gateway could resolve the name
+ */
+export async function resolveIPNSViaGateway(ipns: string, gateways: string[]): Promise<CID | null> {
+	if (!ipns.startsWith('k51')) return null // only IPNS libp2p-key names go through gateway
+	if (!gateways?.length) return null
+
+	for (const rawGateway of gateways) {
+		const gateway = rawGateway.replace(/\/+$/, '')
+		const url = `${gateway}/ipns/${ipns}/`
+		try {
+			DEBUG(`[resolveIPNSViaGateway] HEAD ${url}`)
+			const response = await fetch(url, { method: 'HEAD' })
+			if (!response.ok) {
+				DEBUG(`[resolveIPNSViaGateway] ${gateway} returned ${response.status}`)
+				continue
+			}
+			const roots = response.headers.get('x-ipfs-roots') ?? response.headers.get('X-Ipfs-Roots')
+			if (roots) {
+				const first = roots.split(/[\s,]+/)[0]?.trim()
+				if (first) {
+					const cid = CID.parse(first)
+					DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} x-ipfs-roots:`, cid.toString())
+					return cid
+				}
+			}
+			// Some gateways omit X-Ipfs-Roots but put the CID in etag (e.g. `<cid>.dag-json`)
+			const etag = response.headers.get('etag')
+			if (etag) {
+				const m = etag.match(/^"?([a-z0-9]+)/i)
+				if (m) {
+					const cid = CID.parse(m[1])
+					DEBUG(`[resolveIPNSViaGateway] resolved via ${gateway} etag:`, cid.toString())
+					return cid
+				}
+			}
+			WARN(`[resolveIPNSViaGateway] ${gateway} returned 200 but no usable CID header`)
+		} catch (err) {
+			WARN(`[resolveIPNSViaGateway] ${gateway} failed:`, err)
+		}
+	}
+	return null
+}