Packages

Package Types

Application

This is package main in Go. An application provides an entry point.

I may also limit access to some resources to the Application. For instance os access. In that case, os will provide a file system object that can be passed into any library or module that needs it, but it means that the application knows what's happening.

Library

A library is intended for re-use.

Only a library can access reflection and unsafe. Though not all libraries must.

Libraries have a very high testing and documentation burden. Libraries can only import libraries (not modules). Libraries must return specific errors.

Like Go, unsafe allows for pointer math and pointer conversion. I think unsafe will also allow access to privates.

Libraries have types - not sure if this is declared or inferred

• Unsafe: uses unsafe, high security, testing and documentation burden
• Pure: Or "functional", performs no mutations within the library, very low security and testing burden
• Object: Library is built around providing one object (a red/black tree library).

Module

A module is intended to scope application logic. While a module may be shared between a few applications, it's not intended for wide, general purpose re-use.

Modules cannot include unsafe code. I may not allow operator definitions in libraries.

Script

Something not intended for any distribution or support. Runs as main, essentially no requirements. Intended for one-off projects, scratch area, gists.

Versioning

Package versioning is separate from source control versioning. A fully qualified version has Domain, Package, Major version, Minor version, Patch version and a file list.

The file list is sorted by name and includes the hash of each file. The packages form a cryptographic linked list (yeah, a blockchain) where each minor and patch version point to the previous. All the data is included in a package hash. Also needs to include a list of packages that it uses, their version and hash.

When releasing a patch version, the API tests from all previous versions in the minor branch must pass. The package interface cannot change. When releasing a minor version, all tests from all previous versions must pass, and the previous version must be compatible with the current version. This will allow some coercion though. A function that accepted a single value and now accepts a variadic is ok. Something that accepted a concrete type and now accepts an interface is ok. Something that returned an interface and now returns a concrete type that fulfills that interface is ok.

Major packages are really considered to be a separate package.

Version Collisions

This creates an issue. If an application tries to include packages A and B which both include C but A includes C3.2.1 and B include C3.1.2, this is not ok.

I think the best solution is to always use the highest minor version from any package included.

Bug Fix

One case that can break this is bug fixes.

If a bug in just in a test, we can issue a patch to the test. This requires listing the range of versions with the bug. Those tests will not be run in future versions.

If the bug is in the package that requires a few things. First, there needs to be a test that fails on the previous version and passes on the new version. In most cases a minor release will be required.

License

A fully qualified package must include a license. We can build a graph a license subsets and make sure that there are no license conflicts.

Import Names

Rather than the Go style of adding the imports at the top of each file, the imports are declared on the package. The actual package definition file is generated, but a list of packages is provided in a user defined file. This file is where package names can be aliased. But this means that an alias is consistent through the package, not changing between files. Unlike Go, an unused package can't really happen so it's not an error. There can be a package in the list that isn't used, but since that file doesn't end up in the compiled version, it's not an issue.

Major Migrations

Major version updates can allow a migration script. This requires some base tool for manipulating the AST for refactoring.

In an ideal major update, the script can run against the API and integration tests and all the tests should still run and pass after the migration.

The script is still something that users will have to choose to run, but it should be easy to do from the command line.

Security

This is implemented at a package level. Signatures are based on EigenTrust. So a user can place partial trust in a few base organizations and compute aggregate trust in any organization from there.

But trust isn't needed for all packages. Trust level required is computed from the state of the package.

Applications that don't access restricted resources don't require any trust.

Developer Signatures

A Domain or Package can have developer keys. If it does, then releases of that package must be signed. An advanced option for this could be adding a number of keys and requiring a minimum subset. So there could be 7 keys and 4 are needed to sign a package. Or we could do weighted, there are 10 keys each with a fractional weighting and a sum of at least 1.0 is required.

One of the base use cases for this is the standard library. The domain will be an empty string, but I will have the developer key.

This will also require that there be operations to change out the keys. And of course the whole thing is backed by EigenTrust. So the community always has the option to blacklist one package and swap out a drop in replacement.