@spinekit/assets 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.1.1 — 2026-08-20
+
+### Changed
+- **License:** relicensed from MIT to the **Classytic Source-Available License**
+  (Community & Commercial). Evaluation and development use remain free; production
+  use now requires a commercial license from Classytic LLC. See `LICENSE`.
+
+### Notes
+- First stable **1.0.0** release of the Classytic `arc` suite. Versions published
+  before 1.0.0 remain under their original MIT terms; the new license applies from
+  1.0.0 onward.
+
+## 0.2.0 — 2026-07-20 (amended 2026-07-21, pre-publish)
+
+- **Engine teardown symmetry**: a module-created engine now registers `onClose` → `engine.destroy()` (closes the kernel's event transport); a BYO engine is never closed by the module.
+
+- **scheduledJobs arm**: assetsMaintenanceSchedules (automated depreciation posting, daily) wired into createAssetsModule (factory form — resolves post-bootstrap); opt out with maintenance: false (the deployment-tier decision stays host policy). Peer floor raised @classytic/arc >=2.24.0.
+- TENANCY: sweeps default to a bare cron context; tenant-enabled engines (the kernel default) MUST pass maintenance.context (org scoping) or set maintenance:false — otherwise every tick fails behind arc's fail-open scheduler. Company-wide hosts need nothing.
+- **owns colocation (PACKAGE_RULES §1.5)**: createAssetsModule now declares `ArcModule.owns: ['fixed-asset']`, mirroring its single resource. Hosts remove their hand-maintained supersession lists.
+- Long-interval schedules set explicit leaseMs (~90% of every) — arc's default lease caps at 5min, which would let independently-phased replicas re-run hourly/daily sweeps.
+- Sweep is sequential per asset (idempotent via dep:<scheduleId>:<sequence>); large registers (10k+ assets) should expect a long daily tick — batching is a known future hardening.
+
+## 0.1.1 — 2026-07-18
+
+- Peer floor bumps: `@classytic/arc >=2.23.0`, `@classytic/assets >=0.4.1`,
+  `@classytic/mongokit >=3.23.0` (tracks assets 0.4 API surface + arc 2.23
+  module system).
+- Integrated `permissionMatrix` from `@classytic/arc/permissions` for
+  fine-grained action-level gates on lifecycle transition and valuation routes.
+- Dev toolchain: `tsdown ^0.22.5`, `typescript ^7.0.2`.
+
+## 0.1.1 — 2026-07-11
+
+Initial release.
+
+- **`createAssetsModule(deps)`** — single composition surface that boots the
+  `@classytic/assets` engine (or accepts a BYO engine via `deps.engine` for
+  strangler migrations) and mounts an arc resource serving the full fixed-asset
+  register API: acquisition, lifecycle transitions (commission, place-in-service,
+  retire, dispose), 6-method multi-book depreciation (straight-line, declining-
+  balance, double-declining, sum-of-years, units-of-production, MACRS), IAS 16
+  revaluation, IAS 36 impairment, IAS 8 estimate changes, market/appraisal value
+  history, and disposal with gain/loss calculation.
+- **Ledger bridge injection** — `deps.ledger` (sync or `(app) => LedgerPort`) wires
+  journal posting for depreciation + disposal entries; omit to run without GL
+  posting (read-only register or deferred wiring).
+- **Host-policy surface** — `currency`, `categoryEnum`, `tenantField`, `prefix`,
+  `schemaOptions` let the host inject IAS classification codes, functional currency,
+  and tenant scoping without forking the module.
+- **Event transport + outbox** — `deps.eventTransport` / `deps.outbox` thread through
+  to the engine for durable lifecycle event delivery.
+- Peers: `@classytic/arc >=2.20.0`, `@classytic/assets >=0.3.0`,
+  `@classytic/mongokit >=3.19.0`, `mongoose >=9.4.1`.

package/LICENSE

@@ -0,0 +1,75 @@
+Classytic Source-Available License (Community & Commercial), Version 1.0
+
+Copyright (c) 2026 Classytic LLC. All rights reserved.
+
+This software is source-available, not open source. Please read this License
+before using it.
+
+1. DEFINITIONS
+   "Software" means the contents of this package and any accompanying source
+   code, object code, or documentation, in any form.
+   "Licensor" means Classytic LLC, a limited liability company organized in the
+   United States.
+   "You" means the individual or legal entity exercising rights under this
+   License.
+   "Evaluation Use" means use for evaluation, development, testing,
+   experimentation, or internal non-commercial purposes only.
+   "Production Use" means any use of the Software that is live, commercial,
+   revenue-generating, or customer-facing, or any use other than Evaluation Use.
+   "Commercial License" means a separate written agreement executed with
+   Licensor that grants Production Use rights.
+
+2. OWNERSHIP
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   All rights not expressly granted in this License are reserved by Licensor.
+
+3. EVALUATION GRANT
+   Subject to Your compliance with this License, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable, revocable license
+   to download, install, run, and modify the Software solely for Evaluation Use.
+
+4. PRODUCTION USE REQUIRES A COMMERCIAL LICENSE
+   Production Use of the Software is NOT permitted under this License and
+   requires a Commercial License from Licensor. A Commercial License may be
+   granted at Licensor's discretion, with or without a fee, and may confer
+   perpetual, irrevocable, and transferable Production Use rights as set out in
+   that agreement. Contact licensing@classytic.com to obtain one.
+
+5. RESTRICTIONS
+   You may not:
+   (a) make any Production Use of the Software without a Commercial License;
+   (b) redistribute, resell, rent, sublicense, or otherwise make the Software
+       (in whole or in part, original or modified) available to third parties as
+       a stand-alone product, framework, library, or hosted/managed service that
+       competes with the Software or with Licensor;
+   (c) remove, obscure, or alter any copyright, license, or attribution notice.
+
+6. FEEDBACK AND CONTRIBUTIONS
+   Any feedback, suggestions, or contributions You provide relating to the
+   Software may be used by Licensor for any purpose without obligation to You.
+
+7. TERMINATION
+   This License and the Evaluation Grant terminate automatically if You breach
+   any term. Upon termination You must cease all use of the Software and destroy
+   all copies in Your possession. Rights under a Commercial License are governed
+   by that agreement's own terms and survive termination of this License to the
+   extent stated there.
+
+8. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE
+   FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+10. GOVERNING LAW
+   This License is governed by the laws of the State of Delaware, United States,
+   without regard to its conflict-of-laws principles. (Adjust to Your LLC's state
+   of formation.)
+
+For commercial licensing, contact: licensing@classytic.com

package/README.md

@@ -0,0 +1,41 @@
+# @spinekit/assets
+
+> Arc module for @classytic/assets — fixed-asset register + multi-book depreciation + IAS 16/36 valuation as composable resources.
+
+Part of **Spine**, Classytic's ERP — the arc-module layer composed into an
+[`@classytic/arc`](https://www.npmjs.com/package/@classytic/arc) application via
+`createApp({ modules })`.
+
+## Install
+
+```sh
+npm install @spinekit/assets @classytic/arc @classytic/mongokit mongoose zod
+```
+
+Kernels and the framework are **peer dependencies** — the host installs a single
+copy; this module bundles nothing.
+
+## Usage
+
+```ts
+import { createApp } from '@classytic/arc/factory';
+import { createAssetsModule } from '@spinekit/assets';
+
+const app = await createApp({
+  modules: [
+    createAssetsModule({
+      connection,    // your mongoose connection
+      permissions,   // role gates
+      // BYO engine + host seams (extraActions, extraRoutes, bridges) as needed
+    }),
+  ],
+});
+```
+
+> This is a standard scaffold — expand Usage with the module's specific options.
+
+## License
+
+Proprietary — Classytic Source-Available License (see [LICENSE](LICENSE)).
+Free for evaluation/development; production use requires a commercial license
+from Classytic LLC.

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+import { SpineTenantInput } from "@spinekit/kit/tenant";
+import { AssetsContext, AssetsEngine, LedgerPort } from "@classytic/assets";
+import { ScheduleDefinition } from "@classytic/arc/plugins";
+import { PermissionGate } from "@spinekit/kit/permissions";
+import { EventTransport } from "@classytic/primitives/events";
+import { OutboxStore } from "@classytic/primitives/outbox";
+import { Connection } from "mongoose";
+import { FastifyInstance } from "fastify";
+//#region src/schedules.d.ts
+interface AssetsMaintenanceOptions {
+  /** Automated depreciation posting sweep interval. Default daily (with jitter). */
+  depreciationEvery?: number;
+  /**
+   * Extra kernel-context fields merged over the default `{ actorId: 'cron' }`.
+   * REQUIRED when the host composes the register tenant-scoped (`tenantField`
+   * set): an org-less sweep then fails per-asset under the tenant plugin —
+   * `posted: 0` forever with only error logs. Company-wide registers
+   * (`tenantField: false`, the module default) need nothing.
+   */
+  context?: Partial<AssetsContext>;
+}
+declare function assetsMaintenanceSchedules(engine: AssetsEngine, options?: AssetsMaintenanceOptions): ScheduleDefinition[];
+//#endregion
+//#region src/index.d.ts
+interface AssetsPermissions {
+  /** Read register / schedules / valuations. */
+  view: PermissionGate;
+  /** Acquire, lifecycle transitions, valuation, onboard. */
+  manage: PermissionGate;
+}
+interface AssetsModuleDeps {
+  connection: Connection;
+  /** BYO engine (strangler) - module skips engine creation. */
+  engine?: AssetsEngine;
+  permissions: AssetsPermissions;
+  /**
+   * GL bridge (host policy - category -> chart account). Function form
+   * receives the live app so a host composing arc-accounting FIRST wires
+   * off f.arc.modules.accounting. Omit to run without journal posting.
+   */
+  ledger?: LedgerPort | ((app: FastifyInstance) => LedgerPort | undefined);
+  /**
+   * Modules that MUST bootstrap before this one (arc 2.20 topological order).
+   *
+   * Defaults to `['accounting']` when `ledger` is given in FACTORY form, since
+   * that factory reads `f.arc.modules.accounting`. Without the edge the
+   * factory can receive an undefined module and yield `undefined`, which
+   * silently disables depreciation/disposal journal posting on a financial
+   * register. Pass `[]` to opt out, or a list to add edges.
+   */
+  dependsOn?: readonly string[];
+  /** Functional currency for money fields (ISO 4217). Host-owned — a money
+   *  module must know its currency; there is no jurisdiction default. */
+  currency: string;
+  /** Allowed category values (host policy - NBR/IFRS classes). */
+  categoryEnum?: readonly string[];
+  /** Canonical persistence tenancy. Default false (company-wide register). */
+  tenant?: SpineTenantInput;
+  /** Route prefix. Default /assets. */
+  prefix?: string;
+  /** Extra mongoose schema fields (e.g. host category enum on category). */
+  schemaOptions?: Record<string, unknown>;
+  eventTransport?: EventTransport;
+  outbox?: OutboxStore;
+  /**
+   * Re-register the asset models when they are already on the connection.
+   *
+   * Mongoose locks a schema on the first `model()` call, so a second
+   * registration cannot add fields or indexes — it can only silently drop them,
+   * which is why mongokit refuses instead. Right for production; wrong for a
+   * suite that boots the app twice on one connection, and this module had no way
+   * to say so. (mongokit itself refuses `replace` under NODE_ENV=production, so
+   * this cannot become a production hot-reload path.)
+   */
+  forceRecreate?: boolean;
+  /**
+   * Accept a backend without multi-document transactions. DEV/TEST ONLY.
+   *
+   * Depreciation posting writes the schedule row and its journal entry
+   * together, so the kernel wants a replica set. Absent, this module built an
+   * engine that REFUSED to bind on a standalone mongod — the host could only
+   * get past it by constructing the engine itself, which is exactly the BYO
+   * escape hatch this arm removes the need for.
+   */
+  allowNonTransactional?: boolean;
+  /**
+   * Automated-depreciation sweep interval. Omit for the daily default; pass
+   * `false` to opt OUT of the `scheduledJobs` arm — the DEPLOYMENT-TIER
+   * decision (auto-posting vs the manual `post-period` action) is host policy.
+   * See `assetsMaintenanceSchedules`.
+   */
+  maintenance?: AssetsMaintenanceOptions | false;
+}
+/**
+ * Build the fixed-asset resource over a live assets engine. Exported so a
+ * host can mount it directly (custom module composition).
+ */
+declare function createAssetResource(args: {
+  engine: AssetsEngine;
+  permissions: AssetsPermissions;
+  /** ISO 4217 — host-owned, required (a money module has no default currency). */
+  currency: string;
+  categoryEnum?: readonly string[];
+  prefix?: string;
+}): import("@classytic/arc").ResourceDefinition<import("@classytic/assets").AssetDocument | (import("mongoose").Document<unknown, {}, import("@classytic/assets").AssetDocument, {}, import("mongoose").DefaultSchemaOptions> & import("@classytic/assets").Asset & import("mongoose").Document<import("mongoose").Types.ObjectId, any, any, Record<string, any>, {}> & {
+  id: string;
+})>;
+declare function createAssetsModule(deps: AssetsModuleDeps): import("@classytic/arc/factory").ArcModule<AssetsEngine>;
+//#endregion
+export { type AssetsMaintenanceOptions, AssetsModuleDeps, AssetsPermissions, assetsMaintenanceSchedules, createAssetResource, createAssetsModule };

package/dist/index.mjs

@@ -0,0 +1,817 @@
+import { defineEngineModule } from "@spinekit/kit/engine-module";
+import { resolveSpineTenant } from "@spinekit/kit/tenant";
+import { defineResource } from "@classytic/arc";
+import { permissionMatrix } from "@classytic/arc/permissions";
+import { scopeFirstCtx } from "@classytic/arc/scope";
+import { ValidationError } from "@classytic/arc/utils";
+import { createMongooseAdapter } from "@classytic/mongokit/adapter";
+import { QueryParser } from "@classytic/mongokit";
+import { DEPRECIATION_METHODS, defineAssets } from "@classytic/assets";
+import { isCurrencyCode } from "@classytic/primitives/currency";
+import { money } from "@classytic/primitives/money";
+//#region src/schedules.ts
+const DAY = 864e5;
+function assetsMaintenanceSchedules(engine, options = {}) {
+	return [{
+		name: "assets.depreciation",
+		every: options.depreciationEvery ?? DAY,
+		leaseMs: Math.floor((options.depreciationEvery ?? DAY) * .9),
+		jitterMs: 9e5,
+		handler: async (fastify) => {
+			const ctx = {
+				actorId: "cron",
+				...options.context
+			};
+			const now = /* @__PURE__ */ new Date();
+			const active = await engine.models.FixedAsset.find({
+				status: "active",
+				deletedAt: null
+			}).select("_id name").lean();
+			let posted = 0;
+			for (const asset of active) try {
+				const schedule = await engine.repositories.schedule.findByAssetAndBook(String(asset._id), "accounting", ctx);
+				if (!schedule) continue;
+				const due = schedule.periods.filter((per) => per.status === "scheduled" && new Date(per.periodEnd) <= now).sort((a, b) => a.sequence - b.sequence);
+				for (const per of due) {
+					await engine.services.depreciation.postPeriod(String(asset._id), per.sequence, {}, ctx);
+					posted += 1;
+				}
+			} catch (err) {
+				fastify.log.error({
+					err,
+					assetId: String(asset._id)
+				}, "Depreciation posting failed for asset");
+			}
+			if (posted > 0) fastify.log.info({ posted }, "Depreciation periods auto-posted");
+		}
+	}];
+}
+//#endregion
+//#region src/index.ts
+const createAssetWireBody = {
+	type: "object",
+	required: [
+		"assetNumber",
+		"name",
+		"depreciation"
+	],
+	properties: {
+		assetNumber: {
+			type: "string",
+			minLength: 1
+		},
+		name: {
+			type: "string",
+			minLength: 1
+		},
+		category: {
+			type: "string",
+			description: "Default: 'office_equipment'"
+		},
+		cost: {
+			type: "integer",
+			minimum: 0,
+			description: "Acquisition cost in minor units (paisa)"
+		},
+		salvageValue: {
+			type: "integer",
+			minimum: 0,
+			description: "Salvage value in minor units"
+		},
+		depreciation: {
+			type: "object",
+			required: ["method", "periods"],
+			properties: {
+				method: {
+					type: "string",
+					enum: [...DEPRECIATION_METHODS]
+				},
+				periods: {
+					type: "integer",
+					minimum: 1
+				},
+				decliningRate: {
+					type: "number",
+					exclusiveMinimum: 0,
+					exclusiveMaximum: 1
+				},
+				totalUnits: {
+					type: "integer",
+					minimum: 1
+				},
+				manualSchedule: {
+					type: "array",
+					items: { type: "integer" }
+				}
+			}
+		},
+		placedInServiceAt: {
+			type: "string",
+			description: "Date — parsed by the service"
+		},
+		location: { type: "string" },
+		custodian: { type: "string" },
+		branchId: { type: "string" },
+		sourceId: { type: "string" },
+		sourceModel: { type: "string" },
+		metadata: {
+			type: "object",
+			additionalProperties: true
+		}
+	}
+};
+const updateAssetWireBody = {
+	type: "object",
+	properties: {
+		name: {
+			type: "string",
+			minLength: 1
+		},
+		category: { type: "string" },
+		location: { type: "string" },
+		custodian: { type: "string" },
+		metadata: {
+			type: "object",
+			additionalProperties: true
+		}
+	}
+};
+/**
+* Build the fixed-asset resource over a live assets engine. Exported so a
+* host can mount it directly (custom module composition).
+*/
+function createAssetResource(args) {
+	const { engine, permissions } = args;
+	const currency = args.currency;
+	if (!isCurrencyCode(currency)) throw new Error(`createAssetResource: \`currency\` must be an ISO 4217 code, got ${JSON.stringify(currency)}. It is host config with no default -- an asset register must know its functional currency.`);
+	const categoryEnum = args.categoryEnum;
+	const prefix = args.prefix;
+	const money$1 = (amount) => money(amount, currency);
+	/** Repo verbs return hydrated docs OR lean claim() results - normalize. */
+	const plain = (d) => {
+		const doc = d;
+		return typeof doc?.toObject === "function" ? doc.toObject() : d;
+	};
+	/**
+	* Actor context from the arc request (company-wide - no org scope).
+	*
+	* Scope-FIRST (arc 2.25): `request.scope` is the validated identity every
+	* auth adapter populates, so this resolves a human `userId` OR a service
+	* `clientId`. Reading `request.user._id` directly — as this did before —
+	* silently attributed EVERY fixed-asset mutation to `'system'` on any host
+	* using scope-based auth (service tokens, API keys), destroying the audit
+	* trail on a financial register. `scopeFirstCtx` is structural: it accepts a
+	* raw `FastifyRequest` AND arc's flat `IRequestContext` projection, so one
+	* resolver serves routes, actions, and controller overrides alike.
+	*/
+	const ctxOf = (req) => scopeFirstCtx(req, { fallbackActorId: "system" });
+	const DEPRECIATION_SCHEMA = {
+		type: "object",
+		required: ["method", "periods"],
+		properties: {
+			method: {
+				type: "string",
+				enum: [
+					"straight_line",
+					"declining_balance",
+					"double_declining",
+					"sum_of_years_digits",
+					"units_of_production",
+					"manual"
+				]
+			},
+			periods: {
+				type: "integer",
+				minimum: 1,
+				maximum: 1200
+			},
+			decliningRate: {
+				type: "number",
+				exclusiveMinimum: 0,
+				maximum: 1
+			},
+			totalUnits: {
+				type: "integer",
+				minimum: 1
+			},
+			manualSchedule: {
+				type: "array",
+				items: {
+					type: "integer",
+					minimum: 0
+				}
+			}
+		},
+		additionalProperties: false
+	};
+	/**
+	* CREATE is the domain verb, declared as a WRITE VERB (arc 2.34 `writes`)
+	* rather than a controller override.
+	*
+	* The override replaced arc's whole write pipeline for this slot, so the
+	* seven `systemManaged: true` rules below were declared and never enforced on
+	* `POST /` — as were tenant injection, `createdBy` and the hook sandwich.
+	* `acquire()` happens to build an explicit whitelist, so nothing forged got
+	* through in practice; that is the kernel saving the resource, not the
+	* resource being safe.
+	*
+	* It also fixed a drift the override could not: the controller hardcoded
+	* `tenantField: false` while the resource declares `tenantField ?? false`, so
+	* a host that passed one got a resource scoped by it and a controller that
+	* ignored it. Arc auto-builds the controller now, from the resource's own
+	* value.
+	*/
+	const createFixedAsset = async (data, ctx) => {
+		const asset = await engine.repositories.asset.acquire({
+			assetNumber: String(data.assetNumber ?? ""),
+			name: String(data.name ?? ""),
+			category: data.category ?? "office_equipment",
+			cost: money$1(Number(data.cost ?? 0)),
+			salvageValue: money$1(Number(data.salvageValue ?? 0)),
+			depreciation: data.depreciation,
+			...data.placedInServiceAt ? { placedInServiceAt: new Date(String(data.placedInServiceAt)) } : {},
+			...data.branchId ? { branchId: String(data.branchId) } : {},
+			...data.location ? { location: String(data.location) } : {},
+			...data.custodian ? { custodian: String(data.custodian) } : {},
+			...data.metadata ? { metadata: data.metadata } : {}
+		}, ctxOf(ctx));
+		return {
+			...plain(asset),
+			id: String(asset._id)
+		};
+	};
+	return defineResource({
+		name: "fixed-asset",
+		displayName: "Fixed Assets",
+		tag: "Finance - Fixed Assets",
+		prefix: prefix ?? "/assets",
+		audit: true,
+		adapter: createMongooseAdapter({
+			model: engine.models.FixedAsset,
+			repository: engine.repositories.asset
+		}),
+		customSchemas: {
+			create: { body: createAssetWireBody },
+			update: { body: updateAssetWireBody }
+		},
+		queryParser: new QueryParser({
+			maxLimit: 100,
+			allowedFilterFields: [
+				"status",
+				"category",
+				"assetNumber",
+				"branchId",
+				"location",
+				"custodian"
+			]
+		}),
+		tenantField: resolveSpineTenant(engine.config.tenant).resourceTenantField,
+		/**
+		* The CREATE slot IS the kernel's `acquire()` verb — arc keeps the pipeline
+		* (field-rule sanitization, tenant injection, actor stamp, hooks) and calls
+		* the command where it would have called `repository.create`.
+		*/
+		writes: { create: (data, wctx) => createFixedAsset(data, wctx.req) },
+		schemaOptions: { fieldRules: {
+			status: { systemManaged: true },
+			accumulatedDepreciation: { systemManaged: true },
+			bookValue: { systemManaged: true },
+			grossCarryingAmount: { systemManaged: true },
+			accumulatedImpairment: { systemManaged: true },
+			revaluationSurplus: { systemManaged: true },
+			version: { systemManaged: true }
+		} },
+		permissions: permissionMatrix({
+			read: permissions.view,
+			write: permissions.manage
+		}),
+		actions: {
+			/** draft → active. Optional body: { placedInServiceAt } (past dates OK). */
+			activate: {
+				permissions: permissions.manage,
+				handler: async (id, data, req) => {
+					const body = data ?? {};
+					return engine.repositories.asset.activate(id, ctxOf(req), body.placedInServiceAt ? new Date(body.placedInServiceAt) : void 0);
+				}
+			},
+			/** Compute + persist the depreciation projection (safe pre-activation). */
+			"generate-schedule": {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					properties: {
+						book: {
+							type: "string",
+							description: "Depreciation book — default 'accounting'; 'tax' is projection-only"
+						},
+						firstPeriodFraction: {
+							type: "number",
+							exclusiveMinimum: 0,
+							maximum: 1,
+							description: "Half-year rule = 0.5; mid-month proration"
+						},
+						methodOverride: { type: "string" },
+						periodsOverride: {
+							type: "integer",
+							minimum: 1
+						},
+						decliningRateOverride: {
+							type: "number",
+							exclusiveMinimum: 0,
+							maximum: 1
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => engine.services.depreciation.generate(id, data ?? {}, ctxOf(req))
+			},
+			/**
+			* Post ONE due period → JE `Dr 66xx Depreciation / Cr 1359 Accumulated`
+			* (accounting book; tax-book posts are projection flips only).
+			* Sequential-only; crash-retry dedupes via `dep:<scheduleId>:<sequence>`.
+			*/
+			"post-period": {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					required: ["sequence"],
+					properties: {
+						sequence: {
+							type: "integer",
+							minimum: 0
+						},
+						units: {
+							type: "integer",
+							minimum: 0
+						},
+						book: { type: "string" }
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data;
+					return engine.services.depreciation.postPeriod(id, body.sequence, {
+						...body.units != null ? { units: body.units } : {},
+						...body.book ? { book: body.book } : {}
+					}, ctxOf(req));
+				}
+			},
+			/**
+			* active → disposed. The engine computes gain/loss and posts the
+			* BC-style derecognition JE via the ledger bridge (draft for finance
+			* review): Dr 1359 accumulated + Dr 1113 proceeds / Cr 13xx cost,
+			* plug → 6810 loss or 4304 gain. Idempotent on `disposal:<assetId>`.
+			*/
+			dispose: {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					properties: {
+						proceeds: {
+							type: "integer",
+							minimum: 0,
+							description: "Sale proceeds in paisa (0 = scrapped)"
+						},
+						disposedAt: { type: "string" },
+						note: {
+							type: "string",
+							maxLength: 512
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data ?? {};
+					const { asset, gainLoss, ledgerEntryRef } = await engine.repositories.asset.dispose(id, {
+						proceeds: money$1(body.proceeds ?? 0),
+						...body.disposedAt ? { disposedAt: new Date(body.disposedAt) } : {},
+						...body.note ? { note: body.note } : {}
+					}, ctxOf(req));
+					return {
+						...plain(asset),
+						id: String(asset._id),
+						gainLoss,
+						disposalEntryRef: ledgerEntryRef
+					};
+				}
+			},
+			/** active → retired (kept on register, no longer depreciating). */
+			retire: {
+				permissions: permissions.manage,
+				handler: async (id, _data, req) => engine.repositories.asset.retire(id, ctxOf(req))
+			},
+			/** active → written_off (book value zeroed by decision; JE is finance's manual call). */
+			"write-off": {
+				permissions: permissions.manage,
+				handler: async (id, _data, req) => engine.repositories.asset.writeOff(id, ctxOf(req))
+			},
+			/** Move location / custodian / branch dimension. */
+			transfer: {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					properties: {
+						location: {
+							type: "string",
+							maxLength: 128
+						},
+						custodian: {
+							type: "string",
+							maxLength: 128
+						},
+						branchId: { type: "string" },
+						note: {
+							type: "string",
+							maxLength: 512
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => engine.repositories.asset.transfer(id, data ?? {}, ctxOf(req))
+			},
+			/** Append an informational valuation (market / insurance / tax_assessed / liquidation). */
+			"record-valuation": {
+				permissions: permissions.view,
+				schema: {
+					type: "object",
+					required: ["kind", "value"],
+					properties: {
+						kind: {
+							type: "string",
+							enum: [
+								"market",
+								"insurance",
+								"tax_assessed",
+								"liquidation"
+							]
+						},
+						value: {
+							type: "integer",
+							minimum: 0,
+							description: "Value in paisa"
+						},
+						asOf: { type: "string" },
+						basis: {
+							type: "string",
+							enum: [
+								"market_approach",
+								"cost_approach",
+								"income_approach",
+								"index",
+								"manual"
+							]
+						},
+						appraiser: {
+							type: "string",
+							maxLength: 256
+						},
+						notes: {
+							type: "string",
+							maxLength: 1024
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data;
+					return engine.repositories.valuation.record(id, {
+						kind: body.kind,
+						value: money$1(body.value),
+						...body.asOf ? { asOf: new Date(body.asOf) } : {},
+						...body.basis ? { basis: body.basis } : {},
+						...body.appraiser ? { appraiser: body.appraiser } : {},
+						...body.notes ? { notes: body.notes } : {}
+					}, ctxOf(req));
+				}
+			},
+			/** IAS 16 revaluation — restate carrying amount to fair value (prospective rebase). */
+			revalue: {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					required: ["fairValue"],
+					properties: {
+						fairValue: {
+							type: "integer",
+							minimum: 0,
+							description: "Fair value in paisa"
+						},
+						asOf: { type: "string" },
+						appraiser: {
+							type: "string",
+							maxLength: 256
+						},
+						notes: {
+							type: "string",
+							maxLength: 1024
+						},
+						remainingPeriods: {
+							type: "integer",
+							minimum: 1
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data;
+					return engine.services.valuation.revalue(id, {
+						fairValue: money$1(body.fairValue),
+						...body.asOf ? { asOf: new Date(body.asOf) } : {},
+						...body.appraiser ? { appraiser: body.appraiser } : {},
+						...body.notes ? { notes: body.notes } : {},
+						...body.remainingPeriods != null ? { remainingPeriods: body.remainingPeriods } : {}
+					}, ctxOf(req));
+				}
+			},
+			/** IAS 36 impairment — write down to the recoverable amount (prospective rebase). */
+			impair: {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					required: ["recoverableAmount"],
+					properties: {
+						recoverableAmount: {
+							type: "integer",
+							minimum: 0,
+							description: "Recoverable amount in paisa"
+						},
+						asOf: { type: "string" },
+						appraiser: {
+							type: "string",
+							maxLength: 256
+						},
+						notes: {
+							type: "string",
+							maxLength: 1024
+						},
+						remainingPeriods: {
+							type: "integer",
+							minimum: 1
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data;
+					return engine.services.valuation.impair(id, {
+						recoverableAmount: money$1(body.recoverableAmount),
+						...body.asOf ? { asOf: new Date(body.asOf) } : {},
+						...body.appraiser ? { appraiser: body.appraiser } : {},
+						...body.notes ? { notes: body.notes } : {},
+						...body.remainingPeriods != null ? { remainingPeriods: body.remainingPeriods } : {}
+					}, ctxOf(req));
+				}
+			},
+			/** IAS 36 impairment reversal — capped at the accumulated loss. */
+			"reverse-impairment": {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					required: ["amount"],
+					properties: {
+						amount: {
+							type: "integer",
+							minimum: 1,
+							description: "Reversal amount in paisa"
+						},
+						asOf: { type: "string" },
+						notes: {
+							type: "string",
+							maxLength: 1024
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data;
+					return engine.services.valuation.reverseImpairment(id, {
+						amount: money$1(body.amount),
+						...body.asOf ? { asOf: new Date(body.asOf) } : {},
+						...body.notes ? { notes: body.notes } : {}
+					}, ctxOf(req));
+				}
+			},
+			/** IAS 8 estimate change — remaining life and/or salvage, prospective. */
+			"change-estimate": {
+				permissions: permissions.manage,
+				schema: {
+					type: "object",
+					properties: {
+						remainingPeriods: {
+							type: "integer",
+							minimum: 1
+						},
+						salvageValue: {
+							type: "integer",
+							minimum: 0,
+							description: "New salvage in paisa"
+						}
+					},
+					additionalProperties: false
+				},
+				handler: async (id, data, req) => {
+					const body = data ?? {};
+					return engine.services.valuation.changeEstimate(id, {
+						...body.remainingPeriods != null ? { remainingPeriods: body.remainingPeriods } : {},
+						...body.salvageValue != null ? { salvageValue: money$1(body.salvageValue) } : {}
+					}, ctxOf(req));
+				}
+			}
+		},
+		routes: [
+			{
+				method: "GET",
+				path: "/:id/schedule",
+				summary: "Depreciation schedule (all periods with posting state; ?book=tax for alternate books)",
+				permissions: permissions.view,
+				rawHandler: async (req, reply) => {
+					const { id } = req.params;
+					const { book } = req.query;
+					const schedule = await engine.repositories.schedule.findByAssetAndBook(id, book ?? "accounting", {});
+					return reply.send(schedule ?? null);
+				}
+			},
+			{
+				method: "GET",
+				path: "/:id/valuations",
+				summary: "Append-only valuation history (market/insurance/tax + revaluation/impairment events)",
+				permissions: permissions.view,
+				rawHandler: async (req, reply) => {
+					const { id } = req.params;
+					const rows = await engine.models.FixedAssetValuation.find({ assetId: id }).sort({ asOf: -1 }).lean();
+					return reply.send(rows);
+				}
+			},
+			{
+				method: "GET",
+				path: "/:id/current-value",
+				summary: "Value resolution — ?kind=book|market|insurance|tax_assessed|liquidation (&asOf=ISO)",
+				permissions: permissions.view,
+				rawHandler: async (req, reply) => {
+					const { id } = req.params;
+					const { kind, asOf } = req.query;
+					const result = await engine.services.valuation.currentValue(id, {
+						...kind ? { kind } : {},
+						...asOf ? { asOf: new Date(asOf) } : {}
+					}, {});
+					return reply.send(result);
+				}
+			},
+			{
+				method: "POST",
+				path: "/onboard",
+				summary: "Onboard an EXISTING asset at go-live (net method — no JEs; GL values come from the opening-balance batch)",
+				permissions: permissions.manage,
+				schema: { body: {
+					type: "object",
+					required: [
+						"assetNumber",
+						"name",
+						"category",
+						"originalCost",
+						"accumulatedDepreciation",
+						"placedInServiceAt",
+						"depreciation"
+					],
+					properties: {
+						assetNumber: {
+							type: "string",
+							minLength: 1,
+							maxLength: 64
+						},
+						name: {
+							type: "string",
+							minLength: 1,
+							maxLength: 256
+						},
+						category: categoryEnum ? {
+							type: "string",
+							enum: categoryEnum
+						} : { type: "string" },
+						originalCost: {
+							type: "integer",
+							minimum: 1,
+							description: "Historical acquisition cost (paisa)"
+						},
+						accumulatedDepreciation: {
+							type: "integer",
+							minimum: 0,
+							description: "Depreciation already taken pre-migration (paisa)"
+						},
+						salvageValue: {
+							type: "integer",
+							minimum: 0,
+							default: 0
+						},
+						placedInServiceAt: {
+							type: "string",
+							description: "Original in-service date (past)"
+						},
+						depreciation: DEPRECIATION_SCHEMA,
+						branchId: { type: "string" },
+						metadata: {
+							type: "object",
+							additionalProperties: true
+						}
+					},
+					additionalProperties: false
+				} },
+				rawHandler: async (req, reply) => {
+					const body = req.body;
+					const salvage = body.salvageValue ?? 0;
+					const remainingBookValue = body.originalCost - body.accumulatedDepreciation;
+					if (remainingBookValue < salvage) throw new ValidationError(`accumulatedDepreciation leaves book value (${remainingBookValue}) below salvage (${salvage})`);
+					const ctx = ctxOf(req);
+					const asset = await engine.repositories.asset.acquire({
+						assetNumber: body.assetNumber,
+						name: body.name,
+						category: body.category,
+						cost: money$1(remainingBookValue),
+						salvageValue: money$1(salvage),
+						depreciation: body.depreciation,
+						placedInServiceAt: new Date(body.placedInServiceAt),
+						...body.branchId ? { branchId: body.branchId } : {},
+						metadata: {
+							...body.metadata ?? {},
+							onboarded: true,
+							originalCost: body.originalCost,
+							accumulatedAtMigration: body.accumulatedDepreciation
+						}
+					}, ctx);
+					const id = String(asset._id);
+					const activated = await engine.repositories.asset.activate(id, ctx, new Date(body.placedInServiceAt));
+					const schedule = await engine.services.depreciation.generate(id, {}, ctx);
+					return reply.code(201).send({
+						asset: {
+							...plain(activated),
+							id: String(activated._id)
+						},
+						schedule
+					});
+				}
+			}
+		]
+	});
+}
+function createAssetsModule(deps) {
+	const maintenance = deps.maintenance;
+	const dependsOn = deps.dependsOn ?? (typeof deps.ledger === "function" ? ["accounting"] : []);
+	/**
+	* The live Fastify instance, captured for the FACTORY ledger form only.
+	*
+	* `defineEngineModule`'s `boot` is nullary by design, but a FACTORY ledger
+	* (`deps.ledger(fastify)`) must read `f.arc.modules.accounting` at bind
+	* time. Arc runs a module's `plugins` arm — which DOES receive the live
+	* instance — before ANY bootstrap, so the `extend` arm below captures it
+	* there and `boot` dereferences it. Registered only when the factory form
+	* is in play; the timing of the factory CALL is unchanged (still at
+	* bootstrap, still after accounting's own bootstrap via `dependsOn`).
+	*/
+	let app;
+	const { module } = defineEngineModule({
+		name: "assets",
+		...deps.engine !== void 0 ? { supplied: deps.engine } : {},
+		...dependsOn.length > 0 ? { dependsOn } : {},
+		/**
+		* Deferred by construction (the old hand-rolled dance said "NOT
+		* `ownedEngine()`" for the same two reasons): `defineAssets().bind()` is
+		* async, and a FACTORY ledger needs the live Fastify instance — so
+		* nothing here may run at composition. `defineEngineModule` runs this at
+		* arc's bootstrap, after `dependsOn` modules.
+		*/
+		boot: async () => {
+			let ledger;
+			if (typeof deps.ledger === "function") {
+				if (app === void 0) throw new Error("[spinekit/assets] a FACTORY ledger (`deps.ledger(fastify)`) is resolved with the live Fastify instance this module captures in its plugins phase — boot() ran without it, i.e. outside arc's lifecycle. Boot through arc, or resolve the LedgerPort yourself and pass it as a value.");
+				ledger = deps.ledger(app);
+			} else ledger = deps.ledger;
+			return defineAssets({
+				tenant: resolveSpineTenant(deps.tenant ?? false).input,
+				...deps.schemaOptions ? { schemaOptions: deps.schemaOptions } : {},
+				...deps.forceRecreate !== void 0 ? { forceRecreate: deps.forceRecreate } : {}
+			}).bind(deps.connection, {
+				...ledger ? { bridges: { ledger } } : {},
+				...deps.eventTransport ? { eventTransport: deps.eventTransport } : {},
+				...deps.outbox ? { outbox: deps.outbox } : {},
+				...deps.allowNonTransactional !== void 0 ? { allowNonTransactional: deps.allowNonTransactional } : {}
+			});
+		},
+		close: (engine) => engine.close(),
+		resources: (engine) => [createAssetResource({
+			engine,
+			permissions: deps.permissions,
+			currency: deps.currency,
+			...deps.categoryEnum ? { categoryEnum: deps.categoryEnum } : {},
+			...deps.prefix ? { prefix: deps.prefix } : {}
+		})],
+		extend: (get) => ({
+			...typeof deps.ledger === "function" ? { plugins: (fastify) => {
+				app = fastify;
+			} } : {},
+			...maintenance === false ? {} : { scheduledJobs: () => assetsMaintenanceSchedules(get(), maintenance) }
+		})
+	});
+	return module;
+}
+//#endregion
+export { assetsMaintenanceSchedules, createAssetResource, createAssetsModule };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@spinekit/assets",
+  "version": "0.1.1",
+  "description": "Arc module for @classytic/assets — fixed-asset register + multi-book depreciation + IAS 16/36 valuation as composable resources. BYO-engine or module-created; ledger bridge is host-injected (any chart of accounts). Depreciation posts through the bridge; GL account mapping stays host policy.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@classytic/arc": ">=2.34.0",
+    "@spinekit/kit": ">=0.1.0",
+    "@classytic/assets": ">=0.5.0",
+    "@classytic/mongokit": ">=3.34.0",
+    "mongoose": ">=9.4.1"
+  },
+  "devDependencies": {
+    "@classytic/arc": "^2.34.0",
+    "@classytic/arc-testkit": "^0.4.0",
+    "@classytic/assets": ">=0.5.0",
+    "@classytic/mongokit": ">=3.34.0",
+    "@classytic/primitives": ">=0.23.0",
+    "@types/node": "^24.3.0",
+    "fastify": "^5.12.0",
+    "mongodb-memory-server": "^10.4.3",
+    "mongoose": "^9.7.2",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4",
+    "@spinekit/kit": "0.1.1"
+  },
+  "author": "Classytic",
+  "homepage": "https://www.npmjs.com/package/@spinekit/assets",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/spine.git",
+    "directory": "packages/spine-assets"
+  },
+  "keywords": [
+    "arc",
+    "classytic",
+    "spine",
+    "erp",
+    "fixed-assets",
+    "depreciation",
+    "ias-16"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}